Animation Components

AnimatorComponent

Controls animation playback on an entity. Supports single clip playback and a locomotion state machine that blends between idle, walk, run, jump, and other movement states based on character velocity.

Core Properties

Property	Type	Default	Description
controller_mode	Enum	clip	Mode: clip (single clip) or locomotion (state machine)
default_clip_guid	Guid	null	GUID of default animation clip
play_on_start	Bool	true	Auto-play when entering play mode
loop	Bool	true	Loop the animation
speed	Float	1.0	Playback speed multiplier (min: 0)
apply_root_motion	Bool	false	Apply root bone motion to entity transform

Locomotion Properties

When controller_mode is locomotion, these properties control the state machine:

Property	Type	Default	Description
locomotion_enabled	Bool	false	Enable locomotion blending
wall_locomotion_enabled	Bool	false	Enable wall-run/slide states
walk_speed_threshold	Float	0.15	Speed threshold for idle → walk transition
run_speed_threshold	Float	3.0	Speed threshold for walk → run transition
blend_smoothing	Float	12	Blend interpolation speed

State Clip Assignments

Each locomotion state maps to an animation clip by name:

Property	State
state_clip_idle	Standing still
state_clip_walk	Walking
state_clip_run	Running
state_clip_jump_start	Jump takeoff
state_clip_in_air_up	Rising in air
state_clip_in_air_down	Falling
state_clip_land	Landing
state_clip_wall_run	Wall running
state_clip_wall_slide	Wall sliding
state_clip_crouch_walk	Crouching movement
state_clip_slide_steep	Sliding on steep slope

Scripting: Animation Control

void OnUpdate(ScriptContext* ctx) {
    // Play a specific clip
    ctx->play_animation_clip(ctx, ctx->self, "<clip-guid>", true);

    // Set animation speed
    ctx->set_animation_speed(ctx, ctx->self, 1.5f);

    // Set locomotion parameters
    ctx->set_animation_param_float(ctx, ctx->self, "speed", 5.0f);
    ctx->set_animation_param_bool(ctx, ctx->self, "grounded", true);

    // Query current state
    const char* state = ctx->get_animation_state(ctx, ctx->self);

    // Stop animation
    ctx->stop_animation(ctx, ctx->self);
}

---

JointComponent

Connects two entities with a physics joint. Supports fixed, hinge, and distance joint types.

Property	Type	Default	Description
joint_type	Enum	fixed	Type: fixed, hinge, or distance
other_entity	String	""	Name of the other entity to connect to
anchor1	Vec3	{x:0, y:0, z:0}	Anchor point on this entity (local space)
anchor2	Vec3	{x:0, y:0, z:0}	Anchor point on the other entity (local space)
break_force	Float	0	Force threshold to break the joint (0 = unbreakable)
break_torque	Float	0	Torque threshold to break the joint (0 = unbreakable)

Hinge Joint Parameters

Property	Default	Description
hinge_params.axis	{x:0, y:1, z:0}	Rotation axis
hinge_params.has_limits	false	Whether rotation is limited
hinge_params.min_angle	-π	Minimum angle in radians
hinge_params.max_angle	π	Maximum angle in radians

Distance Joint Parameters

Property	Default	Description
distance_params.min_distance	-1	Minimum distance (-1 = no limit)
distance_params.max_distance	-1	Maximum distance (-1 = no limit)

Example: Door Hinge

{
  "op": "AddComponent",
  "params": {
    "entity_name": "Door",
    "component_type": "JointComponent",
    "data": {
      "joint_type": "hinge",
      "other_entity": "DoorFrame",
      "anchor1": { "x": -0.5, "y": 0, "z": 0 },
      "anchor2": { "x": 0.5, "y": 0, "z": 0 },
      "hinge_params": {
        "axis": { "x": 0, "y": 1, "z": 0 },
        "has_limits": true,
        "min_angle": 0,
        "max_angle": 1.57
      }
    }
  }
}