> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/game-feel.md).

# AI Rogue Game Feel And Audio Baseline

**Status**: Current **Checked**: 2026-07-01

This document records the durable game-feel behavior and runtime contracts for AI Rogue. It intentionally excludes session logs, generation prompts, and completed task history.

## Runtime Shape

AI Rogue keeps `render-model.ts` as a pure projection of one simulation snapshot. Clock-driven presentation lives in `runtime/effects.ts`, which owns the transient effect state that must animate between turns.

The renderer uses separate presentation layers:

* World layers are camera-offset and screen-shaken together.
* `worldFx` holds world-anchored impact sprites and particles.
* `overlay` holds HUD text, event banners, floating numbers, flashes, transitions, and end screens.

`runtime/pixi-runtime.ts` exports the Pixi primitives used by this layer, including `Text` and `TextStyle`. Keep Pixi imports behind the AI Rogue runtime facade so PixiJS stays out of the extension registry, app shell, and unit-test graphs that do not mount the Play route.

All animated effects must honor reduced motion. With reduced motion enabled, the game should stay readable through static or instant feedback instead of running tweens, screen shake, or decorative motion.

## Current Game-Feel Behavior

The Play route renders numeric state on the canvas:

* HP, shards, depth, turn, class, and relic are drawn in the HUD.
* The bottom event banner echoes the latest readable combat event.
* Combat, pickup, and damage events can spawn floating numbers.

Combat and movement presentation is event-driven:

* Hit, surge, pickup, and defeat events use packed `fx_*` atlas frames, particles, rings, and fades.
* Kills and player damage can apply short hit-stop and small decaying screen shake.
* Entity movement interpolates between tiles for normal turn changes.
* Camera origin eases toward the render-model target and snaps on descend, reset, and load.
* Player damage uses a red full-canvas flash, low-HP HUD pulse, damage vignette, and low-HP heartbeat audio.

Atmosphere and enemy readability are part of the baseline:

* Background color grade changes by authored level theme.
* The screen uses an edge vignette and drifting scanline/grid treatment.
* Standard enemies idle between available frames.
* Kernel Arena and Firewall Gauntlet exit guards use the Kernel Sentinel boss. It remains a one-tile logical blocker, renders at 2x tile size through `spriteScale`, and cycles through the packed boss idle frames. The final defense projection is owned by Firewall Gauntlet finale metadata, not by depth alone.
* Firewall Sentry attacks use a delayed warning model: the warning turn stores a pending line, the player gets one action to move or kill the sentry, and the next enemy turn only fires if the sentry is alive, still at the warning origin, still has line of sight, and the player remains on the originally warned segment within range.
* `threat` events pulse a `telegraph_warning_target` marker, while pending sentry threats keep a visible warning line on the board during the dodge turn.

Run arc presentation is also part of the baseline:

* Start and descend show a sector intro card.
* Descend plays a short fade transition.
* Relic shrine tiles render as full before collection and empty after one shrine choice consumes the floor's remaining relic choices. Pickup state stays the logical interaction source; shrine tiles and icons are presentation.
* Shrine choices use specific `icon_relic_*` UI atlas frames, and the HUD keeps active in-run relic effects visible after the pickup event scrolls out.
* Relic pickup shows a brief golden relic moment.
* Victory and defeat use an end screen with result glyphs and run stats.

## Simulation And Save Contracts

The game-feel runtime is persisted through the existing save schema version 1. Additive fields use safe defaults so older saved runs continue to parse, and whole level specs stay in the content registry rather than in save payloads:

* `depth` and `maxDepth` select the authored level while the registry owns the level spec.
* `activeRelicEffects` stores collected in-run shrine effects in order.
* `pendingThreats` stores delayed sentry warning lines across save/load, including source enemy, origin, target, and due turn.
* `kernel-sentinel` is a valid enemy kind. Its current template uses ranged sentry behavior with 18 HP, 4 attack, 2 defense, 6 range, and a 2x visual sprite scale.
* `insight-beetle` is valid saved enemy content and is guaranteed on Firewall Gauntlet as the first prepared real-content enemy path.
* `relic-shrine` is a passable, non-sight-blocking tile kind.

In-run shrine effects map to stable UI atlas frames:

* `overclock` -> `icon_relic_overclock`
* `hardening` -> `icon_relic_hardened_chassis`
* `capacitor` -> `icon_relic_surge_capacitor`

Do not conflate progression loadout relics with in-run shrine relic effects. The loadout relics still represent Syntax Compass, Context Cache, and Integrity Seal; shrine effects represent Overclock Core, Hardened Chassis, and Surge Capacitor.

## Audio Runtime Contract

AI Rogue audio is implemented in `runtime/audio.ts`. The module is the playback, mixing, looping, and preference layer only. Sound sources are committed, project-owned generated assets:

* Music: six Ogg Opus tracks under `src/assets/ai-rogue/audio/music/`, with provenance in `src/assets/ai-rogue/audio/music/provenance.json`.
* SFX: 64 Ogg Opus effects under `src/assets/ai-rogue/audio/sfx/`, with provenance in `src/assets/ai-rogue/audio/sfx/provenance.json`.
* Theme ambience: five low-gain Ogg Opus loops under `src/assets/ai-rogue/audio/music/`, with provenance in `src/assets/ai-rogue/audio/music/provenance.json`.

The audio engine requirements are:

* Create or resume the `AudioContext` only after a user gesture through `unlock()`, so browser autoplay policy is respected.
* Load and decode buffers lazily; cache decoded buffers by URL.
* Dynamically import the audio module from the renderer so eager audio asset globs do not enter happy-dom unit tests.
* Degrade to a silent no-op engine when Web Audio is unavailable.
* Persist `audioMuted`, `musicVolume`, and `sfxVolume` through the AI Rogue preferences schema and Settings view.
* Support typed adaptive requests for high-value gameplay moments through bounded music/theme ambience ducking and dedicated committed stinger SFX cues.
* Do not add a compressor, sidechain dependency, separate adaptive-audio preference, save field, or remote content path.
* Treat Web Audio as an internal engine; do not add an external audio wrapper unless a later profiling or feature need justifies the dependency.

Music behavior:

* Title loop plays before a run after audio unlock.
* Starting a run switches to the sector loop declared by the current authored level.
* Descend events crossfade to the next authored level's declared sector loop.
* Win and loss states crossfade to victory or defeat themes.
* Reset and destroy stop music.

Theme ambience behavior:

* Theme ambience is a second low-gain lane beside the primary music lane, not a replacement for title, depth, victory, or defeat music.
* The route is selected from `snapshot.theme` through stable IDs: `theme_cold_cache_ambience`, `theme_corrupted_index_ambience`, `theme_kernel_core_ambience`, `theme_firewall_ambience`, and `theme_model_vault_ambience`.
* Starting a run begins the current theme ambience. Descending changes ambience only when the new snapshot theme changes, so deeper clamped themes do not retrigger the same bed.
* Victory, defeat, reset, load, and destroy stop theme ambience before terminal or inactive-run states.
* The lane uses the existing master mute and music volume preferences. There is no separate ambience volume, Settings UI control, save field, or schema change.
* Missing ambience assets, failed fetches, failed decodes, and unavailable Web Audio remain silent no-ops.
* The shipped Session 05 ambience files are `theme_cold_cache_ambience.ogg`, `theme_corrupted_index_ambience.ogg`, `theme_kernel_core_ambience.ogg`, `theme_firewall_ambience.ogg`, and `theme_model_vault_ambience.ogg`. They are local 48 kHz stereo Ogg Opus loops, each about 16 seconds and below the 900 KB AI Rogue music-track cap.
* Theme ambience is review-scoped as subtle environmental identity. It should support sector mood without masking SFX, changing simulation behavior, or replacing title, depth, victory, or defeat music.

SFX behavior:

* Simulation events drive one-shots for strike, hit, surge, enemy defeated, enemy melee, enemy-family attack/defeat, sentry charge/fire, boss charge/fire/hit/shutdown, shield absorb/break, hazard, status, protocol, objective, pickup, door, terminal, vault, cache, descend, ranged telegraph, win, and loss cues.
* Event metadata may provide explicit `audioCues`; otherwise `runtime/audio.ts` uses typed actor/enemy/intent metadata before legacy event-type mapping. High-frequency cues use deterministic variants keyed from event IDs.
* Start requests the `combat_start` adaptive moment, which uses the dedicated `stinger_combat_start` one-shot. Runtime controls use a restrained UI click for pause/resume, reset, save, and load confirmations.
* Low HP starts the heartbeat loop at active run HP ratios above 0 and at or below 30%; recovery, terminal states, reset, and destroy stop it.

Adaptive request behavior:

* The runtime exposes `requestAdaptiveAudio()` for `combat_start`, `low_hp`, `boss_reveal`, `objective_unlock`, `final_defense`, `victory_transition`, and `defeat_transition`.
* Each request has a stable cooldown key so repeated triggers cannot stack dedicated stingers or ducking envelopes.
* Adaptive requests transiently lower the primary music and theme ambience lanes only. Master mute, music volume, SFX volume, autoplay unlock, lazy decode, heartbeat, theme ambience, terminal music, and silent fallback keep their existing behavior.
* Renderer routing stays presentation-only. It derives requests from existing event cues, previous/current snapshots, health ratio entry, visible Kernel Sentinel reveal, and terminal status transitions without changing simulation RNG, replay state, saves, scoring, or balance.
* Objective, final-defense, victory, and defeat events still emit their ordinary one-shot SFX. The adaptive layer now plays separate dedicated stingers behind the same request IDs, with cooldowns preventing clutter.
* The dedicated Session 07 stinger files are `58_stinger_combat_start.ogg`, `59_stinger_low_hp.ogg`, `60_stinger_boss_reveal.ogg`, `61_stinger_objective_unlock.ogg`, `62_stinger_final_defense.ogg`, `63_stinger_victory_transition.ogg`, and `64_stinger_defeat_transition.ogg`.

## Session 07 Adaptive Stinger Result

The Phase 36 Session 07 implementation on 2026-06-28 added seven dedicated adaptive stingers behind the Session 06 request IDs:

* Combat start uses a short tactical lock-on pulse.
* Low HP uses a restrained pressure warning sting while the heartbeat loop remains the sustained health cue.
* Boss reveal uses a heavier Kernel Sentinel wake-up hit.
* Objective unlock uses a cleaner tactical success pulse.
* Final defense uses a compact payload-ready alarm hit.
* Victory transition uses a bright core-release success sting.
* Defeat transition uses a short core-dump collapse sting.

Files 58-64 are mono 48 kHz Ogg Opus SFX under `src/assets/ai-rogue/audio/sfx/`, each below 12 KB and below the 200 KB SFX cap. Provenance records the prompts, local ffmpeg render path, raw scratch byte counts, and final render metadata. Raw WAV masters stay in the gitignored `tmp/ai-rogue-adaptive-stingers/` scratch directory.

Playback notes:

* Adaptive request IDs, cooldowns, music/theme ambience ducking, mute, volume, autoplay unlock, lazy decode, failed fetch/decode fallback, silent no-op behavior, and route disposal cleanup remain on the existing audio engine path.
* Renderer routing remains presentation-only and does not change simulation RNG, replay state, saves, scoring, economy, or gameplay balance.
* The Play product surface does not expose adaptive-audio diagnostics; proof lives in focused unit tests, browser tests, and session implementation notes.

Review notes:

* The stingers are deliberately short and conservative so they can punctuate high-value state changes without covering combat, pickup, objective, or terminal SFX.
* Automated checks can verify routing, file format, fallback paths, cooldowns, and browser source starts, but they cannot make a human acoustic masking or fatigue judgment. Session 08 final closeout accepted the current stinger balance for this pack; future tuning should happen in a fresh gameplay tuning session.

## Phase 36 Final Audio Validation Result

The Phase 36 Session 08 closeout on 2026-06-28 approved the shipped AI Rogue audio pack after direct review links were provided for all committed music, theme ambience, SFX, and adaptive stinger Ogg files.

Validated shipped asset counts:

* Music: six primary Ogg Opus tracks under `src/assets/ai-rogue/audio/music/`.
* Theme ambience: five low-gain Ogg Opus loops under `src/assets/ai-rogue/audio/music/`.
* SFX and stingers: 64 Ogg Opus files under `src/assets/ai-rogue/audio/sfx/`, including seven adaptive stingers.

Final listening and balance verdicts:

* Desktop review is approved for title unlock, run start, controls, movement, wall-bump fatigue, pickups, combat, objective/final-defense beats, boss reveal, low HP, victory/defeat, mute and volume controls, and silent fallback.
* Mobile review is approved for touch start unlock, compact controls, pickup/combat SFX, volume balance, mute behavior, and no horizontal overflow.
* The previous watch-list cues (`45_wall_bump_variant_a.ogg`, `terminal_open`, `cache_open`, `compile_payload`, `shield_break`, `status_applied`, and `status_cleansed`) require no Phase 36 gain or asset repair.
* The title loop, theme ambience beds, and adaptive stingers are accepted for the current shipped pack. Any future replacement should be driven by a fresh gameplay tuning session, not by this audio closeout.

Final validation evidence:

* `bun run typecheck` passed.
* `bash scripts/check-asset-sizes.sh` passed.
* Focused audio, combat, and protocol Vitest suites passed.
* AI Rogue runtime and mobile Playwright suites passed.
* Provenance records cover all 11 committed music/ambience files and all 64 committed SFX/stinger files.

No Phase 36 closeout change introduced remote loading, hosted writes, collectors, analytics, workers, WebGPU-only behavior, save schema changes, or simulation behavior changes.

## Session 01 Audio Review Result

The Phase 36 Session 01 implementation review on 2026-06-28 confirmed the current browser playback path without changing runtime code or media assets.

Passed browser-path checks:

* Desktop Start creates the unlock path and fetches the queued title loop, `run_start`, and depth 1 sector music through the lazy Web Audio decode path.
* Pause, resume, save, and reset keep UI sound restrained to `ui_click` variants instead of adding sound to every control.
* Settings persist `audioMuted`, `musicVolume`, and `sfxVolume`; muting keeps the volume values available for later unmute.
* Removing `AudioContext` and `webkitAudioContext` leaves gameplay functional with no audio fetches and no page errors.
* Mobile 390x844 touch review keeps compact controls usable, triggers the Start audio path and a gameplay pickup SFX, persists mute/volume settings, and avoids horizontal overflow on Play and Settings.
* Deterministic simulation scenarios emit protocol, terminal, vault, cache, objective, compile-choice, final-defense, and victory cues through supported runtime paths.

Balance caveats from the objective volume scan, resolved by Session 08 closeout:

* `45_wall_bump_variant_a.ogg` remains the loudest mean SFX, but the final review accepted it for this shipped pack.
* `terminal_open`, `cache_open`, `compile_payload`, `shield_break`, `status_applied`, and `status_cleansed` were accepted without Phase 36 gain lift or replacement.
* `compile_payload` is the final payload-defense cue. Ordinary compile-level readiness uses `objective_unlock`, and accepting a compile upgrade uses `equipment_equip`.
* The title loop browser path passes and its pre-run loop suitability is accepted for this shipped pack.

## Session 03 Enemy And Boss SFX Result

The Phase 36 Session 03 implementation on 2026-06-28 added files 46-57 for enemy-family and Kernel Sentinel boss identity:

* Fast enemies (`signal-gnat`, `ping-mosquito`, `index-skink`, and `cache-wraith`) use `enemy_fast_attack` and `enemy_fast_defeated`.
* Packet Thief uses `enemy_thief_grab` and `enemy_thief_escape`.
* Corruption enemies (`corrupt-newt`, `venom-daemon`, `burst-toad`, and `insight-beetle`) use `enemy_corruption_attack` and `enemy_corruption_defeated`.
* Firewall Sentry uses `enemy_sentry_charge` for telegraph and `enemy_sentry_fire` for fire.
* Kernel Sentinel uses `boss_charge`, `boss_fire`, `boss_hit`, and `boss_shutdown`.
* `errant-process`, unknown metadata, missing new URLs, and incomplete metadata keep generic fallback or no-op behavior.

All 12 new SFX are mono 48 kHz Ogg Opus assets below 10 KB each. Session 03 browser path verification confirmed the new URLs are fetched and source starts are requested through simulated real AI Rogue encounter events on desktop 1440x1000 and mobile 390x844 viewports. Session 08 final closeout accepted the current enemy and boss audio balance for this pack.

Follow-up ownership:

* Session 02/03 completed typed enemy-family metadata and enemy/boss audio identity.
* Session 04/05 completed theme ambience routing and assets.
* Session 06/07 completed the adaptive-audio request contract and dedicated stingers.
* Session 08 completed final full-pack audio closeout evidence.

## Session 05 Sector Theme Ambience Result

The Phase 36 Session 05 implementation on 2026-06-28 added the five committed theme ambience loops that Session 04 reserved:

* Cold Cache uses a coolant hum and restrained high shimmer.
* Corrupted Index uses an unstable glitch bed and narrow data tones.
* Kernel Core uses a low drive hum with overclocked machine pressure.
* Firewall uses a distant alarm pulse and warm security-field pressure.
* Model Vault uses restrained sub-bass and locked archive resonance.

All five final files are generated locally through `scripts/generate-ai-rogue-theme-ambience.ts`; raw WAV masters stay in gitignored `tmp/ai-rogue-theme-ambience/`. The committed files are final Ogg Opus renders under `src/assets/ai-rogue/audio/music/`, with per-file prompt, scratch path, byte count, duration, codec, channels, and sample-rate metadata in music provenance.

Playback notes:

* Theme ambience starts from the current `snapshot.theme` after audio unlock.
* Descending across the five sector themes changes ambience while the primary depth music lane continues unchanged.
* Master mute and music volume affect the ambience lane through the existing music bus relationship.
* Failed request, failed decode, missing file, unavailable Web Audio, reset, load, victory, defeat, and route destroy paths remain silent-safe no-ops or cleanup paths.

Review notes:

* The loops are intentionally short, tonal, and low-detail to fit the ambience lane and the media budget without competing with tactical SFX.
* Session 05 browser proof covers real committed file fetches and source starts on desktop and mobile viewports, with no injected asset URLs.
* Session 05 route review opened the AI Rogue Play product surface on desktop and mobile, started the runtime, and confirmed diagnostics remain confined to tests and notes rather than normal visible UI.
* Agent review can verify routing, load/decode fallback, mute/music-volume wiring, and product-surface cleanliness, but cannot make a human acoustic fatigue judgment. Session 08 final closeout accepted the current ambience beds for this pack; future tuning should happen in a fresh gameplay tuning session.

## Asset Contract

Game-feel work should use the committed runtime assets before requesting more generation.

Visual runtime assets are packed into:

* `src/assets/ai-rogue/gameplay-atlas.png`
* `src/assets/ai-rogue/gameplay-atlas.json`
* `src/assets/ai-rogue/ui-atlas.png`
* `src/assets/ai-rogue/ui-atlas.json`

The durable visual inventory, source-image provenance, palette, and acceptance rules live in [Visual Assets](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/visual-assets.md).

Important packed frame groups include:

* `fx_*` impact, surge, pickup, death, and dust frames.
* `telegraph_warning_*` warning frames.
* `tile_g3_*` and `decal_g3_*` sector identity frames for Cold Cache, Corrupted Index, Firewall, Model Vault, and Kernel Core.
* `boss_kernel_sentinel_*`, `fx_boss_*`, and `final_defense_*` boss and final compile-payload defense frames.
* `tile_relic_shrine_*` shrine frames.
* `icon_relic_*` relic icons.
* `icon_status_*`, `icon_equipment_*`, and `icon_tier_*` status, equipment, and material-tier UI frames.
* `icon_g6_*`, `panel_g6_*`, result badge, HUD marker, wallet, storage, audio, and contrast UI frames.
* `frame_title_*`, `frame_end_*`, result glyphs, and result grid tiles.

The current packed contract is 234 gameplay frames and 146 UI frames. The G7 player-animation source sheet was rejected for direct runtime use at 16x16, so the stable player contract remains the four facing frames: `player_down_0`, `player_left_0`, `player_right_0`, and `player_up_0`.

The boss, shrine, relic icon, sector, status/equipment, final-defense, and result UI frames are active in generated play, React surfaces, or the render model where documented in [Visual Assets](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/visual-assets.md). New media should not be added for these behaviors unless a later visual pass deliberately replaces the current atlas set.

## Maintenance Checks

When changing game-feel behavior, keep these checks current:

* Type-check the project.
* Run focused AI Rogue tests and full Vitest when shared runtime contracts change.
* Run `bash scripts/check-asset-sizes.sh` after any media or atlas change.
* Browser-smoke the Play route for canvas readability. Headless tests can verify pixels, but audio output still needs a real browser/manual check.


---

# 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://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/game-feel.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.