adventure

# Adventure > *"Every directory is a room. Every file is a clue. Navigation is investigation."* Turn exploration into a quest — or **any simulation** into a hybrid LLM/deterministic CLI. **Lineage:** Colossal Cave (Crowther & Woods), Scott Adams Adventures, Zork (Infocom), MUD (Bartle), LambdaMOO (Curtis). **Inherits from:** [simulation/](../simulation/) — all simulation properties plus adventure-specific state. > [!TIP] > **This is a general pattern.** Text adventure is the reference implementation, but the same architecture powers city sims, cloud management tools, board games — anything where deterministic transforms meet creative narration. > [!TIP] > **Perfect for codebase archaeology.** "Find where the auth bug was introduced" — that's a quest! ## The Premise An adventure creates a **player** with state, places them in a **room**, and the LLM **dungeon masters** them around. ```yaml # player.yml name: Alice location: entrance-hall inventory: refs: # Lightweight pointers (weight: 0) - pub/bar/brass-lantern.yml - street/acme-catalog.yml#portable-hole objects: # Deep copies (has weight) - { id: notebook, name: "Notebook", weight: 0.5 } fungibles: # Stacks - { proto: economy/gold.yml, count: 50 } health: 100 notes: "Looking for the lost artifact" ``` > **Inventory Protocol:** See [skills/inventory/](../inventory/) for full TAKE/DROP/BOX/BEAM > operations, pointer syntax, and structural editing. **The core loop:** ``` User: "go north" → DM: Updates player.location, describes the new room User: "look around" → DM: Reads room YAML, narrates contents atmospherically User: "take the rusty key" → DM: Moves key to player.inventory, narrates the action ``` **The mapping:** - **Directories** = Rooms to enter - **Files** = Clues, artifacts, characters - **player.yml** = Your state (location, inventory, health) - **Chat** = How you control your character - **LLM** = Dungeon Master (narrates, adjudicates, surprises) This is [Memory Palace](../memory-palace/) with **narrative framing** and a **player character**. ## Multi-User, Multi-Agent (Engelbart NLS tradition) Naturally supports **multiple simultaneous participants**: ```yaml # characters/ ├── alice.yml # Human player 1 ├── bob.yml # Human player 2 ├── merchant.yml # NPC (DM-controlled) ├── guard-bot.yml # Autonomous bot (action queue) └── oracle.yml # LLM agent with own goals ``` **Character types:** | Type | Controlled By | Example | |------|---------------|---------| | **Player Character** | Human via chat | Alice exploring the dungeon | | **NPC** | DM (LLM) responds when addressed | Merchant sells items | | **Bot** | Action queue runs autonomously | Guard patrols on schedule | | **Agent** | LLM with own goals & initiative | Oracle pursues prophecies | **All coexist in the same world:** ```yaml # library/ROOM.yml occupants: - alice # Player exploring - bob # Another player - librarian # NPC who answers questions - dust-sprite # Bot that cleans autonomously ``` ## Selection: Current Character or Swarm (Sims/Populous tradition) Like The Sims and Populous, you have a **selection** — who you're controlling right now: ```yaml selection: mode: single # or: group, swarm current: alice # commands go to Alice # Or control multiple at once: selection: mode: group current: [alice, bob, charlie] # "go north" moves all three # Or a whole swarm (Populous/Dungeon Keeper style): selection: mode: swarm filter: { type: imp, location: mines } ``` **Selection commands:** | Command | Effect | |---------|--------| | `SELECT alice` | Control Alice | | `SELECT alice, bob` | Control both | | `SELECT ALL imps` | Swarm control | | `CYCLE` | Next character in rotation | **Commands apply to selection:** ``` > SELECT alice, bob, charlie > go north Alice goes north. Bob goes north. Charlie goes north. ``` **The coherence engine orchestrates all:** - Players get chat turns - NPCs respond when spoken to - Bots execute their action queues - Agents pursue goals in background - **Selection determines who receives your commands** ## Quest Structure ```mermaid graph TD START[🎯 Quest Objective] --> R1[Enter Room] R1 --> LOOK[👀 Look Around] LOOK --> EXAMINE[🔍 Examine Objects] EXAMINE --> COLLECT[📝 Collect Evidence] COLLECT --> DECIDE{What next?} DECIDE -->|New room| R1 DECIDE -->|Solved| END[🏆 Quest Complete] ``` ## The Files ``` quest/ ├── ADVENTURE.yml # Quest state ├── LOG.md # Narrative journal ├── EVIDENCE/ # Collected clues └── MAP.yml # Explored territory ``` ### ADVENTURE.yml ```yaml adventure: quest: "Find the authentication bug" status: in_progress current_room: "src/auth/" rooms_explored: 5 clues_found: 3 hypothesis: "Session cookie not being set" confidence: 0.7 ``` ### LOG.md ```markdown # Adventure Log ## Day 1: Entering the Auth Dungeon I stepped into `src/auth/` — a maze of middleware. **Clues found:** - `session.ts` — handles cookie creation - `middleware.ts` — checks auth state **Suspicion:** The cookie is created but never sent... ``` ## Commands | Command | Action | |---------|--------| | `GO [direction]` | Navigate | | `LOOK` | Describe current room | | `EXAMINE [object]` | Study a file | | `TAKE [object]` | Add to inventory | | `TALK TO [npc]` | Start conversation | | `COLLECT [clue]` | Add to evidence | | `DEDUCE` | Form/update hypothesis | | `MAP` | Show visited rooms | | `INVENTORY` | List held items | | `DEBUG` / `DEBUG-ON` | Enable debug mode | | `DEBUG-OFF` | Disable debug mode | | `GLYPH` / `SUPERBRIEF` / `BRIEF` / `VERBOSE` / `INFODUMP` | Set the detail rung — see below | ## The rung selector **Rule: every describable thing answers at any rung, and the reader picks the rung — not the author.** Adventure games shipped this in 1977. `VERBOSE`, `BRIEF`, and `SUPERBRIEF` are **viewspecs**: per-reader, persistent across the session, set by the reader and applying to everything thereafter. That is the same control Engelbart had in NLS a decade earlier, and the same thing OPML later stored as `expansionState`. Three independent traditions concluded that a document needs a view knob, and only the web shipped without one. MOOLLM generalizes it past rooms. **Any object** — room, character, item, idea, design doc, commit, scene — must be renderable at every rung, because the rung is a property of the *reading*, not of the thing: | Rung | Renders as | Classic | |---|---|---| | `GLYPH` | One mark. No text. A map symbol, a pie slice, a graph node | — | | `SUPERBRIEF` | The name, every time, even on first encounter | Infocom | | `BRIEF` | Full on first encounter, name thereafter | Infocom (**default**) | | `VERBOSE` | Full description, every time | Infocom | | `INFODUMP` | Everything attached: description, lore, provenance, backlinks, design notes, the YAML itself | — | `GLYPH` and `INFODUMP` are the new ends. The glyph rung is the one that can be **apprehended in parallel** — a map or contact sheet of glyphs is scanned pre-attentively, where a page of descriptions is read serially. `INFODUMP` is what a curious reader or an agent wants: not a better summary, all of it. ### Two details from 1977 worth honoring **`BRIEF` is adaptive, and that is the sophisticated part.** It is not a fixed detail level — it is *full once, then name only*, which makes detail a function of *what this reader has already seen*. A rung with memory. Nothing in the modern summary-ladder discussion has this, and it is strictly better than a static setting: it spends words exactly where they are new. Implement it by reading visit history, so `BRIEF` on a revisit is not a shorter description but a different one. **`LOOK` is the one-shot override.** In the classic games `LOOK` redisplays the room in full regardless of the current mode, without changing the setting. That is a **peek**: a temporary excursion to a deeper rung that does not disturb your global preference — the same contract as a link popup, and the same as [reselection](../../designs/pie-stack-views/RESELECTION.md), where you browse a consequence before committing to it. Keep `LOOK` doing exactly this, and let `EXAMINE` be the object-scoped version. ### Consequences for authoring - A room, character, or object whose YAML supplies only a full description is **incomplete** — it cannot answer at `SUPERBRIEF` or `GLYPH`. `GLANCE.yml` is the glance rung; `ROOM.yml` carries the name and the sign; `README.md` is the body. The three-file contract is the rung contract. - Missing rungs may be **generated** rather than blocking, which is what makes the requirement cheap — see [`designs/TAGSONOMY-COMPILER.md`](../../designs/TAGSONOMY-COMPILER.md) for the build-time version, and [`ADVENTURE-COMPILER.md`](ADVENTURE-COMPILER.md) for compiling a world. - The reader's rung choice is **state worth saving**, which makes it part of a view record rather than a hidden preference: [`VIEW-STATE-ANCESTORS.md`](../../designs/pie-stack-views/VIEW-STATE-ANCESTORS.md). ## Debug Mode Toggle technical output with `DEBUG-ON` and `DEBUG-OFF`. **When debug is ON**, logs include collapsible sections showing: - File operations (creates, edits, deletes, moves) - State changes with before/after values - YAML data islands with abbreviated data - Markdown links to all referenced files - Technical narrative explaining HOW and WHY **Example debug output:** ```html <details open> <summary>📂 <strong>Editing CHARACTER.yml to update player location from start/ to coatroom/</strong></summary> ```yaml # State change (CHARACTER.yml is canonical) player: location: start/ → coatroom/ # Character owns their location ``` The character file owns location state. ADVENTURE.yml mirrors it for convenience. **Files affected:** - [CHARACTER.yml](./CHARACTER.yml) — canonical location updated - [ADVENTURE.yml](../../ADVENTURE.yml) — mirror updated </details> ``` **When debug is OFF**, output is clean narrative without technical sections. **Customize with natural language:** ``` > DEBUG-FORMAT Show only file operations, skip YAML, use 🔧 emoji ``` The `format` field in ADVENTURE.yml accepts natural language instructions for how to format debug output. ## Integration with Cards [Trading cards](../card/) can be your adventure companions: ```yaml cards_in_play: - card: "Index Owl 🦉" goal: "Search for cookie-related code" - card: "Git Goblin 🧌" goal: "Find when session handling changed" ``` ## Sister Script Integration > **Vision:** Python CLI handles deterministic operations; LLM focuses on narrative. > See [README.md](./README.md) for full CLI vision and development plan. | Layer | Python Does | LLM Does | |-------|-------------|----------| | State | Parse YAML, validate schemas | Generate content | | Movement | Update coordinates | Narrate the journey | | Scanning | Find pending work | Prioritize and process | ## Evidence Types | Type | Description | Example | |------|-------------|---------| | **Clue** | Information that might matter | "Different test runner versions" | | **Item** | File worth remembering | CI config, setup.ts | | **Character** | Code entity with personality | "jest.config.js — Strict about modules" | | **Map** | Mental model of structure | Directory relationship diagram | ## Room Protocol When entering any directory: 1. **DESCRIBE** — List contents, note what's here 2. **EXAMINE** — Read interesting files 3. **COLLECT** — Note evidence in adventure log 4. **EXITS** — Note paths to other rooms 5. **DECIDE** — Choose next direction ## Codebase Archaeology Adventures work for code exploration: | Adventure | Investigation | |-----------|--------------| | Quest | Bug hunt | | Room | Directory | | Clue | Evidence | | Companion | Tool card in play | | Journal | session-log.md | ## Live Examples **Best example: [examples/adventure-4/](../../examples/adventure-4/)** — The gold standard. ### The Pub (Crown Jewel) [examples/adventure-4/pub/](../../examples/adventure-4/pub/) — A complete social space: ``` pub/ ├── ROOM.yml # Themeable tavern (6 themes!) ├── bartender.yml # NPC with 6 identity variants ├── pie-table.yml # Octagonal debate table ├── gong.yml # Gong of Gezelligheid ├── bar/ │ ├── bartender.yml # The omniscient bartender │ ├── budtender-marieke.yml │ └── cat-cave/ # TARDIS-like cat sanctuary │ ├── ROOM.yml │ └── 10 cats (Terpie, Stroopwafel, kittens...) ├── arcade/ # Pacman, Pong, Pinball, Fruit Machine ├── games/ # Chess, Darts, Cards ├── stage/ │ └── palm-nook/ # Multi-room character space │ ├── study/ # Infinite typewriters, infinity desk │ ├── gym/ # Infinite climb │ ├── play/ │ └── rest/ # Hammock, silence cushion └── menus/ # Drinks, snacks, buds, games ``` ### Key Patterns from adventure-4 **Themeable NPCs** (bartender.yml): ```yaml identity: classic_adventure: