14 - Crossbow Two-Bone IK

Open Scenes/14_TwoBoneIK.unity and enter Play. Blue is the original animation; red uses two analytic arm chains to pitch the crossbow up and down while attacking. Body heading, waist and legs retain their animation. The yellow target moves automatically. The muzzle ray is read from the committed ECS attachment pose, not drawn from the requested aim angle.

Controls

• Enable IK switches the correction on/off. Weight fades in/out with the actual Attack state.
• Auto attack repeats the supplied crossbow attack. Trigger attack requests it manually.
• Auto target sweeps beyond both limits to show clamping. Turn it off and use the Target elevation slider, or move Aim Target in Scene view during Play. Gameplay can supply another Transform position.
• IK strength blends between the original pose and the constrained pose. At partial strength the muzzle and left grip are intentionally only partially corrected.
• Inspector Max Aim Angle limits vertical pitch to +/-45 degrees by default. Positive Target elevation aims upward; negative elevation aims downward.
• Inspector Attack Speed uses the real AnimatorState speed parameter; the default 0.35 makes the short source shot easier to observe.

Only target height and forward distance drive vertical aim in the character-root YZ plane. Sideways target movement does not change the aim. This pitch rotates about the horizontal root X axis; it does not rotate the body or waist about Y. Outside the allowed angle the crossbow holds the nearest permitted direction; the ray is not expected to hit that target. The two-bone solver still adjusts the arm joints in 3D to retain the grip. At zero weight, the original animation is restored.

Pose flow and source

Animator/state/layer blending -> business CrossbowPoseProcessor -> bind matrices, GPU transport and attachment observations. Inside the static Burst pipeline: right upper arm/forearm/palm IK and palm pitch -> compute the foregrip from the solved right hand -> left arm IK. The crossbow skin is bound to the right palm, so it follows the solved hand. The solver preserves both segment lengths and clamps unreachable positions without stretching. Elbow hints choose the bend side. The target orbit uses the midpoint of this character's animated shoulders, observed from committed attachment poses; arm IK does not move those anchors. This keeps the grip reachable across the supported pitch range without moving the waist.

The original crossbow model, Idle and Shoot clips are reused. This folder owns a source Prefab, CrossbowAim.controller, conversion preset and prebuilt CrossbowGuard_EntityDesc.asset. The muzzle and foregrip are explicit attachment markers under the right palm. Muzzle direction is calibrated from the authored front and rear stock vertices; the stock is tilted in mesh space, so mesh +Z is not its barrel axis. Inspect these markers when adapting a different weapon.

Load key: ECSAnimator/21_TwoBoneIK/CrossbowGuard/CrossbowGuard_EntityDesc. Parameters: Attack Trigger and PlaybackRate Float. State keys: Base Layer/Idle#0, Base Layer/Attack#1.

The earlier yaw version used Max Waist Angle and WaistPivot. This version removes the waist constraint and uses AimPivot as a fallback before shoulder observations are available. Existing source model, clips, bindings and baked resource are unchanged.

Runtime API and limits

The red character installs the preview CharacterPoseProcessor and its own CharacterPoseProcessorData buffer. CrossbowPoseProcessor.Process uses CharacterPoseStream.TrySolveTwoBone with constraint values inside business data; the demo does not install the legacy root yaw/two-bone components. Targets/rotations/hints use character-root space. Resolve this character's exported bone indices through prepared.RuntimeResource.TryFindAttachment(...).GeometryBoneIndex; never reuse indices from another product. See the post-processing API.

The conversion preset explicitly enables Require Pose Processing to bake LocalResolve data. The real speed parameter controls Attack Speed; it is not the capability switch. Check prepared.SupportsPoseProcessing before installing the processor. Compact MatrixInline2 assets do not contain the required local-pose payload and are not promoted at runtime. Two-bone chains require a direct Root -> Mid -> Tip hierarchy. The business callback runs after raw Animator history is stored, so IK does not accumulate into subsequent animation frames. Skinning and sockets consume the same corrected pose. Animation LOD controls callback frequency and pose.DeltaTime carries the accumulated consumed time.

Blue has no processor. Red skips its callback when correction is inactive. Other characters may use different static Burst functions and unmanaged data, or omit the processor entirely. Do not retain the temporary stream/pointers, call managed logic, alter ECS structure, or depend on another character's current-frame pose inside the callback. Invalid processing blocks the new output without providing a complete rollback of mutable animation/business state. This preview extension has algorithm and dispatch costs; it does not promise zero overhead or a runtime PlayableGraph.

This feature does not execute Unity OnAnimatorIK, Animator IK Pass, Foot IK, Animation Rigging components or automatic terrain adaptation. It does not stretch limbs or add root-motion movement. No Blender installation or extra animation is required to run this sample.