Crossbow IK: aim at a changing target height

Updated October 7, 2026. This preview adds programmatic pose processing to the skeletal ECS animation workflow. The crossbow example adjusts both arms and the weapon's pitch during Attack without needing a separate animation for each target height.

Try the included comparison

1. Import Demos from ECSAnimator's Samples in Package Manager.
2. Run Tools > ECSAnimator > Demos > Use Demo Render Settings.
3. Open 14_TwoBoneIK/Scenes/14_TwoBoneIK.unity and enter Play.
4. Blue plays the original animation. Red adds two arm chains and foregrip following. Leave Auto attack enabled and watch the target change height.
5. Disable Auto target, then change Target elevation to compare low, level and high targets. Toggle Enable IK or change IK strength to compare against the original pose.

The supplied scene uses a yellow target. The October 7 promotional recording uses a red target marker for readability; this is a presentation-only color change. The muzzle ray comes from the committed ECS attachment pose, so it displays the resulting weapon direction.

What changes, and what stays animated

Target height and forward distance determine vertical aim in the character-root YZ plane. Pitch rotates about the horizontal root X axis. Sideways target movement does not turn the character. Body heading, waist and legs retain the source animation; this sample does not bend the waist to aim.

The default pitch limit is +/-45 degrees. Targets beyond it demonstrate clamping: the weapon holds its permitted angle and may not point exactly at the target. The right arm positions the weapon, then the left hand follows the solved foregrip. Limb segment lengths remain fixed; unreachable hand targets are clamped without stretching.

Correction fades in with Attack and out after it. At zero strength the original animation is restored. At partial strength, aim and hand placement are deliberately only partially corrected. Attack Speed defaults to 0.35 to make the short source shot easy to observe; it is an actual state-speed parameter.

Integrate with your gameplay

Enable Require Pose Processing during conversion to produce LocalResolve data. Check prepared.SupportsPoseProcessing, resolve the current character's exported bone indices, and supply root-space targets, hints, rotations and weights from your gameplay.

The sample registers a static Burst CharacterPoseProcessor and unmanaged per-character data. Its CrossbowPoseProcessor solves the right arm, reads the corrected hand/foregrip, then solves the left arm. It runs after Animator blending and before skinning and attachment output. Other characters can omit the processor entirely.

See the sample README and source for controls and calibrated weapon markers, and the pose-processing API for ownership, scheduling, failure behavior and a minimal callback. The sample's stable Resources key still contains 21_TwoBoneIK; the visible scene is now numbered 14.

Support boundaries

• This is an explicit ECS API. It does not import or execute Unity Animator IK Pass, OnAnimatorIK, Foot IK or Animation Rigging components.
• Automatic terrain adaptation, whole-body IK and runtime PlayableGraphs are not supplied.
• Two-bone chains must be direct Root -> Mid -> Tip hierarchies. Compact MatrixInline2 resources cannot be promoted to LocalResolve at runtime.
• Animation LOD also controls pose-processing frequency. Callback data/streams are temporary; do not retain pointers, call managed code, change ECS structure or read another character's current-frame pose inside the callback.
• Algorithms and dispatch have a cost. Demonstration recordings and fixed capture rates are not performance benchmarks or universal platform/rig qualification.

The preview package retains version 0.1.0-preview.1; use the delivery date and archive hash to distinguish it from earlier builds. Existing imported Samples are project-owned copies and must be refreshed separately after preserving local changes.