Log inGet started
World

Builtin Library

Branchmain
Branchesmainpublish
Commit70907b77fb

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 of rise past what a slope of slopeAngle degrees gives travel metres across the ground puts the drawn body back by that much, held within stepHeight.
  • StepSmoothing.settle(state, entityId, smoothTime, dt) -> offset: closes the offset by dt seconds 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)