physics

# ceiling Single-ray ceiling-detection helper for the character controller. Casts upward from the character's head to detect overhead obstacles (head bonk, low clearance). No state. ## Exports - `M.cast(x: number, y: number, z: number, height: number, skinWidth: number, selfId: string) -> hit?` — cast a ray from `(x, y + height - skinWidth, z)` upward for `skinWidth * 2`. Returns the raycast hit table or `nil`. ## Usage ```luau local Ceiling = require("@builtin::systems.characterController.characterController.physics.ceiling") local hit = Ceiling.cast(px, py, pz, 1.8, 0.01, selfId) if hit then -- head bonk: zero out upward velocity end ``` ## Notes - Pure function — no module state, no side effects beyond the engine raycast itself. - The ray is intentionally short (`skinWidth * 2`) so a head-bonk check only fires when the character is actively pressing up against a ceiling, not when there is ambient overhead geometry far above.

# ground Ground-probing and slope-math helpers for the character controller. A downward raycast helper plus two pure vector helpers (slope angle, plane projection). No state. ## Exports - `M.cast(x: number, y: number, z: number, skinWidth: number, maxDist: number, selfId: string, riseDist: number?) -> hit?` — cast a ray downward from `(x, y + riseDist + skinWidth, z)`, reaching `maxDist` below the feet. The returned hit's `distance` is adjusted to be relative to the feet, not the ray origin, and is negative for ground standing above them. - `M.slopeAngle(nx: number, ny: number, nz: number) -> number` — degrees between the supplied normal and world up. Returns 0 on a zero-length normal. - `M.projectOnSlope(moveX, moveY, moveZ, normalX, normalY, normalZ) -> (number, number, number)` — project a movement vector onto the plane perpendicular to a normal: `v - (v . n) * n`. ## Usage ```luau local Ground = require("@builtin::systems.characterController.characterController.physics.ground") local hit = Ground.cast(px, py, pz, 0.01, 0.2, selfId) if hit then local angle = Ground.slopeAngle(hit.normal.x, hit.normal.y, hit.normal.z) if angle <= 45 then -- walkable end end local px, py, pz = Ground.projectOnSlope(dx, 0, dz, nx, ny, nz) ``` ## Notes - `cast` shifts the origin up by `skinWidth` to avoid starting the ray inside the ground when the character is sitting on a contact, then subtracts `skinWidth` back off `hit.distance` so callers see the true distance from the feet. - `riseDist` raises the origin further, so the ray also covers ground that stands above the feet — the ground a walking character climbs into. A hit up there reports a negative `distance`: how far the character rises to stand on it. - `slopeAngle` clamps `cos(angle)` into `[-1, 1]` before `acos` — callers don't need to normalise the input. - `projectOnSlope` does not normalise the surface normal; callers should pass a unit normal (raycast normals already are).

# 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 ```luau 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".