# Sound Design

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.

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.

## Runtime mix

`AudioManager` owns registration, aliases, variation, routing and pooled
playback. The hierarchy is:

```text
Master (hard limiter)
├── SFX
│   ├── Weapons (light parallel compression)
│   ├── Explosions (slower body compression)
│   ├── Impacts
│   ├── Footsteps
│   ├── Movement
│   ├── Ambience
│   ├── UI
│   └── Wind
└── Music
```

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.

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.

## Asset construction

Run:

```powershell
python tools/build_audio_assets.py
python tools/audio_audit.py
```

The builder is deterministic except for downloading the pinned CC0 menu track.
It:

- 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.

`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`.