> 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/readme_ai-rogue.md). # AI Rogue Extension Docs AI Rogue is the implemented `ai-rogue` extension: a PixiJS roguelike that turns browser-safe AI OS activity into capped local progression. Phase 30 shipped the supporting extension (route, renderer, persistence, and economy). The first delivered Play route was a fixed smoke-test corridor; the run loop was rebuilt on 2026-06-22 to be an actual playable roguelike. The objective baseline and remediation facts live in [Run Loop Rebuild Notes](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/run-loop-rebuild-notes.md). Session 10 approved local browser enablement through `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`. Phase 34 closeout on 2026-06-26 fixed the audited default-enable blockers, and the current browser registry now production-enables AI Rogue by default. Use `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` only when a build must explicitly hide all extension entries. Phase 35 final release gate on 2026-06-27 kept that posture at Production Go after the app, AI Rogue, Pages, privacy, budget, asset, playthrough, and release-evidence gates passed. Phase 39 then moved level authoring into the typed content registry under `runtime/content/`, expanded the main run to four authored levels, and proved a prepared real-content enemy path with `insight-beetle` on depth 4. ## Tech Stack * Host shell: React 19 views inside the AI OS TanStack Router/Start and Vite 8 application. * Extension model: compile-time `ai-rogue` extension registration with lazy route/view loading and `host-live-data` runtime data mode. * Game renderer: PixiJS v8.19.0, owned imperatively by the Play route runtime and mounted only after the browser view loads. * Graphics path: PixiJS canvas/WebGL runtime with route-scoped ticker, texture, resize, input, and disposal lifecycle. WebGPU remains a future progressive enhancement, not the baseline. * Game logic: pure TypeScript deterministic roguelike simulation with seeded RNG, registry-backed authored levels, generated maps, FOV/fog, hazards, pickups, enemies, combat, terminal states, and run completion rules. * React boundary: React owns routes, menus, forms, coarse state, accessibility text, settings, ledger/loadout views, and runtime event summaries. Per-frame simulation and renderer state stay outside React state. * Persistence: browser-local `localStorage` for small preferences and IndexedDB for wallet, ledger, run history, and save slots. * Validation: Zod-backed versioned save, wallet, ledger, preferences, and economy schemas with private-looking text rejection. * Economy: Insight Shards derived from browser-safe AI OS activity, claimed manually and recorded with provenance labels. * Audio: Web Audio API playback/mixing layer over committed compressed `.ogg` music and sound-effect assets, with fades, loops, one-shots, lazy decode, mute/volume preferences, and silent fallback. * Assets: reviewed compact pixel-art atlases and generated Ogg audio committed as local assets; no remote game-content loading. * Privacy boundary: no collector, raw prompts, transcripts, command bodies, private paths, credentials, logs, or private telemetry export. * Verification: focused Vitest for simulation/economy/save behavior, Playwright canvas/runtime checks, bundle-budget checks, asset-size checks, and private-runtime artifact checks. ## Current Behavior * Primary route: `/extensions/ai-rogue/play`. * Supporting views: Ledger, Loadout, and Settings. * Runtime: lazy PixiJS v8 WebGL mounted only from the Play route. * Run loop: a four-level authored main run on seed-driven generated maps. `runtime/content/levels.ts` owns the shipped level specs: Boot Sector, Index Maze, Kernel Arena, and Firewall Gauntlet. The registry owns max depth, per-level theme, music, ambience, terminal, prefab, protocol, enemy guarantees, objective, and finale metadata. Out-of-range authored main-run depth lookup is rejected instead of silently rotating into unplanned content. Every floor's exit is guarded, so it can never be walked straight through; reaching the exit descends to the next authored level until the final sector resolves. * Verbs: move, **Strike** (attack the faced tile in place), **Surge** (a shard-fuelled pulse that hits all adjacent enemies), and **Protocol** (use a carried single-use tactical tool, including the directional **Trace Lance** raycast and the **Phase Step** leap). * Enemies: melee chasers, ranged firewall sentries, relentless swarm-rusher cache-wraiths, goal-based Packet Thieves, Kernel Sentinel exit guards, and a trait-recombined ecology (Signal Gnat, Ping Mosquito, Index Skink, Corrupt Newt, Venom Daemon, Burst Toad, Insight Beetle) that differ by speed meter, contact/attack effect tags, and method-based death rewards. Depth 4 guarantees `insight-beetle` as the first prepared real-content enemy path without adding new media. * Rewards: each floor drops a three-relic shrine; collecting one (Overclock, Hardened Chassis, or Surge Capacitor) applies its effect and consumes the rest, so it is an exclusive in-run build choice. * Gameplay depth: status effects, inspect/targeting, carried protocols, locked vaults, cache chests, transient equipment, prefab encounter rooms, sector themes, terminal contracts, crash dumps, compile choices, enemy effect tags, initiative/speed meters, an expanded status set, a trait-recombined enemy ecology, a shield buffer, authored floor arcs, directional traversal verbs, objective-locked exits, biome pressure, and a final compile-payload defense beat are documented in [Gameplay Depth](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/gameplay-depth.md). * Simulation: deterministic TypeScript dungeon rules with seeded RNG, FOV/fog, hazards, pickups, enemies, combat, and terminal states. * Persistence: browser-local preferences, wallet, ledger, run history, save slots, and AI Rogue-only reset behavior. Saves keep schema version 1 and persist bounded runtime state such as depth, max depth, world/entity state, IDs, metadata, and small safe labels; whole level specs stay in the registry, not in save payloads. * Input modes: Settings stores raw Auto, Keyboard, or Compact preferences. Auto is the default and resolves at the mounted browser boundary: coarse pointer plus no hover becomes Compact, while desktop/fine-pointer and unavailable capability paths become Keyboard. Explicit Keyboard and Compact selections override Auto. Runtime Canvas passes only concrete `keyboard | compact` values into the PixiJS runtime, and product copy reports resolved Auto states as `Auto (compact)` or `Auto (keyboard)`. * Economy: capped Insight Shards from browser-safe AI OS activity, claimed manually with provenance labels. * Audio: **approved 2026-06-23** and now in scope (previously a non-goal). Real generated audio -- music from Suno, ElevenLabs SFX, and local adaptive stinger renders -- is committed as local compressed Ogg assets and played through Web Audio mixing, music fades, loops, one-shot SFX, low-HP heartbeat, mute/volume preferences, lazy decode, browser-autoplay unlock, dedicated adaptive stingers, and bounded music/theme ducking for combat start, low HP, boss reveal, objective unlock, final defense, victory, and defeat transitions. Runtime behavior lives in [Game Feel And Audio Baseline](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/game-feel.md); audio provenance lives beside the committed files under `src/assets/ai-rogue/audio/`. * Current non-goals: no collector, remote content loading, hosted writes, analytics, raw private telemetry export, raw prompts, transcripts, command bodies, local paths, logs, credentials, WebGPU-only path, worker simulation, broad inventory rewrite, map-editor dependency, gamepad, or pointer-lock behavior. ## Document Map | Document | Use It For | | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [Enablement Decision](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/enablement-decision.md) | Production default-enable decision, historical Session 10 quality-gate evidence, non-goal checks, and follow-ups. | | [Runtime Data And Enablement](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/runtime-data-and-enablement.md) | AI Rogue host-LiveData mode, collector absence, production default enablement, status derivation, and route verification anchors. | | [Run Loop Rebuild Notes](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/run-loop-rebuild-notes.md) | Objective fixed-corridor baseline, rebuilt run-loop acceptance bar, remediation status, and remaining concrete follow-ups. | | [Playtest Notes](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/playtest-notes.md) | Browser playthrough evidence, rebuilt-loop verification, and still-owed human fun verdict. | | [Game Feel And Audio Baseline](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/game-feel.md) | Current HUD text, effects, motion, run arc, audio runtime, asset contracts, and maintenance checks. | | [Gameplay Depth](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/gameplay-depth.md) | Durable run-local depth systems, authored-level rules, future extension principles, and verification expectations. | | [New Level Authoring Guide](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/new-level-authoring-guide.md) | Operational runbook for "build X more levels" requests, inventory-first asset gap reports, code touchpoints, and validation. | | [Phase 39 Level Authoring Infrastructure PRD](/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_39/prd_phase_39.md) | Archived phased implementation plan for turning level expansion into a typed content authoring workflow. | | [Implementation Baseline](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/implementation-baseline.md) | Session 01 ratified product, economy, renderer, asset, privacy, and handoff decisions for implementation sessions. | | [Content Polish And Mobile Notes](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/content-polish-mobile-notes.md) | Historical Session 09 mobile framing, pointer controls, seed sharing, validation notes, and superseded no-audio decision. | | [Extension Plan](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/plan-2026-06-21.md) | Historical product, architecture, economy, runtime, persistence, first slice, phase plan, tests, and non-goals. | | [Visual Assets](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/visual-assets.md) | Runtime pixel-art prompts, palette, tile size, atlas shape, provenance, inventory, and acceptance gates. | | [Imagegen Recovery](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/imagegen-session-recovery.md) | How to recover built-in `image_gen` PNGs from Codex session JSONL when no file appears under `.codex/generated_images/`. | ## Maintenance Notes * Keep the Session 01 implementation baseline as the locked product and technical boundary record; update it only when validated implementation changes a locked decision. * Keep generated prompts, provenance, and asset acceptance notes beside the visual-assets record before committing new game assets. * Keep current game-feel, reduced-motion, and audio runtime contracts in [Game Feel And Audio Baseline](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/game-feel.md). * Keep level-authoring changes routed through `runtime/content/levels.ts`, focused content validation, save-schema parity checks, asset/audio manifest checks, and browser proof when presentation changes. * Keep `AI_ROGUE_SAVE_SCHEMA_VERSION` at 1 unless an actual persisted-shape migration is implemented and tested. * Treat historical optional-audio, no-audio, and opt-in enablement language in old session records as superseded unless the current docs above repeat it. * Keep the production enablement decision current, and rerun the closeout gate bundle before any later capability or visibility expansion. * Keep runtime-data and collector expectations in [Runtime Data And Enablement](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/runtime-data-and-enablement.md) synchronized with extension-platform guidance. * Keep Auto input-mode behavior synchronized with `src/extensions/ai-rogue/input-mode.ts`, Runtime Canvas tests, mobile/runtime Playwright tests, and public-demo mobile smoke before changing control copy or defaults. * Keep repo-wide extension platform guidance in [Extension System](/ai-os-and-trend-finder-docs/docs/extensions/readme_docs-extensions.md). --- # 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/readme_ai-rogue.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.