▶ Watch the 12-second real interaction recording
--- ## Why this exists Most AI text games hand the "world" to a language model: numbers drift, NPCs forget, the same choice gives a different outcome on replay. **World Walker inverts that**: - **The engine does the math** — hits, damage, prices, relationships, karma, faction power, rumor spread are all resolved by deterministic rule functions. - **The agent writes the prose** — the LLM only turns returned JSON into literary text; it must not invent numbers. - **The panel bears witness** — a read-only web stage shows the real state, so every number on screen is checkable. It is not another "AI GM prompt". It is a **world kernel any agent can call**: an MCP server (stdio), a CLI (14 commands), and an HTTP read-only panel sharing one rule set and one state file. --- ## Quick start (30 seconds) ```bash pip install -e ".[mcp]" # stdlib only + optional mcp SDK ``` Add to any MCP client (Claude Code / Codex / Cursor / opencode): ```json { "mcpServers": { "world-walker": { "command": "world-walker-mcp" } } } ``` Then tell your agent: ``` load_setting(path="settings/玄枢界.setting.json") ``` That boots a full game. Every action is then settled by tools: ``` You: I walk into the Wanshi trading house and put the torn page on the counter. Agent → trade(location="临川城", item="yinyuan_canye", direction="sell", quantity=1) → social(actor="player", target="shi_sanniang", event="cooperate") → narration_context(...) → publish_prose(...) → tick() ``` No MCP? The CLI works too: ```bash python init_game.py python engine.py world_state --state game_state.json python engine.py combat --state game_state.json --attacker player --defender goblin --action_type heavy python panel.py --state game_state.json ``` --- ## Screens Every screenshot is a **real render of a real save**, asserted element-by-element in Edge by `scripts/shots.py`. Source saves live in [`docs/demo/`](docs/demo/). | Xuanshu (Eastern fantasy · ink-gold) | Zhejian (Wuxia · ink) | |---|---| |  |  | | **Neon Abyss (cyberpunk · neon)** | **Fogport (investigation · graphite)** | |  |  | Skins are the surface. What actually changes with the world is **vocabulary, tiers, currency and place descriptions**: a setting bundle can write `terms: { level: "身手", gold: "银两" }` and the panel will never show "境界 / 灵石" again. `scripts/verify_settings.py` asserts this for every bundle. | | | |---|---| |  |  | | **World pulse**: Panarchy phase, faction power, connectedness, intensity, rumors — advanced every `tick` | **Character card**: click anyone on stage to read their card text | |  |  | | **Command palette** (`Ctrl/⌘+K`), fully keyboard reachable | **Action queue**: queue actions in the browser; the agent drains them via `pending_actions` | | Codex | Market | Milestones | |---|---|---| |  |  |  | | 768px | 320px | Help | |---|---|---| |  |  |  | | Share mode (hides paths & controls) | First-visit guide | |---|---| |  |  | --- ## How it compares Full method and evidence: **[docs/BENCHMARK.md](docs/BENCHMARK.md)**. One-line version: | Dimension | Typical (AI Dungeon / NovelAI / SillyTavern) | This project | |---|---|---| | Who decides numbers | The LLM, in prose | **Rule functions**, byte-identical replay per seed | | Does the world move on its own | No (waits for input) | **`tick` advances** factions / rumors / culture / NPCs / Panarchy | | Swapping worlds | Prompt + character card | **Setting bundle**: terms, tiers, currency, places, lorebook, brand, skin | | Long-game memory | Context window + summary | **Three layers**: summaries + milestones + generational archive (`recall`) | | Ecosystem | Proprietary | Reads SillyTavern **character cards** (PNG/JSON, V1–V3) and **world info** | | Interface | Chat stream | **Read-only live stage**: narrative + HUD + long-run charts + codex + market | | Auditable | Hard | Structured event fields; read-only tools never write; mutation suite 36/36 | We deliberately **do not** do: image generation, multiplayer, cloud accounts, plugin marketplaces. Reasons are in [ROADMAP.md](ROADMAP.md). --- ## Core mechanics (all on the settlement path) ### 1. The world moves by itself Each `tick` advances: - **Factions** — logistic growth toward a per-faction endowment cap (deterministically derived from the name), mild Lotka–Volterra pressure between the top two, plus challenger backflow. Long-term hierarchy, short-term turnover. - **Rumors** — one SIR step; new rumors seed only on high karma, price anomalies, or violent phases. - **Culture** — Deffuant bounded confidence, evaluated every 10 turns. - **NPCs** — entities tagged `roam: true` change locations. - **Panarchy** — an explicit `r → K → Ω → α → r` state machine driven by real stock (faction mean, relation density, world flags, karma, price deviation), not a lookup table. `verify_world.py` (W1/W2/W11) asserts all four actually happen, including through the real MCP `tick` tool. ### 2. Derived metrics feed settlement | Metric | Where it acts | Test | |---|---|---| | World phase | Ω: event probability ×1.6, damage ×1.25, hit ×0.90 | W3 | | Flow | boredom lowers hit chance, anxiety raises it | W4 | | Six-axis morality | accumulated from karma type (not parsed from Chinese text); infamy dampens social gains | W5 | | Level tiers | combat power bonus per tier; `advance` enforces step-by-step progression | W10 | ### 3. Karma ledger Structured entries: type, amount, creditor, turn, settled. Unsettled debt lowers breakthrough odds, amplifies hostility, and raises "tribulation" severity. The ledger is bounded by **merging** the oldest entries while preserving the total—never truncating. ### 4. Long-game memory ``` write_summary every 20–50 turns: three to five sentences about what changed milestones breakthroughs / kills / first arrivals / karma escalations archive overflow events appended to