summer-engine 2.8.1 → 3.0.0

package/library/skills/vfx-muzzle-flash/_building-blocks/additive-billboard-particles.md

@@ -0,0 +1,37 @@
+# Additive Billboard Particles — Canonical Material Settings
+
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+`BaseMaterial3D` is abstract — `BaseMaterial3D.new()` is a parse error ("Native class
+"BaseMaterial3D" cannot be constructed as it is abstract"). Instantiate
+`StandardMaterial3D`; the `BaseMaterial3D.*` enum constants below are still the right
+way to name the values.
+
+## Settings
+
+```gdscript
+var bm := StandardMaterial3D.new()
+bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
+bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
+bm.emission_enabled = true
+bm.emission_energy_multiplier = 3.0   # 1.0–5.0 typical; bump for HDR bloom
+bm.disable_receive_shadows = true
+bm.shadow_to_opacity = false
+bm.no_depth_test = false              # true only if particles must read on TOP of opaque geometry
+bm.billboard_keep_scale = true        # BILLBOARD_PARTICLES drops per-particle scale without this
+bm.albedo_color = Color(R, G, B, 1.0)
+bm.emission = Color(R, G, B)          # usually same as albedo for single-color motes
+```
+
+## When to use this vs a custom shader
+
+- **Use this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Per-particle color over age does NOT need a custom shader.** `ParticleProcessMaterial` has `color_ramp`, `color_initial_ramp`, `alpha_curve` and `emission_curve` (all verified present in 4.6) — those drive the particle's `COLOR` from age and feed straight into a plain `StandardMaterial3D`. Reach for a ramp before reaching for a shader.
+- **Use a custom `ShaderMaterial`** when you need per-fragment shape masks (muzzle flash star burst), noise-distorted UVs (fire, smoke), or anything that varies *within* the quad. Those are what `StandardMaterial3D` genuinely can't express.
+- If a custom shader does need the particle age, note that the age lives in `INSTANCE_CUSTOM.y` (normalized by `INSTANCE_CUSTOM.w`, the lifetime), that `INSTANCE_CUSTOM.x` is the rotation angle — not the age — and that `INSTANCE_CUSTOM` is **vertex-stage only**. Pass it to `fragment()` through a `varying`.
+
+## Performance note
+
+Additive overdraw is fillrate-bound. `draw_pass_1` is a `Mesh`, so the size dial is on the mesh: keep `QuadMesh.size` at or under `Vector2(0.2, 0.2)` for motes/sparks. Larger quads at full additive intensity destroy mobile fillrate budgets fast.

package/library/skills/vfx-muzzle-flash/_building-blocks/trauma-shake-snippet.md

@@ -0,0 +1,53 @@
+# Trauma Camera Shake — Reusable Snippet
+
+Variant of the canonical "trauma model" shake (see `visual-effects/game-feel/SKILL.md` for the full game-feel discipline). Lightning and explosion recipes call `add_trauma()` to chain visual impact with screen-level reaction.
+
+## Setup (autoload script)
+
+`autoloads/CameraShake.gd`:
+
+```gdscript
+extends Node
+
+var trauma: float = 0.0
+var trauma_decay: float = 1.4
+var max_offset: Vector3 = Vector3(0.4, 0.4, 0.0)
+var max_yaw: float = 0.05
+var max_pitch: float = 0.05
+var camera: Camera3D
+
+func _process(delta: float) -> void:
+    if camera == null:
+        camera = get_viewport().get_camera_3d()
+        if camera == null:
+            return
+    if trauma > 0.0:
+        var s := trauma * trauma  # perceived intensity grows quadratically
+        camera.h_offset = max_offset.x * s * (randf() * 2.0 - 1.0)
+        camera.v_offset = max_offset.y * s * (randf() * 2.0 - 1.0)
+        camera.rotation.x += max_pitch * s * (randf() * 2.0 - 1.0) * 0.1
+        camera.rotation.y += max_yaw * s * (randf() * 2.0 - 1.0) * 0.1
+        trauma = max(0.0, trauma - trauma_decay * delta)
+    else:
+        camera.h_offset = 0.0
+        camera.v_offset = 0.0
+
+func add_trauma(amount: float) -> void:
+    trauma = clamp(trauma + amount, 0.0, 1.0)
+```
+
+Register `CameraShake` as autoload in Project Settings. An autoload is a node at
+`/root/CameraShake`, not an engine singleton — reach it with
+`get_node_or_null("/root/CameraShake")`. `Engine.has_singleton("CameraShake")` is
+always `false` for an autoload (measured), so never gate the call on it.
+
+## Usage
+
+```gdscript
+# In a recipe controller:
+CameraShake.add_trauma(0.6)   # lightning strike
+CameraShake.add_trauma(1.0)   # explosion (saturates to max)
+CameraShake.add_trauma(0.2)   # hit spark
+```
+
+The trauma model: noise-driven shake whose intensity grows quadratically with `trauma`. Multiple sources stack but saturate — a player taking 5 hits in a row shakes harder, but never beyond the max.

package/library/skills/vfx-muzzle-flash/resource.yaml

@@ -0,0 +1,35 @@
+id: skill/vfx-muzzle-flash
+kind: skill
+version: 1.0.3
+summary: Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader.
+use_when:
+  - authoring a muzzle-flash effect — gun fire, weapon flash, barrel flash, spell-cast burst at a hand
+  - a gun or spell-casting hand shoots with no visible flash at the barrel or palm
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/game-feel
+    - skill/vfx-fire
+    - skill/vfx-hit-spark
+    - skill/vfx-lightning
+    - skill/vfx-magic-glow
+    - skill/vfx-smoke
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/visual-effects/recipes/muzzle-flash
+  - muzzle-flash

package/{skills/visual-effects/recipes/smoke → library/skills/vfx-smoke}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: smoke
+name: vfx-smoke
 description: Use when authoring a smoke visual effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D. Trigger on "smoke", "smoke trail", "puff", "chimney smoke", "smoke from a fire", "steam", "fog cloud", "explosion smoke".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_save_scene summer_run_script summer_world_snapshot summer_snapshot_diff summer_screenshot summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -255,6 +255,32 @@ summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key=
 summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="rise_height", value=3.0)
 ```
 
+### 5a. One-script wiring (summer_run_script)
+
+On engines with `summer_run_script` (see `scene-scripting`), the node wiring
+above is ONE ctx script — transactional, and it builds the QuadMesh + ShaderMaterial
+resources directly instead of `.tres` sidecars:
+
+```gdscript
+func run(ctx):
+    var smoke := ctx.add_node("GPUParticles3D", "Smoke", ctx.find("Chimney"))
+    smoke.set_script(load("res://addons/vfx/smoke/smoke_controller.gd"))
+    smoke.process_material = ParticleProcessMaterial.new()
+    var quad := QuadMesh.new()
+    quad.size = Vector2(1, 1)
+    var mat := ShaderMaterial.new()
+    mat.shader = load("res://addons/vfx/smoke/smoke.gdshader")
+    quad.material = mat
+    smoke.draw_pass_1 = quad
+    smoke.position = Vector3(0, 0.3, 0)
+    smoke.set("rise_height", 4.0)
+    smoke.set("particle_count", 48)
+    smoke.set("wind_direction", Vector3(0.4, 0, 0.1))
+    ctx.save_scene()
+```
+
+Verify with `summer_snapshot_diff` (exactly one node added) and a `summer_screenshot`.
+
 ### 5b. Verify
 
 The shader and the controller are compiled code. Check them before tuning anything.
@@ -429,14 +455,14 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/fire` — the partner; almost any fire wants smoke 0.5–2 m above the flame top.
-- `summer:visual-effects/recipes/dissolve` — pair `black-fire-smoke` with a dissolving target for "the bandit camp burns and ashes drift away."
-- `summer:visual-effects/recipes/lightning` — for a smoke flash from a lightning strike (use `puff()` on impact).
-- `summer:audio/sound-effect` — generate `gentle wind through smoke, soft hiss, 4s loop` for chimneys.
+- `vfx-fire` — the partner; almost any fire wants smoke 0.5–2 m above the flame top.
+- `vfx-dissolve` — pair `black-fire-smoke` with a dissolving target for "the bandit camp burns and ashes drift away."
+- `vfx-lightning` — for a smoke flash from a lightning strike (use `puff()` on impact).
+- `sound-effect` — generate `gentle wind through smoke, soft hiss, 4s loop` for chimneys.
 
 ## See also
 
 - `_building-blocks/noise-3d-fbm.gdshaderinc` — the FBM noise this shader includes
-- `summer:visual-effects/recipes/fire` — sister recipe, almost always paired
-- `summer:visual-effects/recipes/dissolve` — for ash particles after disintegration
-- `summer:gdscript-patterns` — for the controller idioms (signals, exports, `@tool`)
+- `vfx-fire` — sister recipe, almost always paired
+- `vfx-dissolve` — for ash particles after disintegration
+- `gdscript-patterns` — for the controller idioms (signals, exports, `@tool`)

package/library/skills/vfx-smoke/_building-blocks/noise-3d-fbm.gdshaderinc

@@ -0,0 +1,45 @@
+// 3D Fractal Brownian Motion noise — used by fire, dissolve, smoke, magic-glow.
+// Include with: #include "res://addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc"
+
+float hash3(vec3 p) {
+    p = fract(p * vec3(443.8975, 397.2973, 491.1871));
+    p += dot(p, p.yxz + 19.19);
+    return fract((p.x + p.y) * p.z);
+}
+
+float noise3(vec3 p) {
+    vec3 i = floor(p);
+    vec3 f = fract(p);
+    f = f * f * (3.0 - 2.0 * f);
+
+    float n000 = hash3(i + vec3(0.0, 0.0, 0.0));
+    float n100 = hash3(i + vec3(1.0, 0.0, 0.0));
+    float n010 = hash3(i + vec3(0.0, 1.0, 0.0));
+    float n110 = hash3(i + vec3(1.0, 1.0, 0.0));
+    float n001 = hash3(i + vec3(0.0, 0.0, 1.0));
+    float n101 = hash3(i + vec3(1.0, 0.0, 1.0));
+    float n011 = hash3(i + vec3(0.0, 1.0, 1.0));
+    float n111 = hash3(i + vec3(1.0, 1.0, 1.0));
+
+    float x00 = mix(n000, n100, f.x);
+    float x10 = mix(n010, n110, f.x);
+    float x01 = mix(n001, n101, f.x);
+    float x11 = mix(n011, n111, f.x);
+
+    float y0 = mix(x00, x10, f.y);
+    float y1 = mix(x01, x11, f.y);
+
+    return mix(y0, y1, f.z);
+}
+
+float fbm3(vec3 p) {
+    float v = 0.0;
+    float amp = 0.5;
+    float freq = 1.0;
+    for (int i = 0; i < 4; i++) {
+        v += amp * noise3(p * freq);
+        freq *= 2.0;
+        amp *= 0.5;
+    }
+    return v;
+}

package/library/skills/vfx-smoke/resource.yaml

@@ -0,0 +1,32 @@
+id: skill/vfx-smoke
+kind: skill
+version: 1.0.2
+summary: Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D.
+use_when:
+  - authoring a smoke effect — smoke trail, puff, chimney smoke, steam, fog cloud, explosion smoke
+  - a chimney, campfire, explosion, or vent needs a rising smoke column or puff in a 3D scene
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/vfx-dissolve
+    - skill/vfx-fire
+    - skill/vfx-lightning
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/visual-effects/recipes/smoke
+  - smoke

package/{skills/visual-effects/recipes/water-ripple → library/skills/vfx-water-ripple}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: water-ripple
+name: vfx-water-ripple
 description: Use when authoring a water-ripple visual effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts. Trigger on "water ripple", "ripples on water", "raindrop ripple", "splash ripple", "rain on water", "footstep in puddle", "fish jumps".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_save_scene summer_run_script summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -246,6 +246,28 @@ summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Pudd
 summer_save_scene(scenePath="res://main.tscn")
 ```
 
+### 5a. One-script wiring (summer_run_script)
+
+On engines with `summer_run_script` (see `scene-scripting`), the node and
+resource wiring is ONE transactional ctx script — and it builds the subdivided
+PlaneMesh directly, so the `plane.tres` sidecar disappears:
+
+```gdscript
+func run(ctx):
+    var puddle := ctx.add_node("MeshInstance3D", "Puddle", null)
+    var plane := PlaneMesh.new()
+    plane.subdivide_width = 32
+    plane.subdivide_depth = 32
+    puddle.mesh = plane
+    puddle.position = Vector3(0, 0.01, 0)
+    puddle.set_script(load("res://addons/vfx/water-ripple/water_ripple_surface.gd"))
+    puddle.set("normal_texture", load("res://addons/vfx/water-ripple/water_normals.png"))
+    ctx.save_scene()
+```
+
+Set the mesh BEFORE the script if the controller reads it in `_ready`; either way,
+`ctx.add_node` has already owned the node, so it survives the save.
+
 ### 5b. Verify
 
 The shader and the controller are compiled code, and the controller `preload`s the
@@ -387,14 +409,14 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/hit-spark` — recolor white-blue and spawn at the impact point for a few water droplets flying up. Pair them.
-- `summer:visual-effects/recipes/smoke` — recolor pale gray for the steam if you're hitting hot water or lava.
-- `summer:audio/sound-effect` — generate `single water drop in shallow puddle, splash, 200ms` and trigger on each `add_ripple`.
-- For weather-driven rain ripples, see `summer:visual-effects/weather` (if available) or scaffold a simple Rain node that calls `add_ripple` 30×/sec across the puddle bounds.
+- `vfx-hit-spark` — recolor white-blue and spawn at the impact point for a few water droplets flying up. Pair them.
+- `vfx-smoke` — recolor pale gray for the steam if you're hitting hot water or lava.
+- `sound-effect` — generate `single water drop in shallow puddle, splash, 200ms` and trigger on each `add_ripple`.
+- For weather-driven rain ripples, scaffold a simple Rain node that calls `add_ripple` 30×/sec across the puddle bounds.
 
 ## See also
 
 - `_building-blocks/additive-billboard-particles.md` — for paired splash droplets
-- `summer:visual-effects/recipes/hit-spark` — sister recipe for the upward droplets
-- `summer:visual-effects/recipes/smoke` — for steam over hot liquids
-- `summer:gdscript-patterns` — for the controller idioms
+- `vfx-hit-spark` — sister recipe for the upward droplets
+- `vfx-smoke` — for steam over hot liquids
+- `gdscript-patterns` — for the controller idioms

package/library/skills/vfx-water-ripple/_building-blocks/additive-billboard-particles.md

@@ -0,0 +1,37 @@
+# Additive Billboard Particles — Canonical Material Settings
+
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+`BaseMaterial3D` is abstract — `BaseMaterial3D.new()` is a parse error ("Native class
+"BaseMaterial3D" cannot be constructed as it is abstract"). Instantiate
+`StandardMaterial3D`; the `BaseMaterial3D.*` enum constants below are still the right
+way to name the values.
+
+## Settings
+
+```gdscript
+var bm := StandardMaterial3D.new()
+bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
+bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
+bm.emission_enabled = true
+bm.emission_energy_multiplier = 3.0   # 1.0–5.0 typical; bump for HDR bloom
+bm.disable_receive_shadows = true
+bm.shadow_to_opacity = false
+bm.no_depth_test = false              # true only if particles must read on TOP of opaque geometry
+bm.billboard_keep_scale = true        # BILLBOARD_PARTICLES drops per-particle scale without this
+bm.albedo_color = Color(R, G, B, 1.0)
+bm.emission = Color(R, G, B)          # usually same as albedo for single-color motes
+```
+
+## When to use this vs a custom shader
+
+- **Use this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Per-particle color over age does NOT need a custom shader.** `ParticleProcessMaterial` has `color_ramp`, `color_initial_ramp`, `alpha_curve` and `emission_curve` (all verified present in 4.6) — those drive the particle's `COLOR` from age and feed straight into a plain `StandardMaterial3D`. Reach for a ramp before reaching for a shader.
+- **Use a custom `ShaderMaterial`** when you need per-fragment shape masks (muzzle flash star burst), noise-distorted UVs (fire, smoke), or anything that varies *within* the quad. Those are what `StandardMaterial3D` genuinely can't express.
+- If a custom shader does need the particle age, note that the age lives in `INSTANCE_CUSTOM.y` (normalized by `INSTANCE_CUSTOM.w`, the lifetime), that `INSTANCE_CUSTOM.x` is the rotation angle — not the age — and that `INSTANCE_CUSTOM` is **vertex-stage only**. Pass it to `fragment()` through a `varying`.
+
+## Performance note
+
+Additive overdraw is fillrate-bound. `draw_pass_1` is a `Mesh`, so the size dial is on the mesh: keep `QuadMesh.size` at or under `Vector2(0.2, 0.2)` for motes/sparks. Larger quads at full additive intensity destroy mobile fillrate budgets fast.

package/library/skills/vfx-water-ripple/resource.yaml

@@ -0,0 +1,31 @@
+id: skill/vfx-water-ripple
+kind: skill
+version: 1.0.2
+summary: Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts.
+use_when:
+  - authoring a water-ripple effect — raindrop ripples, splash ripples, footstep in a puddle, fish jumps
+  - rain, footsteps, or falling objects should disturb a water surface with spreading ripples
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/vfx-hit-spark
+    - skill/vfx-smoke
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/visual-effects/recipes/water-ripple
+  - water-ripple

package/library/skills/voice-line/resource.yaml

@@ -0,0 +1,27 @@
+id: skill/voice-line
+kind: skill
+version: 1.0.2
+summary: Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support.
+use_when:
+  - '"the NPC needs a greeting / a bark / a narrator intro read aloud"'
+  - giving a character a voice that fits their personality (gruff, cheerful, robotic)
+  - a back-and-forth dialogue between two or more characters
+do_not_use_when:
+  - non-speech audio — sound effects or music (skill/sound-effect, skill/music-track)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - audio
+    - assets
+  modalities:
+    - audio
+    - assets
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/audio/voice-line

package/library/skills/world-building-3d/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: world-building-3d
+description: Use when composing, placing, grounding, spacing, or validating 3D objects in Summer Engine scenes. Trigger on "world building", "place props", "snap to floor", "align objects", "distribute objects", "navigation reachability", or requests to make a 3D scene look deliberately arranged rather than roughly positioned.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+allowed-tools: Read Grep summer_open_scene summer_get_scene_tree summer_inspect_node summer_set_prop summer_test_placement summer_snap_to_surface summer_align_distribute_3d summer_navigation_probe summer_screenshot summer_play
+---
+
+# Build 3D Worlds with Spatial Evidence
+
+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](references/spatial-tools.md) 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.
+
+## 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.

package/library/skills/world-building-3d/references/spatial-tools.md

@@ -0,0 +1,50 @@
+# Spatial tool evidence contract
+
+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 Godot 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.
+
+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 Godot 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.

package/library/skills/world-building-3d/resource.yaml

@@ -0,0 +1,44 @@
+id: skill/world-building-3d
+kind: skill
+version: 1.1.0
+summary: Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified.
+use_when:
+  - 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
+do_not_use_when:
+  - the scene is 2D — these tools read Node3D transforms, world AABBs, 3D physics, and World3D navigation
+  - the change is a bulk procedural build with computed placement — skill/scene-scripting
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - level-design
+    - verification
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/test-placement
+    - tool/snap-to-surface
+    - tool/align-distribute-3d
+    - tool/navigation-probe
+    - tool/get-scene-tree
+    - tool/inspect-node
+    - tool/screenshot
+  skills:
+    - skill/scene-composition
+    - skill/verifying-scenes
+    - skill/scene-scripting
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+recommended: true
+aliases:
+  - skills/scene-and-project/world-building-3d