> 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/gameplay-depth.md).

# AI Rogue Gameplay Depth

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

This document preserves durable gameplay-depth decisions for AI Rogue. It replaces the temporary Rotten Soup research note that was used to identify useful roguelike patterns, then re-express them inside AI Rogue's deterministic, typed, browser-local runtime.

The enduring lesson is not to port Rotten Soup systems directly. AI Rogue should use small, explicit, data-driven systems that combine with movement, Strike, Surge, shards, hazards, relics, and local save state without adding hidden complexity or private-data dependencies.

## Current Depth Contract

AI Rogue now layers the following run-local decisions on top of the registry-backed four-level authored main run. The shipped levels are Boot Sector, Index Maze, Kernel Arena, and Firewall Gauntlet; the registry owns max depth, per-level theme/music/ambience, guarantees, objective, terminal, prefab, protocol, enemy table, and finale metadata.

* **Status effects**: player and enemies can carry typed effects such as `jammed`, `burning`, `shielded`, `overclocked`, and `leaking`. Status math is pure simulation code, ticks deterministically, and persists through safe save defaults.
* **Inspect and targeting**: examine mode can describe terrain, pickups, hazards, vaults, enemies, status effects, equipment, and pending threats without spending a turn. This keeps added mechanics readable before they become tactical load.
* **Carried protocols**: the player can carry up to two single-use protocols. `Patch Kit`, `Trace Map`, and `Signal Jammer` are scarce tactical pivots, not a broad inventory system.
* **Goal-based enemy pressure**: `Packet Thief` seeks shards or cache rewards, steals them, flees while carrying loot, and drops recovered shards when defeated. This adds world-reactive enemy behavior without a mutable AI scheduler.
* **Locked vaults and cache chests**: optional vault branches create a resource decision. A key fragment opens a vault for free; otherwise the player can spend shards to force it. Cache chests feed run-local rewards.
* **Transient equipment**: in-run equipment uses three bounded slots: `kernel`, `guard`, and `payload`. Equipment modifies visible combat math and stays transient, while the Loadout view remains the persistent progression surface.
* **Prefab encounter rooms**: a tiny content-only prefab catalog can stamp memorable tactical rooms onto generated floors after generation. Prefabs must fit existing floor space and must not disconnect the map.
* **Sector themes**: floor generation resolves a deterministic theme such as `cold-cache`, `corrupted-index`, `kernel-core`, `firewall`, or `model-vault`. Themes drive enemy families, density deltas, and presentation hints while preserving the seeded run contract.
* **Terminal contracts**: terminals provide the non-NPC story and choice layer. A terminal opens a small set of resource-gated choices with explicit side effects, then records the consumed terminal state for the floor.
* **Crash dumps**: defeated enemies can leave temporary crash-dump tiles. Purging a dump rewards the player and creates post-kill positioning decisions.
* **Compile choices**: real operator combat kills unlock run-local compile milestones. Each milestone offers deterministic build choices without turning AI Rogue into permanent XP grind.
* **Enemy effect tags**: enemy templates carry typed `attackEffects` (applied to the operator on a melee hit) and `contactEffects` (retaliation applied to whoever strikes them), resolved through the shared status path. `shard-drain`, `jam-on-hit`, `leak-on-hit`, `corrupt-on-hit`, and `burn/corrupt-on-contact` produce a lot of variety from small data (`enemy-effects.ts`).
* **Method-based death rewards**: enemy templates can grant a reward keyed by how the operator landed the kill (`strike`, `surge`, `trace-lance`, or `any`): repair, shards, or clear-pending-threats. Insight Beetle repairs on a Strike kill; a felled Firewall Sentry clears its pending firewall lines.
* **Initiative / speed meters**: each enemy carries a `speed` (centi-tempo) and a carried `initiativeMeter`. On every operator action an enemy banks its speed and spends whole points to act, so fast enemies act twice some turns and slow ones skip turns. Jam freezes the meter; `lagged` halves its gain (`initiative.ts`).
* **Expanded status effects**: in addition to the original five, the run supports `lagged` (halves enemy initiative), `traced` (sentries see the operator through one blocker), `corrupted` (halves collected pickup value), `forked` (the next Strike cleaves a second adjacent enemy), and `rooted` (cannot move, can still attack). All purge through a single negative-status cleanse.
* **Enemy ecology**: seven trait-recombined enemies: Signal Gnat, Ping Mosquito, Index Skink, Corrupt Newt, Venom Daemon, Burst Toad, and Insight Beetle, built purely from `speed`, effect tags, `deathReward`, and `selfStatusOnBurst` (Burst Toad overheats and self-jams after a double-action burst). Firewall Gauntlet guarantees Insight Beetle as the first prepared real-content enemy path without adding new media.
* **Shield buffer**: a transient overshield (`shieldBuffer`) absorbs enemy melee damage before integrity; heavy attackers (`piercesShield`, e.g. the Kernel Sentinel) punch through it. Granted by cache chests and crash-dump purges.
* **Authored level specs**: `runtime/content/levels.ts` owns one tactical idea per authored depth: an introduced enemy family, a guaranteed pickup/protocol, an optional exit-locking objective, per-level media choices, and a one-line lesson. `floor-arc.ts` projects those level specs into generated floors so handcrafted fixtures stay exact.
* **Traversal verbs**: two bounded single-use protocols: `Trace Lance` (a directional raycast that strikes, roots, and traces the first enemy in the faced line, with bonus damage to jammed targets) and `Phase Step` (a two-tile leap in the faced direction). Both reuse the existing facing/line geometry.
* **Objective-locked exits**: some floors carry a `floorObjective` (e.g. purge N crash dumps) that locks the exit until resolved; the exit inspect line and HUD show the lock state and progress.
* **Biome pressure**: each sector theme applies an `enemySpeedDelta` to spawned enemies (coolant slows, kernel core overclocks) plus a player-facing pressure label, so the environment itself exerts pressure, not just the enemies.
* **Final defense beat**: reaching the authored finale exit on Firewall Gauntlet begins a one-turn "compile payload": the win is awarded only after the operator survives the immediate enemy volley on the exit tile, so the ending is defended, not walked.

## Design Rules

Depth should come from combinations of readable systems, not from broad hidden rules. New mechanics should follow these rules:

* Keep simulation logic in pure TypeScript reducers and helpers.
* Keep random choices seed-derived and saveable.
* Prefer typed specs: enemy templates, effect specs, protocol specs, equipment specs, room specs, terminal specs, and reward tables.
* Extend save schema additively with safe defaults for older saves.
* Keep `AI_ROGUE_SAVE_SCHEMA_VERSION` at 1 unless a real persisted-shape migration is added with parser and parity coverage.
* Keep whole level specs out of saves. Runtime saves persist bounded run state, IDs, depth/max depth, metadata, and safe labels, then resolve authored behavior from the registry.
* Keep UI copy short and inspectable. If a mechanic cannot be explained in one compact label or inspect line, simplify it.
* Add one major decision layer per implementation session.
* Keep inventory intentionally tiny. Protocols and transient equipment are the current inventory boundary.
* Preserve privacy boundaries. Gameplay depth can use safe labels, counts, caps, and generated runtime state only; it must not read prompts, logs, file paths, command bodies, raw telemetry, or private bridge payloads.
* Do not add runtime pub/sub, mutable global game state, a ROT scheduler, Tiled map loading, or Vue-style component coupling. AI Rogue's browser runtime should remain route-scoped and testable.

## Notes On Two Findings Handled By Design

Two `frogue` findings are satisfied by AI Rogue's existing shape rather than a new mechanic:

* **Pure event cascade**: AI Rogue already resolves each command as a single pure reducer pass: player action, derived effects, status ticks, death rewards, objective updates, then enemy intent, with a bounded, deterministic event log instead of `frogue`'s mutable inbox. `cascade.test.ts` pins both the determinism and the bounded log, so the cascade spirit is kept without runtime pub/sub.
* **Door spatial continuity**: `frogue` preserves the side a player entered from across rooms. AI Rogue floors regenerate on descent and vault branches are single-tile alcoves, so paired-door continuity does not map onto the current model. Entry-side tracking is left for a future side-sector branch (see the branch-IDs note below) rather than ported now.

## Future Extension Principles

The current depth systems leave room for future work, but additions should stay within the existing shape:

* Optional branches can expand from single vault alcoves into small side sectors only if branch IDs, seeds, entity states, and explored keys remain stable save fields.
* Ranged or spell-like verbs should use visible targeting and a resource gate. Firewall Sentry line telegraphs already teach line geometry; player ranged tools should reuse that readability.
* More enemy AI should preview intent. Good candidates are retreating daemons, shielding/healing support enemies, or dump-consuming enemies, but each should add one clear behavior.
* Crash dumps can later support miniboss or boss interactions, but player purge value should remain obvious.
* Terminal contracts can carry more story flavor, but they should stay small choice graphs with bounded effects rather than traditional NPC dialogue.
* End screens can grow run stats such as sectors cleared, vaults opened, dumps purged, telegraphs dodged, shards spent, and relic synergies triggered.

## Verification Expectations

Each new depth system needs focused simulation tests before presentation polish. At minimum, cover:

* deterministic generation or selection,
* save/load parse defaults,
* resource-gated success and failure paths,
* inspect/render-model visibility for player-facing state,
* privacy checks for labels and persisted summaries,
* one browser or runtime-canvas test when the mechanic adds controls or visible choices.

Run the full AI Rogue slice plus normal project quality gates when shared save, runtime, or route behavior changes.


---

# 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/gameplay-depth.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.