spatial
Deterministic spatial reasoning in the world: raycasts, distance and overlap measurement, surface placement, and placement verification.
What it’s for
Deterministic 3D placement and measurement. Instead of moving an actor, taking a screenshot,
and squinting, your assistant traces rays (spatial.raycast,
spatial.raycast_screen), measures real gaps between bounds
(spatial.measure_distance, spatial.measure_overlap), rests actors on
surfaces with pivot-corrected bounds math (spatial.place_on_surface,
spatial.place_relative), and then proves the layout is right
(spatial.verify_placement).
Reach for it whenever level work has to be correct rather than roughly there: props that must sit flush on the floor, spacing that must clear a wall, nothing intersecting anything else. All coordinates are unreal units (cm). Placement verbs return an inline verification, so a flush rest reads back as a resting gap of about zero.
Examples
Rest a prop on whatever is below it
Drop the actor onto the surface under it; the bounds bottom lands on the hit.
You: Put Crate_3 down properly, it is floating.
call("spatial.place_on_surface", {actorName:"Crate_3", dropDown:true})
→ {location:{...}, restingGap: 0.0}
Done. Crate_3 now rests flush on the floor.
Measure a clearance
Get the nearest surface-to-surface gap, not just center distance.
You: How much space is between the crate and the north wall?
call("spatial.measure_distance", {a:"Crate_3", b:"Wall_North", mode:"edge_gap"})
→ {distance: 12.5, centerDistance: 148.0, edgeGap: 12.5, perAxisGap:{...}}
Done. The crate clears the wall by 12.5 cm.
Prove the placement is valid
Run only the checks you name; each returns its own pass and detail.
You: Make sure the crate is grounded and not clipping the wall.
call("spatial.verify_placement", {actor:"Crate_3",
expect:{grounded:{maxGap: 2}, noOverlapWith:["Wall_North"]}})
→ {pass:true, checks:[{check:"grounded", pass:true, ...},
{check:"noOverlapWith", pass:true, ...}]}
Done. Grounded within 2 cm and no overlap with Wall_North.