movement.module
This package holds more than this page lists. See all of its files in its world.
README.md
stepSmoothing
How a character's drawn body climbs a step its capsule takes at once. A grounded character walking up or down a stair is put on the next tread in the frame it reaches it: its capsule, and so its entity, rises or drops a whole riser in one frame, and keeps that exact height. The character's direct children that hold no collider and no physics body, with none below them (its body mesh, a name label) are drawn shifted along its up by an offset that takes the riser back and closes to zero as a critically damped spring, so the body is seen to climb smoothly while the walls, the ground and every query see the character where it stands.
A rise or drop the ground's slope accounts for (a ramp, a hill) is the walk itself and is drawn as the capsule moves; only what goes past it (a riser, a curb, a step down) is smoothed. The offset is held within the character's step height, and a character placed by something else (a teleport, a respawn) is drawn where it was placed at once.
The CharacterController component and the character module's update both
climb through here, so every character smooths its steps by one rule. The
component's stepSmoothing field and the module config's stepSmoothing are
the spring's smoothing time in seconds (default 0.1); 0 draws the body on
the capsule every frame.
Exports
StepSmoothing.new() -> Smoothing: a fresh record for one character, no offset and no child shifted, owned by the controller that moves it.StepSmoothing.climbed(state, rise, travel, slopeAngle, stepHeight) -> offset: takes in one grounded step's rise along up. The part ofrisepast what a slope ofslopeAngledegrees givestravelmetres across the ground puts the drawn body back by that much, held withinstepHeight.StepSmoothing.settle(state, entityId, smoothTime, dt) -> offset: closes the offset bydtseconds of the spring and draws the entity's drawn children at it. Costs nothing on a frame with no offset and no child shifted.StepSmoothing.clear(state, entityId): draws the children back on the capsule at once, for a character placed by something else, no longer moved by its controller, or going away.StepSmoothing.offset(state) -> number: the offset along up in metres, negative while the body is drawn below the capsule (after a step up).StepSmoothing.active(state) -> boolean: whether the body is drawn off the capsule now; a controller keeps stepping a character while it is.
Usage
local StepSmoothing = require("@builtin::systems.characterController.characterController.movement.stepSmoothing")
local smoothing = StepSmoothing.new()
-- In each grounded step that ended on the ground:
StepSmoothing.climbed(smoothing, dy, math.sqrt(dx * dx + dz * dz), slopeAngle, stepHeight)
-- Once a frame, after the steps:
StepSmoothing.settle(smoothing, entityId, 0.1, dt)