summer-engine 3.1.0 → 3.2.0

package/library/skills/verification-before-completion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: "Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always."
 ---
 
 # Verification Before Completion

package/library/skills/verifying-scenes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verifying-scenes
-description: Use when verifying that scene work actually landed — after any mutation batch, asset import, lighting change, or during a playtest — and before claiming any visual or structural result. Runs the before/after discipline (summer_world_snapshot → mutate → summer_snapshot_diff + summer_screenshot), reads live runtime state with summer_get_runtime_tree / summer_inspect_runtime_node instead of stopping the game, and enforces honest-claim rules.
+description: "Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms."
 ---
 
 # Verifying Scenes
@@ -35,6 +35,43 @@ Snapshot ids: the engine retains the last 8 per session; `unknown_snapshot` mean
 - Nothing floats above or sinks into its support.
 - Sizes are real-world plausible: door ≈ 2 units, person ≈ 1.7, car ≈ 4.5. An AABB of 40 on a "chair" is an import-scale bug — pass `target_size` to `summer_instantiate_scene` and re-check.
 
+## Audit the scene after each build stage
+
+A screenshot only shows what its camera points at. Problems behind a wall, under a prop or across the street slip past it: a door insert narrower than its frame (you see the street through the gap), a bench turned 90 degrees against the wall, a floor tile with holes over an underlay. `summer_scene_audit` walks every node in one read-only call and lists where to look.
+
+1. **After each build stage** (a facade, a street, a dressing pass): save, then `summer_scene_audit scenePath:"res://..."`. It reads the SAVED file in a private offscreen copy, so the open tab never becomes unsaved and nothing is saved. Use `root:"Block3"` to audit only what you just built (the rest still counts as surroundings) and `checks:[...]` to rerun one check after a fix.
+2. **Read the page, not just the counts.** Issues come sorted `error`, `warn`, `look`, each with a node path, a world position, a reason, the evidence numbers (sizes, gaps, angles, the ray that reproduces it) and the next tool. The result is at most 5 KB; follow `next_offset` with `offset` for the next page, or narrow with `min_severity:"warn"`.
+   - A check with `partial` in its counts ran out of editor time (`budget_ms`, default 3000) and covered only that share. It is not clean: rerun it alone (`checks:["floor_gap"]`) or with a larger `budget_ms` before you call that check clean.
+3. **Frame every error and look item up close before calling the scene done.** `render:"sheet"` returns one image of the page's first 6 issues framed from their open side (tiles labelled `#n`); otherwise `summer_frame_nodes` on the path and `summer_zoom` into it. A look item (`orientation`, a facing question) is never an answer: decide the facing yourself from the asset (`summer_inspect_asset`).
+4. **Classify each item as real or a false positive** in your notes. Fix the real ones with the placement tools, then audit again: the same check must come back clean (or the remaining items must be ones you have looked at and accepted).
+5. **Accept the look items you judged fine, once.** Pass `accept:[{key, reason}]` with each item's `key` from the page (a warn can be accepted too, an error never). The audit writes them to `res://.summer/audit-accept.json`; later audits count them (`counts.<check>.accepted`) but hide them. An accepted item comes back, marked `accept_stale`, when its evidence changes materially (its severity rises or its measured size moves by over 25%), so a fix that made it worse is not hidden. `show_accepted:true` lists them again.
+
+What the checks mean:
+- `through_hole`: rays pass the wall and reach the far side of the building.
+- `floor_gap`: what a down ray hits FIRST.
+  - "falls to the void" or "holes in its own mesh": the floor really is open.
+  - "covers the floor": an underlay plane sits above the floor's own drain or dip. Lower the underlay; the tile is not holed.
+  - "bare strip ... between <tile> and <wall>": the tile row stops short of the wall.
+  - Areas are measured (a 4 cm seam is a fraction of a square metre).
+- `floating` / `sunken`: props 2 cm above or 3 cm into their support. Sunken names the surface the prop is buried in, seen from above.
+- `interpenetration`: over 3 cm, with every piece it cuts (up to 3). Clear all of them, not only the first.
+- `exposed_edge`: open outline edges of walls, bands, piers and corner blocks that nothing covers within 4-7 mm, seen from walkable space, with the reveal behind them: a 2-60 cm step (an open band end, a module out of line), a seam (the next sheet within 4 cm) or a gap to the next sheet (within 35 cm). A warning on band pieces (and on walls when `depth_step` agrees), a look item on walls. Repeats group per piece type. An open band end at an outside corner: add the corner piece for that band, or wrap one band past the corner by its depth.
+- `open_fixture_end`: an open end of a run piece (a mesh with two or more open rims of one size: a pipe, duct or gutter section, an elbow, a tee) that nothing joins within 2.5 cm, seen from walkable space: a missing elbow, coupler, section or end piece. A piece with one rim, or rims of different sizes (a cap, a funnel, an outlet), is open by design.
+- `depth_step` (look): ray rows across each facade at its band levels and every 1.25 m: band recesses and missing band runs, seams, modules standing proud, holes with something behind them. A hole next to a `through_hole` confirms it (that issue becomes an error). Runs a door-like opening covers are skipped.
+- `orientation`: a long prop near a wall that does not run parallel to it. It never says which way to face.
+- `uv_stretch`: stretched or collapsed texture an instance shows. A face that inserts normally cover is a warning where it shows.
+- `duplicate`: the same scene at the same transform.
+- `z_fight`: coplanar overlapping faces anywhere, including two surfaces of one mesh.
+  - "Coplanar" means closer than twice the 24-bit depth step at the view distance, for the main camera's near and far. `ev` shows the gap, the tolerance and the viewpoint.
+  - `ev.normal` is the shared plane's normal and `ev.nudge` the axis to move along, in the world and in the piece's own frame. A window insert can share its head or a jamb with its host, not its front: nudge along `nudge.local`, not along the facade normal.
+  - A pair whose material may make it intentional comes back as a look item with the reason: `render_priority`, a depth or normal offset, a see-through (alpha) material such as a decal or overlay, or no depth test. Check that it actually renders on top.
+- `lights`: more lights on a mesh than the renderer's per-object limit, and hard spot rims.
+- `transform`: NaN, mirrored, non-uniform scale, far out of bounds, and pieces left at the origin: only an identity LOCAL transform under an identity parent that touches nothing and is not one of a row of siblings. Several pieces sharing that identity transform are a warning each; one alone is a look item. A module whose corner is the world origin is not flagged.
+- `resource`.
+- `budget_ms`: the gap detectors run last on the time the other checks leave. On a large scene the default 3000 ms may cover `exposed_edge` / `depth_step` only partly (band pieces and band rows first). Before calling a facade done, rerun `checks:["exposed_edge","depth_step"]` (or with `budget_ms:6000`) when they show `partial`.
+
+Every check works on any scene from its geometry, the engine's node and resource data and its materials: never node or file names, never kit metadata. The audit decides each piece's role from its shape. See-through cards (every material alpha) are dressing, upright sheets are walls, flat slabs whose tops cover their footprint are floors (a raised one with walls under it is a roof, a large one below the rest is the underlay), a piece in a wall's opening is an insert, and bands, piers and corner blocks against a facade are structure; the rest are props. When a finding looks wrong because the audit read a piece's role differently from you, judge it from the geometry, as the audit did.
+
 ## Choosing the right screenshot
 
 | Question | Call |
@@ -54,9 +91,43 @@ A preset framing re-fits the scene bounds on every capture, so a before/after pa
 
 - **Bookmark once, reuse forever.** `summer_camera_bookmark action:"save" name:"hero"` (omit `position`/`look_at` to capture the current editor 3D viewport camera, or pass both as `"Vector3(x, y, z)"` literals). Then every capture is `summer_screenshot target:"scene" framing:"bookmark" bookmark_name:"hero"` — same pose, real WorldEnvironment, project-persisted (`res://.summer/camera_bookmarks.json`), so it survives sessions and machines. `action:"list"` / `"delete"` manage them.
 - **One-off pose:** `framing:"free"` with `camera_position` + `camera_look_at` (+ `fov`).
-- **Name what you see:** add `marks:true` (cap with `max_marks`) and the caption lists `label -> node path` for the numbered tags drawn over the largest visible 3D nodes. Cite the label AND the path in your claim: "label 3 (`Props/Crate_02`) floats above the floor" — then fix it by that exact path. 2D scenes come back `marks_unsupported`, not annotated.
+- **Name what you see:** add `marks:true` (cap with `max_marks`) and the caption lists `label -> node path` for the numbered tags drawn over the largest visible 3D nodes. Cite the label AND the path in your claim: "label 3 (`Props/Crate_02`) floats above the floor" — then fix it by that exact path. Every labelled node gets an occlusion test from the rendered camera; a label noted `(hidden behind <path>)` sits over whatever is in front of its node, so never cite it. 2D scenes come back `marks_unsupported`, not annotated.
 - **Read the confession.** An engine that predates these framings echoes the preset it fell back to, and the caption says the frame is NOT pose-stable; `marks:true` on such a build draws nothing. Do not compare, and do not read labels, across that warning.
 
+## Environment review: see it like a player and an artist
+
+For "make this place beautiful", one screenshot is not enough evidence. Preview tools; every image comes back inline (one grid per call), rendered from the SAVED scene with its REAL WorldEnvironment and lights, and nothing in the scene changes. Save the scene before each look.
+
+| Need | Call |
+|---|---|
+| Good views you do not have yet | `summer_frame_shot` with `shot` = `establishing`, `eye_level`, `low_angle`, `detail` or `corridor` (+ `subject`, or `spawn` for eye level). Returns the top 3 with score breakdowns, saves the best as a bookmark, renders the 3 as one sheet. |
+| One node group, lit for real | `summer_frame_nodes nodes:[...] direction:"front"` (+ `bookmark_name` to keep the pose, `marks:true` for labels). An explicit `from` is checked: a caption that opens with WARNING means walls block the view or the camera stands behind a one-sided wall and looks THROUGH it; use the nearest valid `from` it offers. |
+| All hero views at once | `summer_shot_sheet shots:[{bookmark_name:"..."}, ...]`. |
+| What changed since last time | `summer_shot_sheet ... compare_previous:true` (or `summer_screenshot framing:"bookmark" compare_previous:true`): previous / now / difference map per bookmark, with the changed-pixel share and where. |
+| Keep or reset the baseline | Plain sheets, debug views and bookmark screenshots never overwrite a bookmark's previous image (they create it when missing). Only `compare_previous:true` (the compared render becomes the next baseline), `update_previous:true`, or re-saving the bookmark's pose with `summer_frame_nodes` / `summer_frame_shot` replaces it. |
+| Why a view reads badly | `summer_debug_views bookmark_name:"..."`: beauty, lighting only, unshaded (albedo), normals, overdraw, wireframe. |
+| A suspicious spot up close | `summer_zoom` with `region:[x, y, w, h]` (rendered exactly, at the region's own aspect) or `mark:N` (from a `marks:true` render of the same pose; pad 0.15, and a warning when that node is hidden): the exact sub-frustum at full resolution. Read the real zoom and any `widened_because` in the caption. |
+
+### The review loop
+
+1. **Bookmark the hero views** once: `summer_frame_shot` for each shot type that matters (an establishing wide, the player's eye at spawn, a corridor per street or lane, a low-angle hero of the landmark, a detail of the best prop). Read the score breakdown and the rejection counts; a pose a wall blocks never ranks, and neither does a camera behind or inside a one-sided wall (`behind_surface`, `inside_volume`: the renderer does not draw a wall's back, so that image would look through it). The top 3 are three different views (one per side while the score allows); the light term prefers side or front-side key light, the edge term penalises sky or void below the horizon.
+2. **After each change** (save first): one `summer_shot_sheet` of all hero bookmarks, `compare_previous:true` when judging a change. Each bookmark keeps exactly ONE previous render in `res://.summer/shots/<bookmark>.jpg`: the compare baseline. A `compare_previous:true` render replaces it after comparing; plain sheets, debug views and screenshots in between leave it alone (pass `update_previous:true` to reset it on purpose).
+3. **Take the weakest shot** to `summer_debug_views`: lighting shows dead-dark areas and missing pools, unshaded shows flat texture and value clashes, wireframe shows floating or duplicated pieces.
+4. **Zoom into each problem** with `summer_zoom` before fixing it, and again after. Cite the mark or region in the claim.
+5. **Find new views** with `summer_frame_shot` whenever the layout changes; bookmark the winners so the sheet stays pose-stable.
+
+### Beauty rubric (judge every sheet against it)
+
+- **Clear focal point**: one subject reads first; the eye has somewhere to go.
+- **Value contrast near versus far**: darker, richer foreground; lighter, hazier distance. A flat-grey frame fails.
+- **Light direction and pools**: a readable key direction, and pools of light where the player should look (doors, lamps, paths); lighting view shows them.
+- **Dressing density at bases and corners**: where walls meet the ground, at corners and doorways, props and grime break the hard line. Empty bases read as unfinished.
+- **No empty frame areas**: no void below the horizon, no blank wall or sky filling a third of the frame without purpose (the frame_shot `void` and `clear` terms flag these).
+- **A level horizon**: no accidental roll; the horizon off the dead center for wide shots.
+- **Foreground framing**: something soft in front (foliage, a fence, a pipe, a doorframe) for depth, never covering the subject.
+
+Disk stays bounded: nothing is written except one previous-image slot per bookmark (created on its first clean render, replaced only as above) and explicit `save_to` copies; JPEG at most 1024 px, at most 20 MB under `res://.summer/shots/` (oldest evicted first); every file there is safe to delete.
+
 ## Runtime reads during playtests
 
 The edited scene is not the running game. While the game runs:
@@ -88,6 +159,9 @@ When the next step depends on the engine reaching a moment — the game booting
 
 | Red flag | Reality |
 |---|---|
+| "The environment looks good" from one screenshot | Judge a shot sheet of the hero bookmarks against the beauty rubric, then debug-view the weakest. |
+| "The scene is done" without a scene audit | Run `summer_scene_audit`, frame every error and look item up close, fix or accept each one, audit again. |
+| Rotating a piece because an orientation look item said so | The audit never says which way to face. Measure the asset (`summer_inspect_asset`), read the kit's own notes, then decide. |
 | Mutating twice in a row without a diff or screenshot between | You are compounding on an unverified base. Verify, then continue. |
 | "The diff is probably fine, the script said ok" | `ok:true` scripts still drop unowned nodes on save. Read the diff. |
 | Judging lighting from an iso/top framing | Flat substitute environment. Use `framing:"camera"`, boot the game, or a probe. |

package/library/skills/verifying-scenes/resource.yaml

@@ -1,12 +1,17 @@
 id: skill/verifying-scenes
 kind: skill
-version: 1.1.1
-summary: Prove scene work landed — snapshot before, diff + screenshot after (bookmarked viewpoint, labels), live runtime reads during playtests — then claim.
+version: 1.5.0
+summary: 'Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms.'
 use_when:
   - after any mutation batch, asset import, or lighting change, before claiming it worked
   - during a playtest, to read live runtime state (spawned nodes, actual stats) without stopping the game
   - deciding what counts as evidence for a visual or structural claim
   - taking before/after screenshots from the same saved camera viewpoint, or an annotated screenshot whose numbered labels map to node paths
+  - '"make this environment beautiful" / reviewing a level like an artist: hero views, a shot sheet after each change, debug views of the weakest shot, zooms into problems'
+  - finding good camera views automatically (establishing, player eye level, low-angle hero, detail, down a lane)
+  - after each build stage of a 3D scene and before calling it done - run the scene audit, then frame every error and look item up close
+  - open band ends and seams on a facade, a gap in a band, a duct missing its elbow - the audit's exposed_edge, depth_step and open_fixture_end checks
+  - accepting the audit's look items you judged fine so later audits stop repeating them
 do_not_use_when:
   - "the engine build lacks GetWorldSnapshot/DiffWorldSnapshot/GetRuntimeSceneTree/GetRuntimeNode (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — fall back to summer_get_scene_tree + summer_screenshot"
 facets:
@@ -30,6 +35,12 @@ related:
     - tool/wait-for-event
     - tool/recent-events
     - tool/camera-bookmark
+    - tool/frame-nodes
+    - tool/shot-sheet
+    - tool/debug-views
+    - tool/zoom
+    - tool/frame-shot
+    - tool/scene-audit
   skills:
     - skill/scene-scripting
     - skill/playtesting-a-feature

package/library/skills/vfx-dissolve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-dissolve
-description: Use when authoring a dissolve effect — an object's mesh disintegrating with a glowing burning edge, driven by a noise threshold ShaderMaterial overriding the target's existing material. Trigger on "dissolve", "disintegrate", "burn away", "Thanos snap", "vanish into ash", "enemy fades out", "object burns up".
+description: "Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-fire/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-fire
-description: Use when authoring a fire visual effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp. Trigger on "torch", "campfire", "bonfire", "flame", "fire effect", "burning", "make this thing on fire", "candle".
+description: "Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-hit-spark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-hit-spark
-description: Use when authoring a hit-spark visual effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact. Trigger on "hit spark", "impact spark", "bullet hit", "sword clash", "metal-on-metal", "ricochet", "impact effect", "spawn sparks at hit point".
+description: "Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-lightning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-lightning
-description: Use when authoring a lightning bolt visual effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake. Trigger on "lightning bolt", "chain lightning", "electric attack", "tesla coil", "shock spell", "thunderbolt", "energy beam".
+description: "Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-magic-glow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-magic-glow
-description: Use when authoring a magic-glow visual effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh. Trigger on "magic glow", "enchanted item", "soul gem", "pulsing aura", "rune glow", "magical orb", "summon circle glow", "fairy", "wisp".
+description: "Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-muzzle-flash/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-muzzle-flash
-description: Use when authoring a muzzle-flash visual 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. Trigger on "muzzle flash", "gun fire", "weapon flash", "barrel flash", "shoot a gun", "spell-cast burst at hand".
+description: "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."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-smoke/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+description: "Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-water-ripple/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+description: "Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/voice-line/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: voice-line
-description: Use when generating TTS voice lines — NPC barks, narrator, dialogue. Covers where voice ids come from, a character-to-voice decision tree, stability/style/similarity guidance, and the multi-line dialogue case via text_to_dialogue. Trigger on "make a voice line", "narrator", "NPC says", "voice for the merchant", "TTS line", "dialogue".
+description: "Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio

package/library/skills/web-and-touch-input/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: web-and-touch-input
+description: "Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: scene-and-project
+user-invocable: false
+allowed-tools: Read Grep summer_input_map_bind summer_add_node summer_set_prop summer_batch summer_write_file summer_save_scene summer_play summer_stop summer_get_diagnostics summer_screenshot
+paths: ["**/*.tscn", "**/*.gd", "**/project.godot"]
+---
+
+# Web and touch input
+
+A browser game is played with a keyboard and mouse on a computer, and with fingers on a phone. Build one set of input actions and drive it from both.
+
+## 1. One set of actions
+
+Bind every control as an input action (`summer_input_map_bind`): `move_left`, `move_right`, `move_up`, `move_down`, `jump`, `action`, `pause`. Game code only reads actions (`Input.get_axis("move_left", "move_right")`, `Input.is_action_just_pressed("jump")`), never raw keys, so touch controls can press the same actions.
+
+## 2. The browser rules
+
+- **Sound and mouse capture need a first click or key.** Browsers block audio and pointer lock until the person interacts. Start music and call `Input.mouse_mode = Input.MOUSE_MODE_CAPTURED` from the title screen's "Click to play" handler, never in `_ready()`.
+- **Escape releases the mouse** in the browser on its own. Treat losing capture as a pause, and recapture on the next click.
+- **Focus:** the game only gets keys after it has been clicked. The title screen's "Click to play" covers this.
+- **Keep keys browser-safe:** avoid Ctrl/Cmd shortcuts, F5, and Tab for gameplay.
+
+## 3. Touch controls, only on touch screens
+
+Add a `TouchControls` CanvasLayer (layer 10) and show it only when `DisplayServer.is_touchscreen_available()` is true:
+
+- **Buttons:** a TouchScreenButton per action, with its `action` property set to the input action name (for example `jump`). It presses the same action as the keyboard. Make them large (at least 96 px), semi-transparent, and placed in the bottom corners, away from the HUD.
+- **Movement:** for left/right only, two TouchScreenButtons (`move_left`, `move_right`). For free movement, a virtual stick: a Control in the bottom-left that reads `InputEventScreenTouch` and `InputEventScreenDrag` within its area and calls `Input.action_press("move_right", strength)` and `Input.action_release(...)` from the drag direction (dead zone about 0.2).
+- **Camera look (3D):** drags on the right half of the screen rotate the camera; keep them separate from the stick's touch index.
+- **Scale:** anchor the layer to the viewport corners so it works in portrait and landscape.
+
+## 4. Verify
+
+Run the game and check the keyboard controls and the title screen's first click. Set `input_devices/pointing/emulate_touch_from_mouse` on temporarily to try the touch buttons with the mouse, then turn it off again.

package/library/skills/web-and-touch-input/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/web-and-touch-input
+kind: skill
+version: 1.0.0
+summary: "Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions."
+use_when:
+  - the game plays in the browser and sound, mouse capture or keys do not work until something is clicked
+  - the game should be playable on a phone or tablet with touch controls
+  - adding a virtual joystick, on-screen buttons or touch camera controls
+facets:
+  lifecycle:
+    - build
+  domains:
+    - gameplay
+    - ui
+  modalities:
+    - scenes
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/character-movement
+    - skill/ui-basics
+source: official
+license: MIT
+status: preview
+recommended: true

package/library/skills/web-compatibility-look/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: web-compatibility-look
+description: "Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: rendering-and-lighting
+user-invocable: false
+allowed-tools: Read Grep summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_batch summer_project_setting summer_save_scene summer_play summer_stop summer_screenshot summer_get_diagnostics
+paths: ["**/*.tscn", "**/*.tres", "**/*.gdshader", "**/project.godot"]
+---
+
+# A great look in the Compatibility renderer
+
+Browser play and web exports run only the **Compatibility** renderer (OpenGL 3 / WebGL 2). Forward+ and Mobile are not available on the web, so a project that plays in the browser must keep:
+
+```
+summer_project_setting(key="rendering/renderer/rendering_method", value="gl_compatibility")
+summer_project_setting(key="rendering/renderer/rendering_method.mobile", value="gl_compatibility")
+```
+
+Never switch it to `forward_plus` or `mobile` for a web game. Features that only exist in Forward+ are ignored or break in Compatibility, so a scene can look fine in a desktop preview and flat or broken in the browser. Design for Compatibility from the start; it can still look premium.
+
+## What to rely on, and what to avoid
+
+| Rely on (works in Compatibility) | Avoid (Forward+ only, or ignored) |
+|---|---|
+| Unshaded and lit StandardMaterial3D, vertex colours, emission | SDFGI, VoxelGI, SSAO, SSIL, SSR |
+| WorldEnvironment: background colour or sky, ambient light, tonemapping, depth fog | Volumetric fog, FogVolume |
+| DirectionalLight3D with shadows, a few Omni/Spot lights | Dozens of shadowed real-time lights |
+| CanvasItem shaders, 2D lights (PointLight2D, DirectionalLight2D), CanvasModulate | GPUParticles with compute-heavy setups (use CPUParticles2D/3D) |
+| CPUParticles2D / CPUParticles3D | Native plugins, threads |
+| Screen-reading canvas shaders (`hint_screen_texture`) for full-screen post effects | Effects you have not seen work in a browser capture |
+
+Glow and some environment adjustments depend on the engine version. If you use them, take a screenshot in the web preview and check that they really show. Never assume a setting worked because the property exists.
+
+## 2D: a finished look
+
+1. **Palette first.** Pick 5 to 7 colours (a dark, a mid, a light, one accent, one danger) and use only those. The player is the brightest, most saturated thing on screen.
+2. **Background with depth.** A GradientTexture2D sky behind two or three Parallax2D layers of simple shapes, each layer lighter and less saturated the further away it is. Nothing is ever a flat default grey.
+3. **Shapes that read.** Polygon2D or `_draw()` per object, with a darker outline (2 to 4 px) and two-tone shading (a lighter top half). Characters get eyes or a face.
+4. **Light and mood.** CanvasModulate tints the world (dusk, night, cave), and PointLight2D with a soft gradient texture makes lamps, pickups and the player glow.
+5. **Post effect, optional.** One full-screen ColorRect on a top CanvasLayer with a canvas_item shader that reads the screen texture: a soft vignette and a slight colour grade. Keep it under a few texture reads.
+6. **Hit flash and juice.** A tiny canvas_item shader (`uniform float flash; COLOR.rgb = mix(COLOR.rgb, vec3(1.0), flash);`) tweened on hits, plus particles and a small camera shake.
+
+## 3D: a finished look
+
+1. **Flat-shaded or stylised materials.** StandardMaterial3D with palette albedo, roughness 1, no metallic. For a toon look use `diffuse_mode = DIFFUSE_TOON` and `specular_mode = SPECULAR_TOON`, or a small spatial shader with banded lighting.
+2. **One sun, real shadows.** One DirectionalLight3D (shadows on, a warm colour) plus an ambient light from the WorldEnvironment in the cool palette colour, so shadows are tinted, not black.
+3. **Depth fog in a palette colour.** Fog that matches the sky colour hides the far edge and gives scale.
+4. **Bake what you can.** Static props can carry vertex-colour ambient occlusion or a hand-painted gradient, which costs nothing at runtime.
+5. **Emission for accents.** Pickups, eyes, lamps and the goal get emissive materials in the accent colour.
+6. **Readable silhouettes.** Keep the camera far enough back, use a slightly saturated rim colour on the player (a fresnel term in a spatial shader), and avoid noisy textures.
+
+## Performance on the web
+
+- Aim for 60 fps on a mid laptop browser: fewer than about 200 visible meshes, shadows on one light only, CPU particles under about 300 alive.
+- Reuse nodes (pools) instead of instancing every frame, and never allocate in `_process`.
+- Keep textures small (1024 px or less) and power-of-two where you can.
+
+## Verify
+
+Run the game, take one screenshot in the web preview, and compare it to the palette and the look. A grey, blank or default-looking capture means the look is not there yet, or a Forward+-only feature was used: fix it before moving on.

package/library/skills/web-compatibility-look/resource.yaml

@@ -0,0 +1,30 @@
+id: skill/web-compatibility-look
+kind: skill
+version: 1.0.0
+summary: "Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance."
+use_when:
+  - the game plays in the browser or is exported for the web and must look finished
+  - the look is flat, grey or default in the web preview, or a Forward+ feature does nothing there
+  - choosing lighting, fog, glow, shaders or post effects for a web or Compatibility project
+facets:
+  lifecycle:
+    - build
+  domains:
+    - rendering
+    - 2d
+    - 3d
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/3d-lighting
+    - skill/art-direction
+    - skill/tune-performance
+    - skill/ui-basics
+source: official
+license: MIT
+status: preview
+recommended: true

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: "Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -24,6 +24,13 @@ Read [references/spatial-tools.md](references/spatial-tools.md) before the first
 
 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.

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

@@ -25,7 +25,7 @@ Interpretation:
 
 ## `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.
+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`,

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

@@ -1,6 +1,6 @@
 id: skill/world-building-3d
 kind: skill
-version: 1.1.0
+version: 1.1.1
 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
@@ -9,6 +9,7 @@ use_when:
 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
+  - placing modular kit pieces (facades, pipes, wall fixtures) from measured geometry — skill/spatial-placement
 facets:
   lifecycle:
     - build

package/library/skills/writing-plans/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-plans
-description: Use when you have a spec or requirements for a multi-step task, before touching code
+description: "Turn a spec or requirements for a multi-step task into a written implementation plan before touching code."
 ---
 
 # Writing Plans

package/library/skills/writing-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-skills
-description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
+description: "Create, edit, and verify agent skills — format, structure, testing with subagents, and best practices."
 ---
 
 # Writing Skills

package/library/templates/3d-lan-multiplayer-starter/resource.yaml

@@ -1,6 +1,6 @@
 id: template/3d-lan-multiplayer-starter
 kind: template
-version: 1.0.1
+version: 1.0.2
 summary: 3D LAN multiplayer starter built on GDQuest's open-source work — host/join flow and synced players.
 use_when:
   - starting a LAN or local multiplayer 3D game
@@ -12,7 +12,7 @@ compatibility:
   engine: ">=4.6"
 source: official
 license: MIT
-status: stable
+status: deprecated
 aliases:
   - template-3d-lan-multiplayer-starter
 repo: https://github.com/SummerEngine/template-3d-lan-multiplayer-starter