Skel: Slice F — IK chain authoring (2-bone analytical IK, pole targets, FK↔IK switch)

[fernandotonon]

Parent epic: #554

Goal

Author IK chains so animating arms/legs is "place the hand here" instead of keying every joint by hand. Minimal viable IK: analytical 2-bone solver (the standard for arm + leg rigs), pole target, FK ↔ IK switch with bake-back.

Scope

• New singleton IKChainController (src/IKChainController.{h,cpp}).
• 2-bone analytical IK (the cheap, fast, joint-limited version every character rig uses):
  • Chain: 3 bones (e.g. shoulder → elbow → hand). Last bone is the effector.
  • Target: a scene node (auto-created with a visible viewport handle) that the effector tries to reach.
  • Pole target: a scene node controlling the middle bone's rotation plane (e.g. elbow direction).
  • Joint limits: per-bone min/max rotation per axis (optional; default off).
• FK ↔ IK switch:
  • Per-chain iKWeight parameter 0..1.
  • At 0: pure FK — the chain's bone TRS animation drives motion.
  • At 1: pure IK — the chain ignores its own animation tracks and solves toward the target.
  • Intermediate: linear blend.
  • Bake IK → FK: convert IK-driven motion into per-bone FK keyframes for export (engines that don't run IK at runtime — i.e. most game engines — need the baked version).
• GUI:
  • "Create IK Chain" button when the user has selected a 3-bone chain. Prompts for target + pole target placement (auto-creates handles at sensible defaults).
  • IK chains listed in a new "IK" inspector subsection per entity.
  • Edit / delete / rename chains.
• Live solve: the IK runs in the same per-frame evaluation step that animation playback uses. Performance: 1–10 chains is the realistic v1 target; profile and document beyond that.
• Round-trip:
  • IK metadata stored in the project file + glTF extras block (for round-trip via QtMeshEditor; not standardized).
  • On export, default behaviour is bake IK to FK for engine compatibility, with an opt-out for users who want to keep the IK metadata round-trippable inside QtMeshEditor.
• CCD / FABRIK are explicitly not in this slice — 2-bone analytical covers the canonical arm + leg case; longer chains can be added in a follow-up.

Acceptance Criteria

• Create a 2-bone IK chain on a fixture arm rig; move the target → the chain solves to reach it.
• Pole target controls the elbow direction correctly.
• FK ↔ IK switch produces expected blend at intermediate weights.
• Bake-IK-to-FK produces per-bone keyframes that play back identically to the IK-driven motion when re-imported with IK off.
• glTF round-trip preserves IK metadata when "keep IK" is on; bakes to FK when "bake on export" is on (default).
• All operations undoable.
• Sentry breadcrumbs scene.skel.ik.*.
• Headless-CI tests cover the 2-bone solver math + bake.

Effort

~12 days. The schedule risk is integrating per-frame solve into the existing animation evaluation without performance regression.