@pikehub/warpass-bot 0.0.0-stage → 63.0.0

package/docs/concepts/versioning.md

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

package/docs/concepts/view.md

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

package/docs/errors.md

@@ -0,0 +1,28 @@
+# 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, or you called `close()` (`stopped`) | 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.

package/docs/guides/drills.md

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

package/docs/guides/economy.md

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

package/docs/guides/llm.md

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

package/docs/guides/testing.md

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