ik-foot-locking · diff
git:20260912.a22b95e to git:20260913.ed0ec2c
17 added, 12 removed. Audit A to A.
---
name: ik-foot-locking
- description: Lock toes on contact so feet do not slide. Two-bone leg IK plus a contact state machine and inertialization. Use for walk/run on terrain. Do not rebuild the whole skeleton.
+ description: Use when rendered feet need contact locking or terrain adaptation after locomotion/animation, including varied skeleton joints, slopes, stairs and moving surfaces without making IK the gameplay movement owner.
---
# IK foot locking
- Source shape: Daniel Holden, Inverse Kinematics and Foot Locking. Engine-neutral.
+ IK is a **presentation pose correction** after the authoritative root/body movement and source animation pose.
+ ## Contact schema
+
+ Select an available contact marker: toe when present/useful, otherwise a **foot/ankle** marker or project-defined sole/contact point. Do not require a toe joint on every rig.
+
+ Contact detection may combine relative velocity, height/distance, animation phase and ground probe with authored hysteresis/debounce. Thresholds and durations are project/scale data.
+
+ For a **moving** or rotating support, store the lock anchor in support-local or otherwise stable reference space and evaluate actor/contact motion **relative** to that surface so the foot follows it without world-space skating.
+
## Rules
- 1. IK is a pose fix, not a locomotion owner. Locomotion writes the root; this skill edits the leg after.
- 2. Lock the toe, not the heel.
- 3. Soft-clamp extension. Never pull the pelvis to reach a target.
- 4. Contact = toe world speed below a threshold (start at 0.1-0.5 m/s) AND height sanity AND a 3-5 frame majority vote.
- 5. Unlock with the same vote so one noisy frame cannot pop the foot.
- 6. Blend with inertialization: keep the old offset, then decay toward the new solve. Do not lerp two world targets.
- 7. Ground height comes from a probe, never y = 0.
+ 1. `locomotion`/physics owns root movement; IK edits leg/foot pose and never fabricates grounding/gameplay collision.
+ 2. Lock point/joint is chosen from the rig/contact schema, not universally toe-vs-heel.
+ 3. Leg extension is clamped to an anatomical/rig range. Optional **pelvis** compensation may be used when authored, bounded and presentation-only; it is not universally forbidden or required.
+ 4. Contact enter/exit hysteresis prevents noisy pops, but no universal 3–5 frame vote is imposed.
+ 5. Ground/support data comes from explicit probes/contacts, never an assumed world Y=0.
+ 6. Blend/inertialisation keeps lock transitions continuous and avoids averaging unrelated world-space targets.
## Accept
- - During a locked contact, toe travel < 1 cm
- - Slope and stairs keep contact without skating
- - Unlock into a stride does not rubber-band the ankle
+ Test stationary and moving/rotating supports, slopes/stairs, missing-toe rigs, reach limits and unlock transitions. Record contact marker, support ID/reference, lock error and pelvis adjustment where used; acceptance tolerance is authored for rig scale rather than a universal 1 cm.