CharacterController:move
methodCharacterController:move(displacement: Vec2 | Vec3, dt?: number) -> physics.CharacterMoveSweep the character by displacement and return the movement actually allowed plus the grounded/slope results and the surfaces hit. Does NOT move the body — apply it yourself (body.pos = body.pos + result.translation). displacement and translation are in the frame of the body's pos: relative to its parent for a nested body, so a character inside a scaled or turned group moves in the group's units and directions; up and the collision points and normals stay in world space. displacement is the full movement you want this frame, each component at most 1000000, and must already include your own gravity·dt and jump velocity; the controller adds no gravity. For correct stair-climbing under gravity, you may move horizontal and vertical displacement in separate calls. dt (seconds, > 0) is the solver timestep used only for moving-platform carry; it defaults to the fixed timestep and does NOT scale displacement (you already scaled that by your frame time).
local floor =
canvas:rect({ pos = vec2(-200, -20), width = 400, height = 20 })
floor:add_body({ type = "static" })
-- New bodies are found once the simulation has stepped.
datumhue.time.sleep(0.1)
-- Walk 50 right and fall 30: the floor takes the fall.
local move = controller:move(vec2(50, -30), 1 / 60)
print(move.translation.x, move.grounded) --> 50.0 true
-- move only measures; moving the body is up to you.
hero.pos = hero.pos + move.translationreturns physics.CharacterMove record 4 keys
| Key | Type | Description |
|---|---|---|
| translation | Vec3 | The movement to apply this frame, in the frame of the body's pos (relative to its parent for a nested body) — the body is not moved; set body.pos = body.pos + translation. |
| grounded | boolean | Standing on ground after applying translation. False while the move commanded upward motion (a jump in progress), so a launching jump is never reported grounded. |
| sliding_down_slope | boolean | The character was let slide down a too-steep slope this frame. |
| collisions | physics.CharacterCollision[] | Surfaces hit during the slide, in application order; empty if unobstructed. Sensors are not surfaces: the character passes through them, and they report it through their collision handlers. |