velocity.module
This package holds more than this page lists. See all of its files in its world.
README.md
velocity
Velocity integration and per-frame movement resolution for the
character controller. Owns no state — every call takes the current
position / velocity / config / state and returns the new position
delta plus the updated velocity. Internally uses the Ground,
Walls, and Ceiling raycasting helpers.
Exports
M.resolve(pos: Vec3, vel: Vec3, moveInput: MoveInput, config: Config, state, dt: number, selfId: string) -> (dx, dy, dz, vx, vy, vz, groundHit, wallHit, ceilHit)— apply gravity + air control, resolve wall slide / corner pin / the steps a grounded body climbs (Walls.movewithstepHeight) / ceiling bonk / ground snap on the ground the footprint stands on (Ground.support) / slope projection / steep-slope slide, in that order.
Types:
Vec3 = { x: number, y: number, z: number }MoveInput = { x: number, z: number }— world-space horizontal input.Config = { height?, radius?, maxSlopeAngle?, stepHeight?, gravity?, airControlFactor?, groundSnapDistance?, skinWidth?, acceleration?, braking?, fallGravityMultiplier?, maxFallSpeed? }
Usage
local Velocity = require("@builtin::systems.characterController.characterController.movement.velocity")
local dx, dy, dz, vx, vy, vz, groundHit, wallHit, ceilHit =
Velocity.resolve(pos, vel, moveInput, config, state, dt, selfId)
Notes
- The function is pure: it returns nine values but mutates nothing.
The caller is responsible for writing the position delta back via
entity.localPosition.setand updating its velocity field. - Air control blends horizontal velocity toward the walk the input asks
for, at its full speed, with
airLerp = min(1, airControlFactor * 10 * dt): a run held through a jump keeps its speed, and a turn or a change of speed takes effect over1 / (airControlFactor * 10)seconds or so (at a factor of 6 or more, within one 60 Hz frame). The blend is relative tostate.keptMotion(the motion kept from a moving body the character left) when the state carries one, so the body goes on moving with it (Platform.steer). Grounded mode uses direct assignment for responsive feel. - Ground cast distance is the larger of
groundSnapDistanceandstepHeightplus twoskinWidths when grounded (the feet stand a skin above the ground, and a second skin holds a riser of exactlystepHeightin reach), so a body walks down stairs on its feet, and100when airborne (so a fast fall doesn't tunnel past the floor). Snap commit threshold is tight (the frame's own vertical travel), so airborne ground hits don't snap unless they are within that travel window. - A grounded frame looks for ground above the feet as well, by the
rise its own travel covers on ground of
maxSlopeAngle— that is the ground a walking character climbs into. The seat takes it up to the rise the surface it found covers over that travel, plus a step; a surface further up stands across the path, and the character keeps the ground it already has. - Steep-slope (above
maxSlopeAngle) hits setgroundHit._sliding = trueso the state machine treats the frame asslidingrather thangrounded. - A frame whose horizontal movement the wall pass cancels outright —
pressed straight into a wall, or wedged where two surfaces meet —
sets
wallHit._blocked = true, so a refused walk reads as refused instead of as a walk that happened to cover no ground. - Step climbing only fires when
state.grounded: the wall pass lifts the body over a riser no taller thanstepHeightthat cut its walk short. - On the ground the walk moves toward the input at
accelerationandbraking(Feel.walkofmovement.feel); along up the step isFeel.vertical, which rises a jumpstate._riseholds against its own gravity and scales and caps the fall. Missing settings read asFeel.DEFAULTS.