Character Controller

Movement

set_character_velocity

Set the character's horizontal movement intent. The CharacterController uses this to move the capsule, handling slopes, stairs, and collisions automatically.

bool set_character_velocity(ScriptContext* ctx, EntityHandle entity, const float velocity[3]);

Parameter	Type	Description
entity	EntityHandle	Entity with CharacterController
velocity	const float[3]	Desired horizontal velocity [vx, vy, vz] in world space

get_character_velocity

bool get_character_velocity(ScriptContext* ctx, EntityHandle entity, float out_velocity[3]);

---

Jumping

character_jump

Request a jump. Only works if the character is grounded (or within coyote time).

bool character_jump(ScriptContext* ctx, EntityHandle entity);

set_character_jump_held

Set the jump button held state for variable-height jumps. Releasing early applies the jump_cut_multiplier to reduce upward velocity.

bool set_character_jump_held(ScriptContext* ctx, EntityHandle entity, bool held);

---

Ground State

is_character_grounded

Check if the character is standing on ground.

bool is_character_grounded(ScriptContext* ctx, EntityHandle entity, bool* out_grounded);

get_character_ground_state

Get the detailed ground state.

bool get_character_ground_state(ScriptContext* ctx, EntityHandle entity, int* out_state);

Ground states:

Value	State	Description
0	OnGround	Standing on walkable surface
1	OnSteepGround	On a slope exceeding max_slope_angle
2	NotSupported	No surface contact
3	InAir	Fully airborne

---

Crouching

set_character_crouch

Set the crouch intent. Resizes the capsule to crouch_height and applies crouch_speed_multiplier.

bool set_character_crouch(ScriptContext* ctx, EntityHandle entity, bool crouch);

is_character_crouching

bool is_character_crouching(ScriptContext* ctx, EntityHandle entity, bool* out_crouching);

---

Sprinting

set_character_sprint

Set the sprint intent. Multiplies movement speed by sprint_multiplier.

bool set_character_sprint(ScriptContext* ctx, EntityHandle entity, bool sprint);

---

Mesh Visibility

set_mesh_visible

Show or hide an entity's MeshComponent. Useful for hiding the player model in first-person view.

bool set_mesh_visible(ScriptContext* ctx, EntityHandle entity, bool visible);

get_mesh_visible

bool get_mesh_visible(ScriptContext* ctx, EntityHandle entity, bool* out_visible);

---

Example: Complete First-Person Controller

static float yaw = 0, pitch = 0;

void OnStart(ScriptContext* ctx) {
    ctx->set_cursor_captured(ctx, true);
    ctx->set_mesh_visible(ctx, ctx->self, false); // Hide in FPS
}

void OnUpdate(ScriptContext* ctx) {
    float dt = ctx->get_delta_time();

    // Mouse look
    float dx, dy;
    ctx->get_mouse_delta(ctx, &dx, &dy);
    yaw -= dx * 0.003f;
    pitch -= dy * 0.003f;
    if (pitch > 1.5f) pitch = 1.5f;
    if (pitch < -1.5f) pitch = -1.5f;

    float cy = cosf(yaw * 0.5f), sy = sinf(yaw * 0.5f);
    float cp = cosf(pitch * 0.5f), sp = sinf(pitch * 0.5f);
    float rot[4] = { cy*sp, sy*cp, -sy*sp, cy*cp };
    ctx->set_rotation(ctx->self, rot);

    // WASD movement (rotated by yaw)
    float move_x = 0, move_z = 0;
    if (ctx->is_key_down(ctx, 87)) move_z -= 1; // W
    if (ctx->is_key_down(ctx, 83)) move_z += 1; // S
    if (ctx->is_key_down(ctx, 65)) move_x -= 1; // A
    if (ctx->is_key_down(ctx, 68)) move_x += 1; // D

    // Rotate movement by yaw
    float cos_yaw = cosf(yaw), sin_yaw = sinf(yaw);
    float vel[3] = {
        (move_x * cos_yaw - move_z * sin_yaw) * 5.0f,
        0,
        (move_x * sin_yaw + move_z * cos_yaw) * 5.0f
    };
    ctx->set_character_velocity(ctx, ctx->self, vel);

    // Jump
    if (ctx->is_key_pressed(ctx, 32))
        ctx->character_jump(ctx, ctx->self);
    ctx->set_character_jump_held(ctx, ctx->self,
        ctx->is_key_down(ctx, 32));

    // Sprint / Crouch
    ctx->set_character_sprint(ctx, ctx->self,
        ctx->is_key_down(ctx, 340)); // Left Shift
    ctx->set_character_crouch(ctx, ctx->self,
        ctx->is_key_down(ctx, 341)); // Left Ctrl
}