⚔️ Adventure

"Every directory is a room. Every file is a clue. Navigation is investigation."

MOOLLM K-Lines

K-Line	Why Related
room/	Adventure IS room + narrative framing
character/	Player and NPC management
incarnation/	NPCs can be popped out into characters
simulation/	Adventure extends simulation
card/	Companions on the quest
memory-palace/	Spatial knowledge organization
world-generation/	Questions create places
debugging/	Investigation as adventure
sniffable-python/	Linter feedback loop drives generation
examples/adventure-4/	Live world with 36 rooms

Full Protocol: SKILL.md | Interface: CARD.yml

Core Protocols:

SUMMON-PROTOCOL.md — Distributed character instantiation
PSIBER-PROTOCOL.md — Step inside any data structure

Overview

Transform exploration into narrative investigation. Directories become rooms, files become clues, and the LLM dungeon-masters you through the quest.

Lineage: Colossal Cave, Zork, LambdaMOO, The Sims.

Primary source (readable world model): Knuth's CWEB recasting of Crowther/Woods Adventure 1.0 — study room + MOOLLM/Repo Show analysis in WillWrightShowForFood: characters/donald-knuth/sources/adventure-knuth/ (CREAM · ANALYSIS). Upstream: Knuth Programs — ADVENT. SHRDLU/WUMPUS trail: advent-shrdlu-wumpus-lineage.md.

Quick Commands

Command	Effect
`QUEST objective`	Start adventure
`ENTER room`	Go to directory
`LOOK`	Describe room
`EXAMINE object`	Study file
`COLLECT clue`	Add evidence
`SELECT character`	Control who
`CYCLE`	Next character
`SUMMON character`	Instantiate character at current location
`ENTER moollm://path`	Enter PSIBER mode (explore data as room)
`CHANGE key TO value`	Edit data in PSIBER mode
`WHAT IS key`	Ask about a key's purpose

When to Use

Codebase archaeology — "Find where the auth bug was introduced"
Onboarding — "Understand this project's structure"
Bug hunting — "Follow the evidence trail"
Documentation diving — "What does this system actually do?"

Room Narrative Levels

Rooms are described in progressive detail:

glance — one‑line entry for lists and maps
look — first impression on entry (glance + more)
examine — architectural detail plus an extra beat, like a song drifting in from outside

Rooms read from ROOM.yml plus local README.md. Objects and characters describe themselves; rooms avoid re‑describing artifacts with their own YAML/MD files.

Roadmap

Planned expansions:

Description alternatives — allow arrays of strings for glance/look/examine, with engine rotation that avoids recent repeats.
Dialog tree schema — descriptions, expressions, and utterances become interactive trees with state and consequences: creating or destroying objects, currency exchange, summoning or incarnating characters, generating rooms and maps, triggering buffs, and reshaping world state.

Templates

File	Purpose
ADVENTURE.yml.tmpl	Quest state & evidence
LOG.md.tmpl	Narrative journal

Tools Required

file_read — Read rooms and clues
file_write — Update adventure state
list_directory — Survey rooms

Browser Runtime with Speech

The dist/ directory contains a publishable browser runtime with text-to-speech:

dist/
├── speech.js          # Voice synthesis library
├── adventure-speech.js # Speech integration
├── index.html         # Demo page
└── README.md          # API documentation

Features:

🔊 Speaks room descriptions, responses, and dialogue
🎭 Character-specific persistent voices
🤖 Robot voices for AI/machine characters
✨ Effect voices for magical events
🌍 Multi-language support (67+ voices on macOS)

const engine = createSpeakingAdventure('adventure', {
    speechEnabled: true,
    speakRooms: true
});

engine.load(adventureJSON);
engine.speak("Welcome to NO AI TOWER!", { voiceType: 'robot' });

See dist/README.md for full API.

Deep Background

The following sections are for humans who want to understand the vision, history, and future plans. LLMs running the simulation don't need this context unless specifically consulting the README.

adventure.py — The CLI Uplift Plan

Vision: A Python CLI that validates, lints, and compiles adventures into standalone browser experiences.

$ adventure.py lint quest/           # Validate schemas, suggest fixes
$ adventure.py compile quest/ -o dist/  # Generate standalone HTML/JS
$ adventure.py serve quest/          # Live preview with hot reload

The Pipeline

1. AUTHOR    — Write empathic YAML in Cursor
2. LINT      — adventure.py lint quest/ → outputs events for LLM
3. COMPILE   — LLM generates: HTML + CSS + JSON + JavaScript
4. BROWSER   — engine.js evaluates expressions, escalates to LLM for complex situations

Key Principles

Linter does NOT auto-fix — outputs events for LLM to read and correct (LLM has context)
Empathic expressions → static data — LLM compiles behavior into executable JSON
Python for precision, LLM for poetry

Runtime Expressions

Objects can have embedded JavaScript expressions for runtime evaluation:

compiled_behavior:
  expressions:
    wander_delay: "2 + Math.random() * 3"
    flee_chance: "player.intimidation > 5 ? 0.8 : 0.3"
    damage_roll: "roll('1d6') + this.strength"

Inspiration: Scott Adams, Don Hopkins & Memory Palaces

This system is directly inspired by a Hacker News exchange (Nov 2021) (AMA thread) between Scott Adams (creator of Adventureland, 1978 — not the Dilbert cartoonist) and Don Hopkins (SimCity, The Sims, pie menus). Soul City interface: skills/soul-city/SOUL-MODEL.md.

The Method of Loci Connection

Don Hopkins asked Scott Adams:

"How do you think Adventure games are like the Method of Loci, or Memory Palaces, in that they can help you remember and retrieve vast amounts of information geographically?"

Adventure games ARE memory palaces. The rooms, objects, and spatial relationships create lasting mental maps.

Pie Menus = Room Navigation

      N
      ↑
  NW ↖ ↗ NE
 W ←  ●  → E     Pie menu = Room exits = Memory palace navigation
  SW ↙ ↘ SE
      ↓
      S

Don Hopkins realized: "4-item and 8-item pie menus are the essential elements of an Adventure map, as long as you think of 'menus' as rooms in a map with two-way links."

Code as Buildings

Don Hopkins visualizes code as memory palaces:

"Each function is a little building like an office or a shop, which has a sign out front telling what services or products it sells, and contains everything inside you need to solve some kind of problem."

The Vision: Archives as Adventures

Both Scott Adams and Don Hopkins want to publish their papers, articles, emails, and biographies as interactive adventures. This system is one iteration of that vision.

The Banned Magic

The Method of Loci was banned by the Puritans in 1584 for evoking "bizarre and irrelevant" imagery. We're bringing it back. 🏰✨

lloooomm Heritage — The Crown Jewels

The Shneiderman Owl Simulation demonstrates the architecture:

# owl.yml (YAML definition)
name: "Nightwatch-7"
type: owl
behaviors: [patrol, hunt, drone]
stats:
  energy: 100
  catches: 0

↓ Compiles to ↓

class Owl {
    constructor(id, timezone) {
        this.id = id;
        this.position = { x: 0, y: 0, z: 50 };
        this.energy = 100;
    }
    patrol(owls) { /* 3D flocking (boids) */ }
    hunt(mice) { /* predator-prey behavior */ }
}

The Projection: Browser version is a deterministic shadow of the full LLM simulation. Simple interactions run locally. Complex situations escalate to LLM.

See SKILL.md for complete runtime specification.