shapez
by sqkl520
README.md
# shapez-ai-bridge
**English** | [简体中文](README.zh-CN.md)
**An AI-operable interface for [shapez.io](https://shapez.io): a single-file official mod + a zero-dependency local bridge + an MCP server.** Observe the factory, place and delete buildings, fast-forward deterministically, move blueprints and savegame snapshots, and let any script or MCP client drive it — all locally, over `127.0.0.1`.
```
┌─ shapez.io (Electron) ───────────────────┐
│ shapez-ai-bridge.js │ the mod is a WebSocket *client*
│ (official single-file mod, no Node) ──┼──▶ ws://127.0.0.1:7777/mod
└─────────────────────────────────────────┘
│
┌─────────────┴────────────────────────────┐
│ bridge.mjs (Node, zero dependencies) │
│ ├─ WS /mod ← game mod │
│ ├─ WS /client ← tools / event stream │
│ └─ HTTP /health /status /rpc ← curl │
└─────────────┬────────────────────────────┘
│ HTTP or stdio
┌─────────────┴──────────┬─────────────────┐
│ mcp/server.mjs │ agent/play.mjs │
│ 8 MCP tools (Claude…) │ reference agent│
└────────────────────────┴─────────────────┘
```
Why a separate bridge process? shapez.io's renderer is sandboxed (`nodeIntegration:false`, `sandbox:true`), so an in-game mod has no file or socket APIs — but the browser's native `WebSocket` client is always available. The mod dials out to a small Node process on your machine; that process owns the HTTP API, the MCP server and the snapshot files.
## Prefer a GUI?
A local web interface covers the whole setup without any commands: double-click
`gui/start.cmd` (Windows), and a wizard walks through environment check, mod
install, configuration, bridge start and verification — with live logs and
explicit fixes when something is missing. No configuration file is ever edited
by hand.
```bash
node gui/server.mjs # or double-click gui/start.cmd on Windows
```
It opens a chromeless app window on `http://127.0.0.1:7801/`. Same zero-dependency
rules as the rest of the project: it needs only Node and a browser, both of which
you already have by the time you get here. See [gui/README.md](gui/README.md)
(中文) for the walkthrough.
Everything below is the command-line path — the GUI drives exactly the same
scripts, so the two are interchangeable.
## 30-second quick start
Prerequisites: **Node.js ≥ 20**, **shapez.io desktop 1.5.6** (Steam build), and a checkout of this repository.
**1. Install the mod (one command).**
Windows (PowerShell):
```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```
macOS / Linux:
```bash
bash install.sh
```
**2. Start the bridge (one command).**
```bash
node src/bridge/bridge.mjs
```
**3. Start shapez.io, load a savegame, then run:**
```bash
node scripts/smoke_test.mjs
```
Expected: `SMOKE TEST PASSED (5/5)`. (The test briefly places and deletes one belt near the hub to prove writes work — your world is left unchanged.)
## What it can do
Curl examples below assume bash. On Windows PowerShell `curl` is an alias for `Invoke-WebRequest` — use `curl.exe` instead, with double quotes around the JSON (escaping the inner quotes), or use the included scripts.
- **Observe** — ask the game what's in the world as JSON: entities with stable uids, hub stock, current goal, camera, stats.
```bash
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"obs","params":{"max_entities":5,"include_hub":true}}'
```
- **Act** — place or delete buildings, lay paths, set game speed, move the camera.
```bash
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"act","params":{"op":"place","building":"belt","x":5,"y":5}}'
```
- **Fast-forward** — advance N game ticks synchronously and deterministically (the same loop the game's own puzzle validator uses), optionally collecting an observation.
```bash
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"act","params":{"op":"step","ticks":600,"collect":true}}'
```
- **Blueprints** — export any region as a portable `SZBP1.*` string and paste it back anywhere (material cost per game rules by default, free with `charge:false`).
```bash
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"act","params":{"op":"export_blueprint","region":[0,0,10,10]}}'
```
- **Save snapshots** — save the game and keep a named copy of the save file on the bridge side, then restore it any time.
```bash
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"snapshot_save","params":{"name":"before-big-build"}}'
```
- **MCP** — all of the above exposed as 8 MCP tools (`shapez_status`, `shapez_observe`, `shapez_action`, `shapez_batch`, `shapez_screenshot`, `shapez_blueprint`, `shapez_save`, `shapez_load`) for Claude and other MCP clients.
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp/server.mjs
```
The full protocol contract (methods, error codes, observation schema) lives in [`docs/PROTOCOL.md`](docs/PROTOCOL.md).
## Build a factory from a target shape
`src/ai/` contains a layout compiler: give it a goal shape, and it plans a working production line offline, then hands you a blueprint that pastes and delivers.
```bash
node src/ai/compiler/cli.mjs --goal "CuCuCuCu" --seed 43391 --hub -2,-2 --json
```
It runs the whole chain with no game running: recipe solver → offline resource map (the world is a pure function of `map.seed`) → row layout → belt routing with explicit `(rotation, rotationVariant)` → ten-check validator → SZBP1 blueprint.
**`--hub` is required.** Without it the compiler can only invent a hub location, so the collection belt feeds empty ground. A compile whose hub is not pinned is reported as a failure (`class: "hub:unpinned"`), not a success. Pass the hub's real top-left corner as observed from the game (`obs`), not a guessed coordinate.
`ok: true` means the plan is internally consistent and reaches the real hub **when pasted onto empty ground**. It does not mean the target area is empty: the compiler is offline and does not read your save, so it cannot see what is already built there. Always `dry_run` the paste first — that is the check that sees the world.
The end-to-end live run (compile → `dry_run` → paste → per-cell diff → hub delivery) was verified on an earlier plan shape of this same goal. The current code produces the 9-entity plan shown above; it passes the offline validator, round-trip, and the world-frame hub check (`hubPinned: true`), but **the paste-and-deliver step has not been re-run on this exact blueprint** — the game was in its menu at the time of the last attempt and `new_game` wedges after long uptime. Treat the live delivery as verified for the pipeline, not for this byte-for-byte blueprint.
### What it handles today
| | |
|---|---|
| Goals that build | `CuCuCuCu`, `RuRuRuRu`, `SuSuSuSu`, `----CuCu`, `RuRu----`, `Cu----Cu`, `Cu------`, `--CuCu--`, `Ru----Ru`, `--SuSu--` — and painted goals when the map allows it: `CrCrCrCr` (119 entities), `RbRb----` (262 entities, needs `--range 200`) |
| Not yet | `CpCpCpCp` and `CgScScCg` — these need three or more miners on one row at fixed spacing, and no such resource pattern exists near the hub on seed 43391 (`no-resource-in-range`, honestly reported). Multilayer goals are out of scope by design (`scope.layers: 1`). |
**Painted goals are map-permitting, not unconditional.** The row layout puts every miner on one row at a fixed pitch, so a painted goal needs the world to offer its ore in exactly that pattern. `CrCrCrCr` needs `Cu` with `red` four cells west; on seed 43391 that pattern occurs twice in a 512×512 window. Other seeds may have none — the compiler says `no-resource-in-range` rather than producing a line that starves. Treat painted goals as "works where the ore lines up", not "works anywhere".
### Safety rules the compiler enforces
- **Refuses to emit a plan that would land on existing buildings.** Only belts and wires are replaceable in shapez; pasting over one silently destroys it, and pasting over a machine half-builds the line while still reporting success. `paste_blueprint` gained a `dry_run` that reports `would_apply` / `would_delete` / `blocked` before anything happens.
- **Refuses corners that would flip.** A belt's turn is recomputed from its neighbours, so a corner must be a fixed point of that recomputation; when no original rotation makes it one, the plan fails instead of producing a line that breaks later.
- **Never pastes into a dirty region.** v1 builds on fresh ground only. The builder refuses a world snapshot that contains non-hub entities, on both the pinned and unpinned paths — but it only sees a world if you hand it one, so `dry_run` remains the authoritative check.
- **Refuses a plan whose hub is unknown.** Without `--hub` the collector belt would terminate at an invented coordinate. Such a compile returns `ok: false` with `class: "hub:unpinned"` instead of a blueprint.
See [`research/ai-plan/BATCH.md`](research/ai-plan/BATCH.md) for the build ledger and [`research/ai-player/SYNTHESIS.md`](research/ai-player/SYNTHESIS.md) for the research behind it.
## Compatibility
Generated from `compat.json`:
| Game version | Mod version | Protocol | Status |
|---|---|---|---|
| 1.5.6 (Steam build `ee2279d5`, Electron 16.2.8) | 0.1.x | 1 | Supported — development baseline |
| any other | any | any | **Hard fail** (error `1002`) — no downgrade, no override |
The mod declares `minimumGameVersion: 1.5.6`, and the bridge re-checks the game version reported at handshake against this table; on mismatch nothing is routed.
## Uninstall
Delete `shapez-ai-bridge.js` from the mods folder (that single file is the entire mod), or run `install.ps1 -Uninstall` / `bash install.sh --uninstall`.
## Known limitations
An honest list, taken from the phase-0 recon ([`PHASE0-RECON.md`](PHASE0-RECON.md)):
- **Steam achievements are disabled while ANY mod is installed.** The game only enables its Steam layer when zero mods are loaded (`if (mods.length === 0) steam.listen()`). This is official shapez.io behavior, not a bug of this project.
- **The game clears localStorage on every launch** (`clearCache()` + `clearStorageData()` in the main process), so the mod has no cross-session local storage. Anything persistent must go through mod settings files or the savegame.
- **shapez.io 1.5.6 has no native blueprint string format.** This project defines its own `SZBP1.*` format (built on the game's own LZ-string compression), so blueprints are only exchangeable between the same game version — the embedded `gv` field is checked on paste, and a mismatch fails with error `2006`.
- **Pasting a blueprint charges "blueprint shape" material** (in regular mode, `CbCbCbRb:CwCwCwCw`) per the game's own cost formula. Use `charge:false` to paste for free.
- **`step` / `await` fast-forward runs synchronously on the render thread** — large tick counts briefly freeze the screen. A single step is capped at 20,000 ticks.
- **Observations of big factories must be clipped** with `region` and/or `max_entities`. Over-limit observations report `truncated: true` and always include full `stats` — never a silent cut.
- **Desktop only** (Windows / macOS / Linux Electron builds). The mobile and browser versions of shapez.io do not support mods and are not applicable.
- **`new_game` needs a fresh game process.** After a very long uptime the game can wedge in the menu: the save is created but the state machine never enters the world. Restart the game and it works immediately.
- **The layout compiler's output is god-mode.** It uses `charge:false` and does not check building unlock levels, so it can place a stacker at level 2. The acceptance target (`CuCuCuCu`) needs only the level-1 cutter, so it holds under either reading, but any "cleared level N" claim from the compiler is a god-mode claim.
- **The compiler builds on fresh ground only.** It refuses to place over existing buildings (v1), so extending a running factory is not supported yet.
## Troubleshooting
**"I can't connect."**
1. Is the bridge running? `curl -s http://127.0.0.1:7777/health` should return `{"ok":true,...}`. "Connection refused" → start `node src/bridge/bridge.mjs`.
2. Is the game running? `health` reports `mod_connected:true` only once the game is open *with the mod loaded*. `mod_connected:false` means the game (or the mod) isn't there yet.
3. Is the mod in the right place? The game reads `%APPDATA%\shapez.io\mods` (Windows), `~/Library/Preferences/shapez.io/mods` (macOS), `~/.local/share/shapez.io/mods` (Linux). It must be a **single `.js` file directly in that folder** (not a subfolder). On startup the game logs `Loaded N mods` — N must be ≥ 1. The install scripts pick the right folder automatically; `-ModsDir` / `--mods-dir` override it.
4. Security software: a firewall/proxy that blocks localhost traffic can break both the bridge's listener and the mod's WebSocket. Allow `node` on `127.0.0.1:7777`; if a system proxy is forced for all traffic, exclude `127.0.0.1`.
**"Version mismatch (error 1002)."** The bridge refused the handshake because the game version isn't in the compatibility table. This is a hard fail by design: building codes and internal APIs are version-specific. Fix by upgrading to a mod/bridge version that lists your game build in `compat.json` (or switch the game back to a supported build via Steam betas). There is no override flag.
**"Observation is empty / errors."**
- Error `1003 not_in_game` → you're in the main menu or still loading. Load a savegame (or start a new one); `status` will say `in_game:true`.
- Region selection: `region:[x0,y0,x1,y1]` is an inclusive bounding box — everything outside it is filtered out. Omit `region` to observe the bounding box of all entities.
- Layer: entities live on `regular` or `wires`; observe the right one (default `regular`).
**"My MCP client doesn't list the tools."**
- The path in the client config must be **absolute** and point at `src/mcp/server.mjs`. In JSON on Windows use forward slashes (`C:/...`) or escaped backslashes (`C:\\...`).
- Restart the MCP client after editing its config.
- Test the server standalone: `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp/server.mjs` — you should get a JSON line listing 8 tools.
- The server logs to stderr, not stdout; check your client's MCP logs for its stderr output.
## MCP configuration
`mcp-config.example.json`:
```json
{
"mcpServers": {
"shapez": {
"command": "node",
"args": [
"C:/path/to/shapez-ai-bridge/src/mcp/server.mjs"
],
"env": {
"SHAPEZ_BRIDGE_URL": "http://127.0.0.1:7777"
}
}
}
}
```
Replace the path with the absolute path of your checkout. **Windows path writing in JSON:** either forward slashes (`C:/Users/you/shapez-ai-bridge/src/mcp/server.mjs`) or escaped backslashes (`C:\\Users\\you\\...`); single backslashes are invalid JSON. `command` must resolve to a `node` ≥ 20. If your bridge runs with a token (`bridge.config.json`), add `"SHAPEZ_BRIDGE_TOKEN": "<token>"` to `env`.
## License and provenance
- This project's code is **MIT** — see [`LICENSE`](LICENSE).
- Vendored [lz-string](https://github.com/pieroxy/lz-string) 1.4.5 (`src/shared/lz-string.cjs`): © 2013 Pieroxy, dual-licensed **MIT / WTFPL** — see [`src/shared/lz-string.LICENSE.txt`](src/shared/lz-string.LICENSE.txt). It compresses blueprints and mirrors the game's own savegame compression.
- This repository contains **no shapez.io game code**. All integration goes through the game's official mod API (single-file mods with `METADATA`/`Mod`, `ModInterface`, the `window.shapez` module exports). shapez.io is © [tobspr Games](https://shapez.io).
## Development
Directory layout:
| Path | What it is |
|---|---|
| `src/mod/shapez-ai-bridge.js` | In-game mod — single file, loaded by the official mod loader |
| `src/bridge/bridge.mjs` | Zero-dependency Node bridge: WS `/mod` + `/client`, HTTP `/health` `/status` `/rpc`, snapshot file management |
| `src/mcp/server.mjs` | MCP stdio server (8 tools), forwards to the bridge's HTTP API |
| `src/agent/play.mjs` | Reference agent driving the bridge over HTTP |
| `src/shared/` | Vendored lz-string + the `SZBP1` blueprint codec |
| `scripts/smoke_test.mjs` | Zero-dependency end-to-end smoke test |
| `docs/PROTOCOL.md` | The frozen protocol contract — the single source of truth |
| `compat.json` | Machine-readable compatibility matrix |
| `test/` | Layer selftests (mod RPC in a Node sandbox, lz-string interop, blueprint round-trips) |
| `recon/` | Phase-0 reverse-engineering artifacts (local research only, excluded from distribution) |
Running the layers and their selftests:
```bash
npm run selftest:bridge # bridge layer selftest
npm run selftest:mcp # MCP layer selftest
npm run smoke # end-to-end smoke test (needs game + bridge running)
npm run agent # reference agent
node test/mod_rpc_selftest.mjs # mod RPC logic, exercised in a Node sandbox
node test/lzstring_interop.mjs # lz-string byte-level interop with the game's variant
node test/blueprint_selftest.mjs # SZBP1 codec round-trips
```
**Smoke test details:** fully non-interactive by default; exit code `0` = pass, `1` = bridge not running, `2` = game not in a world, `3` = other check failed. `SHAPEZ_SMOKE_AUTOPLAY=1` additionally suppresses the notice about the temporary belt it places. Override the bridge address with `--url` / `SHAPEZ_BRIDGE_URL`; authenticate with `--token` / `SHAPEZ_BRIDGE_TOKEN`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues