🔸 Animation system

Overview

Gameplay Animation Controller is the main animation component in Sci-Fi FPS Pack. It combines the character’s Animator output with weapon poses and action animations, then applies procedural motion and IK. For example, your Animator can keep playing a walking animation while the upper body reloads a rifle. The reload clip controls how much of the walking motion remains visible in each body part. Procedural features then adjust the weapon and hands for aiming, recoil, and sway.

Gameplay Animation Controller

Add GameplayAnimationController to the same GameObject as the character’s Animator. Character setup configures it for you.

General settings

Weight controls the overall animation effect, from 0 to 1. Use 1 for normal playback. Reducing it blends the layered result toward the original Animator pose.
Base Pose is the reference clip used to calculate the difference between locomotion and the reference pose. It is not the current weapon’s idle animation.
Procedural Asset contains the active weapon pose, optional overlay Animator Controller, and procedural features. Equipping an item changes this reference to the asset assigned to that item’s view.

The Skeleton tab maps the character’s bones. The Procedural tab lets you inspect the features in the active procedural asset. The Override tab contains retargeted replacements for the pack animations.

Animation inputs

Your gameplay controller updates these public fields. The procedural features read them to animate the character.

Field	What to pass
`moveInput`	Movement input as a `Vector2`: sideways movement on X and forward movement on Y.
`lookInput`	View angles; the example controller stores vertical aim in Y.
`deltaLookInput`	The current look delta, used for mouse sway and turning.
`leanInput`	The desired lean angle in degrees.
`isAiming`	Whether the character is aiming down sights.
`isUsingItem`	Whether the use button is held, as tracked by the example controller.

See Character for the input callbacks and movement implementation.

Character skeleton

The controller stores its skeleton in GameplaySkeleton. The skeleton records the character hierarchy and identifies which transforms represent the pelvis, spine, hands, fingers, feet, weapon, and IK targets.

Bone groups

Group	Bones and purpose
Lower Body	Pelvis, thighs, calves, feet, and toes. Used for lower-body blending and leg IK.
Spine	Up to three spine bones. Used for upper-body blending and procedural aim rotation.
Neck	Neck and head. These bones share the spine’s blending weights.
Arms	Upper arm, lower arm, and hand on each side. Used for arm blending and two-bone IK.
Fingers	Thumb and finger joints. Each hand uses its arm’s local blending weight.
IK / Hands	Hand targets that procedural features move before the arms are solved.
IK / Feet	Foot targets used by leg IK.
IK / Weapon	The weapon attachment transform and a separate transform for additive weapon motion.

The weapon prefab is attached to Weapon Bone. Procedural weapon motion moves this transform and the hand targets so the hands continue following the weapon. Bone fields use GameplayTransform, which can store a direct Transform reference or a bone name. A direct reference resolves to that Transform; a name resolves through the controller’s skeleton. Keep names unambiguous when using name-based references.

Rig presets and automatic mapping

Choose Rig Preset in the Skeleton tab to apply the naming pattern for your character. The available presets are Humanoid, Mixamo, Synty, Unreal Engine, Character Creator, and Human (Generic). Humanoid reads standard bones from the Animator’s Avatar. The other presets match bone names. Auto Map Bones rebuilds the skeleton mapping and detects a matching preset. Mapping also creates the helper transforms used for the camera, weapon, and IK when needed. After mapping, inspect the references for your character. If a bone is missing, expand the skeleton in the Hierarchy and drag its Transform into the corresponding field. An arms-only character will not have leg bones; check the groups that exist on your model.

How mapping affects retargeting

Retargeting needs to know which source and target bones perform the same role. A correct mapping lets it transfer arm and finger motion to a character with different bone names and proportions. An incorrect hand or forearm reference can produce a twisted grip even when the animation itself is valid. Check the mapping before adjusting retargeting offsets. Then use a target reference pose to correct differences in shoulder, wrist, and finger orientation. Follow Retarget the animations to preview and bake the result.

Blending locomotion and weapon animations

The character Animator normally handles locomotion. An overlay is the weapon pose or action animation that is blended with that locomotion. The controller first captures the Animator pose, combines it with the overlay, and then applies any Full Body action. Procedural features and IK run afterward. This allows you to aim or apply recoil while an action animation is playing.

Body weights

The current system has four groups of blending weights:

lowerBody controls the pelvis and legs.
spine controls the spine, neck, and head.
rightArm controls the right arm and the local blending of its fingers.
leftArm controls the left arm and the local blending of its fingers.

Each group has these properties:

Property	What it changes
Base Weight	Blends between locomotion and the overlay. `0` keeps locomotion; `1` uses the overlay with the selected additive motion.
Additive Weight	Adds locomotion motion relative to the Base Pose onto the overlay. `0` removes that added motion; `1` keeps it at full strength.
Local Weight	Blends toward the overlay in each bone’s parent space. `1` preserves the local pose authored in the overlay, which is useful for hand and finger poses.

For a reload that must keep the arms in the authored position, start with arm Base Weight at 1 and Additive Weight at 0. Increase additive motion only if you want movement from locomotion to affect the reload. Fingers use local blending only. Their weight comes from rightArm.localWeight or leftArm.localWeight; they do not have separate finger-weight fields.

Custom curve properties

Blending weights are float curves stored on the Animation Clip. Each animation can therefore define its own blending, and a curve can change that blending during the action.

Select the Animation Clip in the Project window.
Choose Assets ▸ Edit Gameplay Curve Properties.
Use + to add a property. Set a constant value or right-click the field to switch to Curve Mode.
Use Value Mode to return to a constant value, or - to remove the property.
Preview the animation while moving the character.

For example, spine.baseWeight controls the spine’s overlay influence. rightArm.localWeight controls the right arm’s local blend, including its fingers. These are Gameplay Framework properties; CAS curve names belong to a different system. Weapon Bone Weight controls hand-relative weapon alignment. Positive values blend toward the right hand, negative values toward the left hand, and 0 keeps the animated weapon transform. Animate this value when an action changes which hand should guide the weapon. The curve editor also finds fields marked with AnimatedProperty on item views. The charge weapon’s charge field is one example: an item animation can animate the charge effect while the character animation controls body blending.

Gameplay Animation Asset

A GameplayAnimationAsset is a ScriptableObject that stores a clip and the settings used to play it. Select an Animation Clip or FBX, then choose Assets ▸ Create ▸ KINEMATION ▸ Gameplay Framework ▸ Animation Asset to create an asset beside it.

Setting	Description
Clip	The Animation Clip to play.
Slot	Where the animation is applied: Overlay or Full Body.
Mask	An Avatar Mask that limits the bones affected by the action. Include custom weapon and IK transforms when the animation needs them.
Blend Time	Blend-in time, blend-out time, and easing. Times are in seconds.
Play Rate	Playback speed multiplier. `1` is normal speed; `2` plays twice as fast.
Is Additive	Adds the animation’s motion to the pose below it.
Auto Blend Out	Starts blending the action out near the end of playback. Disable it when you need to stop the action explicitly.

Use Modify Avatar Mask when a mask is missing a custom transform.

Animation slots

Overlay plays an action over the current weapon pose or overlay controller. Use it for weapon actions such as draw, reload, inspect, and fire. The body curves determine how that result combines with locomotion. Full Body plays after layered blending. Use it for an action that should take over the character, such as a full-body interaction. Its mask still determines which transforms are affected, and procedural animation runs afterward. A GameplayProceduralAsset sets the idle overlay through Default Idle Pose. Assign Overlay Controller when the overlay needs states, transitions, or blend trees. If both are assigned, the controller drives overlay playback while the idle pose remains the reference pose. Matching float, integer, and boolean parameters are copied from the character Animator to the overlay controller. Triggers are not copied. Use HasOverlayAnimator before accessing OverlayAnimator to set an overlay trigger from code.

Play animations from code

Call these methods on GameplayAnimationController:

public bool PlayAnimation(GameplayAnimationAsset newAnimation, float startTime = 0f);
public bool StopAnimation(GameplayAnimationAsset animation);

Attach this example to your character, assign the controller and action asset in the Inspector, then call PlayAction from your gameplay code:

using KINEMATION.Shared.GameplayFramework.Scripts.Runtime.Animation;
using UnityEngine;

public class CharacterAction : MonoBehaviour
{
    [SerializeField] private GameplayAnimationController animationController;
    [SerializeField] private GameplayAnimationAsset action;

    public void PlayAction()
    {
        if (animationController.HasActiveAction) return;
        if (!animationController.PlayAnimation(action)) return;

        float duration = animationController.ResolveAnimationAsset(action).GetPlayLength();
        animationController.StartAction(duration, duration > 0f);
    }

    public void StopAction()
    {
        animationController.StopAnimation(action);
        animationController.StopAction();
    }
}

PlayAnimation returns false if the graph is not ready or the asset is invalid. GetPlayLength() returns the clip length divided by Play Rate; it returns 0 for a missing clip or zero Play Rate. StartAction sets HasActiveAction. With a timer, it clears the flag after the duration; without one, your code calls StopAction when finished. The flag lets the example controller prevent conflicting actions. Playing an animation does not set the flag automatically.

Character and weapon animation pairs

GameplayCharacterItemClip stores a character animation asset, an item animation asset, and an optional sound. GameplayItemView.PlayCharacterItemAnimation starts both animations together and plays the sound. Its GetLength() method returns the longer of the two animation durations. See Item View for the item-side setup.

Retargeted animation overrides

The Override tab stores GameplayAnimationOverride assets. Each asset maps original animations, clips, or Animator Controllers to retargeted replacements. The controller checks the list in order and uses the first matching replacement. If none exists, it uses the original asset. Pass the original pack animation to PlayAnimation; the controller resolves the replacement for your character. You do not need to replace every character animation reference on each weapon prefab after retargeting.

​Overview

​Gameplay Animation Controller

​General settings

​Animation inputs

​Character skeleton

​Bone groups

​Rig presets and automatic mapping

​How mapping affects retargeting

​Blending locomotion and weapon animations

​Body weights

​Custom curve properties

​Gameplay Animation Asset

​Animation slots

​Play animations from code

​Character and weapon animation pairs

​Retargeted animation overrides