Wave 2 (player actions I): drop-through, ladder climb, duck, hurt-knockback; harness v10

[SethMorrowSoftware]

The first Kit-touching wave of the content phase, implementing docs/expansion-prep.md §9 in full. Statically verified (all script gates green, embedded Kits in sync, native smoke test passes); needs the OXT pass: harness v10 RUN ALL TESTS first, then both games.

Kit — four controller abilities

Drop-through. Open chains (b2kChain/b2kSmoothGround/b2kAddChain) are created carrying a reserved ONE-WAY collision category (bit 31; b2kDefineLayer now hands out 30 named layers). DOWN+JUMP while standing on one strips the bit from the player's mask for dropMs (260). Two traps found and solved at design time:

• A pure timer FAILS at real scales — 260 ms of freefall moves a capsule ~14–20 px but the capsule is 48–88 px tall, so restoring the filter mid-straddle makes the one-sided push-out pop the player back on top. The window's close is geometry-aware (straddle rays at expiry, 2-frame extensions, dropMs × 4 hard cap).
• Rays ignore shape filters, so the ground probe skips one-way hits by category while dropping, or it would re-ground mid-drop.

Hills/slopes opt out with a new trailing noDrop flag (the platformer's mound passes it). No ABI change: b2lc_chain_create already consumes the staged one-shot shapedef filter — the design's open question dissolved on inspection. ABI stays 4.

Ladder climb. b2kPlayerAddLadder x1,y1,x2,y2 registers polled zones (zero physics objects; wiped by clear/teardown). In-zone + UP/DOWN → state climb: gravity 0, moveY drives y at climbSpeed, x at half speed, releasing hangs. The jump-exit listens only to jump keys that are not also moveY keys — so SPACE dismounts while UP keeps climbing, even under the platformer's space,up,w binding. UP grabs only with ladder above the head (standing on the deck a zone pokes through, UP jumps — never re-grabs); DOWN grabs only mid-air (drop through the deck, hold DOWN, catch the ladder).

Duck. DOWN while grounded brakes vx to 0 with the duck pose; jump presses are swallowed (down+jump on solid ground just ducks). No hitbox change this wave — documented so nobody designs duck-under gaps before Wave 5.

Hurt-knockback standard. b2kPlayerHurt [fromX]: control off, away-pop (hurtPopX/hurtPopY, ground-snap exempt), hurt anim, control restored at the first landing after hurtMs/2 or at hurtMs, whichever comes first, then an invulnerability window (invulnMs) with b2kPlayerHurtIs() as the game-side gate.

Plus: b2kPlayerAnims gains optional climb/duck/hurt slots with fallbacks; b2kPlayerState() adds the three states; and a latent cross-build landmine fixed — b2kSetCategory/b2kSetCollisionGroup fed Box2D v3.1's 64-bit default-mask read-back (≈1.8e19) into the shim's 2^53 gate, silently no-oping the whole write; both setters now normalise to the Kit's 32-bit space.

Harness v10

Four new suites, ~20 self-diagnosing assertions: drop-through (pierce, land below, chain re-solidifies), climb (grab/hang/ascend/jump-off/ground-out, gravity-scale restored), duck (brake, down+jump never launches), hurt (away-pop, invuln no-op, control auto-restore).

Games (the two consumers proving the API)

• Platformer: L2 gains the ladder + one-way bonus ledge above the plate area (9th coin) on real character_beige_climb_a/b frames; knockback for slime sides/saws/spikes (no fall counted), respawn kept for pits/kill plane/thwomp crush; the OnFinish respawn handler is gated by gHurtLock so the controller's non-looping hurt pose can never teleport the hero.
• Micro-game: same knockback/respawn split; the L2 exit door moves onto a tower no jump reaches, climbed via a new ladder level verb; an optional alien skin picker (S on the menu — embedded hero + five aliens with real climb/duck/hurt frames) behind the Spritesheets folder, falling back silently so the file stays zero-asset by default.

Docs ride along: kit-reference, kit-guide (a new action-verbs teaching section + the noDrop recipe), CHANGELOG, plan.md decision log, expansion-prep §9 as-built notes.

OXT checklist for the user

1. Harness v10: RUN ALL TESTS → expect ALL PASS (~122 assertions; report any FAIL line verbatim).
2. Platformer: drop through the L1 bridge/clouds (duck on the mound must NOT sink); climb the L2 ladder to the bonus coin, drop back through the deck; get hit by a slime side/saw/spike → knocked away + flashing, no teleport; fall in a pit → respawn as before; finish all three levels (no Wave 1 regressions).
3. Micro-game: paste-and-play asset-free; L1 ledge drop; L2 tower climb (hold RIGHT at the top to drift over the lip); spikes/sweeper knock back, world-fall respawns; S on the menu cycles skins once the folder is given.

https://claude.ai/code/session_01ECCfoqgaPXT8v32VCxWjBG

---

Generated by Claude Code