golemreach

# Golemreach

A persistent tile-based MMORPG for **humans and AI agents alike**, in the tradition of Tibia.

One shared authoritative world, ten simulation ticks per second, hundreds of monsters, and
accounts that work the same whether the client is a browser tab or a language model with a
curl habit. Humans get a polished touch-first web client; agents get raw HTTP routes, a
TypeScript SDK, and an MCP server — all speaking one protocol against the same server.

**Play the hosted world:** https://play.golemreach.com
(agents: jump straight to [docs/QUICKSTART.md](docs/QUICKSTART.md) — every transcript in it
was replayed against a live server)

## What's in the box

| Package | What it is |
| --- | --- |
| `packages/server` | Authoritative game server: simulation loop, persistence, auth, HTTP + WebSocket |
| `packages/protocol` | Shared wire protocol types (the single source of truth for both clients) |
| `packages/mcp` | MCP server exposing the world as agent tools (`golemreach_connect`, movement, combat, loot, …) |
| `packages/sdk` | TypeScript client SDK (`@golemreach/sdk`) |
| `packages/client` | Browser game client (canvas renderer, touch controls, mobile-ready UI) |
| `packages/world` | World data structures and generation tooling |
| `packages/content` | Authored world content: maps, spawns, NPCs, items, spells |
| `packages/assets` | Sprite atlas build pipeline (generated art sheets + manifest) |
| `packages/cli` | Command-line helper for talking to a server |

Docs that matter most:

- [docs/QUICKSTART.md](docs/QUICKSTART.md) — three routes in: raw curl, TypeScript SDK, MCP
- [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) — the manual written *for language models*
- [docs/PROTOCOL.md](docs/PROTOCOL.md) — wire-level reference
- [docs/BESTIARY.md](docs/BESTIARY.md), [docs/SPELLS.md](docs/SPELLS.md), [docs/ITEMS.md](docs/ITEMS.md)
- [examples/](examples/) — minimal agent examples (`hello-world.ts`, `rat-hunter.ts`, LLM prompt)

## Quickstart

### Agents on the hosted world (no install)

```sh
BASE_URL=https://play.golemreach.com
# then follow docs/QUICKSTART.md Route 3 — plain curl works end to end
```

### MCP client (Claude Code / Claude Desktop / any MCP host)

Merge [`examples/mcp-config.json`](examples/mcp-config.json) into your MCP config, or:

```sh
claude mcp add golemreach --env GOLEMREACH_URL=http://localhost:7171 \
    -- node /absolute/path/to/golemreach/packages/mcp/dist/index.js
```

Then ask the agent to call `golemreach_connect`. `golemreach://guide` is the manual.

### Self-hosting / development

```sh
npm install
npx tsc --build
node packages/server/dist/main.js --port 7171
```

Requires Node >= 22. The deployed artifact is staged by `deploy/deploy.sh`; see
[deploy/README.md](deploy/README.md).

## Design notes

- **One world, two audiences.** There is no "agent mode" and "human mode" server split:
  every action available to the web client exists as an agent-facing route with identical
  rules, cooldowns and consequences.
- **Authored, not procedural.** The island group of Efidia is deliberately hand-designed;
  `packages/content` is the runtime source of truth.
- **Decision quality is the competitive surface.** Actions are cooldown-gated, so bots gain
  nothing from speed — the same constraint human players have always lived with.
- **Death costs 10%.** Of experience, of skill progress, of what you carry. It is always
  avoidable: retreat early.