[blugart-dev]

Summary

Milestone 0.6.0 — Balance + behaviors (docs/PLAN.md), into develop (main is frozen until the maintainer's feel gate). This PR carries the milestone; step 1, feet load-bearing, is complete and measured. Later steps (BalanceState, behaviors, the deletions) land as further commits here.

Step 1 — the legs carry the body

Before: the root anchor's position motor held the pelvis with up to 2500 N, the feet were masked out of collision while foot IK solved, and when allowed to collide they carried ~2 % of the 804 N body (tools/bench/foot_probe.gd).

• Sole-aligned foot collider (BoneDefinition.sole_aligned): a level box with its bottom face on the foot IK sole and a heel behind the ankle. The old bone-aligned box followed the Mixamo foot bone 27° down; its corner sat 7 cm under the floor, a colliding foot was pushed 15° off its pose — the reason the feet had to be masked.
• Feet collide in every state (foot_ik_disable_foot_collision default false) and report contacts.
• muscle_root_support (default 0): the anchor has no vertical authority; a second, world-aligned anchor carries the position motor so the up-axis limit is truly vertical.
• Get-up on load-bearing feet: full anchor support + frictionless feet during the canned blend, faded back over 0.75 s. Shooting range: ≤ 8° at recovery_finished, 1–4° after 3 s, pelvis at target height on its own legs.

Numbers (ybot, tools/bench/ybot_bench.gd)

Mode, Hz	IDLE mean/max	HIT peak/recover	SETTLE after react	SAG	FEET	resolver ms
legacy 60	0.81 / 1.56	1.2° / 4	0.96 (balance 0.09)	+0.5 mm	100 %	0.16
JOINT_MOTOR 60	1.10 / 3.51	1.9° / 4	9.9 (balance 0.54)	+6.2 mm	100 %	0.22
JOINT_MOTOR 120	0.73 / 1.87	2.0° / 4	1.63	+0.8 mm	100 %	0.21
JOINT_MOTOR 30	5.45 / 23.0	6.6° / 4	20.9	+9.3 mm	100 %	0.22

Exposed, and the next step's job: after the violent react clip the loaded feet stay where friction planted them while the animation returns to idle (SETTLE 9.9° vs legacy 0.96°). A load-bearing foot cannot be dragged into place — it must be unloaded and stepped. That is BalanceState + StepBehavior. 30 Hz regressed 4.85 → 5.45 and stays open.

Suite: 253 tests green (9 new in test_feet_load_bearing.gd); all 8 demos load headless clean.

Human gate (visual, when the milestone is complete)

• idle stands on its feet, no float, no sag visible
• knock a character down (Explosion) — gets up upright and stands on its legs
• steps read as steps; no moon-walking feet (after the step behavior lands)

🤖 Generated with Claude Code

https://claude.ai/code/session_018RbYJ9LscLhHypHqWfhtGF

[blugart-dev]

Step 2 — self-collision on (maintainer asked for the ragdoll look before the balance state). self_collision defaults to true: jointed pairs excluded by the joint, build-pose overlaps excluded by a safety net, everything else collides — a limp arm is blocked by the chest (test_self_collision.gd). Measured: no non-adjacent overlaps on the ybot idle / react / ragdoll, bench bit-identical on/off, get-up 2–5°. Limits not tightened: tools/bench/limit_envelope.gd shows the 21 clips already exceed 17 authored axes (elbow lateral ±58 vs ±20, spine X −75 vs ±35, knee 149 vs 140); tightening would fight the get-up / injured clips. 259 tests green, demos load clean.

[blugart-dev]

Step 3 — BalanceState. One balance measurement per tick: CoM, CoM velocity, XCoM (CoM + v/√(g/h)), support polygon = convex hull of the sole footprints of the feet in contact, signed margin to the edge, ratio (0 centre / 1 edge / >1 outside), loaded foot. Replaces the static CoM-vs-ankle ratio that read 0.5–0.6 while standing; ybot idle now reads 0.40–0.42 with a 12.5 cm margin, thresholds recalibrated (stagger 0.8, recovery 0.6, ragdoll 1.0). HUD draws the hull + XCoM. 266 tests green. Tip-over on the XCoM waits for the step behavior.

[blugart-dev]

Step 4 — behavior layer + StepBehavior; the directed stumble is gone. KickbackBehavior reads BalanceState and answers with stiffness floors + pose targets; the controller runs a fixed list in NORMAL/STAGGER. StepBehavior: balance steps to the capture point and re-plants of a loaded foot the animation cannot drag, via foot locks + FootIKSolver.begin_step (hover-until-arrived landing). The root teleport, stumble brace and windmill are deleted (grep 'global_position +=' addons/ is empty). Measured: root moved 0.25 m → both feet re-planted by 0.83 s; after react_front legs within 3° by 2.8 s (SETTLE 10.4 → 6.2 in the 2nd second). muscle_root_hold stays 1: with it released and no upright behavior the idle is unstable (7.2°, constant steps) — UprightBehavior is next. 269 tests green.

[blugart-dev]

Step 5 — balance control. muscle_root_hold 0.25: the root anchor is a bounded assist (≈625 N) instead of the thing holding the character up. Ankle torque 150 N·m, muscle_leg_gain 0.2, smoothed CoM velocity, step trigger 1.0, and a physical fall detector (pelvis low / tilted for 0.15 s → RAGDOLL, no dice — a 400 N·s shove with the assist released is detected within 2 s). Measured: idle 0.98°, settle after react 10.4 → 6.1°, 150 N·s shove caught by legs + steps. Hold 0 not reached: the passive stance is 3.4–4.4° and chaotic under the shove; the IK-shift UprightBehavior measured worse and ships off. 275 tests green.