fallout2-sdk

A Claude Code project that allows Claude to play Fallout 2 autonomously.

Overview

fallout2-sdk bridges Claude Code and Fallout 2 by modifying the Fallout 2 Community Edition (CE) open-source engine to emit structured game state and accept input commands via JSON files. Claude observes the game world each tick, reasons about objectives and tactics, and issues commands — playing Fallout 2 through an observe → decide → act loop, with an in-character persona voice rendered as floating text in the game world.

Project Structure

fallout2-sdk/
├── engine/
│   ├── fallout2-ce/            # Fallout 2 CE (git submodule) — upstream engine
│   └── patches/                # Engine patches (applied on top of CE)
├── src/                        # C++ agent bridge
│   ├── agent_bridge.h          # Public API
│   ├── agent_bridge_internal.h # Shared internals
│   ├── agent_bridge.cc         # Core: init/exit, ticker, context detection
│   ├── agent_state.cc          # State emission (character, map, combat, dialogue, etc.)
│   └── agent_commands.cc       # Command handlers (86 commands)
├── scripts/
│   ├── executor.sh             # Gameplay shell — all Claude interaction goes through here
│   ├── executor_world.sh       # Movement, navigation, exploration, interaction, healing
│   ├── executor_combat.sh      # Auto-combat monitoring loop and quip generation
│   ├── executor_dialogue.sh    # Dialogue, persona, and thought system
│   ├── executor_chargen.sh     # Character creation & level-up helpers
│   ├── executor_state_helpers.py # Extracted state query helpers (look_around, find_object, etc.)
│   ├── executor_dialogue_helpers.py # Dialogue/persona JSON processing helpers
│   ├── game_state_hook.py      # PreToolUse hook: injects game state before Bash calls
│   ├── float_response.sh       # Hook: renders Claude's responses as in-game floating text
│   ├── check_state_schema.py   # Validates agent_state.json contracts
│   ├── check_bridge_source_drift.sh # Detects header drift between src/ and engine copy
│   ├── setup.sh                # First-time setup (copies game data)
│   ├── apply-patches.sh        # Apply engine patches after clone/pull
│   └── generate-patches.sh     # Generate thematic patches after modifying engine
├── tests/                      # Python unit tests
│   ├── test_state_schema.py    # Schema validation tests (11 tests)
│   ├── test_game_state_hook.py # Game state hook output tests (6 tests)
│   └── test_dialogue_helpers.py # Dialogue helper tests (4 tests)
├── docs/
│   ├── gameplay-guide.md       # Spoiler-light interaction cheat sheet
│   ├── default-persona.md      # Default character persona (copied to game/ at start)
│   ├── state-schema.md         # Complete agent_state.json field reference
│   ├── command-schema.md       # All 86 bridge commands with params and context gating
│   ├── adding-a-command.md     # Step-by-step checklist for adding new commands
│   └── journal.md              # Session-by-session development history
├── .claude/
│   ├── settings.json           # Claude Code hooks (PreToolUse, Stop, PreCompact)
│   └── skills/                 # Slash commands (/game-note, /game-log, /game-recall, /run-codex)
├── game/                       # Runtime data (NOT committed — see Setup)
│   ├── agent_state.json        # Game state output (written every tick by bridge)
│   ├── agent_cmd.json          # Command input (read and consumed by bridge)
│   ├── agent_float.json        # Float channel (display commands only — separate from cmd)
│   ├── knowledge/              # Persistent in-game notes (locations, items, quests, etc.)
│   ├── debug/                  # NDJSON debug logs (bridge, executor, hook)
│   ├── game_log.md             # Gameplay decision/event log
│   ├── persona.md              # Active character persona (copied from docs/default-persona.md)
│   ├── thought_log.md          # In-character reasoning log
│   └── objectives.md           # Current tactical sub-objectives
├── sdk.cfg.example             # Configuration template (copy to sdk.cfg)
├── CLAUDE.md                   # Claude Code project instructions
└── LICENSE

Prerequisites

• Fallout 2 — A legal copy from GOG, Steam, or other retailer
• CMake 3.13+
• C++17 compiler (Clang on macOS, MSVC on Windows, GCC on Linux)
• SDL2 (bundled with the CE build by default)
• Python 3 (for JSON state parsing in shell helpers)
• Git

Setup

1. Clone the repository

git clone --recurse-submodules https://github.com/liminalwarmth/fallout2-sdk.git
cd fallout2-sdk

If you already cloned without --recurse-submodules:

git submodule update --init --recursive

2. Provide Fallout 2 game data

The SDK needs the original Fallout 2 data files (master.dat, critter.dat, patch000.dat, etc.). These are copyrighted and not included in this repository.

Option A: Setup script (recommended)

# Interactive — will prompt you for the source
./scripts/setup.sh

# From an existing installation directory
./scripts/setup.sh --from /path/to/fallout2/install

# From a GOG macOS DMG
./scripts/setup.sh --from-dmg ~/Downloads/fallout_2_2.0.0.4.dmg

Option B: Manual copy

Copy the following from your Fallout 2 installation into game/:

File / Directory	Required
master.dat	Yes
critter.dat	Yes
patch000.dat	Yes
fallout2.cfg	Optional (generated if missing)
data/	Optional (override data)
sound/music/	Optional (music files)

Where to find your game files

macOS (GOG): Right-click the app, choose "Show Package Contents", then navigate to:

Contents/Resources/game/Fallout 2.app/Contents/Resources/drive_c/Program Files/GOG.com/Fallout 2/

Windows (GOG):

C:\GOG Games\Fallout 2\

Windows (Steam):

C:\Program Files (x86)\Steam\steamapps\common\Fallout 2\

Linux (GOG via Wine):

~/.wine/drive_c/GOG Games/Fallout 2/

3. Verify setup

After copying game files, check that the required files are in place:

ls -lh game/master.dat game/critter.dat game/patch000.dat

You should see master.dat (~318 MB), critter.dat (~159 MB), and patch000.dat (~2.2 MB).

Building

Apply engine patches (required after cloning or pulling), then build:

./scripts/apply-patches.sh

cd engine/fallout2-ce
mkdir -p build && cd build
cmake .. -DAGENT_BRIDGE=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5
make -j$(sysctl -n hw.ncpu)

# Deploy and launch (macOS)
cp -R "Fallout II Community Edition.app" ../../../game/
codesign --sign - --force --deep ../../../game/"Fallout II Community Edition.app"
cd ../../../game && open "Fallout II Community Edition.app"

CMake presets in engine/fallout2-ce/CMakePresets.json support cross-platform builds (macOS, Windows, Linux, iOS, Android).

Architecture

Claude Code (CLI) ←→ JSON files ←→ Agent Bridge (C++) ←→ Fallout 2 CE Engine + SDL2

The agent bridge hooks into the Fallout 2 CE engine to provide two-way JSON communication:

• State emission (game/agent_state.json) — player stats/skills/perks, map/objects, inventory, combat (AP, hostiles, hit chances), dialogue, barter, world map, quests, party, message log, game time — across 17 fine-grained contexts
• Command input (game/agent_cmd.json) — 86 commands for exploration, combat, dialogue, inventory, barter, world map, level-up, save/load, character creation, and queries — with centralized context gating and pre-validation
• Float channel (game/agent_float.json) — dedicated channel for display-only commands (floating text, status overlays), processed independently from gameplay commands to prevent I/O races
• Muse system — floating orange text above the player's head renders Claude's inner monologue in real-time, spoken in the character's persona voice with complexity scaled to the character's Intelligence stat (INT 1-3: simple fragments, INT 9-10: eloquent prose)
• Float response hook — Claude's natural language responses are also rendered as in-game floating text via a Claude Code hook (scripts/float_response.sh), so the character "speaks" in the game world

Hooks

Claude Code hooks (.claude/settings.json) provide real-time integration:

• PreToolUse (game state) — scripts/game_state_hook.py injects a compact [GAME] status line before every Bash call (scoped via "matcher": "Bash"), so Claude always has current HP/tile/map/context without explicit polling
• PreToolUse + Stop (float response) — scripts/float_response.sh renders Claude's natural language output as in-game floating text via the dedicated float channel (async, scoped to Bash calls)
• PreCompact — sets an in-game status overlay ("Compacting context") via the float channel when the conversation is being compressed

Gameplay Layer

On top of the C++ bridge, a shell-based gameplay layer provides Claude with high-level abstractions:

• Executor shell (scripts/executor.sh + sub-modules) — tactical helper functions for common gameplay loops, split across focused modules:
  • executor_world.sh — unified move_and_wait (tile movement + exit grid navigation), exploration sweeps, interaction (loot, examine, use_skill, talk), healing, party management, ammo/reload
  • executor_combat.sh — do_combat monitoring loop (engine-native _combat_ai() handles decisions; the shell monitors for death, stuck, critical HP, and combat end)
  • executor_dialogue.sh — dialogue assessment, option selection, persona system, thought logging
  • executor_chargen.sh — character creation (SPECIAL, traits, skills) and level-up (skill points, perks)
  • Core (executor.sh) — I/O primitives (cmd, py, field), wait helpers, state inspection (status, look_around, inventory), save/load, knowledge management (note, recall, game_log, objective), bridge version negotiation
• Python helpers — extracted state query logic (executor_state_helpers.py), dialogue/persona processing (executor_dialogue_helpers.py), schema validation (check_state_schema.py), and header drift detection (check_bridge_source_drift.sh)
• Test suite (tests/) — 21 unit tests covering schema validation, game state hook output formatting, and dialogue helper correctness
• Persona system (docs/default-persona.md → game/persona.md) — defines the character's personality, voice, and roleplaying style. Claude plays in-character, with inner monologue via muse and spoken responses as floating text
• Knowledge system (game/knowledge/) — persistent notes organized by topic (locations, characters, items, quests, strategies, world lore). Claude records discoveries during play and recalls them when relevant
• Debug system (game/debug/) — structured NDJSON logging across bridge, executor, and hooks. Functions like debug_tail, debug_find, debug_timeline, and debug_last_failure provide post-hoc analysis
• Claude Code skills — slash commands (/game-note, /game-recall, /game-log, /run-codex) for quick access to knowledge, logging, and cross-model code review

Key engine integration points: ticker callback (per-tick state/commands), context hooks (mainmenu.cc, character_selector.cc, character_editor.cc, main.cc), animation system (reg_anim_*), action system (actionPickUp, actionUseSkill, etc.), and custom accessor functions for static engine state. Engine modifications are organized as 7 thematic patches (see engine/patches/) for easy upstream rebasing.

See CLAUDE.md for development and gameplay instructions.

Project Status

Active development. The agent bridge has been validated through autonomous gameplay:

• Temple of Trials — fully cleared legitimately (character creation, 3 dungeon levels, combat, lockpicking, explosive puzzle, Cameron's unarmed test)
• Klamath — world map travel, NPC dialogue trees, barter trading, ranged combat with ammo tracking, container looting, Sulik recruitment
• All major gameplay systems functional: exploration, combat (auto-combat AI + manual), dialogue, inventory, barter, world map, quests, level-up, party, save/load, holodisk reading
• 86 bridge commands with centralized context gating, pre-validation, and structured result codes
• 17 game contexts detected with full state emission per context
• Hardened I/O — dedicated float channel, fread/fwrite/rename error checking, parse-before-delete command handling, bridge version negotiation
• 7 thematic engine patches (core, combat, dialogue, worldmap, inventory, UI, cmake) with safety checks for uncaptured file drift
• 21 unit tests covering schema contracts, hook output, and dialogue helpers

License

This project is licensed under the MIT License.

Note: The Fallout 2 CE engine (in engine/fallout2-ce/) is licensed under the Sustainable Use License. Fallout 2 game data files are copyrighted by Interplay/Bethesda and require a legal copy of the game.