feat: directed stumble — first active survival reaction (0.4.0)

[blugart-dev]

What

The first active self-preservation reaction for 0.4.0: a staggering hit now visibly shoves the character — it lurches in the hit direction, the feet step to follow, the upper body reacts, and it ends up displaced before recovering to idle.

This consolidates and supersedes #83, #84, #85 (which describe an earlier emergent approach that was reworked — see below). One clean PR for the whole feature.

The pivot it records

The first attempt drove stumbling emergently (wait for the centre-of-mass to drift into a balance band, then make a small foot reposition to "catch" it). In practice it was invisible and unreliable — most hits never reached the band or blew straight past it to a ragdoll, and a foot reposition on an otherwise-rigid body read as nothing.

Reworked to be directed, which is closer to how Euphoria actually works (triggered behaviors, not pure emergent physics): the hit triggers the reaction reliably, it's big (displaces the character), and it's art-directable. The now-unused StumblePlanner decision class is removed.

How the directed stumble works

1. Knockback displacement — root drifts along the hit direction (stumble_push_speed, decaying at stumble_push_decel); the springs pull the body along, so the whole character moves.
2. Stepping feet — every stumble_step_length of travel the trailing foot steps, placed ahead of the hips and kept in its own lane (no crossing), lifted along a sine arc (stumble_step_lift) so it steps rather than slides.
3. Differential stiffness — only the lower body stiffens (stumble_brace_strength) to step + stay upright; the upper body stays loose and reacts to the momentum (purposeful legs, reactive torso/arms/head).
4. Commit + end — the tip-over→ragdoll transition is suspended while stumbling, so the reaction plays out; strong hits still ragdoll, light hits just wobble.

Built on the hardened active-ragdoll springs (foot-IK orientation fix + spring settle deadband, already on main).

Changes

• ActiveRagdollController — _update_directed_stumble / _do_directed_step (hit-driven), _apply_stumble_brace (lower-body-only stiffening), stumble_step_started signal.
• FootIKSolver — begin_stumble() / is_stepping() with the lift arc, reusing the stagger pin/IK plumbing.
• RagdollTuning — "Self-Preservation: Stumble Steps" group.
• docs/SELF_PRESERVATION.md (directed design + the pivot), ROADMAP 0.4.0 → 🚧, CHANGELOG.

Validation

• GUT 116/116 (test/test_stumble_step.gd drives the real controller + foot IK on a live rig: a hit displaces the character along the hit direction + fires steps; disabling suppresses it). Motion quality validated visually on the real ybot (the synthetic rig's emergent fall is too nonlinear to assert).
• Import clean. User-validated in-editor — reads as "shoved and stumbled," with the upper body reacting.

Follow-up

Arm bracing (the upper-body active layer — windmill + reach) is next, and completes the 0.4.0 milestone.

🤖 Generated with Claude Code