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

# World building 3D skill for AI agents

> Compose, ground and space 3D scenes with Summer's four spatial tools, one geometric decision at a time. A Summer Engine skill for AI agents.

`world-building-3d` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Compose, ground and space 3D scenes with Summer's four spatial tools, one geometric decision at a time.

| | |
| - | - |
| Status | Preview: not yet exercised in-engine by the Summer team |
| Domains | Scenes and project, 3D models, World building, Level design, Verification |
| Version | `1.1.1` |
| Engine version | `>=4.6` |
| Recommended set | Yes, installed by `--recommended` |

## When your agent uses it

* Placing or grounding props on floors, shelves, ramps, or tables without hand-tuning transforms
* Aligning or evenly spacing a group of 3D objects along one world axis
* Verifying an NPC, pickup, or portal position is reachable on the navigation map

## Install

`summer setup` installs every skill for your agent. To add only this one:

```bash theme={null}
npx -y summer-engine@latest skills install world-building-3d --agent claude-code
```

Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option.

## The skill

Use exact scene and node paths, make one geometric decision at a time, and verify the saved result. Treat spatial tools as bounded evidence: they reduce guesswork but do not replace a final rendered or gameplay check.

Read [references/spatial-tools.md](/skills/world-building-3d/references/spatial-tools) before the first spatial-tool call in a task. It defines each tool's evidence boundary and the result fields that must not be overinterpreted.

## Choose the narrowest tool

| Need | Tool | Effect |
| - | - | - |
| Evaluate a proposed prop pose | `summer_test_placement` | Read-only ghost pose |
| Seat one object on a floor, shelf, table, or ramp | `summer_snap_to_surface` | Moves subject and saves |
| Align or evenly space 2–16 objects | `summer_align_distribute_3d` | Moves subjects and saves |
| Check whether two positions share a navigation route | `summer_navigation_probe` | Read-only |

Use ordinary `summer_get_scene_tree` and `summer_inspect_node` first when paths, hierarchy, authored transforms, collision layers, or camera settings are unknown.

For modular kit pieces (facade modules, storeys, pipes, gutters, wall lamps,
clamp rows) use the `spatial-placement` skill: it adds `summer_inspect_asset`
(measure a piece before placing it), placed `summer_instantiate_scene`,
`summer_place_adjacent`, `summer_attach_to_surface`, `summer_repeat_along`,
`summer_connect_ports`, `summer_raycast`, `summer_measure` and
`summer_starcast` to the four tools here.

## Follow the composition loop

1. Open the exact target scene and resolve exact `./`-relative paths.
2. Inspect the subject, its visual/collider descendants, intended support or neighbors, and the camera.
3. State the intended invariant: contact gap, clearance, spacing axis, or reachable destination.
   If the support, ordering, or destination is genuinely ambiguous, ask
   `Proceed?` with the concrete choice before making a user-visible mutation.
4. Query before mutation when a read-only tool exists.
5. Apply the smallest mutation. Prefer the dedicated solver over hand-tuned transform loops.
6. Re-query the saved pose. Do not treat a successful mutation receipt as proof of visual quality.
7. Run a rendered or gameplay verification when renderer visibility, transparent materials, concave silhouettes, navigation behavior, or player perception matters.

Keep scene A and scene B independent. Never copy a solved world transform between scenes unless their relevant parents, bounds, and obstacles are proven identical.

There is no raw `.tscn` fallback for these evidence queries or solver mutations.
They depend on the running Summer Engine's live scene, physics, camera, and
navigation state. If the required tool is unavailable, inspect and explain the
limitation instead of hand-editing a scene around it.

## Place and ground props

For a known candidate pose, call `summer_test_placement` before setting the transform. Preserve the current global scale unless the user asked to resize the asset.

* `overlapCount > 0` or known overlap evidence means reject the pose.
* `fits: null` means the physics backend could not prove completeness; it is not `true`.
* Require `grounded: true` and an acceptable absolute `floorGap` for seated props.
* Treat `visual_aabb` as broad-phase evidence. Irregular meshes can have empty-looking AABB corners.

For a direct seat operation, call `summer_snap_to_surface` with a world-space direction. Use `alignUp: true` only when the object should inherit an exact physics support normal. After slope alignment, verify both up alignment and preserved heading. Do not infer a usable normal from `visual_aabb` fallback.

`SnapToSurface` does not return the raw support normal or a heading residual.
Require `evidence: physics`, `evidenceDetails.contactResolved: true`, the expected
`supportPath`, `alignApplied: true`, a plausible `slopeDeg`, and inspect the saved
`after.basis` plus a rendered view. Keep `maxDistance` tight because the current
solver cannot take an expected-support path and will stop at the first surface.

On mixed-height or sloped supports, arrange the subjects laterally first, then
snap each subject. A later alignment can lift a grounded prop or bury it in a
slope. For a final placement re-query, use the exact saved global pose; if the
post-alignment basis cannot be expressed confidently as global Euler degrees,
do not invent angles - use the snap receipt and an independent rendered or
physics check.

## Arrange groups

Pass subjects to `summer_align_distribute_3d` in intentional order. Choose a world axis explicitly.

* Use `align_min`, `align_center`, or `align_max` to share one projected anchor.
* Use `distribute_centers` when equal center spacing matters.
* Use `distribute_gaps` when visible edge clearance matters; endpoints remain fixed.

Inspect the result's residuals and `changedCount`; infer unchanged subjects only
as `subjectCount - changedCount`. Rerun placement checks for dense groups because
alignment solves one axis and does not prove full 3D clearance.

## Validate navigation placement

Use `summer_navigation_probe` before moving an NPC, pickup, portal, or encounter anchor whose route matters.

* `ready: false` means no trustworthy navigation evidence; wait or fix the navigation map.
* `reachable: false` is meaningful only when `ready: true`.
* Check requested-to-snapped endpoint distance. A route to a distant snapped point does not validate the requested placement.
* After moving the subject, probe the final authored position again.

Probe each destination separately from the intended player/start point. Use the
final inspected global origin and the scene's actual navigation-layer mask. Set
the acceptable snap distance from the navigation agent radius or the authored
placement tolerance; if neither is known, report the distance instead of
declaring it small. For iteration 0, allow one bounded navigation-sync wait and
retry once - never loop indefinitely.

## Fail closed

Do not work around world-mismatch failures such as `subject_world_mismatch` or
`subject_geometry_world_mismatch`, non-finite transforms, hierarchy limits,
unavailable physics, or missing bounds by guessing. Fix the scene structure or
choose a clearly labeled manual fallback, then verify it.

Do not retry a mutation after an oversized or ambiguous result unless the receipt explicitly says it is retry-safe; the first mutation may already have landed.

## From a shell

No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.

| In this skill | Command |
| - | - |
| `summer_align_distribute_3d` | `summer engine align-distribute-3d` |
| `summer_attach_to_surface` | `summer engine attach-to-surface` |
| `summer_connect_ports` | `summer engine connect-ports` |
| `summer_get_scene_tree` | `summer engine get-scene-tree` |
| `summer_inspect_asset` | `summer engine inspect-asset` |
| `summer_inspect_node` | `summer engine inspect-node` |
| `summer_instantiate_scene` | `summer engine instantiate-scene` |
| `summer_measure` | `summer engine measure` |
| `summer_navigation_probe` | `summer engine navigation-probe` |
| `summer_open_scene` | `summer engine open-scene` |
| `summer_place_adjacent` | `summer engine place-adjacent` |
| `summer_play` | `summer engine play` |
| `summer_raycast` | `summer engine raycast` |
| `summer_repeat_along` | `summer engine repeat-along` |
| `summer_screenshot` | `summer engine screenshot` |
| `summer_set_prop` | `summer engine set-prop` |
| `summer_snap_to_surface` | `summer engine snap-to-surface` |
| `summer_starcast` | `summer engine starcast` |
| `summer_test_placement` | `summer engine test-placement` |

## Files in this skill

* [`references/spatial-tools.md`](/skills/world-building-3d/references/spatial-tools)

## Related skills

* [`scene-composition`](/skills/scene-composition): Scene structure: node hierarchy, when to extract sub-scenes, reusable prefabs, instance vs add node.
* [`verifying-scenes`](/skills/verifying-scenes): Prove scene work landed: snapshot, diff, screenshots, runtime reads, 3D audits, shot sheets and zooms.
* [`scene-scripting`](/skills/scene-scripting): Build scenes, levels, HUDs and wiring with one editor GDScript (summer\_run\_script) instead of call chains.
* [`spatial-placement`](/skills/spatial-placement): Place 3D objects and modular kit pieces from measured geometry: floors, walls, facades, pipes, alcoves.

***

Source: [`library/skills/world-building-3d/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/world-building-3d/SKILL.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.