> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/game-design/07-content-audio-and-feature-inventory.md).

# Content, Audio, And Feature Inventory

**Project:** FactionOS — The War Effort **Document role:** Content, presentation, and asset brief

## 10. Bosses & Set-Piece Moments

Peak-fun punctuation, all mapped to real milestones:

* **Blight Titan (weekly):** the scanner's oldest/most-severe issue cluster materializes as a titan on its sector. Killing it = actually fixing the old debt. Guaranteed relic.
* **Campaign World Boss:** see §8 — campaign task queue as HP bar.
* **The Siege:** if `task_stalled` escalations pile up, siege engines reach the keep and a horn sounds — a *real* "your orchestration needs attention" alarm dressed as defense gameplay. Repelling it = using the existing recovery/diagnostic paths.
* **The Rumored Fifth:** the lobster unlock (exists) is the template — keep shipping *secrets* (hidden tomes, one-time map events, the Ouroboros legendary) so the community trades rumors.
* **Named Nemeses (fourth pass):** the most frustrating real-world pattern — the bug that keeps coming back — is currently anonymous enemy state. Fix: a **promotion rule**. A camp that survives ≥2 failed linked missions, a test path whose skirmisher respawns ≥3 times within a week, or a wraith stack that hits its cap gets a deterministic name (seeded from its stable key against a Legion name table — "Gorefang the Regressor", "Vex of the Broken Gate") plus a nameplate, a silhouette trim, and a Dawn Report mention ("Gorefang stirs again in apps/server"). A verified kill drops a guaranteed relic and the "Bane of ⟨name⟩" title, and writes the saga's best line. **Rule: nemeses only rename and dress existing enemy state** — no new HP, spawn, or kill logic; verification requirements unchanged. Why it's peak fun-per-engineering: recurring failure converts from ambient guilt into the game's most *anticipated* content, and its death into the game's best story. (Attachment works for enemies too.)

## 11. Juice & Sensory Design (using what's on the shelf)

* **Audio:** 12 music tracks (exist) → dynamic layering: calm exploration mix when idle, adds percussion stem per active hero, war horns on flares/sieges. 25 bark cues being replaced with recorded SFX (`docs/ongoing-projects/synthetic-sound-map.md`) — align the new SFX brief with the events table in §3. Faction voice lines (20 MP3s across all five factions) cover picks/clicks.
* **Visual:** stay inside the 2D DOM/CSS contract. Add: sector tinting, building smoke/level dressings, peon micro-units for subagents, flare/gate/ siege iconography, banner-planting animation, boss standees (one new art gen per boss type via existing media pipeline + provenance gates).
* **Reduced motion:** every juice element needs the static variant (contract already established in `docs/battlefield.md`).
* **Toast → Town Crier:** ToastTray (exists) gets herald framing for game events; keep work-critical toasts visually senior to game toasts. Always.

### Current Runtime Asset Baseline

The shipped media baseline is intentionally narrow:

* Approved 2D battlefield runtime set: one board background and five faction hero standees in `apps/web/public/battlefield/`, mirrored to `public-demo/assets/battlefield/`.
* Faction portraits: five JPG portraits in `apps/web/public/portraits/`, mirrored to `public-demo/assets/portraits/`.
* Background music: twelve full MP3 tracks in `apps/web/public/music/`, also present under `public-demo/assets/music/`.
* Click voice lines: twenty MP3 clips for orc, human, elf, undead, and lobster in `apps/web/public/speech/`, all mapped in `FACTION_CLICK_VOICE_LINES`. Public-demo Lobster `claw-*` clips remain reference-only unless demo parity is explicitly promoted.
* Bark SFX: fifteen MP3 clips under `apps/web/public/sfx/` for orc, undead, and lobster. Orc and undead non-error cues plus all five lobster cues are mapped. Human and elf non-error bark cues are absent; human, elf, orc, and undead error barks currently reuse recorded speech.
* Game-design Phases 1-3 have shipped projection state, scanner camps, live enemy presentation, combat playback, world-cue synth fallbacks, reduced motion parity, and typed Phase 3 generated-asset references. XP, loot, bosses, Dawn Report, dynamic music stems, War Games, and browser-loaded generated game-design PNGs remain future phase scope.

### Remaining Audio Backlog

| Gap                         | Needed to deliver                                                                                                                                                                                                                                                                                                                                                                | Current state                                                                                                                                    | Owning phase                 |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| Human bark SFX              | `human-idle`, `human-active`, `human-complete`, `human-celebration`; optionally a dedicated `human-error` if speech reuse is retired                                                                                                                                                                                                                                             | No human files are present under `apps/web/public/sfx/`; `sfxAssets.ts` comments mark them unsourced and reuse speech for error                  | Phase 4-5                    |
| Elf bark SFX                | `elf-idle`, `elf-active`, `elf-complete`, `elf-celebration`; optionally a dedicated `elf-error` if speech reuse is retired                                                                                                                                                                                                                                                       | No elf files are present under `apps/web/public/sfx/`; `sfxAssets.ts` comments mark them unsourced and reuse speech for error                    | Phase 4-5                    |
| Bark SFX policy pass        | Decide whether error barks stay speech-backed or become dedicated SFX for all five factions                                                                                                                                                                                                                                                                                      | `orc-error.mp3` and `undead-error.mp3` exist but are not mapped; human and elf dedicated error files are absent; lobster error is file-backed    | Phase 4-5                    |
| Lobster click voice lines   | Four premium unlock click lines in `FACTION_CLICK_VOICE_LINES` and app speech assets                                                                                                                                                                                                                                                                                             | App files and mapping exist; rights, catalog, loudness, credits, and demo-parity evidence are not fully recorded                                 | Phase 4 or 8                 |
| Recorded world cues         | File-backed versions of `camp_hit`, `camp_collapse`, `ram_crash`, `ram_break_triumph`, `skirmisher_red_slash`, and `flare_attention`                                                                                                                                                                                                                                             | Phase 3 shipped typed world cues with synth fallback; `SFX_FILES.world` is intentionally empty until recorded assets are auditioned and promoted | Post-Phase 3 media promotion |
| Full verb ceremony cue pack | Short cues for rally horn, summon/banner raise, flare douse, wax seal, plan scroll tear, portcullis raise/drop, target flag, class flare, contract stamp, tome pickup, salute/banner fold, decree gavel, scouts, report unfurl, missive unfurl, shield block, forge hit, lore glint, summon shimmer, low supply horn, trophy pin, scout report, flag flutter, and inspector seal | Not present as a coherent cue pack                                                                                                               | Phase 4-5                    |
| Dynamic music stems         | Calm/idle base, active-hero percussion layers, siege/flare horn layers, boss intensity layers, report/council/dawn stingers, and victory/kill punctuation                                                                                                                                                                                                                        | Current twelve tracks are full songs, not state-addressable stems or stingers                                                                    | Phase 9                      |
| Class and role barks        | Audio or short SFX identity cues for Bug Hunter, Test Engineer, Operator, Refactor Specialist, Scribe, Quartermaster, Feature Architect, and Wandering Generalist                                                                                                                                                                                                                | Class system exists as data; class barks do not                                                                                                  | Phase 5                      |
| Report and season audio     | Dawn Report underscore, Battle Report close, War Council objective completion, season rollover, saga page, Golden Age, and boss-week stingers                                                                                                                                                                                                                                    | Not present                                                                                                                                      | Phase 6, 9, 11               |

### Presentation Scope Guardrails

The current design does not need a new 3D battlefield runtime, a new base battlefield background for Phases 4-8, new hero standees for the five current factions, fake issue/progress/work media that cannot inspect through to a real source, or low-level admin/diagnostic artwork unless a later design rationale graduates that surface into the game layer.

### Existing Generated Visual Assets

`manifest.md` is the authoritative generated-asset record for IDs, dimensions, source assets, runtime posture, and visible equivalents. Before commissioning new visual production for this content brief, check these already-present production-generated assets:

| Content area                                    | Existing production-generated assets                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Live enemies, strikes, and reduced-motion twins | `assets/generated/game-design/phase03/live-enemies/live-enemy-effects-sheet.png`, `assets/generated/game-design/phase03/strike-vocabulary/strike-vocabulary-effects-sheet.png`, `assets/generated/game-design/phase03/reduced-motion/reduced-motion-static-badges-sheet.png`                                                                                                                                                  |
| Verbs and ceremony                              | `assets/generated/game-design/phase04/town-crier/town-crier-toast-chrome-sheet.png`, `assets/generated/game-design/phase04/command-ceremony/command-ceremony-props-sheet.png`, `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png`, `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png`, `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png` |
| Session, return, and onboarding loops           | `assets/generated/game-design/phase06/battle-report/battle-report-frame.png`, `assets/generated/game-design/phase06/war-council/war-council-objective-board.png`, `assets/generated/game-design/phase06/war-tide/war-tide-meter-sheet.png`, `assets/generated/game-design/phase06/dawn-report/dawn-report-recap-backdrop.png`, `assets/generated/game-design/phase06/onboarding/first-ten-minutes-onboarding-sheet.png`       |
| Map, home sector, and siege                     | `assets/generated/game-design/phase07/territory-map/territory-map-base.png`, `assets/generated/game-design/phase07/home-sector/home-sector-building-dressings.png`, `assets/generated/game-design/phase09/siege/siege-set-piece-static.png`                                                                                                                                                                                   |
| Progression, collections, and legends           | `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png`, `assets/generated/game-design/phase08/hero-quirks/hero-quirks-palette-sheet.png`, `assets/generated/game-design/phase08/tomes/tome-expansion-art-sheet.png`, `assets/generated/game-design/phase08/relics/relic-set-art-sheet.png`, `assets/generated/game-design/phase08/nemesis/nemesis-presentation-sheet.png`                |
| Bosses and set pieces                           | `assets/generated/game-design/phase09/bosses/blight-titan-standee.png`, `assets/generated/game-design/phase09/bosses/blight-titan-standee-chroma-source.png`, `assets/generated/game-design/phase09/bosses/null-sovereign-world-boss-standee.png`, `assets/generated/game-design/phase09/bosses/null-sovereign-world-boss-standee-chroma-source.png`                                                                          |
| Alliance War, seasons, saga, and War Games      | `assets/generated/game-design/phase10/alliance-war/alliance-war-visuals-sheet.png`, `assets/generated/game-design/phase11/seasons-saga/seasons-saga-visuals-sheet.png`, `assets/generated/game-design/phase12/war-games/war-games-demo-presentation-sheet.png`                                                                                                                                                                |

## 12. What Exists vs. What This Design Adds

| Layer                                                                                                                                                                                    | Status                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Factions, heroes, names, archetypes, barks, standees, board                                                                                                                              | ✅ shipped                                                                                      |
| Missions, tool events, plans, lineage, metrics, complexity, tags, specialization                                                                                                         | ✅ shipped                                                                                      |
| Scrolls (8), achievements (7, tiered, attributed), celebration bursts                                                                                                                    | ✅ shipped                                                                                      |
| Quest Board scanners + accept flow; Notice Board; War Room; campaigns/queues                                                                                                             | ✅ shipped                                                                                      |
| Leaderboard, faction standings, session rollup, replay, heatmap, efficiency, cost                                                                                                        | ✅ shipped                                                                                      |
| Music, voice lines; SFX replacement in flight                                                                                                                                            | ✅ / 🔶 in flight                                                                               |
| **Null Legion** (issue→enemy mapping, wraiths, sieges, dawn patrol)                                                                                                                      | 🆕 this design                                                                                 |
| **Territory map** (sectors=directories, fog, banners, building levels, fronts)                                                                                                           | 🆕 this design                                                                                 |
| **XP/levels/titles/quirks/Hall of Banners**                                                                                                                                              | 🆕 this design                                                                                 |
| **Loot rolls, relics, tome expansion**                                                                                                                                                   | 🆕 this design                                                                                 |
| **World bosses, Blight Titan, Siege set-pieces**                                                                                                                                         | 🆕 this design                                                                                 |
| **Alliance league, shared boss HP**                                                                                                                                                      | 🆕 (reskin of shipped War Room + campaigns)                                                    |
| **Seasons/prestige/saga chronicle**                                                                                                                                                      | 🆕 this design                                                                                 |
| **Battle Report end-of-session screen**                                                                                                                                                  | 🆕 (reskin of shipped SessionRollup)                                                           |
| Live dev-health events (`test_failure`/`test_pass`, `build_error/fix`, `ts_errors`, `lint_error`, `loop_update`)                                                                         | ✅ shipped, **un-exploited** — powers live skirmishers (§3, second pass)                        |
| Client verbs incl. `collect_scroll`, `hero_state_override`, plan/permission/guarded decisions                                                                                            | ✅ shipped — enumerated as the player-verb ceremony layer (§3A)                                 |
| **Combat playback** (mission events rendered as strikes on linked camp)                                                                                                                  | 🆕 second pass (§5A)                                                                           |
| **Essence sinks** (tithe→buildings, cosmetic treasury)                                                                                                                                   | 🆕 second pass (§7A)                                                                           |
| **Dawn Report / Return loop, First Ten Minutes**                                                                                                                                         | 🆕 second pass (§4)                                                                            |
| **`gameProjection.ts`** — single pure reducer, the only new state module                                                                                                                 | 🆕 second pass (§15); state shape + event map + persistence cadence sketched third pass (§15A) |
| **Boredom Audit constraints** (champion mode, map legibility budget, combo strikes, flare ceremony budget, entrenchment, wraith stacking, single-pulse alertFocus, replay honesty guard) | 🆕 third pass (§14)                                                                            |
| **Phase A buildable spec** (DOM layers, CSS-only visuals + static twins, SFX plan, 8 acceptance criteria)                                                                                | 🆕 third pass (§13A)                                                                           |
| **War Council session objectives** (declared stakes → Battle Report ledger)                                                                                                              | 🆕 fourth pass (§4B)                                                                           |
| **Class Advantage** (specialization × quest affinity muster decision)                                                                                                                    | 🆕 fourth pass (§6A)                                                                           |
| **Named Nemeses** (recurring-failure promotion; relic + title on verified kill)                                                                                                          | 🆕 fourth pass (§10)                                                                           |
| **War Tide meter** (single glance topline: advancing/holding/losing)                                                                                                                     | 🆕 fourth pass (§4)                                                                            |
| **Joint assault rendering** (multi-mission camp sieges, shared banner credit)                                                                                                            | 🆕 fourth pass (§5A)                                                                           |
| **Dispatch Scouts verb** (manual scan trigger as scouting ceremony)                                                                                                                      | 🆕 fourth pass (§3A; graduated from hold-out)                                                  |
| **Emissary missives** (inbound channel command arrival + approval ceremony)                                                                                                              | 🆕 fourth pass (§3/§3A; graduated from hold-out)                                               |
| **War Games demo substrate** (mock generator powers the §5B synthetic front, progress-inert)                                                                                             | 🆕 fourth pass (§5B; graduated from hold-out)                                                  |

## 12A. Implemented Audio And Sensory Substrate

Code references: `apps/web/src/lib/backgroundMusic.ts`, `apps/web/src/store/useBackgroundMusic.ts`, `apps/web/src/components/MusicToggleButton.tsx`, `apps/web/src/lib/audioRuntime.ts`, `apps/web/src/store/useAudioRuntimeStore.ts`, `apps/web/src/store/useVoiceBarks.ts`, `apps/web/src/store/useFactionVoiceLine.ts`, `apps/web/src/lib/factionVoiceLines.ts`, `apps/web/src/lib/fileVoiceSynth.ts`, `apps/web/src/lib/sfxAssets.ts`, `apps/web/src/components/SettingsDrawer.tsx`. Focused tests: `apps/web/tests/audioRuntime.test.ts`, `apps/web/tests/SettingsAudio.test.tsx`, `apps/web/tests/FactionVoiceLine.test.tsx`, `apps/web/tests/factionVoiceLines.test.ts`.

* Background music playback is opt-in, uses a 12-track playlist, loops through the playlist, advances when a track ends, skips failed loads, persists resume point, and honors volume settings.
* Recorded hero and faction voice lines already play on click when audio is enabled, with volume setting and cutoff to prevent overlapping click lines.
* Hero state-transition barks cover active, idle, error, completed, and dismissed states, with per-hero bark rate limiting.
* Audio unlock waits for first pointer interaction, and playback failures can surface a toast warning when blocked or unavailable.
* File-backed SFX already have synthesized fallback, duplicate cue guard by cue id, and audio status states for unsupported, locked, unlocked, playing, blocked, failed, muted, and unavailable.
* Design implication: world cues added by Phase A should sit beside this runtime, preserve opt-in behavior, and inherit the existing fallback and rate-limit posture.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/docs/game-design/07-content-audio-and-feature-inventory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.