walls

Wall-detection and slide helpers for the character controller. Sweeps the character's own capsule along the movement direction, probes a single height with a horizontal ray, and slides a movement vector along a wall normal. No state.

Exports

• M.castBody(x: number, y: number, z: number, dirX: number, dirZ: number, height: number, radius: number, skinWidth: number, maxSlopeAngle: number, selfId: string) -> hit? — sweep the capsule spanning the character from the top of the ground band above (x, y, z) (its feet) up to y + height, reaching skinWidth past its own surface. Returns the wall standing across the path, or nil when the path is clear.
• M.castDirection(x: number, y: number, z: number, dirX: number, dirZ: number, radius: number, skinWidth: number, selfId: string) -> hit? — single horizontal ray of length radius + skinWidth, from whichever sample height the caller passes.
• M.slideAlongWall(moveX: number, moveZ: number, normalX: number, normalZ: number) -> (number, number) — strip the component of move going into the wall (v - (v . n) * n, XZ only). Returns input unchanged when dot >= 0 or the XZ-normal is effectively zero.

Usage

local Walls = require("@builtin::systems.characterController.characterController.physics.walls")

local hit = Walls.castBody(px, py, pz, dirX, dirZ, 1.8, 0.3, 0.01, 45, selfId)
if hit then
    local slideX, slideZ = Walls.slideAlongWall(dx, dz, hit.normal.x, hit.normal.z)
end

Notes

• castBody sweeps the whole body, so an opening narrower than 2 * radius stops the character even when nothing stands on the centre line — two cabinets 6 cm apart are a wall, not a doorway.
• A contact whose surface faces up or down — the ramps the character walks up, to maxSlopeAngle, and anything directly overhead — belongs to the ground and ceiling passes. castBody sweeps on past those, so a body on a ramp still reports the wall ahead of it.
• castBody starts its sweep above the ground band: a cap of radius resting on ground of angle a reaches radius * (1 / cos(a) - 1) below the surface uphill of it, and a sweep begun inside a surface describes the shortest way out of that overlap instead of the surface standing across the path. The band is measured at maxSlopeAngle, the steepest ground the character walks, and the ground and step passes own everything under it.
• slideAlongWall normalises the wall normal in XZ; callers don't need to pre-normalise. The Y component of the normal is ignored because slide-along is a horizontal operation.
• The slide helper returns the input movement unchanged whenever the movement isn't pressing into the wall — there's no "stick to wall" behaviour, only "don't pass through".