Log inGet started
Package

physics.module

Newest version

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 stops skinWidth short 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 a stepHeight, a wall that cuts the walk short is walked again with the body lifted by up to that much (as far as headroom allows); 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 to maxRise, 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, skinWidth clear of the surface, and whether it overlapped one. The push runs along the overlap's shortest way out, or back to the side cameFrom stands on when the body's centre has crossed the surface since it last stood there. 0, 0, false for a body that overlaps no wall.
  • M.standsAt(placed: Point?, x: number, y: number, z: number) -> boolean: whether feet at (x, y, z) stand at placed, 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 its cameFrom only 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 to y + height, reaching distance + skinWidth past its own surface (skinWidth alone when distance is omitted). 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. The ray passes through the colliders the body carries (selfId and every entity parented under it).
  • 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 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

  • move sweeps 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. pushOut measures 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 with overlapped false, 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 selfId or on an entity parented under it (a held prop, a trigger volume that travels with the character), is no wall: castBody sweeps through it and pushOut pushes 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 CharacterController stands as its upright capsule (physics.characters), so castBody and move stop a skin short of it and slide around it, and a hit on one carries character = true. pushOut pushes nothing out of another character; a character moves itself apart from one it overlaps (Characters.apart). Two characters the contact filter lets pass, by their contactTags, are no walls to each other.

  • 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 runs 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.

  • 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".