summer-engine 1.3.1 → 1.4.0

package/skills/_tests/specs/peer-to-peer-multiplayer.md

@@ -0,0 +1,99 @@
+# Skill Spec: /peer-to-peer-multiplayer
+
+## Fixture
+
+- A Godot 4.5 / Summer Engine project that does NOT yet have multiplayer.
+- Project may be empty or may have an existing single-player scene.
+- Summer MCP tools available; engine running on localhost:6550.
+
+## Case 1: Happy Path — fresh multiplayer architecture from scratch
+
+**Input:** "I want to add 2-player co-op to my game. Players will connect through Steam friend invites."
+
+**Expected behavior:**
+
+1. Skill confirms P2P is the right architecture (Steam friend invite ≤8 players → P2P, not dedicated server).
+2. Skill walks the four layers in order, checkpointing between each.
+3. Layer 1: asks "May I create `autoloads/network_manager.gd`?" — creates it on user OK, calls `summer_project_setting` to register the autoload.
+4. Layer 2: asks "May I create `autoloads/game_state.gd` and walk through the authority decision matrix?" — creates it, prompts user for game-specific state fields and proposes ownership.
+5. Layer 3: explains the three RPC patterns with examples; doesn't auto-apply (this is reference material until concrete game logic exists).
+6. Layer 4: defers prediction/interpolation until there's a player scene to apply it to.
+
+**Expected MCP tool sequence (in order, partial):**
+
+1. `summer_get_scene_tree` — see what already exists.
+2. `summer_get_project_context` — read autoload list to avoid name collisions.
+3. (User approves Layer 1) `Write autoloads/network_manager.gd`.
+4. `summer_project_setting(key="autoload/NetworkManager", value="*res://autoloads/network_manager.gd")`.
+5. (User approves Layer 2) `Write autoloads/game_state.gd`.
+6. `summer_project_setting(key="autoload/GameState", value="*res://autoloads/game_state.gd")`.
+7. `summer_save_scene` and `summer_get_script_errors` to verify clean.
+
+**Assertions:**
+
+- [ ] Skill explicitly checks Step 0 (P2P vs. client-server) before any code is written.
+- [ ] Skill creates Layer 1 (NetworkManager) before Layer 2 (GameState).
+- [ ] NetworkManager is the only place that calls `multiplayer.peer_connected.connect()` directly. GameState listens to NetworkManager signals, NOT to the multiplayer API directly.
+- [ ] GameState uses `@rpc("authority", "call_remote", "reliable")` for host-broadcast functions and `@rpc("any_peer", "call_remote", "reliable")` with a `is_host` guard for client-request functions.
+- [ ] Skill walks the user through the authority decision matrix before writing GameState. Doesn't dump generic state fields without asking what the game has.
+- [ ] Skill asks "May I…" before each new file creation and before the autoload registration.
+- [ ] Skill does NOT apply prediction/interpolation in Layer 4 unless there's an existing player scene to wire into.
+- [ ] At any layer, `summer_get_script_errors` is called after the file write to confirm clean compile.
+
+## Case 2: Failure Path — user wants matchmaking at scale
+
+**Input:** "I'm building a competitive shooter. I want matchmaking with anti-cheat for 10,000 concurrent matches."
+
+**Expected behavior:**
+
+- Skill recognizes Step 0: this is dedicated client-server territory, not P2P.
+- Skill explains why P2P is wrong (host can cheat, no anti-cheat hooks, scale concerns).
+- Skill defers to `/summer:client-server-multiplayer` (when shipped) OR explains the user needs to roll a custom server.
+- Does NOT start writing P2P NetworkManager code anyway.
+
+**Assertions:**
+
+- [ ] Skill stops at Step 0 — does NOT proceed to Layer 1.
+- [ ] Skill explains the architecture mismatch in one sentence.
+- [ ] Skill names the right alternative (client-server) and which skill to use instead.
+
+## Case 3: Edge Case — retrofitting multiplayer to a single-player game
+
+**Input:** "I have a single-player platformer that's mostly done. Can you add multiplayer?"
+
+**Expected behavior:**
+
+- Skill is honest about the cost: retrofitting multiplayer is 5× harder than starting MP-first.
+- Skill asks: "Are you committed? It will require auditing every state mutation in your existing code. Time estimate: significant."
+- If user proceeds: skill walks the same 4 layers but adds an AUDIT phase before Layer 2: identify every place existing code writes to state that should be host-authoritative.
+- If user balks: skill points to alternatives (release MP as a sequel; ship single-player; add async leaderboards instead).
+
+**Assertions:**
+
+- [ ] Skill warns about retrofit cost BEFORE starting Layer 1.
+- [ ] Skill adds an AUDIT step that doesn't exist in the happy-path workflow.
+- [ ] Skill never silently proceeds as if the game were greenfield.
+
+## Case 4: No Summer MCP — fallback path
+
+**Fixture:** Same as Case 1, but Summer MCP unavailable.
+
+**Input:** "Add multiplayer to my Godot game (P2P, friend invite)."
+
+**Expected behavior:**
+
+- Skill detects MCP unavailable.
+- Walks the same 4 layers.
+- Instead of `summer_project_setting`, asks the user to manually edit `project.godot`'s `[autoload]` section — provides the exact lines to paste.
+- Instead of `summer_save_scene` / `summer_get_script_errors`, asks the user to save and check errors via the Godot editor.
+- All file writes still go through `Write` host tool with "May I…" approval per file.
+
+**Assertions:**
+
+- [ ] Skill detects MCP unavailable; doesn't blindly call `summer_*` tools and fail.
+- [ ] Project.godot edits are provided as exact paste-able lines.
+- [ ] Workflow shape (4 layers, checkpoints between) is identical regardless of MCP availability.
+
+---
+
+This spec runs via `/skill-test peer-to-peer-multiplayer spec` (see `_meta/skill-test/SKILL.md`).

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

@@ -0,0 +1,106 @@
+# 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

@@ -0,0 +1,104 @@
+# 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/vfx.md

@@ -0,0 +1,98 @@
+# Skill Spec: /vfx
+
+## Fixture
+
+- Godot 4.5 / Summer Engine project, main scene with `World/Player` (CharacterBody3D + Camera3D) and `World/Enemy` (CharacterBody3D + MeshInstance3D + a `damaged` signal on a script).
+- 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 / movement / pickups / damage / explosions / spell casts."
+2. User says "combat hits".
+3. Skill calls `summer_get_scene_tree`, then `summer_inspect_node "./World/Enemy"` to confirm a MeshInstance3D and a `damaged` signal exist.
+4. Skill proposes hit flash + camera shake bundle: "I'm about to add HitFlash on `./World/Enemy`, attach `scripts/hit_flash.gd`, attach `scripts/camera_shake.gd` to `./World/Player/Camera3D`, and connect the `damaged` signal. OK?"
+5. After user OK:
+   - `summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")`
+   - `Write scripts/hit_flash.gd`
+   - `Write scripts/camera_shake.gd`
+   - `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 the scene tree and inspects the relevant node before adding nodes.
+- [ ] Skill explicitly states the bundle of changes and asks "May I" / "OK?" before mutation.
+- [ ] HitFlash script uses Tween + `set_surface_override_material`, NOT a polled timer in `_process`.
+- [ ] CameraShake uses quadratic falloff (`_trauma * _trauma`), NOT linear.
+- [ ] Skill never calls `summer_set_resource_property` on an inline sub_resource (e.g. ParticleProcessMaterial).
+- [ ] Skill ends with `summer_save_scene` then `summer_get_script_errors`.
+- [ ] Final hit flash duration is 0.06–0.12 sec (NOT 0.3 sec).
+
+## Case 2: Failure Path — no Camera3D in scene
+
+**Fixture:** `World/Player` exists but has no Camera3D child. User asks for screen shake.
+
+**Input:** "Add screen shake when I take damage."
+
+**Expected behavior:**
+
+- Skill calls `summer_get_scene_tree` and `summer_inspect_node "./World/Player"`, sees no Camera3D.
+- Skill does NOT silently spawn a Camera3D — it asks: "I don't see a Camera3D under `./World/Player`. Should I add one (and risk conflicting with an existing camera elsewhere), or do you have a camera node I should target?"
+- Waits for the answer.
+
+**Assertions:**
+
+- [ ] Skill detects the missing Camera3D and stops to ask.
+- [ ] Skill does NOT add a Camera3D unilaterally.
+- [ ] Skill names a concrete next-step path (point to existing camera OR add new one explicitly).
+
+## Case 3: Edge Case — user wants "all the juice"
+
+**Fixture:** Same as Case 1.
+
+**Input:** "Add all the VFX. Make it feel like Hades."
+
+**Expected behavior:**
+
+- Skill resists the temptation to stack 5 recipes at once.
+- Anchors on combat hits first (per skill's own guidance: "loudest perceived improvement per minute spent").
+- Says: "I'd rather land hit-flash + screen-shake first so we can see them work, then stack pickups/explosions next. Sound good?"
+- Does NOT propose a single bundle of 5 recipes.
+
+**Assertions:**
+
+- [ ] Skill explicitly chooses ONE recipe to start with, not all.
+- [ ] Skill names "combat hits" as the anchor.
+- [ ] Skill defers other recipes to a follow-up pass.
+
+## 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 a hit flash to my enemy."
+
+**Expected behavior:**
+
+- Skill detects MCP unavailable.
+- Asks the user to paste the relevant `.tscn` snippet (the Enemy node + its children) so the skill can write the right node-path references.
+- Writes `scripts/hit_flash.gd` directly via host file tools.
+- Provides a `.tscn` patch (or step-by-step manual editor instructions) for adding the HitFlash node and connecting the signal — does NOT blindly call `summer_*` tools.
+- Still asks "May I write `scripts/hit_flash.gd`?" before each file write.
+
+**Assertions:**
+
+- [ ] Skill identifies MCP is unavailable and adapts.
+- [ ] Generated GDScript is syntactically valid Godot 4 GDScript with type hints.
+- [ ] Skill asks the user to paste the `.tscn` snippet for accurate node paths.
+- [ ] Skill still applies the "May I write …" protocol on file writes.
+
+---
+
+This spec runs via `/skill-test vfx spec` (see `_meta/skill-test/SKILL.md`).