big

docs/SOUND_DESIGN.md

@@ -1,67 +1,104 @@
-# Sound Design Plan
+# Sound Design
 
-The current sounds are procedurally generated sine/noise blends
-(`generate_sounds.py`) — functional, but robotic. This doc is the path to
-real sound design with zero budget.
+Papaya Shooter's mix is **stylized impact, comfortable repetition**: graphic
+and energetic enough to match the cel-shaded action, but deliberately free of
+the clipped white-noise and narrow resonant tones that make a fast shooter
+fatiguing.
 
-## What's in place now
+Character movement follows the same 90/10 rule as
+`docs/CHARACTER_ART_DIRECTION.md`: about 90% clean motion/thrust/body and 10%
+actuator, latch or servo. Mechanics explain a verb; they do not become a
+constant texture over the character.
 
-`AudioManager` (autoload, `globals/audio_manager.gd`) provides the plumbing
-good sound design needs:
+## Runtime mix
 
-- **Bus layout**: `Master ← SFX ← {Weapons, Footsteps, UI}`, `Master ← Music`
-  — created automatically at boot, so volume sliders and effects (EQ,
-  compression, reverb zones) can target categories.
-- **Variation playback**: drop `footstep_01.wav`, `footstep_02.wav`,
-  `footstep_03.wav` into `assets/sounds/` and `AudioManager.play_3d("footstep", pos)`
-  picks one at random.
-- **Pitch randomization**: every playback is pitched ±6% by default — the
-  single cheapest trick to stop repeated sounds sounding fake.
-- **Pooled 3D players**: `play_3d()` is safe to call every frame; no node
-  churn, no cut-off management.
+`AudioManager` owns registration, aliases, variation, routing and pooled
+playback. The hierarchy is:
 
-```gdscript
-# anywhere in gameplay code:
-AudioManager.play_3d("ak47_fire", muzzle.global_position)
-AudioManager.play_ui("hit_confirm")
+```text
+Master (hard limiter)
+├── SFX
+│   ├── Weapons (light parallel compression)
+│   ├── Explosions (slower body compression)
+│   ├── Impacts
+│   ├── Footsteps
+│   ├── Movement
+│   ├── Ambience
+│   ├── UI
+│   └── Wind
+└── Music
 ```
 
-## Replacing the procedural sounds (priority order)
+The limiter is only a safety net for coincident shots/explosions. Assets are
+mastered below full scale, and category gain establishes the hierarchy before
+the limiter is reached.
 
-Sound is ~50% of "game feel" in an FPS. Replace in this order:
+Legacy event ids such as `m4_fire`, `explosion`, `wind` and `ui_hover` resolve
+to premium families in `globals/audio_manager.gd`. This preserves gameplay API
+compatibility while keeping source filenames out of weapon and UI code.
 
-1. **Weapon fire** (heard constantly): layered = body (low thump) + crack
-   (mid transient) + tail (room reflection). Sonniss GDC packs have complete
-   layered gunshots. One file per weapon is fine to start; add `_01.._03`
-   variations later.
-2. **Hit confirm + kill confirm**: short, bright, satisfying (this is the
-   "touchdown" pillar in the design doc).
-3. **Footsteps**: 4+ variations minimum, quieter than you think, on the
-   `Footsteps` bus so they can be ducked while firing.
-4. **Movement verbs**: slide (cloth+concrete scrape), dash (air whoosh),
-   wall-run loop, jump/land (land intensity scaled by fall speed).
-5. **Ambience**: a quiet room tone per map kills the "dead air" feeling.
-6. **UI**: menu hover/click/equip from a Kenney UI pack.
+## Asset construction
 
-Where to get files: see [ASSET_SOURCES.md](ASSET_SOURCES.md#sounds) —
-Sonniss GDC bundles first, Kenney CC0 packs second, Freesound (CC0 filter)
-for gaps.
+Run:
 
-## Conventions
+```powershell
+python tools/build_audio_assets.py
+python tools/audio_audit.py
+```
 
-- Files: `assets/sounds/<event>[_NN].wav` — 44.1 kHz, 16-bit, mono for 3D
-  positional sounds, stereo only for UI/music.
-- Ids are auto-registered from filenames at boot (`ak47_fire.wav` →
-  `"ak47_fire"`). Names containing `fire`/`reload` route to the Weapons bus,
-  `footstep` to Footsteps, everything else to SFX
-  (see `BUS_HINTS` in audio_manager.gd).
-- Keep source loudness consistent: normalize weapon shots to about -6 dBFS
-  peak, footsteps/foley around -18 dBFS.
+The builder is deterministic except for downloading the pinned CC0 menu track.
+It:
 
-## Later polish (cheap wins, in order)
+- retains the transient of the CC0 firearm recordings;
+- layers a low-passed body and a short, dark reflection tail;
+- reduces the abrasive 3–5 kHz region and controls peaks;
+- creates four concrete, metal, wood and glass footstep variations;
+- constructs a 48.5-second speed-wind master plus softened scrape, wall-run and
+  grapple loops from recordings;
+- constructs mono mechanical projectile loops for correct 3D localization;
+- layers low relay/clunk UI hover/click/confirm/error/equip feedback;
+- masters the CC0 menu loop to a conservative music level.
 
-1. Distance low-pass on the Weapons bus (far gunfire sounds muffled).
-2. A short duck (sidechain) on Footsteps/ambience when local weapon fires.
-3. Reverb `AudioEffectReverb` per-map on SFX for indoor spaces.
-4. Surface-dependent footsteps: raycast down, map material → sound id
-   (`footstep_metal`, `footstep_concrete`).
+`tools/audio_audit.py` gates family coverage, 48 kHz format, mono/stereo intent,
+clipping, DC offset, headroom, loop duration, seam continuity, spectral
+flatness, high-frequency centroid and the explosion/firearm loudness hierarchy.
+
+## Gameplay behavior
+
+- Footsteps raycast the actual floor collider and use its
+  `acoustic_material`; brick and untagged structure map to concrete.
+- Local and remote footsteps use the same surface families. Remote steps remain
+  positional and pass through material-aware occlusion.
+- Slides switch recorded friction gestures if the floor material changes and
+  scale restrained pitch/gain with speed.
+- Wall-run friction scales with speed and gets a restrained wood/metal
+  resonance shift.
+- Speed wind is a narrowed, filtered field recording and fades in above 12 m/s
+  with a stronger velocity-pitch relationship. Its 48.5-second cycle prevents
+  a short gust cadence from becoming audible. There is no global noise bed.
+- Jump and double-jump are compact jump-jet impulses. Dash is an equally brief
+  thrust-jet cue; clean air and low engine body dominate both.
+- Grapple launch/latch/reel use distinct air, padded latch and restrained motor
+  cues. The reel stays below the character movement and never becomes a
+  continuous metallic foreground.
+- Automatic weapon players keep eight overlapping voices; a new shot no longer
+  cuts the previous shot's body and tail.
+- Explosion pitch and gain scale with blast radius, while reflections and
+  occlusion locate the source in the environment. Masters carry a measured
+  body advantage over firearms and a dark industrial debris layer.
+- UI hover has a short cooldown so crossing dense menus does not become a buzz.
+  All UI feedback is built from softened relay/clunk gestures with 8 ms
+  transient ramps and a two-pole 2.4 kHz ceiling.
+- Menu music fades in and is owned by the menu scene, so it stops cleanly when
+  a match begins.
+
+## Source and naming conventions
+
+Licenses and download pages are recorded in `assets/sounds/SOURCES.md`.
+
+- Positional one-shots and projectile loops: 48 kHz, 16-bit mono WAV.
+- Player-local movement beds: 48 kHz, 16-bit stereo WAV.
+- Music: 48 kHz stereo Ogg Vorbis.
+- Variations: `<event>_00.wav`, `<event>_01.wav`, etc.
+- Runtime event families, bus gains and pitch ranges live in
+  `AudioManager.EVENT_TUNING`.