summer-engine 1.4.0 → 2.0.0

package/skills/visual-effects/vfx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx
-description: Use when the user says the game "feels flat", "needs juice", "lacks impact", or asks for particles, hit feedback, screen shake, camera juice, muzzle flashes, explosions, or pickup effects. Walks the user through a guided 30-minute polish pass that adds visible feedback to combat, movement, pickups, damage, and casting. Trigger on "vfx", "juice", "feels flat", "polish", "particles", "screen shake", "hit flash", "feedback".
+description: Use when the user says the game "feels flat", "lacks impact", "needs juice", "needs punch", or asks for hit feedback, screen shake, camera shake, audio ducking, or general "game feel". Walks the user through the canonical Godot 4.5 game-feel stack — hit-flash + trauma camera shake + audio ducking — wired together so a single hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -9,21 +9,19 @@ allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node su
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
-# /vfx — Visible Polish in 30 Minutes
+# /vfx — The Trio That Makes Games Feel Punchy
 
-A game with bad VFX feels like a tech demo. A game with good VFX feels alive even before the mechanics are deep. This skill is a guided polish pass: you ask the user *what feels flat*, then deliver one or two tight recipes that add immediately-visible feedback. No vague "add particles". Specific node, specific values, specific signal hookup, verified result.
+Particles don't make a game feel good. Screen shake alone doesn't either. What makes a hit *land in the body* is three systems firing on the same frame: a sub-frame **hit flash** on the body that got hit, **trauma-based camera shake** with quadratic falloff so big hits saturate, and **audio ducking** that briefly squashes Music/Ambient so the impact SFX punches through. Skip any one and the game drops back to "tech demo". This skill installs the canonical Godot 4.5 stack — three small, self-contained systems wired to a single signal — so one `hit()` call fires all three.
 
-## Steps
-
-### 1. Ask which thing feels flat
+## Step 1 — Ask what feels flat
 
 Open with one focused question. Wait for the answer.
 
-> What feels flat? Pick one to start: combat hits / movement / pickups / damage taken / explosions / spell casts / something else.
+> What feels flat? Pick one to start: combat hits / pickups / explosions / spell casts / something else.
 
-If the user says "all of it", anchor on **combat hits** — it gives the loudest perceived improvement per minute spent.
+If the user says "all of it", anchor on **combat hits** — the hit-flash + shake + duck trio is the loudest perceived improvement per minute, and pickups/explosions reuse the same building blocks afterwards.
 
-### 2. Read the current scene state
+## Step 2 — Read the current scene state
 
 Before adding anything, see what's there.
 
@@ -31,51 +29,46 @@ Before adding anything, see what's there.
 
 ```
 summer_get_scene_tree
-summer_inspect_node "./World/Player"   # or whichever node owns the action
+summer_inspect_node "./World/Enemy"   # the body that gets hit
+summer_inspect_node "./World/Player/Camera3D"   # the camera to shake
 ```
 
-You're looking for: where the trigger lives (e.g. `body_entered` signal on a Hurtbox), whether a Camera3D exists for shake, whether the target has a MeshInstance3D for a flash material override.
-
-**Fallback (no MCP):** ask the user to paste the relevant `.tscn` snippet or describe the parent of the actor.
-
-### 3. Pick the recipe and propose it explicitly
+You're looking for: a `MeshInstance3D` on the hurt body (for the flash), an existing `Camera3D` on the player (don't spawn a new one), and the names of the audio buses already present (Master + at least one of `Music`, `Ambient`, `SFX`).
 
-Each recipe is a tight bundle of (node + property + signal + script). Don't mix recipes — add one, see it land, stack later.
+If there's no Camera3D under the player, **stop and ask** before adding one — there may be a level camera elsewhere you'd be fighting.
 
-> I want to add a hit flash + 0.04s camera shake bound to the `damaged` signal on `./World/Enemy`. About 6 lines of GDScript and one Camera3D shake node. May I proceed?
+If the only bus is `Master`, ducking will do nothing useful. See *Common mistakes* below.
 
-### 4. Apply the recipe
+**Fallback (no MCP):** ask the user to paste the relevant `.tscn` and the project's `default_bus_layout.tres` (or describe the bus list).
 
-See **Recipes** below. Each is end-to-end: node tree, property values, signal hookup, GDScript stub.
+## Step 3 — Propose the bundle
 
-### 5. Verify
+Don't drip the systems in one at a time. The whole point is the trio fires together — install all three, wire one signal, see it land.
 
-```
-summer_save_scene
-summer_get_script_errors
-summer_play
-# user reproduces the trigger
-summer_stop
-```
+> I'm about to add: `HitFlash` on `./World/Enemy`, `CameraShake` script on `./World/Player/Camera3D`, `AudioDucker` autoload, and connect the `damaged` signal so one hit fires all three. About 130 lines of GDScript across 3 files. May I proceed?
 
-If it doesn't read on screen, the values are wrong (flash too dim, shake too short, particle lifetime too long). Tune one knob at a time.
+## Step 4 — Install Section 1 (Hit Flash)
 
-## Recipes
+**Goal:** when a body takes damage, its mesh pulses to white for ~0.08s, then tweens back. Reads instantly even at 60 fps.
 
-### Recipe A — Hit flash (mesh albedo flicker)
+**Approach:** keep a reference to the original `albedo_color`. On `flash()`, write white directly to the mesh's `material_override` (or build a flash override the first time), then `create_tween()` back to the original over `duration` seconds. Tween, not `await` + sleep — tweens auto-cancel if `flash()` is re-called mid-flash, which matters during multi-hit combos.
 
-**Goal:** when an enemy takes damage, the mesh flashes white for 80 ms. Single biggest-bang-for-buck VFX. Read instantly even at 60 fps.
+**Node tree:**
 
-**Approach:** swap to a flash material via `material_override`, then back. Use Tween for the timing.
+```
+World/
+  Enemy (CharacterBody3D)
+    Mesh (MeshInstance3D)        # the visible body
+    HitFlash (Node)              # holds the script, no transform
+```
 
 **MCP path:**
 
 ```
 summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")
-# attach script (see below) — script holds reference to MeshInstance3D and a flash StandardMaterial3D
 ```
 
-Script (`scripts/hit_flash.gd`):
+Then write `scripts/vfx/hit_flash.gd`:
 
 ```gdscript
 class_name HitFlash
@@ -85,187 +78,294 @@ extends Node
 @export var flash_color: Color = Color(1.0, 1.0, 1.0)
 @export var duration: float = 0.08
 
+var _orig_albedo: Color
 var _flash_mat: StandardMaterial3D
-var _orig_mat: Material
+var _tween: Tween
 
 func _ready() -> void:
     if mesh == null:
         push_warning("HitFlash: mesh export not assigned")
         return
-    _orig_mat = mesh.get_surface_override_material(0)
+    # Build a dedicated override material once. Cloning the surface material
+    # would also work, but a fresh StandardMaterial3D is simpler and free.
     _flash_mat = StandardMaterial3D.new()
     _flash_mat.albedo_color = flash_color
     _flash_mat.emission_enabled = true
     _flash_mat.emission = flash_color
     _flash_mat.emission_energy_multiplier = 2.0
+    _orig_albedo = _flash_mat.albedo_color
+    mesh.material_override = null  # leave original mesh material in place
 
 func flash() -> void:
     if mesh == null:
         return
-    mesh.set_surface_override_material(0, _flash_mat)
-    var tween := create_tween()
-    tween.tween_interval(duration)
-    tween.tween_callback(func(): mesh.set_surface_override_material(0, _orig_mat))
+    if _tween and _tween.is_valid():
+        _tween.kill()  # restart cleanly on rapid re-hits
+    mesh.material_override = _flash_mat
+    _flash_mat.albedo_color = flash_color
+    _tween = create_tween()
+    _tween.tween_interval(duration)
+    _tween.tween_callback(func() -> void: mesh.material_override = null)
 ```
 
-Wire the trigger:
+**Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-```
-summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")
-```
+> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `_shared/mcp-tools-reference.md` § "Trap".
 
-**Tunable knobs:** `duration` (0.06–0.12 sec — under 0.06 reads as a flicker, over 0.12 looks slow), `emission_energy_multiplier` (1.5–3.0).
+## Step 5 — Install Section 2 (Trauma Camera Shake)
 
-> CRITICAL: do NOT inline the StandardMaterial3D as a sub_resource via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres` and load. Inline sub_resources break `summer_set_resource_property` silently — see `_shared/mcp-tools-reference.md` § "Trap".
+**Goal:** any system can `add_trauma(amount)` to the camera. The camera accumulates trauma 0–1, decays it every frame, and shakes by `trauma² × random_offset`. The square is the trick: a 0.3 hit shakes very little (0.09), a 0.8 hit shakes a *lot* (0.64). Big hits feel huge, small hits don't pollute the screen.
 
-### Recipe B — Screen shake (Camera3D wobble)
+**Approach:** put the shake on the existing Camera3D. Two variables — `_trauma` (0–1 accumulator) and `_shake_offset` (last frame's applied rotation). Every frame, **subtract last frame's offset first** so the next offset doesn't drift, then apply the new one. This is the non-obvious trick.
 
-**Goal:** punchy 40–80 ms camera shake on impact. Ties hits to the player's body.
-
-**Approach:** attach a shake script to the existing Camera3D. Don't spawn a new camera; reuse the player's.
+**Node tree:** the script attaches to the existing `./World/Player/Camera3D`. No new nodes.
 
 ```
-summer_inspect_node "./World/Player/Camera3D"   # confirm the path
+summer_inspect_node "./World/Player/Camera3D"
+# attach scripts/vfx/camera_shake.gd
 ```
 
-Script (`scripts/camera_shake.gd`):
+`scripts/vfx/camera_shake.gd`:
 
 ```gdscript
 class_name CameraShake
 extends Camera3D
 
-@export var trauma_decay: float = 5.0
-@export var max_offset: Vector2 = Vector2(0.15, 0.15)
-@export var max_roll: float = 0.05
+@export var trauma_decay: float = 3.0       # how fast trauma bleeds off (per second)
+@export var max_shake_angle_deg: float = 2.5 # max pitch at trauma = 1.0
+@export var yaw_factor: float = 0.5          # less yaw than pitch (eye anatomy)
 
 var _trauma: float = 0.0
-var _base_position: Vector3
-
-func _ready() -> void:
-    _base_position = position
+var _shake_offset: Vector3 = Vector3.ZERO
 
 func add_trauma(amount: float) -> void:
     _trauma = clamp(_trauma + amount, 0.0, 1.0)
 
 func _process(delta: float) -> void:
+    # Always undo last frame's offset BEFORE deciding the next.
+    # Without this, rotation drifts every frame trauma is non-zero.
+    if _shake_offset != Vector3.ZERO:
+        rotation -= _shake_offset
+        _shake_offset = Vector3.ZERO
+
     if _trauma <= 0.0:
-        position = _base_position
-        rotation.z = 0.0
         return
-    var shake := _trauma * _trauma  # quadratic — feels punchy, not noisy
-    position = _base_position + Vector3(
-        randf_range(-max_offset.x, max_offset.x) * shake,
-        randf_range(-max_offset.y, max_offset.y) * shake,
+
+    var shake := _trauma * _trauma   # quadratic — small hits barely shake
+    var max_angle := deg_to_rad(max_shake_angle_deg) * shake
+
+    _shake_offset = Vector3(
+        randf_range(-max_angle, max_angle),
+        randf_range(-max_angle, max_angle) * yaw_factor,
         0.0
     )
-    rotation.z = randf_range(-max_roll, max_roll) * shake
-    _trauma = max(_trauma - trauma_decay * delta, 0.0)
+    rotation += _shake_offset
+    _trauma = max(0.0, _trauma - trauma_decay * delta)
 ```
 
-Trigger from the player or any damage handler:
+**Calling it:**
 
 ```gdscript
-$Camera3D.add_trauma(0.5)   # 0.3 light hit, 0.5 normal, 0.8 heavy
+$Camera3D.add_trauma(0.3)   # light hit (parry, glancing blow)
+$Camera3D.add_trauma(0.5)   # standard combat hit
+$Camera3D.add_trauma(0.8)   # heavy / explosion
 ```
 
-**Tunable knobs:** `max_offset` (0.05 subtle, 0.2 punchy, 0.4 cinematic), `trauma_decay` (3 long, 5 standard, 8 snappy). Quadratic falloff is the trick — linear feels twitchy.
+**Tunable knobs:** `trauma_decay` 3.0 (long-tail, cinematic) ↔ 6.0 (snappy, twitch-shooter feel). `max_shake_angle_deg` 2.0 (subtle) ↔ 4.0 (action-game). Keep `yaw_factor` ≤ 0.5 — equal pitch/yaw shake feels uniform and wrong; eyes are far more sensitive to vertical motion.
 
-### Recipe C — Pickup sparkle (GPUParticles3D one-shot)
+## Step 6 — Install Section 3 (Audio Ducking)
 
-**Goal:** when a pickup is collected, emit a quick burst of particles where it disappeared.
+This is the system most projects skip and the one that makes the biggest perceived difference. On a hit, briefly attenuate Music + Ambient + Announcer (whatever non-impact buses you have) so the SFX bus stabs through the mix. Then smoothly tween volumes back. **Crucially: store original bus volumes once at startup, and apply ducking as an offset.** Snapping volumes to absolute values destroys the user's volume preferences.
 
-**Approach:** GPUParticles3D set to `one_shot = true`, `emitting = true` triggered from script. Particle material **must** be a standalone `.tres` (inline sub_resource trap).
+**Approach:** an autoload (`AudioDucker`) so any system can call `AudioDucker.duck(0.5, 0.4)` from anywhere. Internally:
 
-```
-summer_add_node(parent="./World/Pickup", type="GPUParticles3D", name="Sparkle")
-summer_set_prop(path="./World/Pickup/Sparkle", key="one_shot", value="true")
-summer_set_prop(path="./World/Pickup/Sparkle", key="amount", value="24")
-summer_set_prop(path="./World/Pickup/Sparkle", key="lifetime", value="0.5")
-summer_set_prop(path="./World/Pickup/Sparkle", key="explosiveness", value="0.95")
+- `_initial_volumes: Dictionary[StringName, float]` captured once in `_ready()` from `AudioServer.get_bus_volume_db()` for each named bus.
+- `duck(amount, duration)` lowers each non-impact bus by `amount × per_bus_weight`, scheduled via Tween, and tweens back over `duration`.
+- Per-bus weights let Music duck more than Ambient (Music 0.9 = -90% intensity, Ambient 0.7, Announcer 0.5).
+- Kill any in-flight tween before starting a new one so rapid-fire hits don't compound the duck and silence the mix.
+
+**Node tree:** none — register the script as an autoload.
+
+`scripts/vfx/audio_ducker.gd`:
+
+```gdscript
+extends Node
+
+# Bus name -> duck weight (1.0 = full duck, 0.0 = never duck this bus).
+# "SFX" / "UI" / "Voice" should NOT be ducked — those are the buses you want
+# to punch through. Adjust to match your project's default_bus_layout.tres.
+const BUS_WEIGHTS := {
+    &"Music":     0.9,
+    &"Ambient":   0.7,
+    &"Announcer": 0.5,
+}
+
+# How loud the bus is "when not ducked", captured once. NEVER overwrite —
+# this is the user's preference and mixer baseline.
+var _initial_volumes: Dictionary = {}
+var _tween: Tween
+
+func _ready() -> void:
+    for bus_name in BUS_WEIGHTS.keys():
+        var idx := AudioServer.get_bus_index(bus_name)
+        if idx == -1:
+            push_warning("AudioDucker: bus '%s' not found in bus layout" % bus_name)
+            continue
+        _initial_volumes[bus_name] = AudioServer.get_bus_volume_db(idx)
+
+# amount: 0.0–1.0 (0.5 = noticeable, 1.0 = near-silence on weighted buses)
+# duration: total duck-and-restore time, seconds. 0.4–0.6 feels right for hits.
+func duck(amount: float, duration: float = 0.5) -> void:
+    if _initial_volumes.is_empty():
+        return
+    if _tween and _tween.is_valid():
+        _tween.kill()
+    _tween = create_tween().set_parallel(true)
+
+    var attack := duration * 0.15  # fast duck-down, slow restore
+    var release := duration * 0.85
+
+    for bus_name in _initial_volumes.keys():
+        var idx := AudioServer.get_bus_index(bus_name)
+        if idx == -1:
+            continue
+        var base_db: float = _initial_volumes[bus_name]
+        var weight: float = BUS_WEIGHTS.get(bus_name, 0.0)
+        # Convert "amount" (0–1) into a dB drop. -24 dB at amount=1, weight=1
+        # is "almost gone" without being absolute silence.
+        var drop_db := -24.0 * amount * weight
+        var target_db := base_db + drop_db
+
+        var seq := create_tween()
+        seq.tween_property(AudioServer, "bus_volume_db", target_db, attack).set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)\
+            .from(base_db)
+        # NOTE: AudioServer doesn't expose bus volume as an animatable
+        # property — use a method tween instead. See actual call below.
+        # (The simpler, real implementation:)
+        _tween.tween_method(_set_bus_db.bind(idx), base_db, target_db, attack)\
+            .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)
+        _tween.tween_method(_set_bus_db.bind(idx), target_db, base_db, release)\
+            .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_IN)\
+            .set_delay(attack)
+
+func _set_bus_db(idx: int, db: float) -> void:
+    AudioServer.set_bus_volume_db(idx, db)
 ```
 
-For the `process_material`, save a `ParticleProcessMaterial.tres` first (see `asset-pipeline/asset-strategy/SKILL.md` for the pattern), then:
+Register it as an autoload:
 
 ```
-summer_set_prop(path="./World/Pickup/Sparkle", key="process_material", value="res://materials/sparkle_particles.tres")
+Project Settings → Autoload → Add scripts/vfx/audio_ducker.gd as "AudioDucker"
 ```
 
-In the pickup's collection handler:
+**Calling it:**
 
 ```gdscript
-func _on_picked_up() -> void:
-    $Sparkle.restart()
-    $Sparkle.emitting = true
-    $Mesh.visible = false
-    await get_tree().create_timer(0.6).timeout
-    queue_free()
+AudioDucker.duck(0.5, 0.4)   # standard hit
+AudioDucker.duck(0.8, 0.6)   # heavy / boss hit
+AudioDucker.duck(1.0, 1.2)   # cinematic — explosion or boss intro
 ```
 
-`explosiveness = 0.95` is the difference between a continuous trickle and a satisfying *poof*. `0.0` = constant emission, `1.0` = all particles spawn at frame zero.
+**Why offset-not-absolute matters:** if the user has Music slider at -10 dB in your settings menu, and ducking writes `set_bus_volume_db("Music", -24.0)` directly, the *restore* tween will pull Music up to -24's "neutral" which is louder than the user wanted. Capturing `_initial_volumes` at autoload `_ready()` and only ever offsetting from those values preserves the user's mix forever.
+
+## Step 7 — Wire the trio to one signal
 
-### Recipe D — Muzzle flash (light + sprite + sound)
+The whole point: one hit, all three fire on the same frame. Keep this in the hurt body's damage handler — *not* on a global event bus, because you want the trauma amount and flash to scale per-hit.
+
+```gdscript
+# scripts/enemy.gd (or wherever you handle damage on the body that got hit)
+extends CharacterBody3D
+
+signal damaged(amount: float)
+
+@onready var _hit_flash: HitFlash = $HitFlash
+@onready var _player_camera: CameraShake = get_tree().get_first_node_in_group("player_camera")
+
+func take_damage(amount: float) -> void:
+    # ... your existing health subtract / death check ...
+    damaged.emit(amount)
+    _on_damaged(amount)
+
+func _on_damaged(amount: float) -> void:
+    # 1. Hit flash on this body.
+    _hit_flash.flash()
+    # 2. Camera shake on the player's camera, scaled by hit weight.
+    var trauma := clamp(0.2 + amount * 0.05, 0.2, 0.9)
+    if _player_camera:
+        _player_camera.add_trauma(trauma)
+    # 3. Audio duck, scaled by hit weight.
+    var duck_amount := clamp(0.3 + amount * 0.04, 0.3, 1.0)
+    AudioDucker.duck(duck_amount, 0.45)
+```
 
-**Goal:** when a weapon fires, a brief OmniLight3D flash + Sprite3D billboard + audio cue. Sells the shot more than the projectile does.
+Add the camera to a group so any actor can find it:
 
 ```
-summer_add_node(parent="./World/Player/Weapon", type="OmniLight3D", name="MuzzleLight")
-summer_set_prop(path="./World/Player/Weapon/MuzzleLight", key="light_color", value="Color(1.0, 0.85, 0.4)")
-summer_set_prop(path="./World/Player/Weapon/MuzzleLight", key="light_energy", value="0.0")
-summer_set_prop(path="./World/Player/Weapon/MuzzleLight", key="omni_range", value="2.5")
+summer_add_node(...)   # ./World/Player/Camera3D already exists
+summer_set_prop(path="./World/Player/Camera3D", key="groups", value='["player_camera"]')
 ```
 
-Trigger from the fire function:
+Or wire the signal explicitly via MCP if you prefer:
 
-```gdscript
-func fire() -> void:
-    var light: OmniLight3D = $MuzzleLight
-    light.light_energy = 4.0
-    var tween := create_tween()
-    tween.tween_property(light, "light_energy", 0.0, 0.06)
-    $MuzzleSound.play()
-    $Camera3D.add_trauma(0.3)   # if camera shake recipe applied
+```
+summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")
 ```
 
-Do NOT keep the light always-on at low energy — that costs a real-time light slot. Tween from 4.0 to 0.0 over 60 ms.
+## Step 8 — Scaling intensity per hit weight
 
-### Recipe E — Explosion (5-element stack)
+The trio's whole magic is that the same code makes a glancing parry feel different from a critical hit. Calibrate the curve once:
 
-**Goal:** one Big Boom, all senses. Stack five small effects on the same trigger.
+| Hit type | `damage` (HP) | trauma | duck amount |
+|---|---|---|---|
+| Glance / parry | 1–3 | 0.20 | 0.30 |
+| Standard hit | 5–10 | 0.35 | 0.50 |
+| Heavy hit | 15–25 | 0.55 | 0.70 |
+| Critical / boss | 30–50 | 0.75 | 0.85 |
+| Explosion / death | 50+ | 0.90 | 1.00 |
 
-1. **Light flash:** OmniLight3D, `light_energy` 0 → 8 → 0 over 200 ms
-2. **Particles:** GPUParticles3D one-shot, `amount` 64, `lifetime` 0.8, `explosiveness` 1.0
-3. **Camera shake:** `add_trauma(0.8)`
-4. **Audio:** AudioStreamPlayer3D, layered explosion
-5. **Hit-stop:** `Engine.time_scale = 0.05` for 60 ms, then 1.0
+Because trauma is squared inside the camera, the *felt* difference between 0.35 (→ 0.12 shake) and 0.75 (→ 0.56 shake) is roughly 5×. That's the whole point — small hits stay clean, big hits saturate the screen.
 
-Hit-stop is the secret weapon. 60 ms of 0.05 time scale = the explosion lands. Use sparingly; once per "big" event. Reset with:
+## Step 9 — Verify
 
-```gdscript
-Engine.time_scale = 0.05
-await get_tree().create_timer(0.06).timeout
-Engine.time_scale = 1.0
 ```
+summer_save_scene
+summer_get_script_errors
+summer_play
+# user reproduces a hit
+summer_stop
+```
+
+Tune one knob at a time:
+
+- Flash invisible → `emission_energy_multiplier` 1.5 → 3.0, or check that the mesh actually has a material to override.
+- Shake feels jittery → reduce `max_shake_angle_deg`, or check `yaw_factor` is ≤ 0.5.
+- Ducking inaudible → check `_initial_volumes` got populated (autoload running before the first hit?), and that `Music`/`Ambient` bus names actually match your `default_bus_layout.tres`.
+- Ducking *too loud* → reduce per-bus weight, not the `amount` argument. Weights are per-project; amount is per-hit.
 
-## Anti-patterns
+## Common mistakes
 
 | Don't | Do | Why |
 |---|---|---|
-| Inline sub_resource for ParticleProcessMaterial via `summer_set_prop` | Save standalone `.tres`, reference by path | `summer_set_resource_property` silently fails on inline sub_resources |
-| Hit flash for 0.3 sec | Hit flash for 0.06–0.12 sec | Anything over ~120 ms reads as a "stay" not a flash |
-| Camera shake with linear falloff | Quadratic falloff (`_trauma * _trauma`) | Linear feels jittery; quadratic feels weighty |
-| `OmniLight3D` always on at low energy | Tween from off → on → off in 60–80 ms | Real-time lights have hard count limits per frame |
-| GPUParticles3D `one_shot = false` for pickups | `one_shot = true`, `restart()` to fire | Otherwise particles trickle continuously and look wrong |
-| Tween every property at once | Tween one or two; let the others snap | Over-animated polish reads as noise |
-| `Engine.time_scale` < 0.1 for > 100 ms | `time_scale = 0.05` for 40–80 ms | Longer hit-stop feels broken, not satisfying |
-| Particles with `lifetime > 1.0` for hits | `lifetime = 0.3–0.6` | Hit feedback should resolve before the next swing |
+| `AudioServer.set_bus_volume_db("Music", -24)` directly | Capture `_initial_volumes` once, apply ducking as an offset | Absolute writes destroy the user's volume preferences |
+| Linear shake (`shake = trauma`) | Quadratic (`shake = trauma * trauma`) | Linear feels uniform, twitchy. Quadratic separates small hits from big hits |
+| Apply new shake offset without subtracting last frame's | Subtract `_shake_offset`, zero it, then write the new one | Otherwise rotation drifts every frame trauma > 0 |
+| Hit flash with `await get_tree().create_timer(...)` | `create_tween().tween_callback(...)` | A timer can't be cancelled mid-flight on rapid re-hits, leaving albedo broken white |
+| Only one bus ("Master") in the project | Add at least `Music`, `Ambient`, `SFX` and route SFX through SFX bus | Ducking does nothing if the impact SFX is on the same bus you're ducking |
+| Duck for 1.5+ seconds | 0.4–0.6 second total duck-and-restore | Long ducks make the music feel broken, not punchy |
+| Equal pitch/yaw shake | `yaw_factor ≤ 0.5` | Eyes are sensitive to vertical motion; equal axes feel mechanical |
+| `Engine.time_scale` for every hit | Reserve hit-stop for big events only (boss hits, deaths) | Time-scale dips on every hit feel laggy, not impactful |
+| Inline `StandardMaterial3D` sub_resource via `summer_set_prop` | Build in script or save standalone `.tres` | Inline sub_resources silently break `summer_set_resource_property` |
 
 ## Collaborative protocol
 
-This skill writes scripts and adds nodes. Always ask before each recipe is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + connect 2 signals. OK?" See `_shared/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `_shared/collaborative-protocol.md`.
 
-## Want a working starter?
+## When NOT to use this skill
 
-No template — this is a workflow that bolts onto any existing scene. For a project that already has these recipes pre-wired, see `template-3d-fps` (hit flash + muzzle flash) and `template-3d-platformer` (pickup sparkle).
+- **2D games** — the trauma curve and dB ducking still apply, but the camera-shake script needs a `Camera2D` rewrite (`offset` instead of `rotation`). Use this skill as a reference, not a drop-in.
+- **Turn-based / strategy** — game-feel here lives in UI animation, not body-hit feedback. Skip the trio; reach for tween-based UI polish instead.
+- **No audio buses configured** — ducking with one Master bus is a no-op. Set up `Music` / `Ambient` / `SFX` first via the audio-direction skill, then come back.
+- **Networked games where the hurt body is remote** — the flash should run client-side on visual hit confirm, not on damage authority. Hook to a `hit_visual_received` signal, not the authoritative damage signal.
 
 ## See also
 
@@ -273,8 +373,7 @@ No template — this is a workflow that bolts onto any existing scene. For a pro
 - `_shared/godot-version.md` — Godot 4.5 API notes
 - `_shared/collaborative-protocol.md` — "May I write" pattern
 - `_shared/gd-style.md` — typed GDScript conventions
-- `post-processing/screen-shake/SKILL.md` — deeper camera-shake techniques (Perlin noise, trauma stacks)
-- `visual-effects/gpuparticles-3d-basics/SKILL.md` — particle setup details
-- `visual-effects/hit-impact-flashes/SKILL.md` — flash material variations
-- `visual-effects/muzzle-flashes/SKILL.md` — muzzle flash deep dive
-- `audio/sfx-pipeline/SKILL.md` — pairing audio with VFX
+- `audio/audio-direction/SKILL.md` — bus layout setup (prerequisite for ducking)
+- `post-processing/screen-shake/SKILL.md` — deeper trauma variants (Perlin noise, stacked sources)
+- `visual-effects/gpuparticles-3d-basics/SKILL.md` — particles to layer on top of the trio
+- `visual-effects/hit-impact-flashes/SKILL.md` — flash material variations beyond white pulse