summer-engine 2.7.0 → 2.8.0

package/skills/multiplayer-and-networking/host-authoritative-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: host-authoritative-state
-description: Use when designing the state layer of a multiplayer Godot game — deciding what's host-owned, how clients request changes, how the host validates and broadcasts. Pairs with `/peer-to-peer-multiplayer`. Trigger on "host authority", "authoritative state", "state ownership", "MP cheating", "client validation", "RPC patterns".
+description: Use when designing the state layer of a multiplayer Summer game: deciding what the host owns, how clients request changes, and how the host validates and broadcasts. Pairs with `/peer-to-peer-multiplayer`. Trigger on "host authority", "authoritative state", "state ownership", "MP cheating", "client validation", "RPC patterns".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
@@ -134,7 +134,7 @@ func _broadcast_score(peer: int, value: int) -> void:
     score_updated.emit(peer, value)
 ```
 
-- `authority` = only host can call this. Anyone else's call is dropped by Godot.
+- `authority` = only the host can call this. Summer Engine drops other calls.
 - `call_remote` = doesn't run on the caller. Host already wrote the dictionary; no need to re-run locally.
 - `reliable` = state must arrive. Lost packets retry.
 - **Bug if wrong:** if you mark this `any_peer`, a client can fake a score broadcast → desync.
@@ -151,7 +151,8 @@ func _client_request_use_item(item_id: String) -> void:
 ```
 
 - `any_peer` = any client can call.
-- First line is **always** `if not NetworkManager.is_host: return`. Defensive — Godot already routes correctly, this guards against misconfiguration.
+- First line is **always** `if not NetworkManager.is_host: return`. Summer
+  Engine already routes correctly; this also guards against misconfiguration.
 - `multiplayer.get_remote_sender_id()` is trustworthy — clients can't lie about who sent the request.
 - **Bug if wrong:** missing the `is_host` guard means peers process each other's requests and corrupt local state.
 
@@ -284,7 +285,9 @@ Use flavor 4 (`rpc_id`) so only the joining peer gets the replay. Broadcasting t
 
 ## Anti-pattern: the "synced var" temptation
 
-Godot 4 ships a `MultiplayerSynchronizer` node that automatically replicates a list of properties across the network. It's tempting because it removes RPC boilerplate. **It is wrong for anything game-logic-relevant.**
+Summer Engine ships a `MultiplayerSynchronizer` node that automatically
+replicates a list of properties across the network. It is tempting because it
+removes RPC boilerplate. **It is wrong for anything game-logic-relevant.**
 
 `MultiplayerSynchronizer`:
 - Has no validation hook. Writes go through unconditionally.
@@ -321,12 +324,9 @@ This skill writes new autoload files (one per Manager). Always ask before each:
 
 Don't bulk-create five Managers in one shot. Walk one Manager end-to-end (data → mutators → requests → broadcasts → lifecycle) so the user can verify the shape, then repeat for the next domain.
 
-After each Manager file lands, call `summer_get_script_errors` to confirm clean compile. See [`references/collaborative-protocol.md`](../../references/collaborative-protocol.md).
+After each Manager file lands, call `summer_get_script_errors` to confirm clean compile.
 
 ## See also
 
 - [`peer-to-peer-multiplayer`](../peer-to-peer-multiplayer/SKILL.md) — the four-layer architecture overview. Read this first if you haven't.
 - [`setup-multiplayer`](../setup-multiplayer/SKILL.md) — lighter intro that just gets a session running. Use that one if the user just wants two players to see each other.
-- [`references/godot-version.md`](../../references/godot-version.md) — Godot 4.5 multiplayer API stability notes.
-- [`references/gd-style.md`](../../references/gd-style.md) — typed-GDScript conventions used in the examples above.
-- [`references/mcp-tools-reference.md`](../../references/mcp-tools-reference.md) — `summer_get_script_errors` for compile verification.

package/skills/multiplayer-and-networking/peer-to-peer-multiplayer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: peer-to-peer-multiplayer
-description: Use when starting a multiplayer Godot game from scratch — peer-to-peer with host authority. Build the network architecture top-down so authoritative state, routing rules, and real-time rendering aren't bolted on later. Use BEFORE writing game logic, not after. Trigger on "multiplayer", "peer-to-peer", "p2p", "co-op", "host", "multiplayer architecture", "add multiplayer".
+description: Use when starting a multiplayer Summer game from scratch with peer-to-peer host authority. Build the network architecture top-down so authoritative state, routing rules, and real-time rendering are not bolted on later. Use before writing game logic, not after. Trigger on "multiplayer", "peer-to-peer", "p2p", "co-op", "host", "multiplayer architecture", "add multiplayer".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
@@ -42,7 +42,7 @@ If P2P is right, continue. Otherwise, stop and route to the right skill.
 
 A single autoload that owns the network. Nothing else in the game touches `MultiplayerAPI` directly.
 
-May I create `autoloads/network_manager.gd` and register it as a Godot autoload?
+May I create `autoloads/network_manager.gd` and register it as a Summer Engine autoload?
 
 ```gdscript
 class_name NetworkManager
@@ -361,8 +361,6 @@ This skill writes multiple new files (`autoloads/network_manager.gd`, `autoloads
 
 Don't apply all four layers in one shot — checkpoint after each layer so the user can verify before adding the next.
 
-See [`references/collaborative-protocol.md`](../../references/collaborative-protocol.md).
-
 ## Want a working starter?
 
 No template ships with this exact architecture yet — it's deliberately built fresh for each project because the State Layer's authority decisions are game-specific (a stealth game's "visibility" and a shooter's "ammo count" both want host authority but for different reasons). Run this skill from scratch.
@@ -371,8 +369,5 @@ When the `template-co-op-3d` template ships in the registry, this skill will ref
 
 ## See also
 
-- [`references/godot-version.md`](../../references/godot-version.md) — Godot 4.5 multiplayer API stability notes
-- [`references/mcp-tools-reference.md`](../../references/mcp-tools-reference.md) — `summer_project_setting` for autoload registration
-- [`references/gd-style.md`](../../references/gd-style.md) — typed-GDScript conventions
 - [`host-authoritative-state`](../host-authoritative-state/SKILL.md) — deeper dive on JUST the state ownership decision matrix
 - [`setup-multiplayer`](../setup-multiplayer/SKILL.md) — lighter intro that just gets a session running (use that one if the user just wants 2 players to see each other; use this one if they want to ship a real game)

package/skills/multiplayer-and-networking/setup-multiplayer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-multiplayer
-description: Use when the user wants to add multiplayer to an existing single-player game — co-op LAN, co-op online, competitive PvP, or lobbies/matchmaking. Strong opinion that you start with Godot's high-level MultiplayerAPI plus MultiplayerSpawner and MultiplayerSynchronizer; only roll custom networking with a justified reason. Walks peer authority, RPC patterns, replication graph, and irreversible architecture decisions. Trigger on "multiplayer", "co-op", "PvP", "online", "netcode", "rollback", "MultiplayerAPI", "host migration", "matchmaking".
+description: Use when the user wants to add multiplayer to an existing Summer game: co-op LAN, co-op online, competitive PvP, or a lobby. Start with Summer Engine's high-level MultiplayerAPI plus MultiplayerSpawner and MultiplayerSynchronizer; use custom networking only with a justified reason. Walks peer authority, RPC patterns, replication, and irreversible architecture decisions. It does not claim that managed matchmaking or hosting is live. Trigger on "multiplayer", "co-op", "PvP", "online", "netcode", "rollback", "MultiplayerAPI", "host migration", "matchmaking".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
@@ -13,7 +13,10 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres", "project.godot"]
 
 ## Overview
 
-Multiplayer is a one-way door. Pick the wrong authority model and refactoring later is brutal. This skill enforces an opinionated path: **start with Godot's high-level MultiplayerAPI + MultiplayerSpawner + MultiplayerSynchronizer + ENet**. Don't roll custom networking unless you have a measured reason. Make the irreversible decisions up front, in writing.
+Multiplayer is a one-way door. Pick the wrong authority model and refactoring
+later is brutal. Start with **Summer Engine's high-level MultiplayerAPI +
+MultiplayerSpawner + MultiplayerSynchronizer + ENet**. Do not roll custom
+networking without a measured reason.
 
 **Core principle:** the architecture decision (peer authority vs server authority) is harder than the code. Lock it before touching a single RPC.
 
@@ -48,7 +51,9 @@ State the choice explicitly:
 
 ### 3. Pick the transport
 
-Almost always: **ENetMultiplayerPeer**. It's UDP with reliability layers, ships with Godot, and just works for < 32 peers.
+Almost always: **ENetMultiplayerPeer**. It is UDP with reliability layers and
+ships with Summer Engine. Validate the actual game topology and player count;
+this is local netcode, not managed hosting or matchmaking.
 
 When to switch:
 - **WebSocketMultiplayerPeer**: if you need the game to run in the browser (HTML5 export). ENet doesn't work in browsers.
@@ -163,7 +168,7 @@ func _spawn_player(peer_id: int) -> void:
 Register as autoload in `project.godot`:
 
 ```
-summer_project_setting(name="autoload/Network", value="*res://scripts/network.gd")
+summer_project_setting(key="autoload/Network", value="*res://scripts/network.gd")
 ```
 
 #### b) Player scene with MultiplayerSynchronizer
@@ -179,10 +184,14 @@ Player (CharacterBody3D)
 ```
 
 ```
-summer_add_node(parent="./World/Players/Player", type="MultiplayerSynchronizer", name="Sync")
+summer_add_node(scenePath="res://scenes/player.tscn", parent="./World/Players/Player", type="MultiplayerSynchronizer", name="Sync")
 ```
 
-Configure the synchronizer to replicate `position`, `rotation.y`, `health`. Save as a `SceneReplicationConfig.tres` (NOT inline sub_resource — silent-fail trap):
+`scenePath` is required on `summer_add_node`, `summer_set_prop`,
+`summer_connect_signal` and `summer_save_scene`; it names the exact `res://`
+scene to mutate and does not default to the open tab.
+
+Configure the synchronizer to replicate `position`, `rotation.y`, `health`. A standalone `SceneReplicationConfig.tres` is worth it here because the same config is shared by every player instance — not because embedded sub_resources fail (they don't):
 
 ```gdscript
 # scripts/player_net.gd
@@ -259,15 +268,17 @@ Defer to a specialist skill, but flag the basics:
 
 - For projectiles: spawn locally on owner's machine at fire time, replicate the spawn event with a timestamp. Other peers fast-forward the projectile by their RTT.
 - For hit detection: server-authoritative + simple latency tolerance (host accepts hits within ~100ms past server time).
-- For movement: client-side prediction + server reconciliation is the standard model. Godot doesn't ship this — you write it. If users ask for "competitive PvP shooter", say: this is a deeper specialist topic and link `multiplayer-and-networking/lag-compensation/SKILL.md` when it ships.
+- For movement: client-side prediction plus server reconciliation is the
+  standard model. Summer Engine does not provide this game-specific layer; you
+  write it. Competitive PvP requires specialist lag-compensation work.
 
 ### 8. Save and verify
 
 ```
-summer_save_scene
-summer_get_script_errors
+summer_save_scene(scenePath="res://scenes/player.tscn")
+summer_get_script_errors(path="res://scripts/player_net.gd")   # one file per call; path required
 summer_play
-# user tests by running two instances locally (Project → Run Multiple Instances → 2)
+# user tests by running two instances locally (Debug → Customize Run Instances → 2)
 summer_stop
 ```
 
@@ -286,7 +297,7 @@ Test checklist:
 | Replicate every property | Replicate position, rotation, health, that's it | Bandwidth + bug surface |
 | Run physics on every peer for every player | Physics on owner only, others receive transform | Otherwise jitter and divergence |
 | Trust the client | Validate `get_remote_sender_id()` in every `any_peer` RPC | Cheaters route through the wrong RPC |
-| Inline `SceneReplicationConfig` sub_resource | Save as standalone `.tres` | Silent-fail trap (see `references/mcp-tools-reference.md`) |
+| Copy-pasting a `SceneReplicationConfig` per player scene | One standalone `.tres`, referenced everywhere | Replication config must match on every peer; duplicated copies drift |
 | Roll custom transport | ENet (or WebSocket for browser) | You will hit edge cases ENet already solved |
 | Skip authority check in damage RPC | `if not multiplayer.is_server(): return` at the top of damage handlers | Otherwise damage applied N times |
 | Spawn players on every peer | MultiplayerSpawner — host spawns, clients receive | Otherwise N copies of each player |
@@ -298,27 +309,24 @@ Test checklist:
 - **"Let's also have rollback netcode for our co-op shooter."** Rollback is a 6-month project on its own. Use it for fighting games and lock-step RTS, not co-op.
 - **NAT punchthrough on day one.** Use Steam Networking or a relay; don't write punchthrough yourself for v1.
 - **Dedicated servers without a deploy story.** If you can't redeploy in < 5 min, the dedicated path isn't ready.
-- **Custom serialization.** Godot's variant serialization is fine. Don't write your own packing until you measure bandwidth.
+- **Custom serialization.** Summer Engine's variant serialization is fine. Do
+  not write your own packing until you measure bandwidth.
 - **Host migration in v1.** It's a feature, not a primitive. Ship without it; add later if churn data demands.
 
 ## Collaborative protocol
 
-This skill rewires the project at the architectural level. Always ask before each block of changes. Group writes — "I'm about to add the autoload + 2 scenes + 3 scripts + InputMap entries. OK?". See `references/collaborative-protocol.md`.
+This skill rewires the project at the architectural level. Always ask before each block of changes. Group writes — "I'm about to add the autoload + 2 scenes + 3 scripts + InputMap entries. OK?".
 
 ## Want a working starter?
 
 For a known-good multiplayer scaffold (host + join UI, ENet transport, MultiplayerSpawner, replicated player), point users at:
 
-→ **template-id**: TBD (`template-co-op-online` planned, see `references/template-registry.md`)
+→ **template-id**: none ships today. Run `summer list templates` for the live list rather than naming one from memory.
 
 For now: this skill produces the scaffold inline. When the template lands, link from here.
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full MCP tool list (project-setting, autoload registration)
-- `references/godot-version.md` — `MultiplayerAPI` is medium-churn; `SceneReplicationConfig` settled in 4.0+
-- `references/collaborative-protocol.md` — "May I write" pattern
-- `references/gd-style.md` — typed GDScript conventions
 - `multiplayer-and-networking/multiplayerapi-basics/SKILL.md` — deeper MultiplayerAPI patterns
 - `multiplayer-and-networking/client-server-pattern/SKILL.md` — dedicated server architecture
 - `multiplayer-and-networking/peer-replication/SKILL.md` — synchronizer config patterns

package/skills/performance/tune-performance/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: performance
 user-invocable: true
-allowed-tools: Read Grep Glob Edit summer_get_diagnostics summer_get_console summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_play summer_stop summer_is_running summer_clear_console summer_set_prop summer_project_setting
+allowed-tools: Read Grep Glob Edit summer_get_diagnostics summer_get_console summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_play summer_stop summer_is_running summer_clear_console summer_set_prop summer_add_node summer_save_scene summer_batch summer_screenshot summer_project_setting
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres", "project.godot"]
 ---
 
@@ -37,27 +37,45 @@ Wait. The answer narrows the fix domain by 5x:
 
 Don't guess. Read the engine's actual numbers.
 
-**Preferred (Summer MCP):**
+**`summer_get_diagnostics` is NOT a profiler.** It returns counts of console errors, debugger errors, debugger warnings and script errors — nothing else. It carries no FPS, no frame time, no draw calls, no body counts. Never quote a performance number you claim came from it.
+
+**Preferred (Summer MCP): measure inside a verification probe.** `RunVerification` spawns a hidden, disposable game instance with a real renderer, runs your GDScript probe, and dies without touching the user's editor. `Performance.get_monitor(...)` inside that probe returns the real numbers.
 
 ```
-summer_clear_console
-summer_play
-# user reproduces the slowdown for 5–10 seconds
-summer_get_diagnostics
-summer_get_console               # check for warnings (e.g. "shader compilation hot-path")
-summer_stop
+summer_batch ops:[{
+  "op": "RunVerification",
+  "probe_source": "<probe below>",
+  "max_seconds": 20
+}]
+```
+
+```gdscript
+extends SummerProbeBase
+func _ready() -> void:
+    await super._ready()
+    await get_tree().process_frame
+    await get_tree().create_timer(3.0).timeout    # let it settle, then sample
+    report("fps", Performance.get_monitor(Performance.TIME_FPS))
+    report("process_ms", Performance.get_monitor(Performance.TIME_PROCESS) * 1000.0)
+    report("physics_ms", Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS) * 1000.0)
+    report("draw_calls", Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME))
+    report("objects", Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME))
+    report("primitives", Performance.get_monitor(Performance.RENDER_TOTAL_PRIMITIVES_IN_FRAME))
+    report("video_mem", Performance.get_monitor(Performance.RENDER_VIDEO_MEM_USED))
+    report("bodies_3d", Performance.get_monitor(Performance.PHYSICS_3D_ACTIVE_OBJECTS))
+    report("bodies_2d", Performance.get_monitor(Performance.PHYSICS_2D_ACTIVE_OBJECTS))
+    report("objects_total", Performance.get_monitor(Performance.OBJECT_COUNT))
+    save_frame("baseline")
+    finish()
 ```
 
-`summer_get_diagnostics` returns the aggregate metrics. Note (write down before fixing anything):
+Write the returned numbers down before fixing anything. Drive the probe to the slow state first (`press()` / `key()` to spawn the enemies, walk into the bad room) — measuring the main menu tells you nothing.
 
-- Average FPS during the slow section
-- Frame time (ms) — anything over 16.67 ms = below 60 fps
-- Draw calls per frame
-- Active physics bodies
-- Active GPUParticles instances
-- Script time vs. physics time vs. render time
+**Let it settle for at least a second before sampling.** `TIME_FPS` is a per-second average, so a probe that reports at 0.5 s returns exactly `1.0` and looks like a catastrophic stall. An `fps` of exactly `1.0` almost always means you sampled too early, not that the game runs at 1 fps.
 
-**Fallback (no MCP):** ask the user to enable Godot's built-in monitor (`Debug → Monitor` or in-game with `Performance.get_monitor`) and paste numbers. At minimum: FPS, frame time, draw calls, physics active objects.
+**Never profile with `--headless`.** A headless instance has no renderer: `RENDER_TOTAL_DRAW_CALLS_IN_FRAME` and `RENDER_TOTAL_OBJECTS_IN_FRAME` read `0.0`, and the FPS figure is an uncapped loop rate, not the game's framerate. The verify instance is windowed-offscreen precisely so the numbers are real.
+
+**Genuine fallback (engine not running at all):** ask the user to enable Godot's built-in monitor (`Debug → Monitor`, or in-game with `Performance.get_monitor`) and paste numbers. At minimum: FPS, frame time, draw calls, physics active objects.
 
 ### 3. Identify the dominant cost
 
@@ -73,7 +91,7 @@ Decision tree:
 
 ### 4a. Rendering hotspot
 
-Common Godot 4.5 rendering costs, ordered by frequency:
+Common Godot 4.x rendering costs, ordered by frequency:
 
 | Pattern | Symptom | Fix |
 |---|---|---|
@@ -91,6 +109,8 @@ summer_inspect_node "./World/Enemy"
 summer_inspect_resource "./World/Enemy"   # for mesh/material/shape details
 ```
 
+**Bakes you cannot run for the user.** `LightmapGI` bake and the `OccluderInstance3D` bake are editor-process operations — `LightmapGI.bake()` is not exposed to scripting at all, and there is no MCP op for either. You can add and configure the nodes, but the bake itself is a button the user presses in the editor. Say so explicitly rather than reporting the optimization as applied. Navmesh baking, collision-shape generation from meshes, and `ImporterMesh.generate_lods` are all scriptable and remain yours to do.
+
 ### 4b. Physics hotspot
 
 Top patterns:
@@ -165,13 +185,12 @@ After the user approves:
 ```
 # apply the fix (Edit / summer_add_node / summer_set_prop / etc)
 summer_save_scene
-summer_clear_console
-summer_play
-# user reproduces the same scenario
-summer_get_diagnostics
-summer_stop
+# re-run the SAME probe from step 2 — same scene, same settle time, same drive sequence
+summer_batch ops:[{"op": "RunVerification", "probe_source": "<same probe>", "max_seconds": 20}]
 ```
 
+Re-running the identical probe is the whole point: same instance type, same warm-up, same sample point, so the delta is attributable to the fix and not to how the run was taken.
+
 Compare: was the metric movement at least 50% of what was promised? If yes, ship it. If no, the hypothesis was wrong — go back to step 3 with the new numbers.
 
 > Before: 14.2 ms render / 22 fps. After: 4.1 ms render / 58 fps. Shipped.
@@ -180,7 +199,9 @@ Compare: was the metric movement at least 50% of what was promised? If yes, ship
 
 | Don't | Do | Why |
 |---|---|---|
-| Optimize without baseline metrics | Always `summer_get_diagnostics` before and after | "Felt faster" is not a measurement |
+| Optimize without baseline metrics | Always run the measurement probe before and after | "Felt faster" is not a measurement |
+| Quote FPS or draw calls from `summer_get_diagnostics` | It returns error/warning counts only — get numbers from `Performance.get_monitor` in a probe | Reporting a metric the tool never returned is fabrication |
+| Profile with `--headless` | Use the windowed-offscreen verify instance | Headless has no renderer: draw calls read 0 and FPS is a meaningless loop rate |
 | Fix the second-biggest cost | Fix the biggest first, re-measure, re-prioritize | Amdahl's law — the small win evaporates next to the big one |
 | Bundle 5 fixes into one PR | One fix at a time, verify each | Bundles hide regressions. Hard to attribute the win or the loss. |
 | `_process` for everything | 10 Hz timer for AI / distance checks / range polls | 60 Hz AI is wasted CPU |
@@ -200,7 +221,7 @@ Compare: was the metric movement at least 50% of what was promised? If yes, ship
 
 ## Collaborative protocol
 
-This skill makes scene/resource/code changes. Always ask before each fix is applied. See `references/collaborative-protocol.md`.
+This skill makes scene/resource/code changes. Always ask before each fix is applied. See `../../../references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -208,12 +229,10 @@ No template — this is a workflow. Performance tuning is project-specific by de
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full MCP tool list
-- `references/godot-version.md` — Godot 4.5 renderer notes (Compositor, RenderSceneBuffers churn)
-- `references/collaborative-protocol.md` — "May I write" pattern
-- `references/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
-- `performance/profiling-godot/SKILL.md` — deeper Godot profiler usage
-- `performance/draw-call-batching/SKILL.md` — MultiMeshInstance3D patterns
-- `performance/lod-and-culling/SKILL.md` — LOD setup
+- `../../../references/mcp-tools-reference.md` — full MCP tool list
+- `../../../references/godot-version.md` — renderer API churn notes (Compositor, RenderSceneBuffers)
+- `../../../references/collaborative-protocol.md` — "May I write" pattern
+- `../../../references/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
 - `debugging/debug/SKILL.md` — bug triage (related but different)
-- `rendering-and-lighting/baked-vs-realtime-lighting/SKILL.md` — bake decisions
+- `workflow/diagnosing-perf-regressions/SKILL.md` — when it *got* slow rather than always was
+- `rendering-and-lighting/3d-lighting/SKILL.md` — light setup and bake decisions

package/skills/rendering-and-lighting/3d-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 3d-lighting
-description: Use when setting up lighting in a 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows. Covers DirectionalLight3D vs Omni vs Spot, shadow tuning, ambient/sky-driven lighting, and Godot 4.5-era conventions. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient", "sky", "light".
+description: Use when setting up lighting in a Summer Engine 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows. Covers DirectionalLight3D versus Omni versus Spot, shadow tuning, ambient and sky-driven lighting, and the current Summer rendering conventions. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient", "sky", "light".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting
@@ -25,9 +25,13 @@ Set up lighting and environment for 3D scenes. Follow these patterns for outdoor
 
 ### 1. Directional Light (Sun)
 
+Every tool below also takes a **required** `scenePath` (the exact `res://` scene
+to mutate — get it from `summer_get_project_context`). It is elided in these
+snippets for readability; a real call without it is rejected by the tool schema.
+
 ```
-summer_add_node(parent="./World", type="DirectionalLight3D", name="Sun")
-summer_set_prop(path="./World/Sun", key="rotation_degrees", value="Vector3(-45, 30, 0)")
+summer_add_node(scenePath="res://main.tscn", parent="./World", type="DirectionalLight3D", name="Sun")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Sun", key="rotation_degrees", value="Vector3(-45, 30, 0)")
 summer_set_prop(path="./World/Sun", key="light_energy", value="1.0")
 summer_set_prop(path="./World/Sun", key="shadow_enabled", value="true")
 summer_set_prop(path="./World/Sun", key="light_color", value="Color(1, 0.95, 0.9, 1)")
@@ -43,7 +47,7 @@ summer_set_prop(path="./World/WorldEnvironment", key="environment", value="Envir
 ```
 
 Then configure the Environment's sub-properties. The Environment resource has:
-- `background_mode` — 2 for sky, 1 for color, 3 for canvas
+- `background_mode` — 2 for sky, 1 for color, 3 for canvas (`Environment.BG_SKY` = 2, `BG_COLOR` = 1, `BG_CANVAS` = 3; default is 0, `BG_CLEAR_COLOR`)
 - `sky` — Sky resource (ProceduralSkyMaterial or PhysicalSkyMaterial)
 - `ambient_light_source` — AMBIENT_SOURCE_SKY or AMBIENT_SOURCE_COLOR
 - `ambient_light_color`
@@ -103,6 +107,31 @@ Always use `Color(r, g, b, a)` with values 0.0–1.0:
 - Orange (torch): `Color(1, 0.6, 0.2, 1)`
 - Green (alien): `Color(0.5, 1, 0.5, 1)`
 
+## Baked lighting — what you can and cannot do from here
+
+Real-time lighting (everything above) is fully scriptable. Baking is not, and the
+split is worth stating before you promise a user a bake.
+
+| Approach | Callable from MCP / a script? |
+|---|---|
+| DirectionalLight3D / Omni / Spot with `shadow_enabled` | Yes |
+| `WorldEnvironment` + `Environment` (sky, ambient, tonemap, glow, SSAO, SSR) | Yes |
+| `SDFGI` real-time GI | Yes — `Environment.sdfgi_enabled = true`, no bake step at all |
+| `VoxelGI` | Yes — `VoxelGI.bake()` **is** bound to script (`ClassDB.class_has_method("VoxelGI", "bake")` is true) |
+| **`LightmapGI` bake** | **No.** `LightmapGI` exposes only its `set_*` / `get_*` configuration methods — there is no `bake` in its method list on this build. It runs from the editor's Bake Lightmaps button only. |
+| **`OccluderInstance3D` occlusion bake** | **No.** `bake_single_node` is not script-callable either. Editor-only. |
+
+So when the user asks for baked lighting: add and configure the `LightmapGI`
+node and set the meshes' `gi_mode`, then tell them plainly that the bake itself
+is a button they press in the editor and that you cannot trigger it. Do not claim
+a bake happened. If they want GI without a manual step, steer to `SDFGI`
+(`Environment.sdfgi_enabled`, no bake) or `VoxelGI` (whose `bake()` you can call).
+
+Note the related trap: `Engine.has_singleton("EditorInterface")` returns **true**
+even in a headless non-editor process, so it is not a valid capability probe.
+`ClassDB.can_instantiate("EditorScript")` returns false outside the editor and is
+the reliable check.
+
 ## Fallback (no MCP — edit `.tscn` directly)
 
 If Summer MCP isn't connected, append the lighting block to your scene file:
@@ -121,4 +150,4 @@ Then create `Environment` and `Sky` resources via the inspector or load from `.t
 
 ## Collaborative protocol
 
-This skill mutates the scene (adds lights + WorldEnvironment + tunes Environment sub-properties). Always ask before applying: "May I add a DirectionalLight3D Sun with shadows + a WorldEnvironment with a procedural sky?". See `../../references/collaborative-protocol.md`.
+This skill mutates the scene (adds lights + WorldEnvironment + tunes Environment sub-properties). Always ask before applying: "May I add a DirectionalLight3D Sun with shadows + a WorldEnvironment with a procedural sky?".

package/skills/rendering-and-lighting/art-direction/SKILL.md

@@ -113,7 +113,7 @@ Ask:
 
 ### 6. Write the lighting plan
 
-State the plan in one block. For Godot 4.5:
+State the plan in one block. For the current Summer Engine rendering stack:
 
 ```
 Sun: DirectionalLight3D, color #fff2d9, energy 0.9, angle ~30° (warm low-angle)
@@ -133,7 +133,8 @@ NEVER: full-bright modulation, no soft falloff
 
 ### 7. Define post-processing rules
 
-Godot 4.5 post stack: Glow, SDFGI, SSAO, SSR, Adjustments, Color Correction (LUT). State opinions, not options.
+Summer Engine post stack: Glow, SDFGI, SSAO, SSR, Adjustments, Color Correction
+(LUT). State opinions, not options.
 
 ```
 Glow: ON, threshold 0.9, intensity 0.5  (soft bloom on highlights only)
@@ -168,7 +169,7 @@ This is the contract. Five do's, five don'ts. Specific, enforceable.
 - No chromatic aberration / lens flare / motion blur — they're cheap and date-fast.
 ```
 
-### 9. Apply Godot project-level settings
+### 9. Apply Summer project-level settings
 
 Some art-direction calls translate to `project.godot` settings. Apply them.
 
@@ -261,11 +262,11 @@ End with:
 | Procedural skybox without angle | Mid-day sun + uniform fog reads generic. Always angle the sun. |
 | Skipping the lighting plan | Lighting *is* art direction in 3D. Without a plan, every level looks different. |
 | Adopting "AAA realism" at vertical-slice scope | Asset cost is brutal solo. Stylized always wins. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
+| Calling SetResourceProperty before the property holds a resource | Explicit `resource is null` error, not a silent drop. Assign the resource first (`summer_set_prop key="environment" value="Environment"`), then set its sub-properties. Scene-embedded sub_resources are fully supported targets. |
 
 ## Collaborative protocol
 
-This skill writes one design doc (`.summer/art-bible.md`) and may modify `project.godot` settings + the main scene's `WorldEnvironment`. Always ask. See `references/collaborative-protocol.md`.
+This skill writes one design doc (`.summer/art-bible.md`) and may modify `project.godot` settings + the main scene's `WorldEnvironment`. Always ask.
 
 ## Want a working starter?
 
@@ -273,9 +274,6 @@ No template — this is a workflow that produces the bible the rest of the proje
 
 ## See also
 
-- `references/collaborative-protocol.md`
-- `references/godot-version.md` — Godot 4.5 rendering API notes (Compositor moved in 4.4 / 4.5)
-- `references/mcp-tools-reference.md`
 - `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
 - `audio/audio-direction/SKILL.md` — the sonic counterpart
 - `rendering-and-lighting/3d-lighting/SKILL.md` — implements the lighting plan

package/skills/scene-and-project/brainstorm-game/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_scene_tree
+allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_scene_tree summer_read_file summer_write_file
 paths: [".summer/**", "project.godot", "**/*.md"]
 ---
 
@@ -193,16 +193,14 @@ Don't auto-pick. Let them decide.
 
 ## Collaborative protocol
 
-This skill writes one file (`.summer/GameSoul.md`). Always ask before writing. Always show the brief inline before saving so the user can react. See `references/collaborative-protocol.md`.
+This skill writes one file (`.summer/GameSoul.md`). Always ask before writing. Always show the brief inline before saving so the user can react.
 
 ## Want a working starter?
 
-No template — this is a workflow that produces the brief that drives template selection later. Once `.summer/GameSoul.md` exists, `/summer:make-game` can match it against `references/template-registry.md`.
+No template — this is a workflow that produces the brief that drives template selection later. Once `.summer/GameSoul.md` exists, `/summer:make-game` reads it and `summer list templates` shows what's actually available to match against.
 
 ## See also
 
-- `references/collaborative-protocol.md` — "May I write?" pattern
-- `references/template-registry.md` — templates the brief will be matched against later
 - `gameplay-mechanics/design-mechanic/SKILL.md` — design the core loop in detail
 - `level-design/design-level/SKILL.md` — sketch level 1
 - `rendering-and-lighting/art-direction/SKILL.md` — turn the one-phrase look into a full bible

package/skills/scene-and-project/make-game/SKILL.md

@@ -198,7 +198,8 @@ Use `summer:asset-strategy` to decide whether to generate assets, search the lib
 Skill: summer:vfx
 ```
 
-Walks the canonical Godot 4.5 game-feel stack — hit-flash + trauma camera shake + audio ducking — wired so a single hit fires all three.
+Walks the canonical Summer Engine game-feel stack: hit flash, trauma camera
+shake, and audio ducking wired so a single hit fires all three.
 
 ```
 Skill: summer:tune-performance

package/skills/scene-and-project/play/SKILL.md

@@ -34,10 +34,16 @@ If not running, continue.
 
 Cheapest call. If the script won't compile, play will fail with a noisy error — better to surface that clearly first.
 
+`summer_get_script_errors` checks **one** file and `path` is required — there is
+no project-wide form. Call it on the scripts you just touched:
+
 ```
-summer_get_script_errors
+summer_get_script_errors(path="res://scripts/player.gd")
 ```
 
+If you don't know which scripts changed, use `summer_get_diagnostics` instead —
+it takes no arguments and reports editor + runtime counts across the project.
+
 If errors found:
 > Won't run yet — there's a script error: `<one-line summary>`. Want me to /debug it?
 
@@ -85,7 +91,7 @@ Leave the game running. The user wants to play it. Stop only on explicit ask.
 |---|---|
 | User says "play" with no context | Steps 1–5 above |
 | User says "play and watch it for me" | After step 5, set a timer / poll `summer_get_debugger_errors` every few seconds for the duration the user specifies |
-| User says "play the boss fight scene" | Open the specific scene first (`summer_open_scene "scenes/boss_fight.tscn"`), then steps 1–5 |
+| User says "play the boss fight scene" | Pass it directly: `summer_play(scene="res://scenes/boss_fight.tscn")`. `summer_open_scene(path=...)` needs a full `res://` path too — never a bare relative one |
 | Game is already running and user says "play" again | Step 1's check covers it — ask before restarting |
 
 ## Anti-patterns
@@ -100,9 +106,9 @@ This skill mutates engine state (clearing console, starting play). It's a read-s
 
 ## Want a working starter?
 
-No template — works against any Godot/Summer project that has a main scene set in `project.godot`.
+No template. Works against any Summer project that has a main scene set in the
+technical `project.godot` file.
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full tool list
 - `debugging/debug/SKILL.md` — what to do when /play surfaces an error

package/skills/scene-and-project/scene-composition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-composition
-description: Use when building or organizing scenes in Godot — node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, instance vs add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".
+description: Use when building or organizing Summer Engine scenes: node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -80,8 +80,8 @@ Use `./` for paths relative to the scene root:
 
 1. Build the hierarchy in the main scene
 2. Select the root of what you want to extract
-3. Save as scene: `summer_save_scene(path="res://scenes/player.tscn")`. SaveScene saves the current open scene, so build reusable scenes in their own open scene and save them there. Do not handwrite `.tscn` files as the preferred path.
-4. In the main scene, add it with `summer_instantiate_scene(parent="./World", scene="res://scenes/player.tscn", name="Player")`
+3. Save as scene: `summer_save_scene(scenePath="res://scenes/source.tscn", path="res://scenes/player.tscn")`. `scenePath` names the scene being saved and is **required**; `path` is the optional save-as target. There is no "current scene" default.
+4. In the main scene, add it with `summer_instantiate_scene(scenePath="res://main.tscn", parent="./World", scene="res://scenes/player.tscn", name="Player")`
 
 **Practical approach:** Create reusable scenes (player.tscn, enemy.tscn) as separate scene files, then instantiate them into levels.
 
@@ -97,9 +97,9 @@ Use `./` for paths relative to the scene root:
 
 ## Save Conventions
 
-- Always call `summer_save_scene` after changes you want to keep
-- For new scenes: `summer_save_scene(path="res://scenes/level1.tscn")`
-- For existing scenes: `summer_save_scene` (no path, uses current scene path)
+- The mutation tools (`summer_add_node`, `summer_set_prop`, ...) already append one save per call, so a standalone `summer_save_scene` is only for a save-as or an explicit extra flush
+- Save-as: `summer_save_scene(scenePath="res://main.tscn", path="res://scenes/level1.tscn")`
+- Plain save: `summer_save_scene(scenePath="res://main.tscn")` — `scenePath` is required in both forms
 
 ## Common Mistakes
 
@@ -110,7 +110,20 @@ Use `./` for paths relative to the scene root:
 
 ## Fallback
 
-No fallback for this — Summer MCP required. Handwriting `.tscn` files for hierarchy mutations is error-prone (UID collisions, wrong format version, broken sub_resource refs). If MCP isn't connected, open the scene in the Godot editor and use the SceneTree dock.
+MCP is the preferred path, not a requirement. Hand-written `.tscn` text loads and
+instantiates fine — including `[ext_resource]` lines with **no `uid=` field**,
+which the engine resolves by path (verified by loading such a scene on the
+shipped 4.6.1 build). Format version 3 is current for Godot 4.
+
+What actually goes wrong when you hand-write scenes is mundane and checkable:
+a `SubResource("id")` with no matching `[sub_resource id="id"]` block, a
+`parent=` path naming a node that isn't declared above it, or an
+`[ext_resource path=...]` pointing at a file that hasn't been imported yet
+(`--headless --import`, or `summer_import_from_url`, before it will load).
+
+So: use MCP when it's connected because the ops are undoable as one step and the
+engine validates paths for you. When it isn't, write the `.tscn` and then open it
+once to confirm it loads. Do not tell the user it's impossible.
 
 ## Trap — Cross-scene transform leak when copying a scene as a template
 
@@ -143,4 +156,4 @@ Don't skip the player mask update. If you only move foliage to layer 9 without a
 
 ## Collaborative protocol
 
-This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?". See `../../references/collaborative-protocol.md`.
+This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?".

package/skills/scene-and-project/summer-cloud/SKILL.md

@@ -89,4 +89,4 @@ If the MCP tools are unavailable, run the `summer cloud ...` CLI commands direct
 
 ## Collaborative protocol
 
-Push and pull move bytes and can replace files. Always run `summer cloud status` and say what will move before you push or pull: "Push will upload 4 files and delete 0. OK to push?" For any gated deletion, state the exact count and get explicit confirmation before setting `confirmDeletes`. See `../../references/collaborative-protocol.md`.
+Push and pull move bytes and can replace files. Always run `summer cloud status` and say what will move before you push or pull: "Push will upload 4 files and delete 0. OK to push?" For any gated deletion, state the exact count and get explicit confirmation before setting `confirmDeletes`.