@pikehub/warpass-bot 0.0.0-stage → 63.0.0

package/AGENTS.md

@@ -0,0 +1,37 @@
+# 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.

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changes in 63.0.0
+
+Compared with engine 62.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pikehub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# Warpass bot SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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

package/docs/AGENTS.md

@@ -0,0 +1,37 @@
+# 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.

package/docs/README.md

@@ -0,0 +1,60 @@
+# 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

package/docs/api/act.md

@@ -0,0 +1,30 @@
+# 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` (the footprint must be in view); 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.

package/docs/api/custom.md

@@ -0,0 +1,81 @@
+# 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 |
+| `events(slot)` | `events(slot)` | the [events](events.md) that slot got since the last call, fog-filtered exactly as in a match |
+| `observerEvents()` | `observer_events()` | every event since the last call, unfiltered |
+| `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 |
+
+The first `events` call for a slot (or `observerEvents`) starts recording for it and returns `[]`, so call it once before stepping. After that, each call returns what that player would have received in its `think` during a [local match](local.md):
+
+```js
+import { CustomGame, rules } from "@pikehub/warpass-bot";
+
+const r = rules();
+const [a, b] = r.races;
+const g = new CustomGame({ seed: 5, races: [a, b] });
+const [x0, y0] = g.flattenArea(24, 12);
+const fighter = (race) => r.units.find((u) => u.race === race && !u.worker && u.attack);
+const ours = [0, 1, 2].map((k) => g.spawn(0, fighter(a).id, (x0 + 4) * 256, (y0 + 3 + k) * 256));
+[0, 1, 2].forEach((k) => g.spawn(1, fighter(b).id, (x0 + 10) * 256, (y0 + 3 + k) * 256));
+g.events(0);
+g.events(1);
+g.order(0, (act) => act.attackMove(ours, (x0 + 12) * 256, (y0 + 4) * 256));
+g.step(20 * 30);
+const mine = g.events(0);
+const theirs = g.events(1);
+console.log(`slot 0: ${mine.filter((e) => e.t === "hit").length} hits, ${mine.filter((e) => e.t === "death").length} deaths`);
+console.log(`slot 1: ${theirs.filter((e) => e.t === "hit").length} hits`);
+```

package/docs/api/events.md

@@ -0,0 +1,36 @@
+# 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).
+
+In a [custom game](custom.md), `events(slot)` returns the same events for any slot.
+
+| `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 |
+

package/docs/api/game.md

@@ -0,0 +1,26 @@
+# 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` and is in view now, 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`, `notVisible` (every footprint tile must be in your current vision; send a unit to look first), `somethingInWay`, `cannotBuildThere`, `unevenGround`, `rampBlocked`, `buildOnSite` / `siteGround` (site buildings must stand on their site), `alreadyBuilt`, `limitReached`, `requirementsNotMet`, `unknownBuilding`.

package/docs/api/local.md

@@ -0,0 +1,45 @@
+# 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"]`.

package/docs/api/online.md

@@ -0,0 +1,39 @@
+# 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 |
+| `wp.close()` | `wp.close()` | leaves the queue or lobby and closes the socket; a pending `connect`, `queue`, `accept` or `lobby` fails with `closed` (`stopped`). Call it before exiting on Ctrl-C |
+| `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, Ctrl-C during `connect`, `queue`, `accept` or `lobby` closes the session and raises `KeyboardInterrupt`.
+- 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.

package/docs/api/replay.md

@@ -0,0 +1,28 @@
+# 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);
+```

package/docs/api/rules.md

@@ -0,0 +1,31 @@
+# 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]);
+```

package/docs/api/view.md

@@ -0,0 +1,44 @@
+# 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) |

package/docs/concepts/limits.md

@@ -0,0 +1,10 @@
+# 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.

package/docs/concepts/players.md

@@ -0,0 +1,14 @@
+# 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.

package/docs/concepts/time.md

@@ -0,0 +1,12 @@
+# 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`.