summer-engine 1.3.1 → 1.3.2

package/skills/ai-and-npcs/design-npc/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: design-npc
+description: Use when the user wants to design an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior. Walks perception, decision logic, escalation states, animation/audio tells, and defeat handling — outputs a state-machine GDScript stub plus the recommended node tree. Trigger on "enemy", "NPC", "boss", "companion", "AI", "behavior", "mob", "perception", "design enemy".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: ai-and-npcs
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_save_scene summer_get_script_errors summer_input_map_bind
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# /design-npc — Design an NPC's Behavior End-to-End
+
+## Overview
+
+A good NPC is legible: the player can read its mood, predict its next move, and feel the consequence of theirs. This skill walks the design from the inside out — what does the NPC perceive, how does it decide, what tells signal each state, and how does it die or leave the scene. Output: a state-machine GDScript stub plus the scene tree.
+
+**Core principle:** behavior is what the player *sees*, not what the code does. Every state needs a tell.
+
+## Steps
+
+### 1. Pick the NPC archetype
+
+Open with the question. Wait.
+
+> What's the NPC for? Pick the closest:
+> - **Basic enemy** (melee/ranged grunt, dies in 1–3 hits)
+> - **Boss** (named, scripted phases, 30–120 sec fight)
+> - **Quest-giver** (talks, gives objectives, doesn't fight)
+> - **Friendly companion** (follows player, helps in combat)
+> - **Civilian / ambient** (reacts to events, no combat AI)
+> - **Wave-spawned mob** (cheap, many at once, simple behavior)
+
+Each archetype maps to a different complexity budget:
+
+| Archetype | States | Perception | Decision logic | Tells per state |
+|---|---|---|---|---|
+| Basic enemy | 4 (idle / alert / attack / dead) | Sight cone | State machine | Animation + 1 sound |
+| Boss | 6–10 (per phase) | Sight + hearing + scripted | Behavior tree or hand-coded FSM | Full anim suite + VO |
+| Quest-giver | 2 (idle / talking) | Trigger area | None / dialogue tree | Idle anim + greet |
+| Companion | 5 (follow / combat / wait / heal / dead) | Sight + group awareness | State machine + utility scoring | Anim + voice |
+| Civilian | 3 (wander / panic / dead) | Hearing (loud events) | Simple FSM | Anim + scream |
+| Wave mob | 2 (charge / dead) | Direct line to player | None | Anim + impact |
+
+### 2. Sketch the four design pillars
+
+Walk them in order. Don't skip.
+
+#### a) Perception — what does this NPC *sense*?
+
+Pick the minimum. Over-perception = unfair AI. Common sensors:
+
+| Sensor | Node | Cost | Use case |
+|---|---|---|---|
+| Sight cone | RayCast3D + dot product check | Cheap | Standard enemy |
+| Sphere proximity | Area3D with sphere shape | Cheap | "Felt your presence" / aggro range |
+| Hearing event | Signal from world events (gunshot, footstep) | Cheapest (event-driven) | Alert nearby NPCs |
+| Group awareness | Shared signal bus (autoload) | Cheap | Pack tactics |
+| Scripted scripted (boss) | Manual state changes | Free | Phase transitions |
+
+Recommended setup for a basic enemy:
+
+```
+Enemy (CharacterBody3D)
+├── MeshInstance3D
+├── CollisionShape3D
+├── Vision (Area3D)        # sphere shape, radius = sight range
+│   └── CollisionShape3D
+└── Sight (RayCast3D)      # confirms line-of-sight when target in Vision area
+```
+
+The two-step (Area3D for proximity, RayCast3D for line-of-sight) is the right default. Don't raycast every frame to every potential target — first filter by Area3D overlap, then raycast only the candidates.
+
+#### b) Decision logic — state machine vs behavior tree
+
+**Strong recommendation:** start with a state machine. Always.
+
+| | State machine | Behavior tree |
+|---|---|---|
+| Best for | < 10 states, scripted bosses, basic enemies | Reactive complex AI, branching priorities |
+| Author cost | Low — read top to bottom | High — tree structure has its own learning curve |
+| Debug | Print current state | Tree visualizer needed |
+| Common failure | State explosion at ~15 states | Premature complexity |
+
+Use a behavior tree when:
+- You have 10+ states with priority interactions.
+- You want designers (not coders) editing logic.
+- The NPC has simultaneous goals (hunt + survive + cover).
+
+For everything else: FSM. See `scripting-patterns/state-machine-patterns/SKILL.md`.
+
+#### c) Escalation — tells per state
+
+Every state must have at least one *tell* the player can read. List them up front:
+
+| State | Animation tell | Audio tell | VFX tell |
+|---|---|---|---|
+| Idle | Breathing loop, occasional look | Ambient (snore, hum) | None |
+| Alert | Head turn toward target, posture change | "Huh?" / radio chatter | Eye glow / aggro line |
+| Aggressive | Combat pose, weapon raised | Battle cry | Muzzle flash / windup glow |
+| Attacking | Strike anim with telegraph | Swing/shoot sound | Particle trail |
+| Hurt | Stagger anim | Pain sound | Hit flash (see `vfx`) |
+| Defeated | Death anim + ragdoll | Death sound | Loot drop / dissolve |
+
+**Telegraph is non-negotiable for boss/heavy attacks:** 0.3–0.7 sec of windup the player can react to. Faster than 0.3 sec = "unfair"; slower than 0.7 sec = "boring".
+
+#### d) Defeat handling — what happens when it dies?
+
+Plan it. "It just disappears" is bad. Choices:
+
+- **Death animation** plays, body stays for N sec, then `queue_free`.
+- **Ragdoll**: switch CollisionShape from KinematicBody to RigidBody. Adds weight to the kill.
+- **Loot drop**: spawn a pickup at death position.
+- **Cleanup**: remove from group, disconnect signals, free children. Otherwise leak.
+- **Score / quest hook**: emit a `died` signal the gameplay layer listens for.
+
+### 3. Read the scene to find an attach point
+
+```
+summer_get_scene_tree
+summer_inspect_node "./World"
+```
+
+Identify where the NPC will live (a `Enemies` parent, or directly under World). Confirm the player exists for line-of-sight.
+
+### 4. Propose the bundle
+
+> I'm about to design a basic patrol-and-chase enemy. Scene tree: Enemy (CharacterBody3D) + Vision Area3D + Sight RayCast3D + CollisionShape3D + MeshInstance3D. Script `scripts/enemy_ai.gd` with 4 states (idle / alert / attack / dead). Sight cone radius 12m, line-of-sight raycast. Telegraph: 0.5 sec windup before attack. Drop loot on death. May I create the scene + script?
+
+### 5. Build it
+
+**Preferred (Summer MCP):**
+
+```
+summer_add_node(parent="./World/Enemies", type="CharacterBody3D", name="Enemy")
+summer_add_node(parent="./World/Enemies/Enemy", type="CollisionShape3D", name="Body")
+summer_add_node(parent="./World/Enemies/Enemy", type="MeshInstance3D", name="Mesh")
+summer_add_node(parent="./World/Enemies/Enemy", type="Area3D", name="Vision")
+summer_add_node(parent="./World/Enemies/Enemy/Vision", type="CollisionShape3D", name="VisionShape")
+summer_add_node(parent="./World/Enemies/Enemy", type="RayCast3D", name="Sight")
+summer_set_prop(path="./World/Enemies/Enemy/Sight", key="enabled", value="true")
+summer_set_prop(path="./World/Enemies/Enemy/Sight", key="target_position", value="Vector3(0, 0, -12)")
+```
+
+Set the vision shape to a SphereShape3D with `radius = 12`. Save as standalone `.tres` (do NOT inline sub_resource — see `_shared/mcp-tools-reference.md` § "Trap"):
+
+```
+# Save shape resource externally, then:
+summer_set_prop(path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="res://shapes/vision_sphere.tres")
+```
+
+Connect the area signal:
+
+```
+summer_connect_signal(from="./World/Enemies/Enemy/Vision", signal="body_entered", to="./World/Enemies/Enemy", method="_on_target_seen")
+```
+
+**Fallback (no MCP):** write the scene as `.tscn` text. Ask user to paste their existing scene first, then propose a unified diff.
+
+### 6. Drop the script
+
+`scripts/enemy_ai.gd` (FSM stub):
+
+```gdscript
+class_name EnemyAI
+extends CharacterBody3D
+
+enum State { IDLE, ALERT, ATTACK, DEAD }
+
+@export var move_speed: float = 3.5
+@export var attack_range: float = 2.0
+@export var attack_telegraph: float = 0.5
+@export var attack_damage: int = 10
+@export var max_health: int = 30
+
+@onready var sight: RayCast3D = $Sight
+@onready var vision: Area3D = $Vision
+@onready var anim: AnimationPlayer = $AnimationPlayer
+
+signal died(position: Vector3)
+
+var _state: State = State.IDLE
+var _target: Node3D = null
+var _health: int = 30
+
+func _ready() -> void:
+    _health = max_health
+    vision.body_entered.connect(_on_body_entered)
+
+func _physics_process(delta: float) -> void:
+    match _state:
+        State.IDLE:
+            _process_idle(delta)
+        State.ALERT:
+            _process_alert(delta)
+        State.ATTACK:
+            _process_attack(delta)
+        State.DEAD:
+            pass
+    move_and_slide()
+
+func _process_idle(_delta: float) -> void:
+    velocity = Vector3.ZERO
+    # transition handled by _on_body_entered
+
+func _process_alert(_delta: float) -> void:
+    if _target == null:
+        _change_state(State.IDLE)
+        return
+    if not _has_line_of_sight(_target):
+        _change_state(State.IDLE)
+        _target = null
+        return
+    var dir := (_target.global_position - global_position).normalized()
+    velocity = dir * move_speed
+    look_at(_target.global_position, Vector3.UP)
+    if global_position.distance_squared_to(_target.global_position) < attack_range * attack_range:
+        _change_state(State.ATTACK)
+
+func _process_attack(_delta: float) -> void:
+    velocity = Vector3.ZERO
+    # attack handled in _change_state via async telegraph
+
+func _change_state(new_state: State) -> void:
+    if _state == new_state:
+        return
+    _state = new_state
+    match new_state:
+        State.IDLE:
+            anim.play("idle")
+        State.ALERT:
+            anim.play("alert")
+        State.ATTACK:
+            _execute_attack()
+        State.DEAD:
+            anim.play("death")
+            died.emit(global_position)
+            await get_tree().create_timer(2.0).timeout
+            queue_free()
+
+func _execute_attack() -> void:
+    anim.play("attack_windup")
+    await get_tree().create_timer(attack_telegraph).timeout
+    if _state != State.ATTACK or _target == null:
+        return
+    if global_position.distance_squared_to(_target.global_position) < (attack_range * 1.2) ** 2:
+        if _target.has_method("take_damage"):
+            _target.take_damage(attack_damage)
+    anim.play("attack_recover")
+    await anim.animation_finished
+    _change_state(State.ALERT)
+
+func _has_line_of_sight(target: Node3D) -> bool:
+    sight.target_position = sight.to_local(target.global_position)
+    sight.force_raycast_update()
+    if not sight.is_colliding():
+        return true
+    return sight.get_collider() == target
+
+func _on_body_entered(body: Node3D) -> void:
+    if body.is_in_group("player") and _state == State.IDLE:
+        _target = body
+        _change_state(State.ALERT)
+
+func take_damage(amount: int) -> void:
+    if _state == State.DEAD:
+        return
+    _health -= amount
+    if _health <= 0:
+        _change_state(State.DEAD)
+```
+
+Key design notes embedded above:
+- Telegraph (`attack_telegraph`) is a parameter — designers can tune feel.
+- `take_damage` is the public hook the player's weapon calls.
+- `died` signal is the gameplay-layer hook (loot, score, quest progress).
+- `distance_squared_to` for comparisons (no sqrt cost).
+- LOS check uses `force_raycast_update` for one-shot precision.
+
+### 7. Verify
+
+```
+summer_save_scene
+summer_get_script_errors
+summer_play
+# user tests
+summer_stop
+```
+
+If the enemy doesn't aggro, common causes:
+- Player isn't in `player` group.
+- Vision Area3D's sphere shape is inline sub_resource (silent fail).
+- Sight RayCast3D `enabled = false` or `collide_with_areas = true` blocking on its own Vision area.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| 360° perception | Sight cone or sphere with raycast LOS | "Sees through walls" feels unfair |
+| Instant attack | 0.3–0.7 sec telegraph | Player needs to read the swing |
+| Behavior tree for a grunt | State machine with 4 states | BT overhead unjustified at low complexity |
+| Per-frame `get_tree().get_first_node_in_group("player")` | Cache target on aggro | Tree walks aren't free |
+| `distance_to` in `_physics_process` | `distance_squared_to` for comparisons | Square root costs at scale |
+| Same animation in all states | Distinct animations per state | The state machine is invisible; animations make it visible |
+| `queue_free()` instantly on death | Death anim → 2 sec → free | Instant despawn breaks immersion + skips loot drops |
+| Inline SphereShape3D for Vision Area3D | Standalone `.tres` | Inline sub_resources break SetResourceProperty |
+| 100+ enemies with full FSM | Wave-mob archetype (2 states, no LOS) | Cheap mobs need cheap brains |
+| No `died` signal | Emit on death | Gameplay layer needs the hook |
+
+## Anti-patterns
+
+- **"AI that dodges everything."** Enemies that 100% dodge feel cheap. Random reaction time (50–250 ms) reads as skill, not aimbot.
+- **Boss with 12 unique mechanics.** Cap at 4–6 distinct mechanics across phases. Players can't track more.
+- **Companion that walks through doors.** NavigationAgent3D with proper navmesh. Don't fake it with raw `move_toward`.
+- **Civilian that screams forever.** Add a calm-down state on a 5–10 sec timer.
+
+## Collaborative protocol
+
+This skill writes scenes and scripts. Always ask before each step. Group related writes into one ask. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+For a fully-rigged enemy with anim controller + loot drop:
+
+→ **template-id**: `template-3d-fps` — ships with a sample patrol enemy
+→ **Repo**: https://github.com/SummerEngine/FPS-template-Summer-Engine
+
+For higher-complexity AI (boss with phases, behavior trees), defer to `ai-and-npcs/behavior-trees/SKILL.md`.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full MCP tool list
+- `_shared/godot-version.md` — Godot 4.5 API notes
+- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `_shared/gd-style.md` — typed GDScript conventions
+- `ai-and-npcs/state-machine-npc/SKILL.md` — FSM pattern deep dive
+- `ai-and-npcs/behavior-trees/SKILL.md` — when complexity demands a BT
+- `ai-and-npcs/perception-sight-and-hearing/SKILL.md` — sensor patterns
+- `ai-and-npcs/navmesh-pathfinding/SKILL.md` — NavigationAgent3D for movement
+- `ai-and-npcs/llm-driven-dialogue/SKILL.md` — Summer's wedge for talking NPCs
+- `ai-and-npcs/boss-patterns/SKILL.md` — phase transitions, mechanics
+- `visual-effects/vfx/SKILL.md` — hit flash and death VFX recipes
+- `scripting-patterns/state-machine-patterns/SKILL.md` — generic FSM patterns

package/skills/audio/audio-direction/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: audio-direction
+description: Use when defining the sonic identity — music style, instruments, SFX vocabulary, dynamic music plan. Outputs an audio bible at `.summer/audio-bible.md`. Trigger on "audio direction", "audio bible", "music style", "sound design", "what should it sound like", "dynamic music".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: audio
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_scene_tree summer_inspect_node summer_add_node summer_project_setting summer_generate_audio
+paths: [".summer/**", "project.godot", "**/*.tscn", "audio/**"]
+---
+
+# /audio-direction — Define the Sonic Identity
+
+## Overview
+
+Most indie games sound like a single library used flat. The same generic "swoosh" for menu, jump, pickup, hit. That's not audio direction — that's audio absence. This skill builds an audio bible that names the music style, the SFX vocabulary, the dynamic music plan, and the spatial / mix rules. Writes to `.summer/audio-bible.md` and configures the audio bus layout in the project so the rest of the work has a real foundation.
+
+**Core principle:** SFX needs a *vocabulary*, not a *library*. Eight named SFX classes with consistent character beat 80 random library hits.
+
+## Steps
+
+### 1. Open with three references
+
+Ask exactly this:
+
+> Three reference tracks, games, or films for the music. What instruments matter? And what's the SFX vibe — chunky, clean, synthetic, or organic?
+
+Three is the minimum. One or two collapses into a clone. References are the highest-signal input — listen carefully.
+
+If they freeze, offer four axes (not titles):
+
+> Pick the closest: a) orchestral + cinematic (Hollow Knight, Journey), b) lo-fi electronic + ambient (Disco Elysium, Outer Wilds), c) chiptune / synth (Hyper Light Drifter, Celeste), d) acoustic / folk (Sable, A Short Hike).
+
+### 2. Read the brief and art bible if they exist
+
+```
+Read .summer/GameSoul.md
+Read .summer/art-bible.md
+```
+
+Audio must rhyme with the visuals. Quote it back:
+
+> Art bible says "soft, hand-warmed, golden-hour, painterly". That rhymes with acoustic / folk / lo-fi over orchestral or aggressive synth. Confirming.
+
+If the brief says "horror", that constrains the music style harder than the user's references will. Name the constraint.
+
+### 3. Pin the music style
+
+Force one primary style. Sub-styles can blend, but a primary is required.
+
+| Style | Anchor instruments | Pairs with | Avoid |
+|---|---|---|---|
+| Orchestral cinematic | Strings, brass, choir | Story-led, fantasy | Casual / cozy |
+| Acoustic / folk | Guitar, piano, hand percussion | Cozy, narrative | Action / horror |
+| Lo-fi electronic | Vintage synth pad, tape sat, light beat | Atmospheric, indie | Combat-heavy |
+| Chiptune / synthwave | 8-bit / 16-bit chips, FM synth | Retro, platformer | Realism |
+| Industrial / metal | Distorted bass, percussion-led | Horror, action | Cozy |
+| Ambient drone | Pads, no drums, slow movement | Walking sim, horror | Action |
+| Jazz / fusion | Live instruments, improv | Stylish, narrative | Generic action |
+| Tracker / hyperpop | Glitchy, dense, modern | Esoteric, indie | Mass appeal |
+
+Ask:
+
+> One primary style. Which?
+
+### 4. Define tempo + key range
+
+Concrete numbers, not "varies".
+
+```
+Tempo range: 80–110 BPM (slow side; combat would push 120+)
+Key center: D minor (warm but melancholic)
+Modulation rule: combat tracks shift to D dorian, calm tracks to D natural minor
+Time signature: 4/4 default; 6/8 for emotional cues
+```
+
+### 5. Build the SFX vocabulary
+
+Eight named classes. Each class has a *character*, not a single sound.
+
+| Class | Character | Examples in this game | DON'T |
+|---|---|---|---|
+| **UI** | Soft, woody, short (60-100ms) | Menu hover, button click, tab switch | No bell tones, no synth blips |
+| **Pickup positive** | Warm, ascending interval (major third), 200-400ms | Coin, key, heal | No pure sine "ding" |
+| **Pickup neutral** | Brief tactile, no melodic component | Note, breadcrumb, lore item | No ascending pitch (reads as reward) |
+| **Negative / damage** | Punchy low-mid, slight detune | Player hit, enemy hit, fall damage | No long reverb tail |
+| **Movement / footstep** | Material-aware (wood / stone / grass) | Walk, run, jump, land | No same sample for all surfaces |
+| **Attack / action** | Front-loaded transient, short body | Swing, parry, dash | No layered orchestral hit |
+| **Ambient layer** | Continuous, low presence | Wind, room tone, distant waves | No looping melody |
+| **Stinger / event** | Distinctive, rare, melodic | Boss intro, level clear, story beat | No reuse for normal events |
+
+Ask:
+
+> Eight classes above. Adjust any character / examples / DON'Ts?
+
+### 6. Define the dynamic music plan
+
+Static music = one track loops forever in a level. Boring. Dynamic music = layers swell with player state. Pick a model.
+
+| Model | How it works | Cost | Best for |
+|---|---|---|---|
+| **Layered stems** | One bar / multiple instrument layers; combat adds drum stem, calm removes it | Medium (need stems authored) | Most games |
+| **Vertical re-orchestration** | Same melody, different instrumentation per state | High (composer-led) | Story-led / boss-heavy |
+| **Horizontal sequencing** | Different tracks for different states, crossfade | Low (just author 3-5 full tracks) | Vertical slice scope |
+| **Procedural / generative** | Generate from rules in real-time | High dev cost | Special-case |
+
+Pick one. State the state machine:
+
+```
+States:
+  CALM        — exploration, low intensity
+  TENSION     — enemies aware but not engaged
+  COMBAT      — engaged
+  VICTORY     — encounter cleared (4-second sting → return to CALM)
+
+Transitions:
+  CALM → TENSION   when an enemy detects the player (2s crossfade)
+  TENSION → COMBAT when first damage exchanged (instant drum stem)
+  COMBAT → VICTORY when last enemy dies (drum stem cuts, brass swell)
+  VICTORY → CALM   after 4s
+
+Rules:
+  No state stays > 90s without variation (loop with bar-1 randomization)
+  Volume ducking: dialogue active → music -6dB
+  Boss music is its own track; ignores normal state machine
+```
+
+### 7. Define the spatial + mix rules
+
+| Rule | Value |
+|---|---|
+| 3D attenuation curve | Inverse-square (default), max distance 25m |
+| Reverb buses | 1 small (interior), 1 large (cave / hall), 1 outdoor |
+| HRTF for player | ON (headphone-friendly directional cues) |
+| Master ceiling | -1 dBTP (true peak, no clipping on consoles) |
+| Music vs SFX vs UI mix | -8 dB / 0 dB / -3 dB (SFX is loudest) |
+| Footstep rolloff | Cuts at 4m for player; cuts at 10m for NPC (player needs them, distant NPCs are noise) |
+| Compression | Light bus compression on master (2:1, slow attack, 100ms release) |
+
+### 8. Configure the audio bus layout
+
+Real audio in Godot needs a bus layout. Default Godot has Master only — configure the buses now.
+
+**Preferred (Summer MCP):** Buses are typically in `default_bus_layout.tres`. Modify project setting:
+
+```
+summer_project_setting(key="audio/buses/default_bus_layout", value="res://audio/default_bus_layout.tres")
+```
+
+Ask the user:
+
+> May I create `audio/default_bus_layout.tres` with these buses: Master / Music / SFX / UI / Voice / Ambient / Reverb_Small / Reverb_Large / Reverb_Outdoor?
+
+On yes, write the `.tres` directly via `Write` (it's plain Godot resource format the host can produce):
+
+```
+Write audio/default_bus_layout.tres
+```
+
+**Fallback (no MCP):** Print the `.tres` for the user to paste, plus the `project.godot` line.
+
+### 9. Save the audio bible
+
+Always write the bible. Path: `.summer/audio-bible.md`.
+
+```markdown
+# Audio Bible — <Game Name>
+
+**References:** <3 specific tracks / games / films>
+**Style:** <one of the 8 above>
+**Tempo / key:** 80–110 BPM, D minor, 4/4
+
+## SFX Vocabulary
+| Class | Character | Examples | DON'T |
+|---|---|---|---|
+| UI | Soft, woody, 60-100ms | hover, click | bell tones |
+| Pickup positive | Warm major-third, 200-400ms | coin, heal | pure sine |
+| ... | ... | ... | ... |
+
+## Dynamic Music Plan
+**Model:** Layered stems
+**States:** CALM / TENSION / COMBAT / VICTORY
+**Transitions:** ...
+**Rules:** ...
+
+## Spatial + Mix
+- 3D attenuation: inverse-square, 25m
+- Reverb buses: small / large / outdoor
+- HRTF: ON
+- Master ceiling: -1 dBTP
+- Mix bus: Music -8 dB, SFX 0 dB, UI -3 dB
+- Footstep rolloff: 4m player / 10m NPC
+
+## Bus Layout
+Master → Music, SFX (→ Reverb_Small / Large / Outdoor), UI, Voice, Ambient
+```
+
+Ask:
+
+> May I create `.summer/audio-bible.md` with this bible?
+
+### 10. Optional — generate first SFX seeds
+
+If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals.
+
+```
+summer_generate_audio(prompt="soft woody UI click, 80ms, no reverb, neutral pitch", duration=0.1)
+summer_generate_audio(prompt="warm major-third coin pickup, 300ms, light reverb", duration=0.3)
+summer_generate_audio(prompt="punchy low-mid player damage hit, slight detune, 200ms, no tail", duration=0.2)
+```
+
+Ask first:
+
+> May I generate first-pass SFX seeds for UI, pickup, and damage classes? They're starting points, not finals.
+
+### 11. Route to the next step
+
+End with:
+
+> Bible saved. Next:
+> - `/summer:design-mechanic` to wire SFX cues into specific mechanics.
+> - `/summer:vfx` if you haven't paired audio with visual effect cues yet.
+> - Author or generate the calm music track first; it's the longest-running and sets the room tone.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Single reference for music | Three minimum. Listen for the *common* element across them. |
+| "Library" instead of "vocabulary" | A bag of free SFX with no shared character feels random. Eight named classes with character notes. |
+| Same SFX for all events | If pickup-coin and pickup-key sound identical, the player learns nothing from audio. |
+| No dynamic music plan | Static loops bore in 90s. Pick a model (layered / vertical / horizontal / procedural). |
+| Music louder than SFX | Players need SFX for gameplay; music is mood. Default mix is -8 dB music vs 0 dB SFX. |
+| No reverb buses | "Send" architecture (rooms route to a small/large/outdoor reverb bus) is mandatory or your mix sounds dry-then-wet inconsistently. |
+| Pure sine "ding" for pickup | Reads as cheap mobile game. Use a major-third interval with character. |
+| Same footstep sample for all surfaces | Material-aware footsteps are 80% of the perceived audio quality. |
+| No master ceiling / true peak | Audio clips on console builds without `-1 dBTP` ceiling. Always set it. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+
+## Collaborative protocol
+
+This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow that produces the bible the rest of the project obeys. After the bible exists, the bus layout is set up and any subsequent audio work (footstep system, dynamic music) reads from it.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/godot-version.md` — Godot 4.5 audio API notes
+- `_shared/mcp-tools-reference.md`
+- `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
+- `rendering-and-lighting/art-direction/SKILL.md` — the visual counterpart; audio must rhyme with it
+- `audio/audio-bus-setup/SKILL.md` (NEXT) — implements the bus layout in detail
+- `audio/3d-spatial-audio/SKILL.md` (NEXT) — spatial attenuation patterns
+- `audio/footstep-systems/SKILL.md` (NEXT) — material-aware footstep impl
+- `audio/dynamic-music-stingers/SKILL.md` (LATER) — implements the dynamic music plan