Audio & SFX pipeline

Hits feel heavy when the sound is right as much as the picture. Every hit is layered, every layer is short, and the mixer protects what matters (your hits, boss warnings) when a crowd is fighting.

◆The 4-layer hit

Each layer has 3–5 variations and ±6% pitch randomisation. Telegraph warnings are never randomised.

◆Sources (free first)

Every sound the game needs is already written as a prompt and a ready command on the Audio generation page (audio-requests.json, generated from skills, weapons, bestiary, world, mounts and the UI list). It lists 320 sounds, including two planned boss themes; the 64 P0 sounds are the shared hit layers, telegraph cues, the main UI sounds, loot drops and footsteps.

Default tool (round 6): the local Stable Audio 3 SFX generator (Local SFX generator). Each request has an exact ./tools/sfxgen … --out <saveAs> command; Codex loops the whole queue (audio-requests/queue.json) with the prompt on the Audio generation page, logs every take to logs/audio-gen.jsonl and runs pnpm data:build + node tools/audio/sync-wiki-previews.mjs so the page plays the new takes. Each request also shows an artwork of where the sound is used (skill icon, monster, zone, UI piece).

Why the hit layers are 0.3 s with 4 takes: a hit is not one sound. The game plays the weapon swish, an impact layer (light/medium/heavy), a material layer (fur, carapace…) and a sweetener together. The impact and material layers are only the short transient (0.3 s; the massive impact keeps a 1.5 s rumble), and four takes rotate at random so repeated hits never sound identical.

Small sounds everywhere (round 6): windows open/close, tabs, tooltips, dropdowns, toggles, checkboxes, slider steps, item pick-up/place, quick-slot assign, socket/unsocket, skill-tree node hover/ready/allocate/keystone, chain-slot set, skill rank-up, loot drops by rarity (normal → legend), Zoe purchase, chests, map, bag full, event countdown/start, party and trade requests — all in the ui category, routed to the ui bus (no 3D).

• Never rip audio from other games (Silkroad Online, Path of Exile or any other). It is copyrighted, and their terms forbid extracting it. Use those games only as listening references. Describe the quality you want in your own words; prompts never name another game (a data test enforces this).
• AI models with non-commercial weights (e.g. Meta AudioGen, CC-BY-NC) are not used for shipped sounds.
• Paid tiers or new services need owner approval (PHP 5,000 cap). On the ElevenLabs free plan, the credits screen and docs/LICENSES.md carry "Sound effects generated with elevenlabs.io".
• Music: local Stable Audio 3 Small Music (OPEN-3, ADR-026), for towns, the GM room and named engaged boss encounters. Ordinary outdoor travel/combat remains environment sound from the SFX model; special boss themes are the exception.
• Log every file in docs/LICENSES.md (source, licence, date).

◆Processing and formats

• Trim silence, 5 ms fades, remove DC offset. Peak ≤ −3 dBFS for SFX. Music/ambience at −16 LUFS integrated.
• Masters stay lossless (WAV, 48 kHz). Unity compresses on import per platform: ADPCM for short hit/UI SFX, Vorbis for longer sounds on Windows/Android, AAC on iOS and the Web build. SFX mono, music/ambience stereo.
• Tooling: ffmpeg (optional install, free) for batch loudness and encoding through tools/audio/process.mjs, which writes a report JSON.

◆Mixer (Unity AudioMixer)

Web build limit (checked 2026-10-06): Unity's Web platform supports mixer volume only — no snapshots, effects or limiter — and clips are compressed in memory or decompressed on load, never streamed (Unity manual). Ducking and state mixes must therefore work as bus-gain changes in code, with snapshots and effects as native extras. Proposed standard, with listener placement, crowd coalescing, loudness of the whole mix and footsteps by surface: AAA detail catalog.

Voice limits: total 16/24/32/48 by tier. The oldest, quietest, farthest voice is stolen first. Spatial audio uses panning + distance attenuation (HRTF only on desktop High+). Buses are AudioMixer groups; ducking uses mixer snapshots; voices come from a pooled AudioSource set (no runtime allocation).

◆Music and environment

Owner direction, amended 2026-10-05 (ADR-026): town/GM music and special boss music; ordinary outdoor travel/combat uses quiet environment sound.

• Music is a 60 s loop made with the Small Music bundle (--model sm-music, 2 s crossfade, negative prompt against vocals and synths). Three takes are requested per theme; the owner picks one after listening, the others stay as alternates. Boss themes are encounter music rather than a permanent zone layer. The two new briefs have no generated takes yet.
• Beds are 20 s loops written for each area from its landmark and mood in world.json. Emitters are close 20 s loops placed on one hero prop (kiln, canal, copper relic, sealed gate…) with distance falloff, played over the bed. Both use the SFX model with "music, melody, singing, voices…" as the negative prompt: a negation written inside the prompt can attract the sound it excludes.
• Not annoying by design (owner, round 9): like most games, a town has a calm theme and the outdoors has sparse random sounds, never a constant loop. Runtime rules: the bed plays quietly (about −12 dB under the emitters), and each area has a random accent (acc-<area>, 3 one-shot takes: a distant bell, a bird, thunder, a chime…) triggered every 15–45 s at random, never the same take twice in a row, ±6% pitch, quieter in combat. Town and GM-room music plays one 60 s loop, then rests in silence for 60–120 s before returning, and fades out in combat or under boss warnings. Emitters stay distance-based, so they are only heard near their prop.
• A new town or area stops the audio build until its prompt is written in gen-audio-requests.mjs, so no area ever falls back to a generic bed.
• Day, night and weather (ADR-030, 2026-10-06): each area bed gets a night variant, and weather adds one looped wind or rain layer on the ambience bus (time-weather.json). These requests are not written yet; add them in gen-audio-requests.mjs.

◆Boss encounter music

Special boss music is allowed, including encounters outdoors. Start the assigned theme when the authoritative encounter state engages a participating player, not merely because the player enters a boss zone or a hit event arrives. Join/reconnect resumes the current encounter state without restarting the theme for the party. Keep the loop through active phases; do not apply town/GM silence intervals to it. A phase change may transition at an authored musical boundary later; no extra phase stems are implied by these two initial briefs.

On victory, reset/leash, leaving the encounter, player death or loss of encounter membership, fade the theme and restore the ordinary area bed/emitters/accents. Local death ends that player's playback without stopping it for surviving participants. Re-entry acquires the current encounter state; exactly one theme can own the music bus. Music controls never affect combat outcomes. During a GM boss test, the assigned encounter theme replaces the calm GM loop, which returns afterward.

Keep combat/telegraph SFX above music: warning ducking is −6 dB, ambient accents are quieter in combat, and music volume/mute follows accessibility settings. Streams, fades and transitions respect the existing Low voice/memory budgets. Test encounter lifecycle, phase continuity, muted music, party joins, background/resume and warning audibility on the Low references and both cameras. Audio ownership/fade details must be authored before runtime implementation.

The catalog now contains two planned theme requests with boss, zone and playback: engaged_boss_encounter_only. This documentation update writes briefs; it does not generate music, validate loop seams, approve a take or implement playback. No licence delivery row is added until an asset is produced.

◆Per-skill audio cues

Each skill's presentation.sfx brief becomes cue ids (sfx:warblade.horizon_cleave.swish, …impact). The test audio-cues fails if any skill/monster ability has no cue bound, or if a cue's file is missing.

◆Tests