physics.module
This package holds more than this page lists. See all of its files in its world.
README.md
walls
Wall-detection and slide helpers for the character controller. Runs the horizontal pass of a character's step, sweeps the character's own capsule along the movement direction, puts a body that overlaps a wall back outside it, probes a single height with a horizontal ray, and slides a movement vector along a wall normal. No state.
Exports
M.move(x: number, y: number, z: number, dx: number, dz: number, height: number, radius: number, skinWidth: number, maxSlopeAngle: number, selfId: string, frame: Frame?, cameFrom: Point?, stepHeight: number?) -> Step: the horizontal pass of one step. Puts a body that overlaps a wall back outside it (pushOut), then carries it along(dx, dz): the body stopsskinWidthshort of the first wall the step runs into, and the rest of the step slides along that wall and along the next one the slide meets. With astepHeight, a wall that cuts the walk short is walked again with the body lifted by up to that much (as far asheadroomallows); the lifted walk is taken when it carries the body further and comes down on walkable ground above the feet, no higher than a step, clear of every wall, and the rest of the walk goes on from that step. Returns{ dx, dz, pushX, pushZ, overlapped, blocked, hit, stepUp }: where the body goes (push included), the push itself, whether the body overlapped a wall where the step began, whether the step met a wall and gained no ground towards where it asked to go, the first wall it met, and how far above the feet the ground it stepped up onto stands.M.headroom(x: number, y: number, z: number, sx: number, sz: number, maxRise: number, height: number, radius: number, skinWidth: number, maxSlopeAngle: number, selfId: string, frame: Frame?) -> number: how far the body at the feet(x, y, z)moved(sx, sz)across the frame can rise, up tomaxRise, before its head meets something overhead.M.pushOut(x: number, y: number, z: number, height: number, radius: number, skinWidth: number, maxSlopeAngle: number, selfId: string, frame: Frame?, cameFrom: Point?) -> (number, number, boolean): the horizontal push that puts a body overlapping a wall back outside it,skinWidthclear of the surface, and whether it overlapped one. The push runs along the overlap's shortest way out, or back to the sidecameFromstands on when the body's centre has crossed the surface since it last stood there.0, 0, falsefor a body that overlaps no wall.M.standsAt(placed: Point?, x: number, y: number, z: number) -> boolean: whether feet at(x, y, z)stand atplaced, where a mover last put them, to the precision a position is stored at (a 32-bit float's, which coarsens with the distance from the origin). A mover keeps itscameFromonly while this holds.M.castBody(x: number, y: number, z: number, dirX: number, dirZ: number, height: number, radius: number, skinWidth: number, maxSlopeAngle: number, selfId: string, distance: number?) -> hit?: sweep the capsule spanning the character from the top of the ground band above(x, y, z)(its feet) up toy + height, reachingdistance + skinWidthpast its own surface (skinWidthalone whendistanceis omitted). Returns the wall standing across the path, ornilwhen 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 lengthradius + skinWidth, from whichever sample height the caller passes. The ray passes through the colliders the body carries (selfIdand every entity parented under it).M.slideAlongWall(moveX: number, moveZ: number, normalX: number, normalZ: number) -> (number, number)— strip the component ofmovegoing into the wall (v - (v . n) * n, XZ only). Returns input unchanged whendot >= 0or the XZ-normal is effectively zero.
Usage
local Walls = require("@builtin::systems.characterController.characterController.physics.walls")
local step = Walls.move(px, py, pz, vx * dt, vz * dt, 1.8, 0.3, 0.01, 45, selfId)
px, pz = px + step.dx, pz + step.dz
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
-
movesweeps the whole step, so however long a frame's step is, the body ends outside every wall it walks at, and the next step it asks for starts clear of them, away from a wall it rests against as much as along it. -
A sweep begun inside a wall answers about the overlap in whichever direction it points.
pushOutmeasures how deep the overlap goes by sweeping the same body back in from one body width outside the wall, so a body placed inside a wall, or shoved into one, walks again on the next step. Each push reaches at most that body width, the deepest a body reaches into a surface: a body overlapping one face of a hollow mesh collider is put back outside that face, never across the collider at the face on its far side. A start that lands on another surface of the same collider, the far wall of a passage one mesh bounds on both sides, comes in by half until it stands clear, so a body overlapping one wall of a narrow passage is put back into the passage. A body deeper inside a solid than its own width comes out a body width at a time. -
A surface has a way out on each side. The shortest is the side the body's centre stands on, which is the far side once a long step has carried the centre across a thin surface. A mover passes
cameFrom, the feet position of its last step that began withoverlappedfalse, and a body that last stood clear more than a radius behind the shortest way out is pushed back out the side it came from. The CharacterController keeps it while the body stands where the controller put it (standsAt), and forgets it once anything else moves the body. -
A collider the body carries, on
selfIdor on an entity parented under it (a held prop, a trigger volume that travels with the character), is no wall:castBodysweeps through it andpushOutpushes nothing out of it, so a character carrying one stands where it is put and walks. -
Another character is a wall: every entity carrying a
CharacterControllerstands as its upright capsule (physics.characters), socastBodyandmovestop a skin short of it and slide around it, and a hit on one carriescharacter = true.pushOutpushes nothing out of another character; a character moves itself apart from one it overlaps (Characters.apart). Two characters the contact filter lets pass, by theircontactTags, are no walls to each other. -
castBodysweeps the whole body, so an opening narrower than2 * radiusstops 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.castBodyruns on up along a ramp it meets, the way the body climbs it, so a body on a ramp still reports the wall ahead of it, whether that wall is part of the ramp's collider or another; it sweeps on past a surface overhead. -
A contact on the rim of a surface (the edge of a stair or a curb), where the surface under the contact faces another way than the contact does, stands across the path the way a wall does:
move's step pass decides whether the body climbs it. -
castBodystarts its sweep above the ground band: a cap ofradiusresting on ground of angleareachesradius * (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 atmaxSlopeAngle, the steepest ground the character walks, and the ground and step passes own everything under it. -
slideAlongWallnormalises 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".