Foot IK with pelvis lowering, ground tilt, and edge smoothing

[robtfm]

Summary

Adds an idle-only inverse-kinematics pass that plants avatar feet on the actual ground beneath them — slopes, short steps, uneven terrain — so the avatar doesn't visibly hover or clip when standing on non-flat surfaces.

Toggle in-game with `/footik` (off by default). Applies to the primary user, foreign players, and scene NPCs.

How it works

Runs in `PostUpdate`, after `PlayerUpdate` and before `AttachSync`, with a manual transform-propagate pass so attached items see post-IK bone positions:

1. Bone discovery — recursively finds `avatar_hips` and the six leg bones by name on each `AvatarShape`, caches them in a `FootIkRig` component. Self-heals when wearables reload (any cached bone going stale invalidates the rig and rebuilds the next frame).
2. Per-foot raycast — `cast_ray_nearest` (true ray, not capsule) downward through the scene colliders that contain the avatar. Captures the contact normal too.
3. Pelvis lowering — for each leg, computes the hip drop required to make the foot reach its plant target (law of cosines). The greater of the two becomes a world-Y translation on `avatar_hips`, converted to the bone's parent-local frame via the parent's full affine inverse (the rig is imported with a ~0.01x cumulative scale, so a rotation-only conversion would produce a ~1cm-instead-of-1m delta).
4. Two-bone IK — analytic solve for hip + knee rotations to plant each foot at its target, using the avatar's forward direction as a pole hint.
5. Foot tilt — rotates each foot bone toward the contact normal, axis-angle-clamped to `max_foot_tilt_deg` (default 30°).
6. Engagement / weight blending:
   • `w_anim` ramps toward 1.0 while the active emote is an idle pose, otherwise 0.0, at the rate set by the emote's declared `transition_seconds` (`SceneMovementAnim` overridable flag, or URN match for engine-default idle).
   • Per-leg `engaged` ramps toward `reach_ok ? 1 : 0` over `engage_transition_seconds`. Going up beyond `max_step_up` or down beyond `max_pelvis_drop` makes a leg disengage; rotation `r_hip`/`r_knee`/foot tilt slerp from identity by the per-leg weight.
   • Final per-leg weight is `min(w_anim, engaged)` — the gates clamp rather than compound.
7. Velocity-limited final Y — the foot's final world Y is rate-limited at `target_velocity_limit` m/s while engaged. Smooths the case where the foot's xz sweeps across a cliff edge during a turn-in-place (raycast result jumps but the foot output doesn't). Snaps on the first engaged frame after a disengaged one. Invariant under continuously-moving platforms (avatar moves with them, so the relative offset doesn't change).

Scope

• Primary user, foreign players, NPCs (anything with `AvatarShape`).
• Idle only — fades out via `w_anim` once the avatar enters a non-idle emote.
• All knobs live in `FootIkConfig` with documented purposes; not yet exposed via console subcommands.

Out of scope (could follow up)

• Foot-phase walking IK (engage during foot plants in walk/jog cycles — useful for stairs).
• Toe-joint bend.
• Console subcommands for live tuning.
• Visibility/distance-based culling on foreign avatars and NPCs.

🤖 Generated with Claude Code