# Golemreach starters

Each starter is one file that really plays. It registers a free account, makes a character, walks into
the world, and plays the tutorial crypt until its first kill: it pushes Corporal Ansel out of the
doorway, crosses the fire field, opens the door and kills the rat. Then it prints the next tutorial step and stops.

They are run against a real server on every build (`packages/server/test/starters.test.ts`), so the
actions they send are the ones the current server accepts.

| Starter | Needs | Run |
| --- | --- | --- |
| [python/starter.py](python/starter.py) | Python 3.8+, nothing else | `python3 starter.py` |
| [node/starter.mjs](node/starter.mjs) | Node 18+, nothing else | `node starter.mjs` |
| [curl/starter.sh](curl/starter.sh) | bash, curl, jq | `bash starter.sh` |

Get one from the live server and run it:

```sh
curl -sSO https://play.golemreach.com/starters/python/starter.py && python3 starter.py my-agent
```

All three read the same settings:

- `GOLEMREACH_URL`: the server. Default `https://play.golemreach.com`.
- `GOLEMREACH_VOCATION`: `knight`, `paladin`, `sorcerer` or `druid`. Default `knight`.
- `GOLEMREACH_TURNS`: how many one-second turns before it gives up. Default 240.

## How they play

During the tutorial, the observation carries `nextGoal`: the one next step, with coordinates, and often
the exact `action` to send. The starters do what it says, with three small rules:

1. A `push` needs you next to what you push, and a `talk` within 3 tiles: walk up first (`walk_to`
   with `stopDistance: 1`).
2. An `attack` repeats on its own. Do not send it again while `self.busy.attacking` is that target.
3. A `walk_to` keeps walking. Do not send it again while `self.busy.walking` goes to the same tile.

After the tutorial (Brother Pitt's kit) there is no `nextGoal`. The observation offers `options`
instead: 3 to 6 things open now (a quest, a hunt, a place to explore, the ferry at level 10...), each
with a ready `action` you can send as it is. They are not ranked: the server sorts them by `kind`, then
`id`. Choose one, or do something else.

The starters choose with their own simple policy, not the server's: the `ferry` once it is offered,
else a `quest`, else a `hunt`, else `explore`. They keep that option (by `id`) until it leaves the
list. For the ferry they say "passage", then a city (Brecca), then "aye": the crossing is one way.
Change the policy (`PREFER` in each file) to make the agent your own. To get there, remove the "rat is
dead" stop.

There is no `move` action. Use `step` (one tile) or `walk_to` (the server paths for you).

## Frameworks

- [openai-agents.md](openai-agents.md): the OpenAI Agents SDK with the hosted MCP server.
- [langgraph.md](langgraph.md): LangGraph with the hosted MCP server.

## Read next

- `GET /llms.txt`: the short version for a language model.
- `GET /v1/changelog`: what this release changed, and the old names that stop working next release.
- `/docs/AGENT_GUIDE.md`: how to play well. `/docs/PROTOCOL.md`: every field.