Advanced Animation

var controller = AnimationController;
if (controller != null)
{
    // Use the API ...
}

var p = controller.Parameters;

p.SetFloat("SpeedAbs", speedValue);
p.SetBool("Death", isDead);
p.SetVector3("LookDirection", direction);
p.SetString("GaitState", "Run");

// Generic set (auto-dispatches by type)
p.SetParameter("CustomValue", 3.14f);

float speed = p.GetFloat("SpeedAbs");        // Returns 0 if not found
bool dead = p.GetBool("Death");              // Returns false if not found
Vector3 dir = p.GetVector3("LookDirection"); // Returns Zero if not found

// Safe read
if (p.TryGetFloat("SpeedAbs", out float speed)) { ... }

p.IsDirty;      // Whether any parameter was modified this frame
p.ClearDirty(); // Clear the dirty flag
p.SetDirty();   // Force mark as dirty

// Play the bite animation on the UpperBodyAction layer
bool success = controller.PlayAnimation(
    layerName: "UpperBodyAction",
    animationNameOrAlias: "bite",
    loop: true,
    blendDuration: 0.3f
);

// Play an animation from an external file
controller.PlayExternalAnimation(
    layerName: "Base",
    filePath: "Models/Extra/SpecialAnims.glb",
    animationName: "Dance",
    loop: false,
    blendDuration: 0.5f
);

// Release a specific layer
controller.ReleaseManualControl("UpperBodyAction");

// Release all layers
controller.ReleaseManualControl();

if (controller.IsManualControl("UpperBodyAction"))
{
    // Currently in manual control
}

// Begin attack
public void StartAttack()
{
    controller.PlayAnimation("UpperBodyAction", "bite", loop: true);
}

// Detect attack hit in animation event callback
private void HandleEvent(AnimationEvent evt)
{
    if (evt.Name == "AttackHit")
    {
        PerformDamage();
    }
}

// End attack
public void EndAttack()
{
    controller.ReleaseManualControl("UpperBodyAction");
}

controller.StopAnimation("UpperBodyAction");
// The layer stops playing but remains in manual control mode.
// Call ReleaseManualControl to restore state rules.

public override void OnModelLoaded()
{
    base.OnModelLoaded();
    if (AnimationController != null)
    {
        AnimationController.OnAnimationEvent += OnAnimationEvent;
    }
}

private void OnAnimationEvent(AnimationEvent evt)
{
    switch (evt.Name)
    {
        case "AttackHit":
            // Perform attack judgment at the time point defined in the animation
            PerformAttack();
            break;
        case "PlaySound":
            // Play a sound effect
            SubsystemAudio.PlaySound((string)evt.Parameter, ...);
            break;
        case "JumpLandRecoveryComplete":
            // Jump recovery finished
            m_jumpState = JumpState.None;
            break;
    }
}

// onComplete type="trigger" fires through OnAnimationEvent
private void OnAnimationEvent(AnimationEvent evt)
{
    if (evt.Name == "BarkComplete") { ... }
}

public override void OnModelLoaded()
{
    base.OnModelLoaded();
    if (AnimationController != null)
    {
        // Register an IK chain from the root up to the head bone, using the SingleBoneIK algorithm
        AnimationController.RegisterAndBuildIKChain(
            name: "Head",
            endBoneName: "b_Head_05",
            algorithmName: "SingleBoneIK",
            maxChainLength: 3
        );
    }
}

public override void SyncAnimationParameters()
{
    base.SyncAnimationParameters();

    var controller = AnimationController;
    if (controller == null) return;

    // Aim constraint: orient the head toward a target direction
    Vector3 aimDirection = CalculateAimDirection();
    float weight = CalculateIKWeight(); // 0–1, typically falls off with distance
    controller.SetIKAim("Head", aimDirection, weight);

    // Position constraint: move a bone to a target position
    // controller.SetIKTarget("Hand", targetPosition, weight);
}

controller.ClearIKTarget("Head");

var target = IKTarget.CombinedTarget(
    position: targetPos,       // Target position
    aimDirection: aimDir,      // Target direction
    positionWeight: 1.0f,      // Position weight
    aimWeight: 0.8f            // Direction weight
);
target.Hint = elbowHintDir;        // Bend hint direction (e.g. elbow direction)
target.PositionSmoothTime = 0.1f;  // Position smoothing time
target.AimSmoothTime = 0.15f;      // Direction smoothing time
controller.SetIKTarget("Hand", target);

IKChain chain = controller.GetIKChain("Head");
chain.SetJointLimit("Neck", JointLimit.FromDegrees(
    minDeg: new Vector3(-40, -30, -20),
    maxDeg: new Vector3(40, 30, 20),
    EulerRotationOrder.YXZ
));

chain.UnreachableStrategy = UnreachableStrategy.ExtendTowardTarget;

public class ComponentFoxStareBehavior : ComponentStareBehavior
{
    private const string HeadIKChain = "Head";

    public override void OnModelLoaded()
    {
        base.OnModelLoaded();
        var controller = ComponentCreatureModel?.AnimationController;
        if (controller != null)
        {
            controller.RegisterAndBuildIKChain(
                HeadIKChain,
                "b_Head_05",
                "SingleBoneIK",
                maxChainLength: 3
            );
        }
    }

    public override void Update(float dt)
    {
        base.Update(dt);
        var controller = ComponentCreatureModel?.AnimationController;
        if (controller == null || m_stareTarget == null) return;

        // Calculate direction toward target
        Vector3 modelDir = WorldToModelDirection(m_stareTarget.Value);

        // Weight falls off with distance
        float dist = Vector3.Distance(Position, m_stareTarget.Value);
        float weight = MathHelper.Clamp(1.0f - (dist - MinRange) / (MaxRange - MinRange), 0.3f, 1.0f);

        controller.SetIKAim(HeadIKChain, modelDir, weight);
    }
}

// Associate in OnModelLoaded
controller.Velocity = ref componentBody.Velocity;
controller.EntityRotation = componentBody.Rotation;
controller.SetCollisionBox = (size) => componentBody.BoxSize = size;
controller.DefaultCollisionSize = originalBoxSize;

// Get the average velocity over the entire animation
Vector3 avgVel = cache.GetAverageVelocity();

// Get the average velocity over a specified phase range
Vector3 rangeVel = cache.GetAverageVelocity(0.0f, 0.3f);

// Get peak velocity
Vector3 peakVel = cache.GetPeakVelocity();

// Get total displacement
Vector3 totalDisp = cache.GetTotalTranslation();

// Enable Blend mode
controller.SetRootMotionConfig(new RootMotionConfig
{
    SourceBone = "Hips",
    Translation = new TranslationConfig
    {
        Mode = TranslationMode.Blend,
        BlendMethod = BlendMethod.SmoothDamp,
        SmoothTime = 0.3f
    }
});

// Disable
controller.SetRootMotionConfig(null);

var prop = DynamicProperty<float>.FromExpression("[SpeedAbs] * 0.5");
float value = prop.GetValue(controller.Parameters, controller.ExpressionEvaluator);

// Set bone remapping on a ClipAnimationSource
var boneRemapping = new Dictionary<string, string>
{
    { "Hand_L", "Hand_R" },
    { "Arm_L", "Arm_R" },
    { "Leg_L", "Leg_R" }
};

// Create programmatically
var blendSpace = new AnimationBlendSpaceDefinition
{
    Name = "Movement",
    ParameterName = "SpeedNorm",
    SyncTime = true,
    Samples = new[]
    {
        new AnimationBlendSample { Value = 0.0f, AnimationName = "Idle" },
        new AnimationBlendSample { Value = 0.5f, AnimationName = "Walk" },
        new AnimationBlendSample { Value = 1.0f, AnimationName = "Run" }
    }
};

var blendSpace2D = new AnimationBlendSpaceDefinition2D
{
    ParameterNameX = "MoveX",
    ParameterNameY = "MoveY",
    Samples = new[]
    {
        new AnimationBlendSample2D { ValueX = 0,  ValueY = 0,  AnimationName = "Idle" },
        new AnimationBlendSample2D { ValueX = 1,  ValueY = 0,  AnimationName = "WalkFwd" },
        new AnimationBlendSample2D { ValueX = -1, ValueY = 0,  AnimationName = "WalkBack" },
        new AnimationBlendSample2D { ValueX = 0,  ValueY = 1,  AnimationName = "WalkLeft" },
        new AnimationBlendSample2D { ValueX = 0,  ValueY = -1, AnimationName = "WalkRight" }
    }
};

public interface IAnimationDriver
{
    string Name { get; }
    AnimationBlendMode BlendMode { get; }
    string[] TargetBones { get; }
    void Update(float deltaTime, AnimationParameters parameters);
    void SampleTransforms(Matrix?[] boneTransforms, Model model);
}

public class CustomHeadBobDriver : IAnimationDriver
{
    public string Name => "CustomHeadBob";
    public AnimationBlendMode BlendMode => AnimationBlendMode.Override;
    public string[] TargetBones => ["Head"];

    private float m_time;

    public void Update(float deltaTime, AnimationParameters parameters)
    {
        m_time += deltaTime;
    }

    public void SampleTransforms(Matrix?[] boneTransforms, Model model)
    {
        ModelBone head = model.FindBone("Head");
        if (head == null) return;

        float bob = MathF.Sin(m_time * 5f) * 0.05f;
        boneTransforms[head.Index] = Matrix.CreateTranslation(0, bob, 0);
    }
}

// Register the driver type
AnimationDriverManager.Register<CustomHeadBobDriver>("CustomHeadBob");

// Use it in code
var driver = new CustomHeadBobDriver();
controller.SetDriver("Base", driver);