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. The ray passes through the colliders the body carries (selfId and every entity parented under it), so a prop held overhead is never a ceiling.

Usage

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.