summer-engine 1.4.0 → 1.5.0

package/dist/lib/skills-registry.d.ts

@@ -160,6 +160,22 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_get_scene_tree", "summer_inspect_node", "summer_add_node", "summer_set_prop", "summer_connect_signal", "summer_save_scene", "summer_get_script_errors", "summer_project_setting", "summer_play", "summer_stop"];
     readonly testScenario: "Add co-op LAN multiplayer (2-4 players) using MultiplayerAPI + MultiplayerSpawner + MultiplayerSynchronizer + ENet; lock authority model up front.";
+}, {
+    readonly name: "peer-to-peer-multiplayer";
+    readonly category: "multiplayer-and-networking";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_scene_tree", "summer_inspect_node", "summer_create_scene", "summer_add_node", "summer_set_prop", "summer_connect_signal", "summer_save_scene", "summer_get_script_errors", "summer_project_setting"];
+    readonly testScenario: "Build the four-layer P2P architecture from the ground up (NetworkManager + GameState + RPC patterns + prediction/interpolation) for a 2-player co-op game.";
+}, {
+    readonly name: "host-authoritative-state";
+    readonly category: "multiplayer-and-networking";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_scene_tree", "summer_inspect_node", "summer_save_scene", "summer_get_script_errors"];
+    readonly testScenario: "Walk a 17-field state ownership audit, design a HealthManager + ScoreManager with the canonical Manager pattern, and verify late-join state replay works.";
 }, {
     readonly name: "export-and-ship";
     readonly category: "deployment";

package/dist/lib/skills-registry.js

@@ -332,6 +332,39 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Add co-op LAN multiplayer (2-4 players) using MultiplayerAPI + MultiplayerSpawner + MultiplayerSynchronizer + ENet; lock authority model up front.",
     },
+    {
+        name: "peer-to-peer-multiplayer",
+        category: "multiplayer-and-networking",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_scene_tree",
+            "summer_inspect_node",
+            "summer_create_scene",
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_connect_signal",
+            "summer_save_scene",
+            "summer_get_script_errors",
+            "summer_project_setting",
+        ],
+        testScenario: "Build the four-layer P2P architecture from the ground up (NetworkManager + GameState + RPC patterns + prediction/interpolation) for a 2-player co-op game.",
+    },
+    {
+        name: "host-authoritative-state",
+        category: "multiplayer-and-networking",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_scene_tree",
+            "summer_inspect_node",
+            "summer_save_scene",
+            "summer_get_script_errors",
+        ],
+        testScenario: "Walk a 17-field state ownership audit, design a HealthManager + ScoreManager with the canonical Manager pattern, and verify late-join state replay works.",
+    },
     {
         name: "export-and-ship",
         category: "deployment",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",

package/skills/_tests/specs/design-npc.md

@@ -6,7 +6,7 @@
 - Summer MCP tools available.
 - Host file tools available (Read, Edit, Write).
 
-## Case 1: Happy Path — basic patrol-and-chase enemy
+## Case 1: Happy Path — basic patrol-and-chase enemy with personality + intent
 
 **Input:** "Add a basic enemy that chases the player when it sees them."
 
@@ -16,7 +16,7 @@
 2. User confirms "basic enemy".
 3. `summer_get_scene_tree`
 4. `summer_inspect_node "./World/Player"` — confirms it's in `player` group
-5. (Skill proposes the bundle: scene tree + script + states + telegraph + loot hook + "May I create?")
+5. (Skill proposes the bundle: scene tree + script + personality knobs + intent enum + action SM + telegraph + loot hook + "May I create?")
 6. After user OK:
    - `summer_add_node(parent="./World/Enemies", type="CharacterBody3D", name="Enemy")`
    - `summer_add_node(parent="./World/Enemies/Enemy", type="CollisionShape3D", name="Body")`
@@ -36,9 +36,14 @@
 - [ ] Skill asks the archetype question before any tool call.
 - [ ] Scene has BOTH a Vision Area3D AND a Sight RayCast3D (the two-step perception pattern).
 - [ ] Vision shape is saved as a standalone `.tres`, NOT inline sub_resource (silent-fail trap).
-- [ ] Script defines an `enum State` with at least 4 states (idle / alert / attack / dead).
-- [ ] Script has an attack `telegraph` parameter in 0.3–0.7 sec range.
-- [ ] Script emits a `died` signal.
+- [ ] Script declares four `@export_range(0.0, 1.0)` personality knobs: `aggression`, `patience`, `caution`, `punishment`.
+- [ ] Script jitters personality in `_ready` via `randf_range` clamped to `[0.0, 1.0]`.
+- [ ] Script defines an `enum Intent` with at least 5 values from {IDLE, PATROL, INVESTIGATE, HUNT, KILL, RETREAT, RESCUE_ALLY}.
+- [ ] Script defines an `enum State` with the 4 action states (CALM / ALERT / AGGRESSIVE / DEFEATED).
+- [ ] Intent layer (`_update_intent` / `_decide_intent`) computes `current_intent` from perception + personality.
+- [ ] Action SM (`_update_action`) reads `current_intent`; it does NOT write it.
+- [ ] Script has an `attack_telegraph` parameter in 0.3–0.7 sec range, scaled by aggression at attack time.
+- [ ] Script emits a `died` signal AND an `ally_defeated` signal.
 - [ ] Script uses `distance_squared_to` (NOT `distance_to`) for range comparisons.
 - [ ] Script uses typed GDScript per `_shared/gd-style.md`.
 - [ ] Skill asks "May I create / write …" before each user-visible mutation.
@@ -53,7 +58,7 @@
 **Expected behavior:**
 
 - Skill recognizes the scale conflict.
-- Says: "100 enemies with full FSM + LOS perception will eat your frame budget. For wave mobs at this scale, the right archetype is the wave-mob (2 states, no LOS, direct line to player). Want me to build that instead?"
+- Says: "100 enemies with full intent SM + LOS perception will eat your frame budget. For wave mobs at this scale, the right archetype is the wave-mob (single KILL intent, 2 action states, no LOS). Want me to build that instead?"
 - Does NOT silently build 100 expensive enemies.
 - Offers the trade-off explicitly.
 
@@ -73,8 +78,9 @@
 **Expected behavior:**
 
 - Skill picks the **boss** archetype (different complexity budget).
-- Calls out: "Boss complexity (6–10 states, scripted phases) is at the threshold where a behavior tree might pay off, but I recommend a hand-coded FSM with phase enum first since you're a single dev."
-- Walks the four pillars but at boss scale: more tells per state, telegraph 0.5–0.7 sec, distinct mechanics per phase (cap at 4–6 total mechanics).
+- Calls out: "Boss complexity (6–10 action states, 5–7 intents incl. RESCUE_ALLY, scripted phases) is at the threshold where a behavior tree might pay off, but I recommend a hand-coded FSM with phase enum first since you're a single dev."
+- Recommends boss personality bias: aggression 0.7–0.9, patience 0.7–0.9, punishment 0.8–1.0 (from the tunable matrix).
+- Walks all six pillars at boss scale: more tells per state, telegraph 0.5–0.7 sec, distinct mechanics per phase (cap at 4–6 total mechanics).
 - Defers to `ai-and-npcs/boss-patterns/SKILL.md` for the deeper phase-transition patterns.
 - Does NOT just scale up the basic-enemy stub.
 
@@ -83,6 +89,7 @@
 - [ ] Skill recognizes "boss" requires a different design.
 - [ ] Skill caps at 4–6 distinct mechanics across phases.
 - [ ] Skill mentions phase enum as the FSM extension.
+- [ ] Skill cites boss-archetype personality ranges from the tunable matrix.
 - [ ] Skill defers to boss-patterns for deeper detail rather than trying to one-shot it.
 
 ## Case 4: No Summer MCP — fallback path
@@ -94,19 +101,43 @@
 **Expected behavior:**
 
 - Skill detects MCP unavailable.
-- Asks user to paste the existing scene tree (or the relevant `.tscn` snippet) so node paths are right.
+- Asks user to paste the existing scene tree (or relevant `.tscn` snippet) so node paths are right.
 - Generates a `.tscn` snippet (Enemy + Vision + Sight + Mesh + CollisionShape) with valid Godot 4 scene syntax.
-- Writes `scripts/enemy_ai.gd` directly.
-- Provides manual editor instructions for connecting the `body_entered` signal (or a connection block in the `.tscn`).
+- Writes `scripts/enemy_ai.gd` directly with the personality + intent + action layers intact.
+- Provides manual editor instructions for connecting the `body_entered` signal.
 - Still asks "May I write …" before each file write.
 
 **Assertions:**
 
 - [ ] Skill does not blindly call `summer_*` tools and fail.
 - [ ] Generated `.tscn` is valid Godot 4 syntax (parseable).
-- [ ] Generated GDScript has the same FSM structure (states / telegraph / died signal).
+- [ ] Generated GDScript has personality knobs, intent enum, action SM (same structure as MCP path).
 - [ ] Skill still asks "May I" on writes.
 
+## Case 5: Group emergence — squad of 4 with varied aggression
+
+**Fixture:** Same as Case 1. User wants a small squad, not a wave.
+
+**Input:** "Spawn a patrol squad of 4 basic_grunt enemies near the gate."
+
+**Expected behavior:**
+
+- Skill picks the **basic enemy** archetype with squad framing.
+- Confirms the squad uses the **same `enemy_ai.gd` script and same archetype `.tscn`** — variation comes from per-instance personality jitter, NOT 4 different scripts.
+- Shows / verifies that `personality_jitter` (default 0.15) is set on each instance, with base aggression in the basic_grunt range (0.5–0.7).
+- Predicts the emergent roles: with jitter, post-spawn aggression values land roughly across `0.35 / 0.5 / 0.65 / 0.85` and produce a sniper / anchor / flanker / berserker mix.
+- Does NOT author per-instance roles by hand.
+- Does NOT duplicate the script per role.
+
+**Assertions:**
+
+- [ ] All 4 spawned NPCs use the same script file and same archetype scene.
+- [ ] Each instance's `_ready` jitters all 4 personality knobs via `randf_range` clamped to `[0.0, 1.0]`.
+- [ ] Skill explicitly cites group emergence (varied aggression -> varied roles) instead of authoring roles centrally.
+- [ ] Skill does NOT recommend creating `sniper_ai.gd`, `flanker_ai.gd`, etc. as separate scripts.
+- [ ] Skill calls out that two NPCs with the same base archetype will still feel different post-jitter.
+- [ ] If the user pushes back ("I want one to definitely be a sniper"), skill suggests narrowing that *instance's* base values (e.g., aggression 0.2, caution 0.8) rather than forking the script.
+
 ---
 
 This spec runs via `/skill-test design-npc spec` (see `_meta/skill-test/SKILL.md`).

package/skills/_tests/specs/fps-controller.md

@@ -16,29 +16,41 @@
 1. `summer_get_scene_tree` — verify empty World exists.
 2. `summer_add_node(parent="./World", type="CharacterBody3D", name="Player")`
 3. `summer_add_node(parent="./World/Player", type="CollisionShape3D", name="Collision")`
-4. `summer_add_node(parent="./World/Player", type="Camera3D", name="Camera")`
-5. `summer_set_prop("./World/Player/Collision", "shape", "CapsuleShape3D")` (creates standalone, NOT inline sub-resource)
-6. `summer_set_resource_property("./World/Player/Collision", "shape.height", "1.8")` (only after the shape is standalone)
-7. `summer_set_prop("./World/Player/Camera", "position", "Vector3(0, 1.6, 0)")`
-8. `summer_input_map_bind(name="move_forward", events=[{type:"key", key:"W"}])`
-9. `summer_input_map_bind(name="move_back", events=[{type:"key", key:"S"}])`
-10. `summer_input_map_bind(name="move_left", events=[{type:"key", key:"A"}])`
-11. `summer_input_map_bind(name="move_right", events=[{type:"key", key:"D"}])`
-12. `summer_input_map_bind(name="jump", events=[{type:"key", key:"Space"}])`
-13. (User-side write) `Write` script file `scripts/player_controller.gd` after the agent asks "May I attach the controller script to ./World/Player?"
-14. `summer_save_scene`
-15. `summer_get_script_errors`
+4. `summer_set_prop("./World/Player/Collision", "shape", "CapsuleShape3D")` (creates standalone, NOT inline sub-resource)
+5. `summer_set_resource_property("./World/Player/Collision", "shape", "radius", "0.4")`
+6. `summer_set_resource_property("./World/Player/Collision", "shape", "height", "1.8")`
+7. `summer_add_node(parent="./World/Player", type="Node3D", name="Head")`
+8. `summer_set_prop("./World/Player/Head", "position", "Vector3(0, 1.6, 0)")`
+9. `summer_add_node(parent="./World/Player/Head", type="Camera3D", name="Camera")`
+10. `summer_input_map_bind(name="move_forward", events=[{type:"key", key:"W"}])`
+11. `summer_input_map_bind(name="move_back",    events=[{type:"key", key:"S"}])`
+12. `summer_input_map_bind(name="move_left",    events=[{type:"key", key:"A"}])`
+13. `summer_input_map_bind(name="move_right",   events=[{type:"key", key:"D"}])`
+14. `summer_input_map_bind(name="jump",         events=[{type:"key", key:"Space"}])`
+15. `summer_input_map_bind(name="sprint",       events=[{type:"key", key:"Shift"}])`
+16. (User-side write) `Write` script file `scripts/player_controller.gd` after the agent asks "May I create the controller script and attach it to ./World/Player?"
+17. `summer_save_scene`
+18. `summer_get_script_errors`
 
 **Assertions:**
 
 - [ ] CharacterBody3D node exists at `./World/Player`.
 - [ ] CollisionShape3D is a child of Player with a CapsuleShape3D (NOT BoxShape, NOT SphereShape).
-- [ ] Camera3D positioned at `y ≈ 1.6` (head height).
-- [ ] All 5 input actions bound: `move_forward`, `move_back`, `move_left`, `move_right`, `jump`.
+- [ ] A `Head` Node3D pivots at `y ≈ 1.6` and contains the Camera3D as a child (yaw on body, pitch on head — never both on the body).
+- [ ] All 6 input actions bound: `move_forward`, `move_back`, `move_left`, `move_right`, `jump`, `sprint`.
 - [ ] Skill asks "May I create / attach …" before the script write.
 - [ ] Skill never calls `summer_set_resource_property` on an inline `sub_resource` (the silent-fail trap from `_shared/mcp-tools-reference.md`).
 - [ ] Final step is `summer_save_scene` followed by `summer_get_script_errors`.
 - [ ] Script uses typed GDScript per `_shared/gd-style.md` (`@export`, `:=`, `class_name`).
+- [ ] Script defines `coyote_time` and `jump_buffer_time` as `@export` floats with sensible defaults (0.05–0.2).
+- [ ] Script defines separate `ground_accel`, `ground_friction`, `air_accel`, `air_friction` exports — NOT a single `move_speed` snap-to-target.
+- [ ] Script implements `air_accel < ground_accel` (reduced air control, not zero, not full).
+- [ ] Script defines an `external_velocity: Vector3` accumulator AND a public `add_external_velocity(impulse: Vector3)` method.
+- [ ] Script subtracts the previous frame's external contribution at the top of `_physics_process` BEFORE applying gravity (prevents knockback compounding).
+- [ ] Script uses `move_toward` for horizontal acceleration/deceleration — not `velocity.x = direction.x * speed` snap.
+- [ ] Script applies asymmetric gravity (`fall_gravity_multiplier` when `velocity.y < 0`).
+- [ ] Mouse look pitches `Head`, not `Player`. Pitch is clamped to `[pitch_min, pitch_max]`.
+- [ ] `Input.mouse_mode = Input.MOUSE_MODE_CAPTURED` set in `_ready`.
 
 ## Case 2: Failure Path — existing PlayerOld in scene
 
@@ -83,16 +95,17 @@
 
 **Expected behavior:**
 
-- Skill detects no MCP and falls back to direct file edits on `level.tscn`.
-- Writes a `.tscn` snippet with CharacterBody3D + CollisionShape3D + Camera3D following the format in the skill's "Fallback (no MCP)" sections.
-- Writes `scripts/player_controller.gd` directly via host file-write tools.
-- Edits `project.godot` to add the InputMap actions.
+- Skill detects no MCP and falls back to direct file edits on `level.tscn` (or whatever main scene exists).
+- Writes a `.tscn` snippet with CharacterBody3D + CollisionShape3D + Head Node3D + Camera3D following the format in the skill's "Fallback (no MCP)" section.
+- Writes `scripts/player_controller.gd` directly via host file-write tools — same skeleton as the MCP path (coyote + buffer + air-accel + external-velocity + move_toward).
+- Edits `project.godot` to add the InputMap actions (all 6: WASD + jump + sprint).
 
 **Assertions:**
 
 - [ ] Skill identifies that MCP is unavailable (does not blindly call `summer_*` tools and fail).
-- [ ] Generated `.tscn` is syntactically valid Godot 4 scene format (parseable by Godot).
-- [ ] Generated `project.godot` patch follows Godot's input action format (`input/move_forward = { ... }`).
+- [ ] Generated `.tscn` is syntactically valid Godot 4 scene format (parseable by Godot, includes `[gd_scene ... format=3]` header and a CapsuleShape3D sub-resource with `radius` and `height`).
+- [ ] Generated `project.godot` patch follows Godot's input action format (`input/move_forward = { "deadzone": ..., "events": [...] }`).
+- [ ] Generated script still includes coyote_time, jump_buffer_time, external_velocity, move_toward acceleration model (the fallback path is NOT a downgraded skeleton).
 - [ ] Skill still asks "May I write …" before each file write.
 
 ---

package/skills/_tests/specs/host-authoritative-state.md

@@ -0,0 +1,104 @@
+# Skill Spec: /host-authoritative-state
+
+## Fixture
+
+- A Godot 4.5 / Summer Engine project with `/peer-to-peer-multiplayer` Layer 1 already done — `NetworkManager` autoload exists, exposes `peer_joined` / `peer_left` signals.
+- Project may have a partial player scene; no Managers yet.
+- Summer MCP tools available; engine on localhost:6550.
+
+## Case 1: Happy Path — design HealthManager from scratch with full ownership audit
+
+**Input:** "I want to add health, damage, and a kill counter to my multiplayer game. Help me set it up correctly."
+
+**Expected behavior:**
+
+1. Skill confirms `NetworkManager` already exists; if not, defers to `/peer-to-peer-multiplayer`.
+2. Skill walks the user through the fundamental question on each new field: `health`, `max_health`, `score`, `kills`. All four → host-owned.
+3. Skill proposes one Manager per domain — `HealthManager` for health/max_health, `ScoreManager` for score/kills. Asks before creating each.
+4. For `HealthManager`, skill walks the canonical shape:
+   - Data dict keyed by `peer_id`.
+   - `_host_apply_damage()` mutator with `if not NetworkManager.is_host: return` first line.
+   - `_client_request_damage()` RPC with `@rpc("any_peer", "call_remote", "reliable")` and validation (range, line-of-sight, cooldown, magnitude).
+   - `_broadcast_health()` and `_broadcast_death()` with `@rpc("authority", "call_remote", "reliable")`.
+   - `peer_joined` registers, `peer_left` cleans up.
+5. After file write, `summer_get_script_errors` to verify clean compile.
+
+**Expected MCP tool sequence (partial):**
+
+1. `summer_get_scene_tree` — confirm NetworkManager autoload presence.
+2. `Read autoloads/network_manager.gd` — confirm signals match expected shape.
+3. (User approves HealthManager) `Write autoloads/HealthManager.gd`.
+4. `summer_get_script_errors` to verify.
+5. (User approves ScoreManager) repeat.
+
+**Assertions:**
+
+- [ ] Skill applies the fundamental question explicitly to each field — does not silently dump generic state.
+- [ ] Skill proposes one Manager per domain, not one mega-Manager for all state.
+- [ ] Every `_host_apply_*` function's first line is `if not NetworkManager.is_host: return`.
+- [ ] Every `_client_request_*` is `@rpc("any_peer", "call_remote", "reliable")` and has at least three validators.
+- [ ] Every `_broadcast_*` is `@rpc("authority", "call_remote", "reliable")`.
+- [ ] `peer_joined` and `peer_left` lifecycle is wired in `_ready()`.
+- [ ] Skill does NOT use `MultiplayerSynchronizer` for any health/score field.
+- [ ] Skill asks "May I…" before each new file creation.
+
+## Case 2: Late-join state sync
+
+**Input:** "I have HealthManager working but new players who join mid-match see 100 HP for everyone, even players who are at 30 HP. Fix it."
+
+**Expected behavior:**
+
+- Skill identifies the bug: no late-join state replay.
+- Skill explains the pattern: `_send_full_state(peer_id)` method on each Manager, called from `peer_joined`, uses `rpc_id` (flavor 4) to target only the joining peer.
+- Skill audits all existing Managers for missing `_send_full_state` and adds it.
+- Skill verifies idempotency — receiving a broadcast twice for the same peer must be a no-op.
+
+**Assertions:**
+
+- [ ] Skill diagnoses the missing late-join replay before writing code.
+- [ ] Skill uses `rpc_id(target_peer, ...)` (flavor 4), NOT a broadcast to all peers.
+- [ ] Skill audits ALL existing Managers, not just HealthManager — score, inventory, cooldowns all need the same fix.
+- [ ] Skill checks that broadcast handlers are idempotent before shipping.
+- [ ] `summer_get_script_errors` runs after each file edit.
+
+## Case 3: Edge — client wants to lie about position (client-predicted)
+
+**Input:** "A peer reports another player is teleporting around the map. I added validation to `_client_request_position()` and it blocks legitimate movement. What do I do?"
+
+**Expected behavior:**
+
+- Skill identifies the user has put `position` into the wrong column. Position is **host-authoritative with client prediction**, not pure host-owned.
+- Skill explains: clients send their input/intent (movement direction + jump), not their final position. Host runs the same physics function authoritatively. If host's computed position diverges from client's reported position by more than a tolerance, host snaps the client (reconciliation).
+- Skill removes the `_client_request_position` validator and points to `/peer-to-peer-multiplayer` Layer 4 for the prediction/reconciliation pattern.
+- Skill notes that "blocking" position requests defeats the point of prediction — it would make movement feel terrible. The right response to a divergent client is reconciliation, not rejection.
+
+**Assertions:**
+
+- [ ] Skill recognizes position is the "Sometimes" category from the fundamental question, not pure host-owned.
+- [ ] Skill defers reconciliation logic to `/peer-to-peer-multiplayer` Layer 4 instead of inventing a new pattern.
+- [ ] Skill does NOT propose validating each position update with range/distance checks — that's the wrong tool.
+- [ ] Skill explains why teleport-cheating is caught by reconciliation, not rejection.
+
+## Case 4: No Summer MCP — fallback path
+
+**Fixture:** Same as Case 1, but Summer MCP unavailable.
+
+**Input:** "Add a HealthManager autoload to my multiplayer game."
+
+**Expected behavior:**
+
+- Skill detects MCP unavailable.
+- Walks the same Manager shape (data, mutators, requests, broadcasts, lifecycle).
+- Instead of `summer_get_script_errors`, asks the user to save and check errors via the Godot editor.
+- Provides exact `[autoload]` lines for `project.godot` to paste.
+- File write still goes through `Write` host tool with "May I…" approval.
+
+**Assertions:**
+
+- [ ] Skill detects MCP unavailable; doesn't blindly call `summer_*` tools and fail.
+- [ ] `project.godot` autoload lines are provided as exact paste-able text.
+- [ ] Manager shape (5-part: data / mutators / requests / broadcasts / lifecycle) is identical regardless of MCP availability.
+
+---
+
+This spec runs via `/skill-test host-authoritative-state 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.
 
 ---