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

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).