Animation

Clip Playback

play_animation_clip

Play an animation clip by GUID string.

bool play_animation_clip(ScriptContext* ctx, EntityHandle entity,
                         const char* clip_guid, bool loop);

Parameter	Type	Description
entity	EntityHandle	Entity with AnimatorComponent
clip_guid	const char*	Animation clip GUID as string
loop	bool	true to loop the clip continuously

stop_animation

Stop all animation playback on an entity.

bool stop_animation(ScriptContext* ctx, EntityHandle entity);

set_animation_speed

Set the playback speed multiplier (clamped to >= 0).

bool set_animation_speed(ScriptContext* ctx, EntityHandle entity, float speed);

Value	Effect
0.0	Paused
0.5	Half speed
1.0	Normal speed
2.0	Double speed

---

Parameters

Animation parameters drive state machine transitions in locomotion mode.

set_animation_param_float

bool set_animation_param_float(ScriptContext* ctx, EntityHandle entity,
                               const char* param_name, float value);

set_animation_param_bool

bool set_animation_param_bool(ScriptContext* ctx, EntityHandle entity,
                              const char* param_name, bool value);

Common parameters:

Parameter	Type	Description
"speed"	float	Movement speed for locomotion blending
"grounded"	bool	Whether character is on ground
"jumping"	bool	Jump state trigger

---

State Query

get_animation_state

Get the name of the current animation state.

const char* get_animation_state(ScriptContext* ctx, EntityHandle entity);

Returns the state name (thread-local buffer), or nullptr if the entity has no AnimatorComponent.

Possible states in locomotion mode: "idle", "walk", "run", "jump_start", "in_air_up", "in_air_down", "land", "wall_run", "wall_slide", "crouch_walk", "slide_steep"

---

Example: Animation-Driven Character

void OnUpdate(ScriptContext* ctx) {
    // Get character velocity to drive animation
    float vel[3];
    ctx->get_character_velocity(ctx, ctx->self, vel);
    float speed = sqrtf(vel[0]*vel[0] + vel[2]*vel[2]);

    // Set locomotion parameters
    ctx->set_animation_param_float(ctx, ctx->self, "speed", speed);

    bool grounded;
    ctx->is_character_grounded(ctx, ctx->self, &grounded);
    ctx->set_animation_param_bool(ctx, ctx->self, "grounded", grounded);

    // Query current state for sound effects
    const char* state = ctx->get_animation_state(ctx, ctx->self);
    if (state && strcmp(state, "land") == 0) {
        // Play landing sound
    }
}

Example: One-Shot Animation

static bool attack_playing = false;

void OnUpdate(ScriptContext* ctx) {
    if (ctx->is_mouse_button_down(ctx, 0) && !attack_playing) {
        ctx->play_animation_clip(ctx, ctx->self,
            "attack-clip-guid-here", false); // false = don't loop
        ctx->set_animation_speed(ctx, ctx->self, 1.5f);
        attack_playing = true;
    }

    // Check if attack finished
    const char* state = ctx->get_animation_state(ctx, ctx->self);
    if (attack_playing && state && strcmp(state, "idle") == 0) {
        attack_playing = false;
    }
}