> 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/new-level-authoring-guide.md). # AI Rogue New Level Authoring Guide **Status**: Current operational guide **Checked**: 2026-07-01 Use this guide when someone asks for more AI Rogue levels, for example: ``` I want you to build me 3 more levels for the game. ``` The expected workflow is inventory first, asset gap report second, and implementation third. Do not jump straight into code if the requested levels depend on new art, audio, mechanics, or saved IDs that are not already present. ## Operating Rule Before implementing new levels, inspect the shipped content and media inventories, then produce a concrete expansion plan: 1. Which requested levels can be built by reusing existing content. 2. Which requested levels need new assets or new code contracts. 3. The exact asset IDs, frame names, audio IDs, and destination paths needed. 4. The implementation files and validation commands that will be touched. If no new assets are needed, proceed with implementation after documenting the reuse decisions. If assets are needed and the user intends to provide them locally, stop after the asset gap report and wait for those local files or an explicit instruction to reuse existing assets instead. ## Current Architecture Facts AI Rogue is a typed, reviewed, repo-local extension. It is not a remote content loader, mod system, or dynamic data-pack runtime. The shipped main run is source-owned and deterministic. The level-authoring surface starts in `runtime/content/` and then projects into specialized runtime catalogs: | Concern | Current Source | | -------------------------------- | ----------------------------------------------------------------------------------------- | | Full-run depth | `runtime/run-factory.ts` derives `AI_ROGUE_MAX_DEPTH` from `AI_ROGUE_LEVEL_SPECS.length`. | | Level registry | `runtime/content/levels.ts` and `runtime/content/types.ts`. | | Registry validation | `runtime/content/validate.ts` and `runtime/content/__tests__/levels.test.ts`. | | World generation | `runtime/world-generator.ts` resolves an authored level spec by depth. | | Floor lessons and guarantees | `runtime/floor-arc.ts` projects from level specs for authored depths. | | Sector themes and enemy pressure | `runtime/themes.ts` projects from level specs for authored depths. | | Theme tile/decal mapping | `runtime/theme-visuals.ts`. | | Prefab encounter overlays | `runtime/prefabs.ts`. | | Enemy templates and pickups | `runtime/entities.ts` and `runtime/types-entities.ts`. | | Protocol pickup order and specs | `runtime/protocols.ts`. | | Terminal contracts | `runtime/terminals.ts`. | | Equipment and compile rewards | `runtime/equipment.ts` and `runtime/compile.ts`. | | Boss and finale contracts | `runtime/boss-contracts.ts` and `runtime/boss-presentation.ts`. | | Audio routing | `runtime/audio.ts` and `runtime/renderer-audio-adapter.ts`. | | Atlas frame contracts | `runtime/types-assets.ts`, `runtime/assets.ts`, and content-derived frame checks. | | Save and privacy validation | `src/extensions/ai-rogue/save-schema.ts`. | The current depth assembly is: ``` depth -> authoredLevelSpecForDepth(depth) -> createAiRogueWorld({ levelSpec }) -> applyLevelGuarantees(levelSpec) -> musicTrackForDepth(depth) -> themeAmbienceForTheme(theme) -> finalePresentationSpecForDepth(depth) ``` The level spec owns the authored identity: theme, room modifier, baseline protocol, music, ambience, exit guard, terminal, prefab, enemy table, guarantees, objective, and finale metadata. `themeAmbienceForTheme()` maps by theme ID, and `validateAiRogueContentRegistry()` rejects a level ambience that does not match the theme's `audioHint`. Main-run lookup is intentionally strict: * `levelSpecForDepth(depth)` returns an authored spec for valid depths and throws `AiRogueLevelSpecLookupError` outside the authored main-run range. * `authoredLevelSpecForDepth(depth)` returns a spec or `null`. * Legacy helper fallbacks still exist for focused fixture paths, but the playable main run should not silently clamp or rotate into unplanned content. * If an endless mode is added later, it needs its own explicit policy instead of weakening the authored-main-run rules. ## Current Reusable Inventory This is the inventory a future agent should start from before asking for new assets. ### Authored Levels Current main run levels live in `src/extensions/ai-rogue/runtime/content/levels.ts`. | Depth | ID | Theme | Music | Ambience | Finale | | ----- | ------------------- | ----------------- | ---------- | -------------------------------- | ------ | | 1 | `boot-sector` | `cold-cache` | `sector_1` | `theme_cold_cache_ambience` | No | | 2 | `index-maze` | `corrupted-index` | `sector_2` | `theme_corrupted_index_ambience` | No | | 3 | `kernel-arena` | `kernel-core` | `sector_3` | `theme_kernel_core_ambience` | No | | 4 | `firewall-gauntlet` | `firewall` | `sector_3` | `theme_firewall_ambience` | Yes | `AI_ROGUE_MAX_DEPTH` derives from `AI_ROGUE_LEVEL_SPECS.length`. Adding main-run levels means appending contiguous depths and moving final-level metadata to the new last authored level unless the work is explicitly creating a separate mode. ### Themes Current theme IDs live in `src/extensions/ai-rogue/runtime/themes.ts` and visual frame mapping lives in `src/extensions/ai-rogue/runtime/theme-visuals.ts`. | Theme ID | Current Use | Asset Status | | ----------------- | --------------------------------------------- | --------------------------- | | `cold-cache` | Depth 1 opening floor | Visuals and ambience exist. | | `corrupted-index` | Depth 2 status/pressure floor | Visuals and ambience exist. | | `kernel-core` | Depth 3 kernel/finale pressure | Visuals and ambience exist. | | `firewall` | Depth 4 reused-media finale floor | Visuals and ambience exist. | | `model-vault` | Available catalog theme, not used in main run | Visuals and ambience exist. | `model-vault` is the lowest-friction candidate for a reused-media fifth level because visual frames and ambience already exist. A new theme requires theme type/schema updates, visual frames, ambience routing, and tests. ### Enemies Enemy IDs and templates live in `src/extensions/ai-rogue/runtime/entities.ts`. Persisted enemy IDs live in `src/extensions/ai-rogue/save-schema.ts`. | Enemy ID | Current Role | Art Status | | ----------------- | ---------------------------------- | ---------------------- | | `errant-process` | Baseline melee chaser | Legacy frames exist. | | `firewall-sentry` | Ranged sentry | Legacy frames exist. | | `cache-wraith` | Fast rusher | Five-frame set exists. | | `packet-thief` | Loot thief | Five-frame set exists. | | `kernel-sentinel` | Boss/exit guard/finale boss | Boss frame set exists. | | `signal-gnat` | Small jam-on-hit enemy | Five-frame set exists. | | `ping-mosquito` | Fast shard-pressure enemy | Five-frame set exists. | | `index-skink` | Leaking/status pressure enemy | Five-frame set exists. | | `corrupt-newt` | Contact-punish enemy | Five-frame set exists. | | `venom-daemon` | Corruption/status enemy | Five-frame set exists. | | `burst-toad` | Tempo/self-jam enemy | Five-frame set exists. | | `insight-beetle` | Prepared real-content reward enemy | Five-frame set exists. | Current enemy audio families are `fast`, `thief`, `corruption`, `sentry`, `boss`, and `generic`. New standard monsters should usually reuse one of these families unless their identity needs dedicated SFX. ### Protocols, Terminals, Prefabs, And Pickups | Catalog | Current IDs | | ------------ | ------------------------------------------------------------------------------------------------------ | | Protocols | `patch-kit`, `trace-map`, `signal-jammer`, `trace-lance`, `phase-step` | | Terminals | `patch-mirror`, `quarantine-terminal` | | Prefabs | `crossfire-sentries`, `hazard-cache`, `thief-stash`, `boss-anteroom` | | Pickup kinds | `insight-shard`, `health`, `upgrade-relic`, `context-cache`, `protocol`, `key-fragment`, `cache-chest` | New item-drop or reward types need simulation behavior, save schema coverage, frame contracts, atlas entries, HUD/inspect copy when visible, and tests. Do not add a new pickup kind just for flavor if an existing cache, protocol, key fragment, shrine, terminal, or equipment reward can carry the decision. ### Audio Audio assets live under `src/assets/ai-rogue/audio/`. Runtime routing lives in `src/extensions/ai-rogue/runtime/audio.ts`. Current music IDs: * `title` * `sector_1` * `sector_2` * `sector_3` * `victory` * `defeat` Current ambience IDs: * `theme_cold_cache_ambience` * `theme_corrupted_index_ambience` * `theme_kernel_core_ambience` * `theme_firewall_ambience` * `theme_model_vault_ambience` Current SFX coverage includes player actions, pickups, protocols, terminals, vault/cache/equipment, objective/final-defense, enemy families, boss cues, and adaptive stingers. Add new SFX only when the existing cue families would make the new level's identity unclear. ### Visual Assets Runtime atlases live at: * `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` Generated source and crop records live under: * `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/` * `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/alpha/` * `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` The packer is: ```bash python3 scripts/extensions/ai-rogue/pack-visual-assets.py ``` The active asset inventory and provenance narrative live in `docs/extensions/ai-rogue/visual-assets.md`. The Phase 39 no-new-media closeout and future asset conditions live in `docs/ongoing-projects/ai-rogue-phase-39-asset-generation-plan.md`. ## Intake Workflow For "Build X More Levels" ### 1. Clarify The Level Count And Content Ambition Usually this can be inferred from the request: * "Build 2 more levels" means append depths 5 and 6 to the authored main run. * "Build X more levels using existing assets" means no new art/audio requests; reuse current themes, enemies, music, ambience, pickups, terminals, prefabs, and protocols deliberately. * "Build X real levels" means each level needs recognizable identity in theme, encounter pressure, objective, enemy mix, reward hook, and audio. For large asks, split implementation by content pack. One new level with a new enemy or theme is a realistic session. Several levels plus new monsters, SFX, soundtracks, and item art should become multiple sessions. ### 2. Inventory The Current Repo Read these files before proposing assets: | Area | Files | | ---------------------- | -------------------------------------------------------------------------------------------------------- | | Level registry | `src/extensions/ai-rogue/runtime/content/levels.ts`, `types.ts`, `validate.ts` | | Architecture and rules | This guide, `docs/extensions/ai-rogue/gameplay-depth.md`, `docs/extensions/ai-rogue/game-feel.md` | | Asset inventory | `docs/extensions/ai-rogue/visual-assets.md`, atlas JSON files, crop manifest | | Audio inventory | `src/extensions/ai-rogue/runtime/audio.ts`, `src/assets/ai-rogue/audio/**/provenance.json` | | Enemy inventory | `src/extensions/ai-rogue/runtime/entities.ts`, `types-entities.ts` | | Theme inventory | `src/extensions/ai-rogue/runtime/themes.ts`, `theme-visuals.ts` | | Gameplay catalogs | `protocols.ts`, `terminals.ts`, `prefabs.ts`, `equipment.ts`, `status.ts`, `compile.ts` | | Save contracts | `src/extensions/ai-rogue/save-schema.ts`, `src/extensions/ai-rogue/__tests__/save-schema-parity.test.ts` | | Validation precedent | `.spec_system/archive/phases/phase_39/`, `.spec_system/specs/phase39-*` | Useful inspection commands: ```bash find src/assets/ai-rogue -maxdepth 4 -type f | sort find docs/ongoing-projects/generated/ai-rogue-visual-audio-assets -maxdepth 3 -type f | sort rg -n "AI_ROGUE_LEVEL_SPECS|AiRogueEnemyKind|AI_ROGUE_ENEMY_TEMPLATES|AI_ROGUE_SECTOR_THEMES|AI_ROGUE_PROTOCOLS|AI_ROGUE_TERMINALS|AI_ROGUE_PREFABS|AiRogueMusicId|AiRogueThemeAmbienceId|SFX_FILE_BASENAMES" src/extensions/ai-rogue ``` ### 3. Produce An Asset Gap Report Before Implementation The first substantial response for an asset-dependent expansion should include a table like this: | Needed? | Asset Or Code Contract | Proposed IDs | Why Needed | Existing Fallback | | ------- | ---------------------- | -------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------- | | No | Theme visuals | `model-vault` | Level 5 can use the prepared vault theme. | Reuse `model-vault`. | | Yes | Monster art | `enemy_null_archivist_idle_0`, `idle_1`, `attack`, `hit`, `defeated` | New monster is not in the atlas. | Reuse `index-skink` behavior/art if no new art is provided. | | Yes | Soundtrack | `sector_4` | Requested level has a distinct pacing identity. | Reuse `sector_3`. | | No | SFX | `enemy_corruption_attack`, `enemy_corruption_defeated` | New enemy can share corruption cues. | Reuse existing family. | Asset gaps should be specific enough that the user can provide local files without another discovery round. ### 4. Decide Reuse, Provide, Or Generate Each missing asset should land in exactly one bucket: | Bucket | Meaning | Agent Action | | ------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Reuse existing | The current inventory can support the level without new media. | Document the reuse rationale and implement. | | User provides local files | The user will place source art/audio in the workspace. | Stop after listing required files, frame names, audio IDs, and destination paths. | | Generate assets | The agent is allowed to create new bitmap/audio assets. | Follow the existing source/alpha/crop/provenance/packer workflow before runtime wiring. | | Defer | The level can ship without that identity in this pass. | Mark it as deferred and do not add dead IDs or placeholder runtime references. | Do not add placeholder frame names, audio IDs, save IDs, or level spec entries that point to assets the repo does not actually contain. ## Level Content Requirements There are two useful scopes for "a new level": | Scope | Meaning | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lightweight extra floor | Reuses existing themes, enemies, protocols, prefabs, music, ambience, and SFX. Adds a level spec, balance tuning, tests, and usually one authored floor arc. | | Real content level | Adds enough identity that the player can recognize the level by sight, sound, encounter pressure, objective, reward hook, and pacing. This may require new art, audio, mechanics, saved IDs, and broader validation. | A lightweight extra floor is good for proving the pipeline. A player-facing content level should make reuse deliberate and visible, or bring a complete content pack. Minimum content for a real level: | Element | Required Decision | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Level identity | Name, one-line lesson, pressure label, theme/palette, and run-arc purpose. | | Generation profile | Room modifier, hazard/shard/health pressure, exit guard policy, and pathing acceptance tests. | | Enemy mix | Weighted enemy table plus at least one introduced, recombined, or guaranteed threat. | | Forced decision | Guaranteed encounter, vault detour, terminal, objective lock, prefab pressure, or boss gate that prevents a straight walk to the exit. | | Reward hook | Shrine, protocol, cache, equipment, compile choice, terminal trade, or other run-local build decision. | | Visual identity | Theme wall/decal/atmosphere frames, monster frames, objective markers, or documented reuse rationale. | | Audio identity | Sector music choice and theme ambience; add new loops only when the existing routes do not fit. | | Verification | Deterministic generation tests, asset/audio validation, save-schema parity when IDs persist, at least one simulated clear path, and browser proof if presentation changes. | The first expansion after Phase 39 should stay modest. One new floor arc and one or two enemies are a better proving ground than a broad subsystem. ## Asset Requirements By Content Type ### New Standard Monster Required deliverables: * `AiRogueEnemyKind` ID. * `AI_ROGUE_ENEMY_TEMPLATES` row with label, behavior, HP, attack, defense, range, speed, effect tags, death reward, audio family, and frame set. * Save-schema persisted enemy ID if it can appear in a saved world. * Five gameplay frames for new art: `enemy__idle_0`, `enemy__idle_1`, `enemy__attack`, `enemy__hit`, `enemy__defeated`. * Frame names in `types-assets.ts` and derived/required atlas checks. * Spawn inclusion through a theme enemy table, level enemy table, guarantee, prefab, or boss/guard rule. * Tests for spawn placement, combat/effects, render frame projection, audio family routing, and save-schema parity. Only add a new behavior when `melee-chaser`, `ranged-sentry`, `swarm-rusher`, and `thief` cannot express the enemy. New behavior needs pure simulation tests before art polish. ### New Boss Or Miniboss Required deliverables: * Boss enemy kind and template, or a clear miniboss policy if it reuses standard enemy behavior. * `boss-contracts.ts` spec with role, finale eligibility, reveal/audio metadata, and presentation footprint. * Boss frame set, generally: `idle_0`, `idle_1`, `charge_0`, `telegraph_0`, `attack_0`, `shielded_0` or `enraged_0` if relevant, `hit_0`, and `shutdown_0`. * Dedicated or reused boss audio family cues: charge, fire/attack, hit, shutdown/defeat, optional reveal stinger. * Finale or placement metadata in the level spec. * Tests for reveal, telegraph, damage, defeat, render frames, audio metadata, final-defense isolation, browser bounds, and reduced-motion readability. Do not create a second final boss by hard-coded depth checks. Boss ownership belongs in level finale metadata and boss contracts. ### New Theme Required deliverables: * `AiRogueSectorThemeId` and `AI_ROGUE_SECTOR_THEMES` entry. * Theme visuals in `theme-visuals.ts`. * Save-schema sector theme ID if the theme can persist in saves. * Wall/floor/accent/decal frame names in the gameplay atlas, or a documented decision to reuse existing theme frames. * New ambience loop if the current ambience beds do not fit. * Tests for theme projection, visual frame existence, ambience mapping, save parity, and generated world identity. ### New Soundtrack Or Ambience Required deliverables: * Final `.ogg` file under `src/assets/ai-rogue/audio/music/`. * `AiRogueMusicId` or `AiRogueThemeAmbienceId`. * `MUSIC_FILE_BASENAMES` or `AI_ROGUE_THEME_AMBIENCE_FILE_BASENAMES` entry. * Provenance JSON update beside the committed files. * Level spec or theme route that selects the new ID. * Audio tests proving the ID resolves to a committed file and falls back silently when playback is unavailable. Use 48 kHz Ogg Opus and keep AI Rogue music under the reviewed music-track cap from `docs/media-policy.md`. ### New SFX Required deliverables: * Final `.ogg` file under `src/assets/ai-rogue/audio/sfx/`. * `AiRogueSimulationAudioCueId` value. * `SFX_FILE_BASENAMES` entry, with variants grouped under one cue ID when appropriate. * Dispatch path through simulation `audioCues`/`audioMetadata`, `dispatchEventSound()`, or `cueForAudioMetadata()`. * Provenance JSON update. * Audio tests. Prefer existing enemy-family cues for standard monsters. Dedicated SFX are most valuable for bosses, new protocols, unique objectives, and high-value transitions. ### New Item Drop, Pickup, Protocol, Or Reward Required deliverables: * Runtime type ID and schema ID when persisted. * Pickup or UI frame names, plus effect frames if the action has board presentation. * Simulation behavior and command handling. * HUD, inspect, reward, or terminal copy if route-visible. * Save parse defaults and compatibility behavior. * Tests for pickup placement, use effect, save round trip, render model, audio cue, and browser controls when the command surface changes. Use existing protocols, relic shrine choices, cache chests, key fragments, terminals, compile choices, or transient equipment before adding another item class. ### New Objective Required deliverables: * Objective kind and progress model. * Exit-lock and unlock behavior. * HUD/inspect copy. * Optional lock/progress/unlock frames if visible. * Save-schema state and old-save defaults. * Tests for progress, unlock, failed exit attempts, descent/win behavior, and render/audio feedback. ## Code Architecture Checklist ### Level Spec Add one contiguous `AiRogueLevelSpec` per authored main-run level: ```ts { id: "model-vault", depth: 5, label: "Model Vault", lesson: "Model vault: chase the thief before the vault seals.", generation: { themeId: "model-vault", roomModifier: "cache-dense", baselineProtocolId: "trace-map", musicTrackId: "sector_3", ambienceId: "theme_model_vault_ambience", }, placements: { exitGuardKind: "kernel-sentinel", terminalId: "quarantine-terminal", prefabId: "boss-anteroom", }, enemyTable: ["cache-wraith", "packet-thief", "firewall-sentry", "cache-wraith"], guarantees: { enemyKinds: ["ping-mosquito"], pickupKind: "key-fragment", protocolId: "phase-step", }, objective: { floorObjective: { kind: "purge-dumps", label: "Purge 2 crash dumps to unlock the exit", target: 2, progress: 0, isComplete: false, }, }, finale: { isFinalAuthoredLevel: true, bossKind: "kernel-sentinel", requiresFloorObjectiveClear: true, }, } ``` If this appends depth 5 to the main run, depth 4's finale should usually change to non-final and depth 5 becomes the only final authored level. Registry validation should continue to enforce one final authored finale on the last level. ### Catalog Updates Touch only the catalogs needed by the content: | New Need | Files | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | Level only | `runtime/content/levels.ts`, content tests, depth/content baseline tests | | Theme | `themes.ts`, `theme-visuals.ts`, `save-schema.ts`, theme tests | | Enemy | `types-entities.ts`, `entities.ts`, `save-schema.ts`, combat/render/audio/save tests | | Boss | `entities.ts`, `boss-contracts.ts`, `boss-presentation.ts`, level finale metadata, boss/render/audio/browser tests | | Protocol | `protocols.ts`, `simulation.ts`, `types-runtime.ts`, `save-schema.ts`, frame/audio/tests | | Terminal | `terminals.ts`, `save-schema.ts`, terminal/simulation tests | | Prefab | `prefabs.ts`, world placement tests, fixture symbol support if needed | | Tile or hazard | `world-tiles.ts`, `world-generator.ts`, `theme-visuals.ts`, save tile-kind coverage if kind changes | | Audio | `audio.ts`, committed `.ogg`, provenance, audio tests | | Art | source/alpha files, crop manifest, packer output, `types-assets.ts`, `assets.ts`, asset tests | | Objective | entity/objective types, simulation, floor arc/objective lock, save schema, tests | Do not move unrelated catalogs into `runtime/content/` unless doing so removes real level-authoring friction. The current registry is intentionally small and source-owned. ### Current Friction Adding a level is much narrower than it was before Phase 39, but new content still needs deliberate updates when it introduces new IDs or presentation contracts: * Theme IDs, enemy IDs, protocol IDs, terminal IDs, status IDs, audio cue IDs, and frame names are still TypeScript unions or Zod enums. * `themeForDepth()`, `floorArcForDepth()`, `prefabForDepth()`, `protocolForDepth()`, `terminalForDepth()`, `musicTrackForDepth()`, and `themeAmbienceForTheme()` remain public compatibility helpers. Keep authored depths registry-backed and legacy fallback behavior covered for fixture-only paths. * Kernel Sentinel has a reusable boss/finale contract. A second boss still needs metadata, frame, combat, render, audio, save, and browser coverage. * Asset frame requirements are partly derived from declared content and partly static for shared gameplay/UI frame groups. * Fixture row symbols cover current prefab/test vocabulary only. New enemies, pickups, hazards, or interactables may need fixture vocabulary updates before efficient tests can be written. This friction is intentional: it keeps shipped content reviewed, browser-local, deterministic, and safe to validate. ### Derived Validation Expectations Expansion work should keep pushing content-owned requirements through tests: * Every level's theme references a valid theme, and its ambience matches that theme's `audioHint`. * Every declared theme tile/decal frame exists in the gameplay atlas. * Every standard enemy frame set exists in the gameplay atlas. * Every boss frame set and boss FX frame exists in the gameplay atlas. * Every protocol pickup/effect frame exists. * Every visible status has overlay, HUD pip, and supplemental UI coverage when the status appears in those surfaces. * Every declared music, ambience, SFX, and stinger ID resolves to a committed file and provenance record. * No rejected frame names enter runtime contracts. `runtime/assets.ts` currently combines `listAiRogueContentGameplayFrameNames()` with static gameplay/UI frame groups. A packer-generated asset manifest is optional future hardening; add it only if it removes real manual frame-list drift. ### Future Hardening Notes When content additions reveal repeated switch edits, prefer small spec-driven improvements over broad rewrites: * Standard enemies should continue moving toward metadata-owned `audioFamily` and `frameSet` declarations instead of renderer/audio code knowing every enemy ID. * Bosses should keep reveal trigger, state frames, telegraph/firing FX, shutdown presentation, and adaptive audio metadata in boss specs or finale specs. * Behavior additions should be narrow and pure. Examples that justify new AI are a support enemy that shields a nearby hostile, a dump-eater that consumes crash dumps for tempo, or a retreating ranged enemy. * Do not add an endless/looped mode by weakening main-run lookup. Give it a separate policy and tests. ### Save And Privacy Rules * Keep full level specs out of save slots. Persist IDs and bounded runtime state, then resolve current specs from the registry. * Add active runtime IDs to parser-owned persisted ID arrays when they can be saved: enemy kinds, themes, protocols, terminals, statuses, objective types, or pickup kinds. * Use explicit compatibility arrays only for retired IDs that older saves still need to parse. * Keep `AI_ROGUE_SAVE_SCHEMA_VERSION` at 1 unless the persisted shape itself is not backward-compatible. * Run save-schema parity whenever adding saved IDs. * Keep labels short and browser-safe. No private paths, raw prompts, transcripts, command output, logs, credentials, tokens, or local usernames in level specs, save payloads, fixtures, docs, provenance, or tests. ## Implementation Sequence For a straightforward reused-media expansion: 1. Add new level specs in `runtime/content/levels.ts`. 2. Move finale metadata to the new last authored level. 3. Update registry tests for depth order, IDs, max depth, final-level metadata, and out-of-range rejection. 4. Update content baseline, depth resolver, world, deterministic run, run-loop, objective-lock, final-presentation, and save tests. 5. Run focused validation. 6. Update docs with level identity and reuse rationale. For a real-content expansion with new assets: 1. Produce the asset gap report. 2. Prove the level identity and encounter contracts with existing reusable media when possible. 3. Ingest or generate assets after the mechanic, enemy, boss, objective, or audio pacing is stable. 4. Update crop manifest/provenance and pack visual atlases, or add audio files and provenance. 5. Add the new content IDs and runtime contracts. 6. Add the level specs. 7. Add focused tests by content type. 8. Run asset-size, type, unit, build/budget, and browser proof gates. 9. Update docs with final inventory and validation evidence. Do not generate new bosses, music, ambience, protocol art, status art, or theme art just to make a level count larger. Generate media only when the shipped level identity needs it and the repo is ready to wire it into real contracts. ## Validation Commands For level-only changes, start with: ```bash bunx vitest run src/extensions/ai-rogue/runtime/content/__tests__/levels.test.ts src/extensions/ai-rogue/runtime/__tests__/content-baseline.test.ts src/extensions/ai-rogue/runtime/__tests__/depth-resolver.test.ts bunx vitest run src/extensions/ai-rogue/runtime/__tests__/world.test.ts src/extensions/ai-rogue/runtime/__tests__/golden-determinism.test.ts src/extensions/ai-rogue/runtime/__tests__/roguelike-loop.test.ts src/extensions/ai-rogue/runtime/__tests__/objective-lock.test.ts src/extensions/ai-rogue/runtime/__tests__/biome-final.test.ts bunx vitest run src/extensions/ai-rogue/__tests__/save-schema-parity.test.ts src/extensions/ai-rogue/__tests__/save-schema.test.ts bun run typecheck ``` Add these when assets or audio change: ```bash python3 scripts/extensions/ai-rogue/pack-visual-assets.py bunx vitest run src/extensions/ai-rogue/runtime/__tests__/assets.test.ts src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts bunx vitest run src/extensions/ai-rogue/runtime/__tests__/audio.test.ts src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts bash scripts/check-asset-sizes.sh ``` Add these when route rendering, imports, budgets, or browser behavior change: ```bash bun run build bun run budget:check bun run test:e2e -- tests/e2e/ai-rogue-runtime.spec.ts tests/e2e/ai-rogue-mobile.spec.ts ``` For release-grade work, follow the broader AI Rogue gate list in `docs/development.md`. ## Response Template For Future Agents Use this shape before implementing a content-heavy request: ``` I inspected the current AI Rogue content registry, enemy catalog, visual atlas, audio maps, save-schema IDs, and Phase 39 docs. I can build N levels with existing assets by reusing: - Themes: ... - Monsters: ... - Music/ambience: ... - Protocols/terminals/prefabs: ... Missing assets only if we want the requested identity: - Monster art: ... - SFX: ... - Item-drop art: ... - Soundtrack/ambience: ... - Boss/theme/objective art: ... Implementation plan: - Add levels ... - Update catalogs ... - Update tests ... - Run validation ... ``` If the user provides local files, verify they are present, update the source/alpha/crop/provenance records, run the packer or audio map updates, and only then wire the new IDs into runtime code. ## Non-Goals * No remote content loading. * No dynamic mod/plugin system. * No unreviewed JSON content packs. * No hosted writes, collectors, analytics, or private telemetry dependency for AI Rogue level content. * No raw prompts, transcripts, command bodies, local paths, logs, credentials, tokens, or private bridge payloads in game content. * No broad inventory rewrite. Protocols, transient equipment, terminals, caches, relics, and compile choices are the current item-decision boundaries. * No new save schema version unless persisted data shape changes require a real migration. ## Quick Bottom Line The fastest safe expansion today is one or more reused-media levels using existing themes, enemies, protocols, terminals, prefabs, music, ambience, and SFX. The first likely low-friction new level is a `model-vault` floor because that theme already has visual and ambience coverage but is not part of the four-level main run. A player-facing real-content expansion needs an explicit content pack: level spec, theme or documented theme reuse, enemy mix, forced decision, reward hook, visual frames, audio routing, safe copy, save-schema coverage, deterministic simulation tests, asset/audio validation, and browser proof. --- # 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/new-level-authoring-guide.md?ask=&goal= ``` `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.