Log inGet started
Package

characterController.module

Newest version

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.move with stepHeight) / 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.set and 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 over 1 / (airControlFactor * 10) seconds or so (at a factor of 6 or more, within one 60 Hz frame). The blend is relative to state.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 groundSnapDistance and stepHeight plus two skinWidths when grounded (the feet stand a skin above the ground, and a second skin holds a riser of exactly stepHeight in reach), so a body walks down stairs on its feet, and 100 when 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 set groundHit._sliding = true so the state machine treats the frame as sliding rather than grounded.
  • 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 than stepHeight that cut its walk short.
  • On the ground the walk moves toward the input at acceleration and braking (Feel.walk of movement.feel); along up the step is Feel.vertical, which rises a jump state._rise holds against its own gravity and scales and caps the fall. Missing settings read as Feel.DEFAULTS.