> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatial tool evidence contract (World building 3D skill)

> spatial-tools.md from the World building 3D skill in the Summer Engine skill library. Compose, ground and space 3D scenes with Summer's four spatial tools, one geometric decision at a time.

<Note>Part of the [`world-building-3d` skill](/skills/world-building-3d). The skill links here when your agent needs the detail.</Note>

Load this reference before using Summer's 3D world-building tools.

## Shared rules

* Pass exact `scenePath` and exact scene-root-relative node paths. Do not rely on editor selection.
* Use one `World3D`. The tools fail closed across SubViewport-owned worlds.
* Keep subjects bounded: placement/snap one subject, alignment sixteen.
* Normal model-visible results stay below 5 KiB. Prefer targeted calls over collecting an entire scene.
* Read-only tools never save: placement test, navigation probe.
* Mutation tools register undo and save the exact target scene: snap, align/distribute.

## `summer_test_placement`

Input is a candidate global position and global Euler rotation. The subject's current global scale is preserved, and the scene is not mutated.

Interpretation:

* Physics overlap counts are lower bounds because the physics server exposes no broadphase-completeness bit.
* Any known obstruction makes `fits: false`.
* Zero known physics overlaps can still yield `fits: null`; never coerce it to success.
* `grounded`, signed `floorGap`, and support evidence are independent of overlap certainty. Claim physics-grounded only when `floorEvidence` is `physics` and `supportQueryComplete` is true; otherwise label the evidence approximate or incomplete.
* `visual_aabb` includes visible mesh-only obstacles but is conservative.

## `summer_snap_to_surface`

The subject sweeps along a normalized world direction. Physics evidence uses enabled collider shapes; `visual_aabb` is a mesh-only fallback. When the engine answers with `visual_aabb` (no collider on the subject or the support), the tool re-measures the seat on visible triangles and reports `evidence: visual_mesh` with `verify.final_gap`; a prop without a collider is still invisible to physics.

Use `alignUp` only when an exact collider support is intended. After the call,
require `evidence: physics`, resolved contact, the expected `supportPath`,
`alignApplied`, plausible `slopeDeg`, final gap/error bound, and the saved basis.
The result does not expose the raw support normal or a heading residual, so use
the saved basis plus an independent rendered/physics check. If overlap recovery
fails, do not teleport manually through the obstruction.

## `summer_align_distribute_3d`

Anchors and extents come from visible descendant world AABBs. The solver translates only along the requested axis and preserves basis/scale. Distribution preserves caller order and fixed endpoints.

This is one-dimensional arrangement evidence. It does not prove clearance on the other two axes.

## `summer_navigation_probe`

Iteration 0 is unready; iteration 1 and later can be queried. Layer-filtered snapped endpoints and the reported snap distances define what the engine actually tested. `ready: false` means unknown, not unreachable.

Require both a reachable path and a small endpoint snap distance appropriate to the authored target.
Probe every independent destination; one reachable subject does not validate the
others. Derive the snap-distance threshold from the navigation agent radius or
an explicit authored tolerance.

***

Source: [`library/skills/world-building-3d/references/spatial-tools.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/world-building-3d/references/spatial-tools.md), rendered from `summer-engine@4.3.0` on npm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.