summer-engine 1.3.2 → 1.5.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/vfx.md

@@ -2,7 +2,8 @@
 
 ## 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).
+- 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).
 
@@ -12,14 +13,16 @@
 
 **Expected behavior:**
 
-1. Skill asks one focused question: "What feels flat? combat hits / movement / pickups / damage / explosions / spell casts."
+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`, 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?"
+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/hit_flash.gd`
-   - `Write scripts/camera_shake.gd`
+   - `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`
@@ -27,71 +30,86 @@
 **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 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 script uses Tween + `set_surface_override_material`, NOT a polled timer in `_process`.
+- [ ] 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.
-- [ ] Skill never calls `summer_set_resource_property` on an inline sub_resource (e.g. ParticleProcessMaterial).
+- [ ] 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`.
-- [ ] Final hit flash duration is 0.06–0.12 sec (NOT 0.3 sec).
 
-## Case 2: Failure Path — no Camera3D in scene
+## Case 2: Failure Path — missing audio buses
 
-**Fixture:** `World/Player` exists but has no Camera3D child. User asks for screen shake.
+**Fixture:** project's `default_bus_layout.tres` has only `Master`. No `Music`, `Ambient`, `SFX`.
 
-**Input:** "Add screen shake when I take damage."
+**Input:** "Add hit feedback. Audio ducking too."
 
 **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.
+- 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 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).
+- [ ] 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 — user wants "all the juice"
+## Case 3: Edge Case — pickup pulse without trauma
 
-**Fixture:** Same as Case 1.
+**Fixture:** Same as Case 1, but the user is polishing pickups (peaceful glow), not combat.
 
-**Input:** "Add all the VFX. Make it feel like Hades."
+**Input:** "Make my health pickups feel more rewarding when collected."
 
 **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.
+- 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 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.
+- [ ] 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 a hit flash to my enemy."
+**Input:** "Add hit-flash + camera-shake + audio ducking to my combat."
 
 **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.
+- 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 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.
+- [ ] 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.
 
 ---