@pikehub/warpass-bot 0.0.0-stage → 62.0.1

package/docs/llms-full.txt

@@ -0,0 +1,842 @@
+<!-- README.md -->
+
+# Warpass bot SDK
+
+Play Warpass from code. The SDK is the game engine itself (simulation, AI, map generation, replays) compiled to native code, with bindings for Node.js and Python. It plays online matches against people and other bots, local games at full CPU speed, staged custom games, and replays.
+
+- **Online:** a bot account queues, accepts, plays a real ranked match in lockstep like the browser does, and gets the server-verified result.
+- **Local:** any mix of your bot, the built-in AI (levels 1–10) and idle players, seeded and reproducible, one game or hundreds in parallel.
+- **Custom games:** stage terrain, units, buildings, tech and resources, then play it out. Custom games replay exactly.
+- **Replays:** save, load, verify against recorded hashes, and analyse per-minute combat.
+
+The SDK version is `<ENGINE_VERSION>.0.0`. Offline play works with any version; online play needs the version the server runs (see [concepts/versioning.md](concepts/versioning.md)).
+
+## Install
+
+Node 20+:
+
+```
+npm i @pikehub/warpass-bot
+```
+
+## A first bot
+
+```js
+import { Ai, Bot, Match, play, rules } from "@pikehub/warpass-bot";
+
+const r = rules();
+const race = r.races[0];
+const worker = r.units.find((u) => u.race === race && u.worker);
+const hall = r.buildings.find((b) => b.race === race && b.trains.includes(worker.id));
+
+export function think({ view, game, act }) {
+  const home = view.buildings.find((b) => b.type === hall.id);
+  if (!home) return;
+  if (game.canTrain(home, worker.id) && home.queue.length < 2) act.train(home, worker.id, 1);
+  const idle = view.units.filter((u) => u.worker && u.order === "idle");
+  const gold = game.nearestResource(home.tile, "gold", 30);
+  if (idle.length && gold) act.gather(idle, gold);
+}
+
+const result = await play(new Match({ seed: 42, maxTicks: 6000, players: [Bot({ race, think }), Ai({ race: r.races[1], level: 3 })] }));
+console.log(result.winnerSlot, result.endTick, result.stats[0].unitsProduced);
+```
+
+The same `think` plays online (code blocks marked `js online` need a server and a bot key):
+
+```js online
+import { Warpass } from "@pikehub/warpass-bot";
+
+const wp = await Warpass.connect({ token: process.env.WARPASS_BOT_TOKEN });
+const offer = await wp.queue({ race: "templars" });
+const match = await offer.accept();
+match.onThink(think, { everyTicks: 10 });
+console.log(await match.result());
+```
+
+## Next
+
+- [quickstart.md](quickstart.md): bot account, key, first local game, first online match
+- [AGENTS.md](AGENTS.md): the rules of the road for coding agents
+- [llms.txt](llms.txt): every page with a one-line summary; `llms-full.txt` is all of them in one file
+- [rules/index.md](rules/index.md): every unit, building and upgrade of the bundled engine
+
+<!-- AGENTS.md -->
+
+# AGENTS.md: writing a Warpass bot
+
+You are writing code that plays a real-time strategy game through the Warpass SDK. Read this page first, then the page for what you need from [llms.txt](llms.txt). Every fact about units, costs and ids is in [rules/index.md](rules/index.md) and `rules()`; never guess an id.
+
+## The loop
+
+A bot is one function, `think({ view, events, tick, slot, game, act })`, called every `everyTicks` ticks (default 10, minimum 2; 20 ticks = 1 second).
+
+1. Read `view` (what your player can see right now) and `events` (what happened to you since the last think).
+2. Ask `game` questions (`canTrain`, `findPlacement`, `nearestResource`, …). Queries never change the game.
+3. Give orders on `act` (`train`, `gather`, `build`, `attackMove`, …).
+4. Return. The orders are sent together and land in the next turn.
+
+## Invariants
+
+- **Orders land later.** An order given at tick `t` takes effect a couple of ticks later. The next view may not show it yet; don't re-issue the same order every think.
+- **Entities are `(eid, uid)`.** `eid` slots are reused after death; a stored reference is valid only while its `uid` matches. Pass the whole view object (`{ eid, uid }`) as an attack target.
+- **Fog.** `view` only has what your units and buildings see; `enemyBuildings` also keeps buildings you saw before (`visible: false`).
+- **Coordinates.** `x`, `y` are in 1/256 tile; `tile`, `at`, `near` are whole tiles `[tx, ty]`. Orders that move take positions (`x`, `y` in 1/256 tile).
+- **Rate limit online.** At most 20 orders per second (burst 40). Consecutive orders with the same opcode and arguments are merged into one; give one order for many units rather than one order per unit.
+- **Never block think.** Online, the game keeps running while you think. A slow think skips thinks, it doesn't pause the match. Async thinks are fine.
+- **Version.** Online play needs the SDK built for the server's engine; otherwise `connect` throws `OutdatedEngine`. Upgrade the package to the version in the error.
+- **Determinism.** Local games are exact for a given seed and deterministic bot. Use `playMany` over seeds to measure a change, not one game.
+
+## Where things are
+
+- Orders: [api/act.md](api/act.md). View fields: [api/view.md](api/view.md). Queries: [api/game.md](api/game.md). Events: [api/events.md](api/events.md).
+- Online: [api/online.md](api/online.md). Local and batch play: [api/local.md](api/local.md). Custom games: [api/custom.md](api/custom.md). Replays: [api/replay.md](api/replay.md).
+- Errors and what to do: [errors.md](errors.md).
+
+## Pitfalls
+
+- A building trains only when finished (`done: true`) and has room in its `queue` (5 entries).
+- Supply: training stops at `supply.cap`; build the race's housing building (see rules) before you hit it.
+- Workers gather from a resource tile (`nearestResource`), food comes from farms and bushes, and every worker needs a drop-off building nearby.
+- `findPlacement` returns `null` when nothing fits within the radius; try a larger radius or another spot.
+- Surrender (`act.surrender()`) ends the match as a loss at once.
+
+<!-- quickstart.md -->
+
+# Quickstart
+
+From nothing to a bot that has played a local game and an online match.
+
+## 1. Create a bot account
+
+Sign in on the site, open **Developer** in the menu and create a bot. It gets its own name (shown as `<name> (AI)` to other players), rating and match history. The key (`wpb_…`) is shown once; keep it secret and pass it to the SDK. Rotating the key kills the old one at once.
+
+## 2. Install
+
+Node.js 20 or newer:
+
+```
+npm i @pikehub/warpass-bot
+```
+
+The package carries the engine for Linux (x64 and arm64, glibc 2.17 or newer). On macOS or Windows, run your bot in a Linux container or WSL.
+
+## 3. Play locally
+
+Local games need no key and no network. They run as fast as the CPU allows.
+
+```js
+import { Ai, Bot, Match, play, rules } from "@pikehub/warpass-bot";
+
+const r = rules();
+const [mine, theirs] = r.races;
+
+function think({ view, act }) {
+  const army = view.units.filter((u) => !u.worker);
+  const seen = view.enemyBuildings[0];
+  if (army.length >= 4 && seen) act.attackMove(army, seen.x, seen.y);
+}
+
+const result = await play(new Match({ seed: 7, maxTicks: 2400, players: [Bot({ race: mine, think }), Ai({ race: theirs, level: 2 })] }));
+console.log({ winner: result.winnerSlot, ticks: result.endTick, finished: result.finished });
+```
+
+## 4. Play online
+
+```js online
+import { Warpass } from "@pikehub/warpass-bot";
+
+const wp = await Warpass.connect({ token: process.env.WARPASS_BOT_TOKEN });
+const offer = await wp.queue({ race: "templars" });
+console.log(`matched with ${offer.opponent.name} (${offer.opponent.rating})`);
+const match = await offer.accept({ everyTicks: 10 });
+match.onThink(({ view, act }) => {
+  const idle = view.units.filter((u) => !u.worker && u.order === "idle");
+  const enemy = view.enemyBuildings[0];
+  if (idle.length >= 6 && enemy) act.attackMove(idle, enemy.x, enemy.y);
+});
+const result = await match.result();
+console.log(result.outcome, result.verified, result.ratingDelta);
+```
+
+`result()` waits until the match is over and the server has replayed it (`verified: "ok"`). A bot plays under the same rules as a person: same queue, same rating, same match ledger.
+
+## Python
+
+The same API in snake_case (`pip install warpass-bot` once published):
+
+```python
+from warpass_bot import Ai, Bot, Match, play, rules
+
+r = rules()
+
+def think(t):
+    idle = [u for u in t.view.units if u.worker and u.order == "idle"]
+    home = t.view.buildings[0] if t.view.buildings else None
+    gold = t.game.nearest_resource(home.tile, "gold", 30) if home else None
+    if idle and gold:
+        t.act.gather(idle, gold)
+
+result = play(Match(seed=7, max_ticks=1200, players=[Bot(r.races[0], think), Ai(r.races[1], level=2)]))
+print(result.winner_slot, result.end_tick)
+```
+
+<!-- concepts/time.md -->
+
+# Time and turns
+
+Ticks, turns, when your think runs and when your orders land.
+
+- The game advances in **ticks**, 20 per second. Every number of time in the SDK is ticks unless it says seconds.
+- Online, the match is **lockstep**: every client runs the same simulation and the server only relays orders. A turn is 1 tick (50 ms); an order is scheduled a couple of ticks ahead so every client applies it on the same tick.
+- Your **think** runs every `everyTicks` ticks (default 10 = 0.5 s, minimum 2).
+  - Online, the game does not wait for you. If a think is still running when the next one is due, the next one is skipped; you always get the newest tick, never a backlog.
+  - Locally, the game waits for each think, so a local game is reproducible for a given seed and deterministic bot.
+- Orders from one think are sent together. They land in a later tick, so the view you get next may still show the old state.
+- `events` holds what happened to your player since your last think (see [../api/events.md](../api/events.md)).
+- A local `Match` stops at `maxTicks` if nobody has won; `result.finished` is then `false`.
+
+<!-- concepts/view.md -->
+
+# Seeing the game
+
+What a bot can know, how entities are named, and the two coordinate systems.
+
+## Fog of war
+
+The view is built from your player's vision, exactly what a person sees on screen:
+
+- `units`, `buildings`: everything you own.
+- `enemyUnits`: enemy units your units or buildings see right now.
+- `enemyBuildings`: enemy buildings you see now (`visible: true`) and the ones you have seen before (`visible: false`, last known state).
+- `neutrals`: neutral creatures in sight.
+
+There is no way to see more; the server verifies every match by replaying it.
+
+## Entity references
+
+Every entity has an `eid` (slot index) and a `uid` (unique id). Slots are reused after an entity dies, so a stored `eid` is only the same entity while its `uid` matches. Orders that target an entity take the view object itself or `{ eid, uid }`.
+
+## Coordinates
+
+- **Positions** (`x`, `y` on units and buildings, and the `x`, `y` of move orders) are in 1/256 tile.
+- **Tiles** (`tile` on units and buildings, `at`, `near`, `from`, `to` in queries and build orders) are whole tiles `[tx, ty]`; `tile = [x >> 8, y >> 8]`.
+- A building's `tile` is its top-left tile; `w`, `h` its size in tiles.
+- The map is `mapSize × mapSize` tiles (see `rules().mapSize` and `game.map()`).
+
+<!-- concepts/players.md -->
+
+# Players
+
+Who fills each slot of a match. They differ only in where orders come from.
+
+| Kind | Where its orders come from | Where |
+|---|---|---|
+| `Bot({ race, think, everyTicks })` | your `think`, from the fogged view | local, custom, and you online |
+| `Ai({ race, level })` | the built-in AI inside the simulation, levels 1–10 | local and custom |
+| `Idle({ race })` | nobody; it never gives an order | local and custom |
+| remote opponent | the server, from the other player (person or bot) | online |
+
+- Online, you never build the player list: `accept()` gives you a match where you are one slot and the opponent is whoever the queue found.
+- The built-in AI sees only its own vision, like you.
+- Bots play by the same rules as people online. Their names show as `<name> (AI)`; people can choose to avoid bots in matchmaking.
+
+<!-- concepts/versioning.md -->
+
+# Versioning
+
+Why online play needs the right SDK version, and how to upgrade.
+
+- The SDK bundles one engine version. The package version is `<ENGINE_VERSION>.0.<n>` (`ENGINE_VERSION` is exported); `n` counts SDK releases on the same engine.
+- Every engine release is breaking: unit stats, ids and rules can change, and two clients on different engines would disagree about the game.
+- **Offline** (local games, custom games, replays recorded with the same version) works with any SDK version, forever.
+- **Online**, `Warpass.connect` compares versions with the server and throws `OutdatedEngine { have, need }` on a mismatch. Install the version in `need`:
+
+```
+npm i @pikehub/warpass-bot@<need>
+```
+
+- A replay records the engine it was played on; loading it on another version fails verification with reason `engine`.
+- The rules pages under [../rules/index.md](../rules/index.md) are generated for the version you have installed.
+
+<!-- concepts/limits.md -->
+
+# Limits
+
+The few limits that apply to bots online.
+
+- **Order rate:** the server accepts 20 orders per second per player, with a burst of 40, and drops the rest (answering once with a `rate` error). The SDK paces your orders below that (18 per second, burst 32): orders above the pace wait in a queue and go out in order, a little later. Consecutive orders with the same opcode and arguments are merged, and one order can carry many units, so a busy bot rarely queues.
+- **Order size:** an order carries at most 256 values (its arguments and unit ids); the SDK stops merging before that. Split huge selections yourself.
+- **Think interval:** at least 2 ticks.
+- **One match at a time** per bot account; queueing while in a match is refused (`inMatch`).
+- **Leaving:** a bot that disconnects has a grace period to reconnect, then forfeits, exactly like a person.
+- Rating, titles and matchmaking rules are the same as for people. A very short match (under 3 minutes of play, or with too little activity) is unrated for both sides.
+
+<!-- api/online.md -->
+
+# Online
+
+Connect a bot account, queue or join a lobby by code, play a match and read the verified result.
+
+| JS | Python | Returns |
+|---|---|---|
+| `await Warpass.connect({ token, url? })` | `Warpass.connect(token=, url=)` | `Warpass` (`name`, `engineVersion` / `engine_version`) |
+| `await wp.queue({ race, avoidBots? })` | `wp.queue(race, avoid_bots=False)` | `Offer` once a rival is found |
+| `await offer.accept({ everyTicks? })` | `offer.accept(every_ticks=10)` | `OnlineMatch` once both accepted |
+| `await wp.lobby({ code, race, everyTicks? })` | `wp.lobby(code, race, every_ticks=10)` | `OnlineMatch` once the host starts: joins a player's lobby by its code, marks ready (again after the host changes the map or race) and waits |
+| `await offer.decline()` | `offer.decline()` | declines; the queue may give you a short penalty |
+| `await Warpass.join({ token, matchId, url?, everyTicks? })` | `Warpass.join(match_id, token=, url=, every_ticks=10)` | `OnlineMatch`: rejoin a match you are in after a crash |
+| `match.onThink(think, { everyTicks? })` | `match.on_think(think, every_ticks=None)` | registers your think; returns the match |
+| `await match.ended()` | `match.ended()` | `{ reason }` when the match ends |
+| `await match.result({ timeoutMs? })` | `match.result(timeout_ms=120000)` | the verified result (below) |
+| `match.game` | `match.game` | [queries](game.md) on the live game |
+| `match.id`, `match.slot` | `match.id`, `match.slot` | the match id and your slot |
+
+- `url` defaults to `DEFAULT_URL` (`https://warpass.pike.com.br`).
+- `Offer.opponent` is `{ name, bot, rating, race }`.
+- `lobby` fails with `refused` (`missing`, `full`, `started`) when the code is wrong or taken, and with `cancelled` (`closed`) when the host closes the lobby.
+- In Python, `ended()` and `result()` run your think loop on the calling thread until the match ends; an `async def` think is awaited.
+- In JS, the think loop runs in the background after `onThink`; `ended()` and `result()` wait for it.
+
+## Result
+
+```
+{ matchId, outcome, won, winnerSlot, endTick, verified, ratingDelta }
+```
+
+- `outcome`: `victory`, `defeat`, `draw`, `surrender`, `abandoned` (your side).
+- `verified`: `ok` when the server's replay of the match matched every client hash, `failed` otherwise.
+- `ratingDelta`: points won or lost, `null` when the match was unrated (too short or idle).
+
+## Reconnects
+
+The SDK reconnects by itself when the socket drops and catches up from the server's turn log; your think keeps running. If the process dies, `Warpass.join` resumes the same match while the grace period lasts.
+
+<!-- api/local.md -->
+
+# Local play
+
+Play matches on your machine: bots, the built-in AI and idle players, one at a time or many in parallel.
+
+```js
+import { Ai, Idle, Match, play, playMany, rules } from "@pikehub/warpass-bot";
+
+const [a, b] = rules().races;
+const one = await play(new Match({ seed: 3, maxTicks: 1200, players: [Ai({ race: a, level: 4 }), Idle({ race: b })] }));
+const many = await playMany([1, 2, 3].map((seed) => new Match({ seed, maxTicks: 1200, players: [Ai({ race: a, level: 3 }), Ai({ race: b, level: 3 })] })));
+console.log(one.endTick, many.map((g) => g.finalHash));
+```
+
+## Match
+
+| JS | Python | |
+|---|---|---|
+| `new Match({ seed, players, maxTicks?, mapSize? })` | `Match(seed, players, max_ticks=None, map_size=None)` | `seed` is a 32-bit integer; the same seed makes the same map |
+| `Bot({ race, think, everyTicks?, name? })` | `Bot(race, think, every_ticks=10, name="")` | your code |
+| `Ai({ race, level? })` | `Ai(race, level=5)` | built-in AI, level 1–10 |
+| `Idle({ race })` | `Idle(race)` | never acts |
+
+Slot numbers follow the order of `players`.
+
+## Playing
+
+| JS | Python | |
+|---|---|---|
+| `await play(match)` | `play(match)` | one game; thinks run in order, so it is reproducible |
+| `await playMany(matches, { concurrency? })` | `play_many(matches, workers=4)` | many games; AI-only lists run on every core inside the engine |
+
+## `GameResult`
+
+| Field | |
+|---|---|
+| `winnerSlot` / `winner_slot` | winning slot, `-1` if none |
+| `finished` | `false` when `maxTicks` stopped the game first |
+| `reason` | why it ended (`unfinished` when stopped by `maxTicks`) |
+| `endTick` / `end_tick`, `finalHash` / `final_hash` | where it stopped and the state hash there |
+| `stats` | per slot: `unitsProduced`, `unitsLost`, `unitsKilled`, `buildingsBuilt`, `buildingsLost`, `buildingsRazed`, `gathered*`, `upgradesResearched`, `peakSupply`, `commandCount` |
+| `timeline` | per slot every 10 s: resources, supply, workers, army, buildings |
+| `replay` | a [Replay](replay.md) |
+| `won(slot)` | `finished && winnerSlot === slot` |
+
+In Python, results and views are dictionaries that also read as attributes in snake_case: `result.end_tick == result["endTick"]`.
+
+<!-- api/view.md -->
+
+# View
+
+Everything a bot sees in one think: `view` (and `game.view()` / `match.game.view()`).
+
+```
+{
+  tick, slot, race,
+  resources: { food, wood, stone, gold },
+  supply: { used, cap },
+  researched: [upgradeId], researching: [upgradeId],
+  units: [Unit], buildings: [Building],
+  enemyUnits: [Unit], enemyBuildings: [Building],
+  neutrals: [Unit],
+  players: [{ slot, race, defeated }],
+  over: winnerSlot | null
+}
+```
+
+## Unit
+
+| Field | |
+|---|---|
+| `eid`, `uid` | reference (see [../concepts/view.md](../concepts/view.md)) |
+| `owner` | slot, or `-1` for neutral creatures |
+| `type` | unit id (see [../rules/index.md](../rules/index.md)) |
+| `worker` | can gather, build and repair |
+| `x`, `y` | position in 1/256 tile |
+| `tile` | `[tx, ty]` |
+| `hp`, `maxHp` | hit points |
+| `order` | `idle`, `move`, `attackMove`, `attack`, `gather`, `returnCargo`, `build`, `repair`, `hold`, `farm`, `follow`, `flee`, `guard` |
+| `moving` | walking this tick |
+| `target` | eid it is working on or attacking, `-1` if none |
+| `carrying` | resource index it carries (0 food, 1 wood, 2 stone, 3 gold), `-1` if none |
+
+## Building
+
+| Field | |
+|---|---|
+| `eid`, `uid`, `owner`, `type`, `x`, `y`, `hp`, `maxHp` | as for units |
+| `tile`, `w`, `h` | top-left tile and size in tiles |
+| `done` | construction finished |
+| `progress` | construction progress |
+| `queue` | your own buildings only: unit and upgrade ids in production, first is in progress |
+| `visible` | `false` for an enemy building you saw before and can't see now (last known state) |
+
+<!-- api/game.md -->
+
+# Game queries
+
+Questions a bot can ask during a think (`game`, or `match.game` online). Queries read the game and never change it.
+
+| JS | Python | Returns |
+|---|---|---|
+| `canAfford(id)` | `can_afford(id)` | `true` if you have the resources for a unit, building or upgrade id |
+| `cost(id)` | `cost(id)` | `{ food, wood, stone, gold }` with your current discounts, or `null` |
+| `trainRefusal(building, unit)` | `train_refusal(building, unit)` | `null` if the building can train it now, else a reason |
+| `canTrain(building, unit)` | `can_train(building, unit)` | `trainRefusal(...) === null` |
+| `researchRefusal(building, upgrade)` | `research_refusal(building, upgrade)` | `null` or a reason |
+| `canResearch(building, upgrade)` | `can_research(building, upgrade)` | |
+| `placeRefusal(building, at)` | `place_refusal(building, at)` | `null` if a building id fits with its top-left at tile `at`, else a reason |
+| `canPlace(building, at)` | `can_place(building, at)` | |
+| `findPlacement(building, near, radius = 16)` | `find_placement(building, near, radius=16)` | `[tx, ty]` where it fits closest to `near`, or `null` |
+| `nearestResource(from, resource, radius = 40)` | `nearest_resource(start, resource, radius=40)` | `[tx, ty]` of the nearest tile with `food`, `wood`, `stone` or `gold` left |
+| `reachable(from, to)` | `reachable(start, end)` | `true` if your units can walk between the two tiles |
+| `front(toward?)` | `front(toward=None)` | `[tx, ty]`: the tile where your army should gather to face tile `toward` (default: the map centre), usually a choke near your base |
+| `tile(at)` | `tile(at)` | `{ tile, x, y, terrain, height, passable, buildable, resource, amount }` |
+| `map()` | `map()` | `{ width, height, starts, chokes, sites }` (tiles); each site is `{ id, kind, tile, size, centre, owner }`: `kind` `passive` (claim by standing near it) or `active` (build the site's building, same id, on it), `tile` its top-left, `owner` a slot or -1 |
+| `view()` | `view()` | the current [view](view.md) |
+
+- `building` arguments take a view object or an eid; `unit`, `upgrade` and building ids are strings from the rules.
+- Tile arguments take `[tx, ty]` or an object with `x`, `y` in tiles.
+- Training and research refusals: `notEnough` (resources), `supplyLimit`, `needHousing`, `queueFull`, `requirementsNotMet`, `limitReached`, `invalid` (wrong building, not finished, not yours).
+- Placement refusals: `outOfBounds`, `somethingInWay`, `cannotBuildThere`, `unevenGround`, `rampBlocked`, `buildOnSite` / `siteGround` (site buildings must stand on their site), `alreadyBuilt`, `limitReached`, `requirementsNotMet`, `unknownBuilding`.
+
+<!-- api/act.md -->
+
+# Orders
+
+Every order a bot can give, on `act` during a think (and on the builder passed to `CustomGame.order`).
+
+`who` is a unit view, an eid, or a list of them. Positions `x`, `y` are in 1/256 tile; `at`, `tile`, `from`, `to` are tiles `[tx, ty]`. Every order returns `act`, so orders chain. `queued: true` adds the order after the units' current ones instead of replacing them.
+
+| JS | Python | |
+|---|---|---|
+| `move(who, x, y, { queued })` | `move(who, x, y, queued=False)` | walk there, ignoring enemies |
+| `attackMove(who, x, y, { queued })` | `attack_move(who, x, y, queued=False)` | walk there, fighting what they meet |
+| `formMove(who, x, y, { face, queued, attack })` | `form_move(who, x, y, face=(0, 256), queued=False, attack=False)` | move as a formation facing the direction `face` |
+| `formUp(who)` | `form_up(who)` | gather into formation where they stand |
+| `attack(who, target, { queued })` | `attack(who, target, queued=False)` | attack one entity (`target` = a view object or `{ eid, uid }`) |
+| `target(who, target, { queued })` | `target(who, target, queued=False)` | the right-click order: attack an enemy, gather a resource, repair your building |
+| `repair(who, target, { queued })` | `repair(who, target, queued=False)` | workers repair one of your buildings |
+| `gather(who, tile, { queued })` | `gather(who, tile, queued=False)` | workers gather the resource on a tile (from `nearestResource`) |
+| `build(who, building, at, { queued })` | `build(who, building, at, queued=False)` | workers place and build a building with its top-left at `at`; pays on placement |
+| `buildLine(who, building, from, to, { queued })` | `build_line(who, building, start, end, queued=False)` | a line of wall segments |
+| `train(building, unit, count = 1)` | `train(building, unit, count=1)` | queue units (pays now) |
+| `research(building, upgrade)` | `research(building, upgrade)` | queue an upgrade (pays now) |
+| `cancel(building, index)` | `cancel(building, index)` | cancel queue entry `index` (0 = in progress) and get the cost back |
+| `rally(buildings, x, y)` | `rally(buildings, x, y)` | where new units from those buildings walk |
+| `stop(who)` | `stop(who)` | drop all orders |
+| `hold(who)` | `hold(who)` | stand still and fight only what comes in range |
+| `remove(who)` | `remove(who)` | delete your own units or buildings |
+| `spawnToggle(buildings, on)` | `spawn_toggle(buildings, on)` | pause or resume buildings that produce units by themselves |
+| `surrender()` | `surrender()` | concede the match |
+
+- Orders that the game refuses (not enough resources, wrong building, dead unit) are ignored when they land; check with [queries](game.md) first.
+- Low level: `act.push(name, args)` takes the order name and an argument object (`{ units, x, y, queued, … }`); the methods above call it.
+
+<!-- api/events.md -->
+
+# Events
+
+What happened to your player since the last think, in `events` (oldest first). Each event is an object with a type tag `t` and its own fields; ids are numbers that index the rules (unit, building and upgrade lists in `rules()` order).
+
+| `t` | When |
+|---|---|
+| `trained` | one of your units finished training |
+| `researched` | an upgrade finished |
+| `built` | a building finished |
+| `placed` | a foundation was placed |
+| `death` | an entity died (`owner`, `killer` slot, `kind`, position): yours, one you killed, or one where you have vision |
+| `hit` | an entity took damage (`eid` attacker, `tgt` target, position): yours dealt or took it, or it happened where you have vision |
+| `defeated` | a player was defeated |
+| `over` | the match ended (`winnerSlot`) |
+| `deplete` | a resource tile ran out |
+| `deposit` | a worker dropped off resources |
+| `site` | a site (an objective on the map) changed hands |
+| `weather`, `forecast` | weather started or is coming |
+| `msg` | a game message for the player (`key`, `params`) |
+| `glimpse`, `armyPing` | an enemy was spotted |
+
+Other tags (`shoot`, `impact`, `beam`, `charge`, `whiff`, `snared`, `heal`, `fire`, `fireOut`, `meteor`, `meteorWarn`, `lightning`, `lightningWarn`, `regrow`, `reseed`, `spawned`, `trap`) describe visual effects and rarer happenings.
+
+## Fog of war
+
+You get exactly the events a person playing your slot gets. Every event falls in one of four groups:
+
+| Group | Tags | You get it |
+|---|---|---|
+| public | `defeated`, `over`, `site`, `weather`, `forecast`, `meteor`, `meteorWarn`, `lightning`, `lightningWarn`, `fire`, `fireOut`, `msg` without an owner (site and weather news) | always |
+| private | `trained`, `researched`, `built`, `placed`, `deposit`, `reseed`, `glimpse`, `armyPing`, `aiOpportunity`, `aiRaid`, `aiRetreat`, `msg` with an owner | only your own |
+| seen | `hit`, `death`, `shoot`, `impact`, `beam`, `charge`, `whiff`, `snared`, `heal`, `spawned`, `trap`, `deplete`, `regrow` | when it involves you (your slot is its `owner` or `killer`, or its `eid` or `tgt` is your entity) or its position is in your current vision (a `beam` counts if either end is) |
+| hidden | `aiWave`, `aiCounter` | never |
+
+<!-- api/custom.md -->
+
+# Custom games
+
+Stage a situation, then play it out step by step. Custom games are local only and replay exactly: the setup is recorded with the match.
+
+```js
+import { CustomGame, rules } from "@pikehub/warpass-bot";
+
+const r = rules();
+const [a, b] = r.races;
+const g = new CustomGame({ seed: 11, races: [a, b] });
+const [x0, y0] = g.flattenArea(30, 16);
+const soldier = r.units.find((u) => u.race === a && !u.worker && u.attack);
+const target = r.buildings.filter((x) => x.race === b && !x.site).sort((p, q) => p.hp - q.hp)[0];
+const hall = g.building(1, target.id, x0 + 20, y0 + 6);
+g.reveal(0, hall);
+const army = [0, 1, 2, 3].map((k) => g.spawn(0, soldier.id, (x0 + 3) * 256, (y0 + 4 + k) * 256));
+const ref = g.observer().enemyBuildings.find((x) => x.eid === hall) ?? g.observer().buildings.find((x) => x.eid === hall);
+g.order(0, (act) => act.attack(army, ref));
+const ticks = g.until(20 * 120, (obs) => !obs.buildings.concat(obs.enemyBuildings).some((x) => x.eid === hall && x.uid === ref.uid));
+console.log(ticks > 0 ? `razed in ${ticks / 20} s` : "still standing");
+console.log(g.replay().verify().ok);
+```
+
+## Creating
+
+`new CustomGame({ seed, races?, mapType?, aiLevel? })` / `CustomGame(seed=1, races=(), map_type=None, ai_level=0)`. Two players; slot 1 is the built-in AI when `aiLevel > 0`, otherwise idle. The map is a standard map of `mapType` (default `riverVale`).
+
+## Setup ops (before the first step)
+
+| JS | Python | Returns |
+|---|---|---|
+| `flattenArea(w, h)` | `flatten_area(w, h)` | `[tx, ty]`: an empty flat grass rectangle away from bases |
+| `spawn(owner, unit, x, y)` | `spawn(owner, unit, x, y)` | eid of a new unit at position `x`, `y` (1/256 tile) |
+| `building(owner, building, tx, ty)` | `building(owner, building, tx, ty)` | eid of a finished building at tile `tx`, `ty` |
+| `terrain(tx, ty, terrain)` | `terrain(tx, ty, terrain)` | set one tile (`terrain` = name or id from `rules().terrains`) |
+| `research(owner, upgrade)` | `research(owner, upgrade)` | complete an upgrade |
+| `resources(owner, { food, wood, stone, gold })` | `resources(owner, food=0, wood=0, stone=0, gold=0)` | set a bank |
+| `weather(key, duration, ramp?)` | `weather(key, duration, ramp=0)` | force weather for `duration` ticks |
+| `reveal(owner, eid = -1)` | `reveal(owner, eid=-1)` | make `owner` know an entity (`-1`: every building) |
+| `remove(eid)` | `remove(eid)` | remove an entity |
+| `setup(op)` | `setup(op)` | any op as data, e.g. `{ op: "spawn", owner, unit, x, y }` |
+
+Ops after the first step still apply but make the game unreplayable.
+
+## Playing
+
+| JS | Python | |
+|---|---|---|
+| `order(slot, (act) => …)` | `order(slot, lambda act: …)` | give [orders](act.md) for any slot |
+| `step(n = 1)` | `step(n=1)` | advance `n` ticks; returns the tick |
+| `until(maxTicks, (observer, tick) => done)` | `until(max_ticks, lambda observer, tick: done)` | step until `done`; returns ticks taken or `-1` |
+| `view(slot)` | `view(slot)` | the fogged [view](view.md) of a slot |
+| `observer()` | `observer()` | the full view of everything, no fog |
+| `game(slot)` | `game(slot)` | [queries](game.md) as that slot |
+| `map()` | `map()` | map size, starts, chokes, sites |
+| `replay()` | `replay()` | a [Replay](replay.md) of setup and orders so far |
+| `tick`, `winner` | `tick`, `winner` | current tick; winning slot once over |
+
+<!-- api/replay.md -->
+
+# Replays
+
+A replay is the seed, the setup, every order and the state hashes. Replaying it gives the same game, tick for tick.
+
+| JS | Python | |
+|---|---|---|
+| `result.replay` / `customGame.replay()` | same | a `Replay` |
+| `replay.save(path)` | `replay.save(path)` | write JSON |
+| `Replay.load(pathOrText)` | `Replay.load(path_or_text)` | read JSON |
+| `replay.verify()` | `replay.verify()` | replay it and compare hashes |
+| `replay.analyse()` | `replay.analyse()` | the combat analysis from `verify()` |
+| `replay.data` | `replay.data` | `{ engineVersion, config, commands, hashes, endTick }` |
+
+`verify()` returns `{ ok, reason, tick, stats, timeline, events, analysis }`:
+
+- `ok`: every recorded hash matched; `reason` is `mismatch` (with the first bad `tick`) or `engine` (recorded on another engine version).
+- `analysis.minutes`: per slot and minute, kills, losses, buildings razed and lost, units trained, damage dealt and taken.
+- `analysis.units`: per unit and building type, trained, lost, kills, damage dealt and taken.
+- `analysis.army`: army composition per minute.
+
+```js
+import { Ai, Match, Replay, play, rules } from "@pikehub/warpass-bot";
+
+const [a, b] = rules().races;
+const game = await play(new Match({ seed: 9, maxTicks: 1200, players: [Ai({ race: a, level: 3 }), Ai({ race: b, level: 3 })] }));
+const again = Replay.load(JSON.stringify(game.replay.data));
+console.log(again.verify().ok, again.analyse().minutes.length);
+```
+
+<!-- api/rules.md -->
+
+# Rules and docs
+
+Static facts about the bundled engine, and these docs, from code.
+
+| JS | Python | |
+|---|---|---|
+| `rules(race?)` | `rules(race=None)` | every unit, building and upgrade (or one race's) |
+| `docs(page?)` | `docs(page=None)` | a docs page as Markdown; no argument: `llms-full.txt`, every page in one text |
+| `docsIndex()` | `docs_index()` | every page path |
+| `ENGINE_VERSION` | `ENGINE_VERSION` | the engine this SDK runs |
+| `TILE`, `TICKS_PER_SECOND` | same | 256 and 20 |
+| `DEFAULT_URL` | same | the public server |
+| `WarpassError` | `WarpassError` | see [../errors.md](../errors.md) |
+| `Orders` | `Orders` | the order builder behind `act` |
+
+`rules()` returns:
+
+```
+{ engineVersion, races, resources, terrains: { name: id }, tile, ticksPerSecond, mapSize,
+  units: [{ id, race, cost, supply, hp, speed, sight, trainTicks, trainedAt, requires, abilities, worker, lane, armor: { melee, pierce }, attack }],
+  buildings: [{ id, race, size, cost, hp, buildTicks, supply, trains, researches, requires, site }],
+  upgrades: [{ id, race, cost, ticks, requires, group }] }
+```
+
+`requires` is `{ buildings, anyBuildings, upgrades, anyUpgrades }` (ids). `attack` is `{ damage, range, minRange, cooldown, splash, onlyBuildings }` or `null`. Units of measure are in [../rules/index.md](../rules/index.md); the same data as tables is under `rules/`.
+
+```js
+import { docs, docsIndex } from "@pikehub/warpass-bot";
+
+console.log(docsIndex().length, docs("AGENTS.md").split("\n")[0]);
+```
+
+<!-- guides/economy.md -->
+
+# An economy bot
+
+A bot that keeps workers busy, builds housing before it is needed and trains from every production building. Uses only rules data, so it works for every race.
+
+```js
+import { Ai, Bot, Match, play, rules } from "@pikehub/warpass-bot";
+
+const r = rules();
+const race = r.races[0];
+const worker = r.units.find((u) => u.race === race && u.worker);
+const hall = r.buildings.find((b) => b.race === race && b.trains.includes(worker.id));
+const house = r.buildings.filter((b) => b.race === race && b.supply > 0 && b.id !== hall.id && !b.site).sort((a, b) => a.cost.wood - b.cost.wood)[0];
+
+function think({ view, game, act }) {
+  const home = view.buildings.find((b) => b.type === hall.id && b.done);
+  if (!home) return;
+  const workers = view.units.filter((u) => u.worker);
+  const idle = workers.filter((u) => u.order === "idle");
+  if (workers.length < 20 && home.queue.length < 2 && game.canTrain(home, worker.id)) act.train(home, worker.id, 1);
+  const building = view.buildings.some((b) => b.type === house.id && !b.done);
+  if (house && !building && view.supply.cap - view.supply.used <= 3 && game.canAfford(house.id) && workers.length) {
+    const spot = game.findPlacement(house.id, home.tile, 12);
+    if (spot) act.build(workers[0], house.id, spot);
+  }
+  for (const [i, kind] of ["food", "wood", "gold"].entries()) {
+    const crew = idle.filter((_, k) => k % 3 === i);
+    const tile = game.nearestResource(home.tile, kind, 30);
+    if (crew.length && tile) act.gather(crew, tile);
+  }
+}
+
+const g = await play(new Match({ seed: 5, maxTicks: 6000, players: [Bot({ race, think }), Ai({ race: r.races[1], level: 1 })] }));
+console.log(g.stats[0].unitsProduced, g.stats[0].buildingsBuilt);
+```
+
+Ideas to grow it: send a fixed share of workers to wood, add military buildings from `rules().buildings` whose `trains` contains combat units, research upgrades from `home.researches`, and attack with `attackMove` once the army is large.
+
+<!-- guides/testing.md -->
+
+# Testing a bot
+
+One game says little; measure over seeds. Local games are exact, so the same bot and seed always give the same game, and a change in the bot shows up as a change in results.
+
+```js
+import { Ai, Bot, Match, playMany, rules } from "@pikehub/warpass-bot";
+
+const [mine, theirs] = rules().races;
+const passive = () => {};
+const seeds = [1, 2, 3, 4];
+const games = await playMany(
+  seeds.map((seed) => new Match({ seed, maxTicks: 1200, players: [Bot({ race: mine, think: passive }), Ai({ race: theirs, level: 2 })] })),
+  { concurrency: 4 },
+);
+const wins = games.filter((g) => g.won(0)).length;
+console.log(`${wins}/${games.length} wins, ${games.filter((g) => !g.finished).length} unfinished`);
+```
+
+- Compare two versions of a bot on the same seeds; a difference is the change, not luck.
+- Climb the AI levels: when a bot wins most games at one level, try the next.
+- Keep the replays of losses (`g.replay.save(...)`) and read `analyse()` to see where fights went wrong.
+- AI-only match lists run on every core inside the engine; matches with your bot run your think in this process, `concurrency` at a time.
+
+<!-- guides/drills.md -->
+
+# Drills with custom games
+
+Measure one thing in isolation: how fast a group razes a building, who wins a fight at equal cost, how long a march takes. A custom game stages it in a flat arena and replays exactly.
+
+```js
+import { CustomGame, rules } from "@pikehub/warpass-bot";
+
+const r = rules();
+const [a, b] = r.races;
+const fighter = (race) => r.units.filter((u) => u.race === race && !u.worker && u.attack && u.attack.range < 256)[0];
+
+function duel(seed, n) {
+  const g = new CustomGame({ seed, races: [a, b] });
+  const [x0, y0] = g.flattenArea(24, 12);
+  const left = Array.from({ length: n }, (_, k) => g.spawn(0, fighter(a).id, (x0 + 4) * 256, (y0 + 2 + k) * 256));
+  const right = Array.from({ length: n }, (_, k) => g.spawn(1, fighter(b).id, (x0 + 18) * 256, (y0 + 2 + k) * 256));
+  g.order(0, (act) => act.attackMove(left, (x0 + 18) * 256, (y0 + 6) * 256));
+  g.order(1, (act) => act.attackMove(right, (x0 + 4) * 256, (y0 + 6) * 256));
+  const alive = (obs, owner) => obs.units.concat(obs.enemyUnits).filter((u) => u.owner === owner && !u.worker && u.hp > 0).length;
+  g.until(20 * 60, (obs) => alive(obs, 0) === 0 || alive(obs, 1) === 0);
+  const end = g.observer();
+  return [alive(end, 0), alive(end, 1)];
+}
+
+console.log([1, 2, 3].map((seed) => duel(seed, 5)));
+```
+
+`observer()` shows everything (no fog), which is what a drill needs to judge the outcome; the units themselves still only act on the orders you give.
+
+<!-- guides/llm.md -->
+
+# LLM strategists
+
+Language models are slow next to a game running at 20 ticks per second. The pattern that works: a fast scripted bot that executes a plan every think, and a slow planner that rewrites the plan every few seconds, never blocking the think.
+
+```js online
+import { Warpass } from "@pikehub/warpass-bot";
+
+let plan = { focus: "economy", attackAt: null };
+let planning = false;
+
+async function replan(view) {
+  planning = true;
+  try {
+    const summary = { tick: view.tick, resources: view.resources, supply: view.supply, army: view.units.filter((u) => !u.worker).length, seen: view.enemyBuildings.length };
+    plan = await askModel(summary);
+  } finally {
+    planning = false;
+  }
+}
+
+const wp = await Warpass.connect({ token: process.env.WARPASS_BOT_TOKEN });
+const match = await (await wp.queue({ race: "templars" })).accept();
+match.onThink(({ view, game, act }) => {
+  if (!planning && view.tick % 200 === 0) replan(view);
+  runPlan(plan, view, game, act);
+});
+console.log(await match.result());
+```
+
+- `askModel` sends a compact summary (counts, not every unit) and parses a small JSON plan; `runPlan` is ordinary code that turns the plan into orders.
+- Don't `await` the model inside `think`: online, a think that takes seconds makes your bot skip seconds of play.
+- Put [AGENTS.md](../AGENTS.md) and [rules/index.md](../rules/index.md) in the model's context; `docs()` returns every page as one text.
+- Test the planner offline with `play` before going online; replace `askModel` with a stub that returns fixed plans to keep games reproducible.
+
+<!-- errors.md -->
+
+# Errors
+
+Every SDK call that fails throws a `WarpassError` with a `kind` and the fields below. In JS, `err.kind`; in Python, `err.kind` and `err.info`.
+
+| `kind` | Fields | Meaning | What to do |
+|---|---|---|---|
+| `outdatedEngine` | `have`, `need` | the server runs another engine | install the SDK version `need` |
+| `unauthenticated` | | the key is wrong, rotated, or the bot was deleted | create or rotate the key on the Developer page |
+| `refused` | `about`, `reason`, `message` | the server refused a request | see reasons below |
+| `cancelled` | `reason` | the offer fell through (`declined`, `timeout`, the rival left) or the host closed the lobby (`closed`) | queue again |
+| `closed` | `reason` | the socket closed and could not reconnect | connect again; `Warpass.join` resumes a running match |
+| `timeout` | | no answer in time (`result` waits 120 s by default) | retry `result()`; the match may still be sealing |
+| `network` | `message` | DNS, TLS or HTTP failure | check `url` and connectivity |
+
+Reasons for `refused`:
+
+| `reason` | |
+|---|---|
+| `version` | the queue or lobby is for another engine (thrown as `outdatedEngine`) |
+| `inMatch` | this bot is already in a match; finish it or `Warpass.join` it |
+| `penalty` | declined or left recently; wait the time in `message` |
+| `invalid` | a malformed request (unknown race, bad arguments) |
+| `missing` | `lobby` with a code that doesn't exist (or expired) |
+| `full` | `lobby` when another player already took the guest seat |
+| `started` | `lobby` when that lobby's battle already started |
+| `matchNotFound` | `join` with a match id that doesn't exist or isn't yours |
+
+Errors from local games and custom games (unknown ids, setup ops off the map) are thrown with `kind: "error"` and a message naming the problem.
+
+<!-- rules/index.md -->
+
+# Rules for engine 62
+
+Generated from the engine this SDK bundles. Every id below is what the view, the queries and the orders use.
+
+- Ticks per second: 20
+- One tile is 256 position units; positions (`x`, `y`) are in 1/256 tile, tiles (`tile`, `at`) in whole tiles
+- Map size: 256 × 256 tiles
+- Resources: food, wood, stone, gold
+- Races: [templars](templars.md), [orcs](orcs.md), [witches](witches.md)
+
+## Terrain ids
+
+| id | terrain |
+|---|---|
+| 0 | deep |
+| 1 | shallow |
+| 2 | river |
+| 3 | sand |
+| 4 | grass |
+| 5 | dirt |
+| 6 | road |
+| 7 | forest |
+| 8 | thicket |
+| 9 | rock |
+| 10 | gold |
+| 11 | stone |
+| 12 | berries |
+| 13 | marsh |
+| 14 | bridge |
+| 15 | burnt |
+| 16 | stumps |
+| 17 | spentVein |
+| 18 | pickedBush |
+| 19 | orchard |
+| 20 | grainField |
+| 21 | mushrooms |
+| 22 | stubble |
+
+## Units of measure
+
+- `hp`, `damage`, `armor`: hit points
+- `speed`: 1/256 tile per tick (tiles per second = speed × 20 / 256)
+- `range`, `minRange`: 1/256 tile
+- `sight`: tiles
+- `cooldown`, `trainTicks`, `buildTicks`, `ticks`: ticks
+