# moo2-mcp

An experiment to let an AI (via Claude) play *Master of Orion 2*, the 1996 DOS-era 4X
strategy game, while it runs inside the DOSBox-X emulator.

Because the emulator isn't modified, the project works in two directions:

## MCP tools

The server (`python -m moo2mcp.server`, stdio) exposes these read-only tools. Every one
of them reads a live DOSBox-X process and raises a descriptive error — rather than
returning a misleading number — when the target is unavailable or no game is loaded.

| Tool | Returns |
|------|---------|
| `get_turn` | the current turn as an integer: the stardate in tenths (÷10 for the displayed value) |
| `get_empire_status` | the player empire: `turn`, `treasury_bc`, `income_bc`, `research_per_turn`, `food`, `production`, `research_target`, plus `unavailable` naming the fields not yet reverse-engineered (those come back `null`, never guessed) |
| `list_colonies` | one entry per colony: `system` (MOO2's own planet name, e.g. `"Skynet I"`), `population`, and the labour outputs `food_output`/`production_output`/`research_output`. `buildings` and `production_queue` stay empty — unresolved |
| `get_colony(index)` | a single colony in the same shape, indexed as in `list_colonies` |
| `get_home_colony` | the home colony's `population` and labour outputs. Identity, buildings and queue stay `null`/empty. The raw farmer/worker/scientist counts aren't stored by MOO2, so they aren't reported |
| `get_player_empire` | `empire_id` (0–4) plus the home system's `home_system` name and `home_system_index`. Errors if the game wasn't started by the harness, whose home-star marker this relies on |
| `list_systems(explored_only=true)` | per system: `index` (for `list_system_planets`), `name`, galaxy `x`/`y`, the global `planets` indices in orbit order, `explored_by_player`, `home_of` and `colonies_of`. Passing `explored_only=false` includes unexplored systems — information the game itself would not show the player |
| `list_system_planets(system_index)` | per planet: `index`, `name`, `body_type` (planet / gas giant / asteroids), `size`, `gravity`, `climate`, `minerals`. Climate only means anything when `body_type` is `"planet"` |
| `list_ships` | per ship: `name` (e.g. `"Colony Ship 2"`), `design`, `location` (the star system it's at) and `owner`. Ships, not fleets |
| `list_fleets` | fleets by `location` and ship composition — **currently always errors**: the ship records are resolved but their grouping into fleets is not, so fleets can't be assembled without guessing |
| `get_game_state` | a consistent snapshot — `empire`, `colonies`, `fleets` read back-to-back — with any unresolved or unreadable domain returned as `null` and named in `unavailable` with a reason |

## Reading game state

The game's state is read by peeking directly into the emulator's memory. Locations of
interest are reverse-engineered two ways: by changing one thing in-game and observing which
memory bytes move, and by searching for structures whose shape is already known — for
instance, the planet table was found because each planet must point back at the star that
lists it, and only one array in 16 MB reproduced that map.

Those values are exposed through an [MCP](https://modelcontextprotocol.io) server, so an AI
can ask what turn it is, how much money it has, what its colonies are producing, or which
nearby planets are worth settling. What is readable today:

- **Empire** — turn, treasury, income, research, food
- **Colonies** — the planet's name, population, and the food/production/research its
  workers generate
- **Galaxy** — star systems with their map positions, and every planet's size, gravity,
  climate and mineral richness
- **Ships** — each ship's name, design and the system it is in

Anything not yet reverse-engineered is reported as unavailable rather than guessed, so a
wrong answer never reaches the AI. Buildings, production queues, and how ships group into
fleets are the main gaps.

One quirk worth knowing: MOO2 gives no reliable way to tell *which* of the five empires the
player is. So the harness names the player's home star with a fixed marker, and the read
path finds that star by name and works backwards to the player's identity.

## MCP tools

All read-only, over stdio (`python -m moo2mcp.server`).

| Tool | Returns |
|------|---------|
| `get_turn` | the live stardate (in tenths; ÷10 for the displayed value) |
| `get_empire_status` | the player empire: `turn`, `treasury_bc`, `income_bc`, `research_per_turn`, `food`; unresolved fields are `null` and named in `unavailable` |
| `list_empires` | every empire: `empire_id`, `name`, `is_player`, plus the same scalars. Shows what the game would hide — AI treasuries are readable from turn 1, and contact status is not reverse-engineered yet, so it can't be limited to empires the player has met |
| `get_player_empire` | which empire the player is: `empire_id` and the home system's name/index |
| `list_colonies` / `get_colony` | colonies: `owner`, `population`, `food_output`, `production_output`, `research_output`, `system` (e.g. `"Skynet I"`). `buildings`/`production_queue` are unresolved and stay empty. `all_empires=true` includes the AI empires'. A colony whose record MOO2 hasn't written yet (it does so some turns after founding) still appears, located by the star table: `owner` and `system` only, every record field `null` and named in `unavailable` |
| `get_home_colony` | the home colony alone, found by verifying the record's owner rather than assuming its index |
| `list_systems` | star systems: `name`, `color`, `x`/`y`, `planets`, `home_of`, `colonies_of`, `explored_by_player`. Explored only unless `explored_only=false` |
| `list_system_planets` | one system's planets: `name`, `body_type`, `size`, `gravity`, `climate`, `minerals` |
| `list_ships` | the player's ships: `name`, `design`, `location`. Ships, not fleets |
| `list_fleets` | **errors** — how ships group into fleets is not reverse-engineered |
| `get_game_state` | a snapshot of empire + colonies + fleets, with unreadable domains `null` and named in `unavailable` |

## Controlling the game

The game is driven by simulating mouse clicks and keystrokes through a virtual screen
(Xephyr + xdotool), since the host desktop blocks normal automation. A harness can launch
the game and start a new match from cold, and a second mode lets Claude drive the live UI a
screenshot at a time — which is how the memory locations get correlated with what the game
actually displays.

This UI driving is a reverse-engineering and verification tool, not the plan for playing.
Real gameplay actions are meant to go below the UI, because synthetic input is fragile:
MOO2's drags are really two separate clicks, and a stray click in the wrong panel silently
reassigns a colony's workers.

In short, this is the plumbing that lets an AI observe and eventually drive an old strategy
game it otherwise can't talk to.

Setup, the resolved memory map, and how each address was found are in
[`docs/setup.md`](docs/setup.md).