@pikehub/warpass-bot 62.0.1 → 63.0.0

package/CHANGELOG.md

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

package/docs/api/act.md

@@ -14,7 +14,7 @@ Every order a bot can give, on `act` during a think (and on the builder passed t
 | `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 |
+| `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) |

package/docs/api/custom.md

@@ -51,7 +51,31 @@ Ops after the first step still apply but make the game unreplayable.
 | `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

@@ -2,6 +2,8 @@
 
 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 |

package/docs/api/game.md

@@ -12,7 +12,7 @@ Questions a bot can ask during a think (`game`, or `match.game` online). Queries
 | `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` |
+| `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 |
@@ -23,4 +23,4 @@ Questions a bot can ask during a think (`game`, or `match.game` online). Queries
 - `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`.
+- 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/online.md

@@ -9,6 +9,7 @@ Connect a bot account, queue or join a lobby by code, play a match and read the
 | `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 |
@@ -19,6 +20,7 @@ Connect a bot account, queue or join a lobby by code, play a match and read the
 - `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.
 

package/docs/errors.md

@@ -8,7 +8,7 @@ Every SDK call that fails throws a `WarpassError` with a `kind` and the fields b
 | `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 |
+| `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 |
 

package/docs/llms-full.txt

@@ -285,6 +285,7 @@ Connect a bot account, queue or join a lobby by code, play a match and read the
 | `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 |
@@ -295,6 +296,7 @@ Connect a bot account, queue or join a lobby by code, play a match and read the
 - `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.
 
@@ -423,7 +425,7 @@ Questions a bot can ask during a think (`game`, or `match.game` online). Queries
 | `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` |
+| `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 |
@@ -434,7 +436,7 @@ Questions a bot can ask during a think (`game`, or `match.game` online). Queries
 - `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`.
+- 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`.
 
 <!-- api/act.md -->
 
@@ -454,7 +456,7 @@ Every order a bot can give, on `act` during a think (and on the builder passed t
 | `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 |
+| `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) |
@@ -475,6 +477,8 @@ Every order a bot can give, on `act` during a think (and on the builder passed t
 
 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 |
@@ -560,11 +564,35 @@ Ops after the first step still apply but make the game unreplayable.
 | `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`);
+```
+
 <!-- api/replay.md -->
 
 # Replays
@@ -773,7 +801,7 @@ Every SDK call that fails throws a `WarpassError` with a `kind` and the fields b
 | `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 |
+| `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 |
 
@@ -794,7 +822,7 @@ Errors from local games and custom games (unknown ids, setup ops off the map) ar
 
 <!-- rules/index.md -->
 
-# Rules for engine 62
+# Rules for engine 63
 
 Generated from the engine this SDK bundles. Every id below is what the view, the queries and the orders use.
 

package/docs/rules/index.md

@@ -1,4 +1,4 @@
-# Rules for engine 62
+# Rules for engine 63
 
 Generated from the engine this SDK bundles. Every id below is what the view, the queries and the orders use.
 

package/docs/rules/orcs.md

@@ -1,4 +1,4 @@
-# orcs (engine 62)
+# orcs (engine 63)
 
 Generated from the bundled engine. Units of measure are in [index.md](index.md).
 

package/docs/rules/templars.md

@@ -1,4 +1,4 @@
-# templars (engine 62)
+# templars (engine 63)
 
 Generated from the bundled engine. Units of measure are in [index.md](index.md).
 

package/docs/rules/witches.md

@@ -1,4 +1,4 @@
-# witches (engine 62)
+# witches (engine 63)
 
 Generated from the bundled engine. Units of measure are in [index.md](index.md).
 

package/docs/rules.json

@@ -1,5 +1,5 @@
 {
-  "engineVersion": 62,
+  "engineVersion": 63,
   "races": [
     "templars",
     "orcs",

package/index.js

@@ -220,6 +220,10 @@ export class Warpass {
     return new OnlineMatch(this.session, info);
   }
 
+  close() {
+    this.session.close();
+  }
+
   static async join({ token, url = DEFAULT_URL, matchId, everyTicks = 10 } = {}) {
     const session = new native.OnlineSession();
     const info = parse(await guard(session.join(url, token, matchId, everyTicks)));
@@ -453,6 +457,14 @@ export class CustomGame {
     return this.native.view(null);
   }
 
+  events(slot) {
+    return this.native.events(slot);
+  }
+
+  observerEvents() {
+    return this.native.events(null);
+  }
+
   map() {
     return this.native.query(0, "map", {});
   }

package/llms-full.txt

@@ -285,6 +285,7 @@ Connect a bot account, queue or join a lobby by code, play a match and read the
 | `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 |
@@ -295,6 +296,7 @@ Connect a bot account, queue or join a lobby by code, play a match and read the
 - `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.
 
@@ -423,7 +425,7 @@ Questions a bot can ask during a think (`game`, or `match.game` online). Queries
 | `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` |
+| `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 |
@@ -434,7 +436,7 @@ Questions a bot can ask during a think (`game`, or `match.game` online). Queries
 - `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`.
+- 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`.
 
 <!-- api/act.md -->
 
@@ -454,7 +456,7 @@ Every order a bot can give, on `act` during a think (and on the builder passed t
 | `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 |
+| `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) |
@@ -475,6 +477,8 @@ Every order a bot can give, on `act` during a think (and on the builder passed t
 
 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 |
@@ -560,11 +564,35 @@ Ops after the first step still apply but make the game unreplayable.
 | `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`);
+```
+
 <!-- api/replay.md -->
 
 # Replays
@@ -773,7 +801,7 @@ Every SDK call that fails throws a `WarpassError` with a `kind` and the fields b
 | `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 |
+| `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 |
 
@@ -794,7 +822,7 @@ Errors from local games and custom games (unknown ids, setup ops off the map) ar
 
 <!-- rules/index.md -->
 
-# Rules for engine 62
+# Rules for engine 63
 
 Generated from the engine this SDK bundles. Every id below is what the view, the queries and the orders use.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikehub/warpass-bot",
-  "version": "62.0.1",
+  "version": "63.0.0",
   "description": "Play Warpass from code: online matches, local games, custom games and replays",
   "type": "module",
   "main": "index.js",
@@ -22,8 +22,8 @@
   },
   "license": "MIT",
   "optionalDependencies": {
-    "@pikehub/warpass-bot-linux-x64-gnu": "62.0.1",
-    "@pikehub/warpass-bot-linux-arm64-gnu": "62.0.1"
+    "@pikehub/warpass-bot-linux-x64-gnu": "63.0.0",
+    "@pikehub/warpass-bot-linux-arm64-gnu": "63.0.0"
   },
   "publishConfig": {
     "access": "public"