summer-engine 2.2.0 → 2.5.0

package/skills/_tests/specs/play.md

@@ -1,88 +0,0 @@
-# Skill Spec: /play
-
-## Fixture
-
-- A Godot/Summer project with a main scene set in `project.godot`.
-- Summer Engine running, MCP available.
-
-## Case 1: Happy Path — clean run
-
-**Fixture:** Project compiles cleanly. Game is not currently running.
-
-**Input:** "Play."
-
-**Expected MCP tool sequence (in order):**
-
-1. `summer_is_running` — false
-2. `summer_get_script_errors` — clean
-3. `summer_clear_console`
-4. `summer_play`
-5. (~2 second wait)
-6. `summer_get_diagnostics`
-7. `summer_get_debugger_errors`
-8. (Skill reports "Running. No errors or warnings.")
-
-**Assertions:**
-
-- [ ] First call is `summer_is_running` to avoid double-launch.
-- [ ] `summer_get_script_errors` runs BEFORE `summer_play` (avoid noisy fail).
-- [ ] `summer_clear_console` runs before `summer_play` (so post-run output is clean).
-- [ ] Skill waits before reading post-play state (≥1 second).
-- [ ] Skill does NOT call `summer_stop` on its own.
-- [ ] Skill reports state in one short sentence, doesn't dump raw tool output.
-
-## Case 2: Failure — game is already running
-
-**Fixture:** Game already running.
-
-**Input:** "Play."
-
-**Expected behavior:**
-
-- `summer_is_running` returns true.
-- Skill asks: "It's already playing. Stop and restart, or leave it?"
-- Waits for user.
-- On "leave it": no further calls. On "stop and restart": `summer_stop`, then continues from step 2.
-
-**Assertions:**
-
-- [ ] Skill does not unilaterally restart.
-- [ ] Skill does not unilaterally `summer_stop` without asking.
-
-## Case 3: Compile error before play
-
-**Fixture:** Script error in `scripts/player.gd:14` (typo). Game not running.
-
-**Input:** "Play."
-
-**Expected behavior:**
-
-- `summer_is_running` → false.
-- `summer_get_script_errors` → returns error.
-- Skill stops, surfaces the error, suggests `/debug`.
-- Does NOT call `summer_play` (would just produce more noise).
-
-**Assertions:**
-
-- [ ] No `summer_play` call when script errors are present.
-- [ ] Error message is one line, not raw tool output.
-- [ ] Skill explicitly mentions `/debug` as the next move.
-
-## Case 4: Runtime crash
-
-**Fixture:** Compiles fine. Game crashes on first frame (e.g. null pointer in `_ready`).
-
-**Input:** "Play."
-
-**Expected behavior:**
-
-- Steps 1–5 run normally.
-- `summer_get_debugger_errors` returns a stack trace.
-- Skill reports the crash in one line and offers `/debug`.
-- Does NOT auto-`summer_stop` — the user might want to inspect.
-
-**Assertions:**
-
-- [ ] Skill detects the crash via `summer_get_debugger_errors`, not by absence of output.
-- [ ] Crash report is concise: error class, location, message.
-- [ ] Skill explicitly mentions `/debug` as the next move.

package/skills/_tests/specs/scene-composition.md

@@ -1,19 +0,0 @@
-# Skill Spec: /scene-composition
-
-> Stub spec. Expand with Happy / Failure / Edge cases. See `fps-controller.md` for the canonical format.
-
-## Fixture
-
-- TBD
-
-## Case 1: Happy Path
-
-**Input:** "<typical user prompt>"
-
-**Expected MCP tool sequence (in order):**
-
-1. TBD
-
-**Assertions:**
-
-- [ ] TBD

package/skills/_tests/specs/setup-multiplayer.md

@@ -1,106 +0,0 @@
-# Skill Spec: /setup-multiplayer
-
-## Fixture
-
-- Godot 4.5 / Summer Engine project, single-player game with `World/Player` (CharacterBody3D) and a working camera + movement script.
-- Summer MCP tools available.
-- Host file tools available (Read, Edit, Write).
-- No multiplayer setup yet (no autoloads, no MultiplayerSpawner, no Synchronizer).
-
-## Case 1: Happy Path — co-op LAN (2–4 players)
-
-**Input:** "Add multiplayer to my game. Co-op for me and three friends."
-
-**Expected MCP tool sequence (in order):**
-
-1. (Skill asks the four blocking questions — type / count / authority / network — and waits.)
-2. User confirms: co-op online, 4 players, host one of the players, public internet.
-3. (Skill explicitly states the locked decision: "Going with **host authority**, ENet transport, 30 Hz input / 20 Hz position. Refactoring authority later is brutal — confirm.")
-4. After user OK:
-   - `summer_get_scene_tree`
-   - `summer_inspect_node "./World/Player"`
-   - `Write scripts/network.gd` (autoload)
-   - `summer_project_setting(name="autoload/Network", value="*res://scripts/network.gd")`
-   - `summer_add_node(parent="./World/Players/Player", type="MultiplayerSynchronizer", name="Sync")` (or the equivalent on the player scene)
-   - SceneReplicationConfig saved as standalone `.tres` (NOT inline)
-   - `Write scripts/player_net.gd`
-   - `summer_save_scene`
-   - `summer_get_script_errors`
-
-**Assertions:**
-
-- [ ] Skill asks all four blocking questions BEFORE any tool call.
-- [ ] Skill explicitly names the authority model (host) and gets a confirmation before mutating.
-- [ ] Skill picks ENet (NOT custom transport, NOT WebRTC).
-- [ ] Generated script uses `MultiplayerSpawner` pattern (host spawns, clients receive).
-- [ ] Player script disables `_physics_process` for non-local peers.
-- [ ] Camera is local-only (`camera.current = is_local`).
-- [ ] Damage RPC checks `multiplayer.is_server()` before applying.
-- [ ] At least one `any_peer` RPC validates `get_remote_sender_id()`.
-- [ ] SceneReplicationConfig is a standalone `.tres`, NOT inline sub_resource.
-- [ ] Skill does NOT replicate cosmetic VFX or local UI.
-- [ ] Final step is `summer_save_scene` then `summer_get_script_errors`.
-
-## Case 2: Failure Path — user wants competitive PvP without dedicated server
-
-**Input:** "Add competitive PvP for 8 players, hosted by one of them, with anti-cheat."
-
-**Expected behavior:**
-
-- Skill names the conflict: "Anti-cheat with host-authority is fundamentally broken — the host can always cheat. For competitive PvP at this scale, you need a dedicated server. Want me to scaffold that path (different code, different deploy story), or are we doing trusted-host co-op-style PvP?"
-- Does NOT silently scaffold host-authority code that the user thinks has anti-cheat.
-- Does NOT scaffold dedicated-server code without explicit confirmation (different complexity).
-
-**Assertions:**
-
-- [ ] Skill flags the architectural impossibility, not just "this is hard".
-- [ ] Skill names the trade-off explicitly (host = host can cheat; dedicated = ops cost).
-- [ ] Skill stops to ask before generating any code.
-- [ ] Skill does NOT just pick host-authority because it's the default.
-
-## Case 3: Edge Case — user says "let's also do rollback netcode for our co-op"
-
-**Fixture:** Same as Case 1.
-
-**Input:** "Add multiplayer with rollback netcode so we don't see lag."
-
-**Expected behavior:**
-
-- Skill calls out: "Rollback netcode is a 6-month project on its own and is the right answer for fighting games / lock-step RTS, not co-op. For co-op, host authority + smooth interpolation gives you 95% of the perceived smoothness for 5% of the work. Want me to scaffold the standard host model?"
-- Does NOT start scaffolding rollback.
-- Does NOT silently downgrade to host-authority — names the choice and the trade-off.
-
-**Assertions:**
-
-- [ ] Skill names rollback as wrong-tool-for-job for co-op.
-- [ ] Skill names the standard alternative (host authority + interpolation).
-- [ ] Skill stops to confirm before scaffolding.
-- [ ] Skill points to specialist skill for lag compensation if user insists on competitive shooter.
-
-## Case 4: No Summer MCP — fallback path
-
-**Fixture:** Same as Case 1, but Summer MCP unavailable.
-
-**Input:** "Add co-op multiplayer for 4 players."
-
-**Expected behavior:**
-
-- Skill detects MCP unavailable.
-- Asks the user to paste their existing main scene `.tscn` so the autoload + spawn paths reference real nodes.
-- Asks the user to paste `project.godot` so the autoload entry can be added by hand.
-- Writes `scripts/network.gd` + `scripts/player_net.gd` directly via host file tools.
-- Provides a manual `project.godot` patch (autoload entry + replication config path) as text the user can paste.
-- Provides scene-editor instructions for adding the MultiplayerSynchronizer + setting up replication properties.
-- Still asks "May I write …" before each file write.
-
-**Assertions:**
-
-- [ ] Skill does not blindly call `summer_*` tools and fail.
-- [ ] Generated scripts compile in Godot 4.5 / Summer Engine.
-- [ ] Skill provides a `project.godot` patch in valid Godot project format.
-- [ ] Skill still asks for confirmation on each write.
-- [ ] Same opinionated decisions hold (host authority, ENet, no replication of cosmetic VFX).
-
----
-
-This spec runs via `/skill-test setup-multiplayer spec` (see `_meta/skill-test/SKILL.md`).

package/skills/_tests/specs/tune-performance.md

@@ -1,104 +0,0 @@
-# Skill Spec: /tune-performance
-
-## Fixture
-
-- Godot 4.5 / Summer Engine project with a 3D scene.
-- Summer MCP tools available (engine running on localhost:6550).
-- Host file tools available (Read, Edit, Write).
-
-## Case 1: Happy Path — rendering hotspot (foliage)
-
-**Fixture:** `World/Foliage` contains 240 individual MeshInstance3D children, all using the same tree mesh. Game runs at ~22 fps, render time ~14 ms / frame.
-
-**Input:** "My game is slow when I look at the forest."
-
-**Expected MCP tool sequence (in order):**
-
-1. (Skill asks one focused question and waits — confirms it's framerate-drops-when-looking-at-X.)
-2. `summer_clear_console`
-3. `summer_play`
-4. (Skill asks user to look at the forest for 5–10 seconds.)
-5. `summer_get_diagnostics` — baseline numbers
-6. `summer_stop`
-7. (Skill identifies render time > 50% frame budget, dominant cost = rendering.)
-8. `summer_get_scene_tree` + `summer_inspect_node "./World/Foliage"` — confirms 240 MeshInstance3D children.
-9. (Skill states hypothesis: "240 MeshInstance3D = 240 draw calls. MultiMeshInstance3D will drop this to ~1.")
-10. (Skill asks: "May I refactor `./World/Foliage` to use a MultiMeshInstance3D? Expected render time: 14 ms → 3–5 ms.")
-11. After OK: applies fix, `summer_save_scene`, `summer_clear_console`, `summer_play`, `summer_get_diagnostics`, `summer_stop`.
-12. Reports before/after.
-
-**Assertions:**
-
-- [ ] Skill takes a baseline measurement BEFORE proposing a fix.
-- [ ] Skill identifies the dominant cost using actual numbers, not a guess.
-- [ ] Skill proposes ONE fix, not a bundle of three.
-- [ ] Proposal includes an expected metric movement (e.g. "14 ms → 3–5 ms").
-- [ ] Skill asks "May I" before mutating.
-- [ ] Skill re-measures after applying the fix and reports before/after.
-- [ ] Skill never optimizes physics or scripting in this scenario (since rendering was dominant).
-
-## Case 2: Failure Path — wrong subsystem hypothesis
-
-**Fixture:** Game stutters every ~3 seconds. User suspects "lag spikes from too many enemies".
-
-**Input:** "Game stutters every few seconds. I think it's the enemy AI."
-
-**Expected behavior:**
-
-- Skill resists the user's guess and takes a baseline.
-- `summer_get_diagnostics` shows: avg frame time fine, but periodic 80 ms spikes.
-- `summer_get_console` shows shader-compilation warnings: "Compiling SpatialMaterial #1234".
-- Skill identifies: this is shader compile jitter, not AI.
-- Skill says: "The spikes correlate with shader compilation, not the AI loop. Fix is a warmup pass on scene load (force-render off-screen to compile materials). Should I add the warmup pass?"
-
-**Assertions:**
-
-- [ ] Skill verifies via diagnostics + console BEFORE accepting the user's hypothesis.
-- [ ] Skill names the actual cause (shader compile) explicitly.
-- [ ] Skill does NOT optimize AI code that wasn't the cause.
-- [ ] Skill proposes a targeted fix (warmup) rather than a generic one.
-
-## Case 3: Edge Case — Summer MCP available but engine not currently running
-
-**Fixture:** Same as Case 1 but the engine is open and idle, not playing.
-
-**Input:** "Why is my game slow?"
-
-**Expected behavior:**
-
-- Skill calls `summer_is_running` → false.
-- Skill explains: "I need to play the game and reproduce the slowdown to get real numbers."
-- Asks user permission: "May I `summer_play` and ask you to reproduce the slow scenario?"
-- After OK: runs the play → reproduce → diagnostics → stop loop.
-- Does NOT skip baseline measurement and just guess from reading code.
-
-**Assertions:**
-
-- [ ] Skill checks `summer_is_running` first.
-- [ ] Skill asks before invoking `summer_play`.
-- [ ] Skill insists on baseline numbers before fixing anything.
-- [ ] Skill does NOT skip straight to "let me read your scripts and guess".
-
-## Case 4: No Summer MCP — fallback path
-
-**Fixture:** Same as Case 1, but Summer MCP unavailable.
-
-**Input:** "My forest scene is slow."
-
-**Expected behavior:**
-
-- Skill detects MCP unavailable.
-- Asks the user to enable Godot's Monitor panel (`Debug → Monitors`) and paste at minimum: FPS, frame time (ms), draw calls, video/video memory used, physics active objects.
-- Reasons over the pasted numbers the same way it would over diagnostics.
-- Continues with hypothesis → proposal → "May I edit?" → manual verification (asks the user to re-run and paste new numbers).
-
-**Assertions:**
-
-- [ ] Skill does not blindly call `summer_*` tools and fail.
-- [ ] Skill asks for the specific numbers it needs (not a vague "tell me more").
-- [ ] Skill still anchors on baseline-first, ONE-fix-at-a-time loop.
-- [ ] Skill names the dominant cost from the user-pasted numbers.
-
----
-
-This spec runs via `/skill-test tune-performance spec` (see `_meta/skill-test/SKILL.md`).

package/skills/_tests/specs/ui-basics.md

@@ -1,19 +0,0 @@
-# Skill Spec: /ui-basics
-
-> Stub spec. Expand with Happy / Failure / Edge cases. See `fps-controller.md` for the canonical format.
-
-## Fixture
-
-- TBD
-
-## Case 1: Happy Path
-
-**Input:** "<typical user prompt>"
-
-**Expected MCP tool sequence (in order):**
-
-1. TBD
-
-**Assertions:**
-
-- [ ] TBD

package/skills/_tests/specs/vfx.md

@@ -1,116 +0,0 @@
-# Skill Spec: /vfx
-
-## Fixture
-
-- Godot 4.5 / Summer Engine project, main scene with `World/Player` (CharacterBody3D + Camera3D) and `World/Enemy` (CharacterBody3D + MeshInstance3D + a `damaged(amount)` signal).
-- `default_bus_layout.tres` defines `Master`, `Music`, `Ambient`, `SFX` buses (at minimum).
-- Summer MCP tools available (engine running on localhost:6550).
-- Host file tools available (Read, Edit, Write).
-
-## Case 1: Happy Path — combat hits feel flat
-
-**Input:** "My combat feels flat. Add some juice."
-
-**Expected behavior:**
-
-1. Skill asks one focused question: "What feels flat? combat hits / pickups / explosions / spell casts / something else."
-2. User says "combat hits".
-3. Skill calls `summer_get_scene_tree`, `summer_inspect_node "./World/Enemy"`, `summer_inspect_node "./World/Player/Camera3D"`, and confirms the audio bus list.
-4. Skill proposes the full trio bundle: "I'm about to add HitFlash on `./World/Enemy`, CameraShake script on `./World/Player/Camera3D`, AudioDucker autoload, and wire the `damaged` signal so one hit fires all three. OK?"
-5. After user OK:
-   - `summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")`
-   - `Write scripts/vfx/hit_flash.gd`
-   - `Write scripts/vfx/camera_shake.gd`
-   - `Write scripts/vfx/audio_ducker.gd`
-   - Register `AudioDucker` as an autoload (project settings or `.cfg` edit).
-   - `summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")`
-   - `summer_save_scene`
-   - `summer_get_script_errors`
-
-**Assertions:**
-
-- [ ] Skill asks the "what feels flat?" question before any tool call.
-- [ ] Skill reads scene tree AND inspects both Enemy mesh and Player Camera3D before mutation.
-- [ ] Skill confirms audio bus names exist before installing AudioDucker.
-- [ ] Skill explicitly states the bundle of changes and asks "May I" / "OK?" before mutation.
-- [ ] HitFlash uses `create_tween()` + `tween_callback`, NOT `await create_timer().timeout`.
-- [ ] HitFlash kills any in-flight tween on re-entry (rapid hits).
-- [ ] CameraShake uses quadratic falloff (`_trauma * _trauma`), NOT linear.
-- [ ] CameraShake subtracts last frame's `_shake_offset` before applying the new one.
-- [ ] AudioDucker captures `_initial_volumes` once in `_ready()` and applies ducking as an offset (relative dB drop), NOT absolute writes.
-- [ ] AudioDucker kills any in-flight tween before starting a new duck.
-- [ ] Final hit flash duration is 0.06–0.12 sec.
-- [ ] Skill never calls `summer_set_resource_property` on an inline sub_resource (e.g. for the flash StandardMaterial3D).
-- [ ] Skill ends with `summer_save_scene` then `summer_get_script_errors`.
-
-## Case 2: Failure Path — missing audio buses
-
-**Fixture:** project's `default_bus_layout.tres` has only `Master`. No `Music`, `Ambient`, `SFX`.
-
-**Input:** "Add hit feedback. Audio ducking too."
-
-**Expected behavior:**
-
-- Skill calls `summer_get_scene_tree` then inspects the bus layout (or asks the user to paste it).
-- Sees only `Master` exists.
-- Skill does NOT install AudioDucker silently — it explains: "Audio ducking only works if at least Music/Ambient/SFX buses exist. With one Master bus, ducking would also duck the impact SFX you're trying to highlight. I can either (a) install hit-flash + camera-shake now and defer ducking until you set up buses via the `audio-direction` skill, or (b) walk through bus setup first."
-- Waits for user choice.
-- Whichever path: hit-flash + camera-shake still install correctly.
-
-**Assertions:**
-
-- [ ] Skill detects single-bus layout and stops to ask.
-- [ ] Skill does NOT register AudioDucker autoload silently.
-- [ ] Skill names `audio-direction` skill as the prerequisite.
-- [ ] Skill still ships the other two systems in this session if the user picks (a).
-
-## Case 3: Edge Case — pickup pulse without trauma
-
-**Fixture:** Same as Case 1, but the user is polishing pickups (peaceful glow), not combat.
-
-**Input:** "Make my health pickups feel more rewarding when collected."
-
-**Expected behavior:**
-
-- Skill asks the focused question; user says "pickups".
-- Skill recognizes pickups should NOT trigger camera shake or aggressive audio ducking — those read as combat, not reward.
-- Skill installs only the HitFlash module (renaming usage as a pickup pulse — same script, called on collection), and proposes a small upward duck (0.2 amount, 0.3 duration) so the pickup "ding" reads above ambient.
-- Skill explicitly says: "Skipping camera shake here — shake reads as 'something hit me', wrong feeling for pickups. Same for heavy ducking. Want a tiny duck (0.2) to make the pickup chime pop?"
-- Does NOT call `add_trauma` from the pickup handler.
-
-**Assertions:**
-
-- [ ] Skill recognizes pickups ≠ combat and adapts the trio.
-- [ ] Skill explicitly skips camera-shake with reasoning, not silently.
-- [ ] HitFlash script is reused (not a forked copy) — `flash()` called on the pickup mesh.
-- [ ] Audio duck `amount` ≤ 0.3, duration ≤ 0.4 (gentle).
-- [ ] Skill does NOT install the full combat trio when the answer was "pickups".
-
-## Case 4: No Summer MCP — file-edit fallback
-
-**Fixture:** Same as Case 1, but Summer MCP is unavailable (Cursor in a project where the engine is not connected).
-
-**Input:** "Add hit-flash + camera-shake + audio ducking to my combat."
-
-**Expected behavior:**
-
-- Skill detects MCP unavailable.
-- Asks the user to paste (a) the relevant `.tscn` snippet showing Enemy + Player + Camera3D node paths, and (b) the bus list from `default_bus_layout.tres`.
-- Writes `scripts/vfx/hit_flash.gd`, `scripts/vfx/camera_shake.gd`, `scripts/vfx/audio_ducker.gd` directly via host file tools.
-- Provides a `.tscn` patch for adding the HitFlash node and a manual instruction for registering the AudioDucker autoload via `project.godot` or the editor.
-- Provides a manual signal-connect instruction (or a `.tscn` connection block) instead of `summer_connect_signal`.
-- Still asks "May I write `scripts/vfx/<file>.gd`?" before each file write.
-- Does NOT blindly call `summer_*` tools.
-
-**Assertions:**
-
-- [ ] Skill identifies MCP unavailable and adapts.
-- [ ] Generated GDScript is syntactically valid Godot 4.5 with type hints.
-- [ ] Skill asks the user to paste the scene snippet AND the bus list.
-- [ ] Skill provides explicit autoload-registration instructions (no `summer_*` autoload tool exists).
-- [ ] Skill applies "May I write …" protocol on each of the 3 file writes.
-- [ ] No `summer_*` tool calls appear in the transcript when MCP is flagged unavailable.
-
----
-
-This spec runs via `/skill-test vfx spec` (see `_meta/skill-test/SKILL.md`).