@v12-engine/engine 0.1.0 → 0.4.0

package/dist/session/protocol.js

@@ -0,0 +1,55 @@
+//#region src/session/protocol.ts
+/**
+* Whether a command is one of the engine's of a kind, narrowed to its shape (`isCommand(sent, 'order')`: its units and
+* its order): what reads a command it did not write, a game's own (`ModCommand`) passed over
+*
+* @beta
+*/
+function isCommand(command, type) {
+	return command.type === type;
+}
+/**
+* The version of what goes over the wire between a host and its players: the messages here and in `session/remote.ts`,
+* and how deltas are made (`session/delta.ts`). The host says it in its welcome and a player says it when joining a
+* server; a player of another version is refused with a reason, not left to fail somewhere strange. Raised by one on
+* any change of their shape, which a game's own data (`Registry.dataHash`) does not show
+*
+* @beta
+*/
+var PROTOCOL_VERSION = 13;
+/**
+* What a player is told when the host's version of the wire is not its own (`PROTOCOL_VERSION`)
+*
+* @internal
+*/
+function protocolMismatch(host, player = 13) {
+	return `The host runs another version of the engine (protocol ${typeof host === "number" ? host : "unknown"}, this player's is ${player}): update the game`;
+}
+/**
+* Reads a message that came over a wire: an object with a `type` that is a string, or nothing. What is not JSON, or is
+* JSON of another shape (`null`, a number, a list), is nothing, so that a peer that sends anything at all makes whoever
+* reads it drop the message, not fall over. The other fields are still the sender's word: check each before it is used
+*
+* @internal
+*/
+function readMessage(text) {
+	let message;
+	try {
+		message = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (typeof message !== "object" || message === null || Array.isArray(message)) return void 0;
+	const { type } = message;
+	return typeof type === "string" ? message : void 0;
+}
+/**
+* A number that is a number: not `NaN`, not infinite, not a string of digits
+*
+* @internal
+*/
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+//#endregion
+export { PROTOCOL_VERSION, isCommand, isFiniteNumber, protocolMismatch, readMessage };
+
+//# sourceMappingURL=protocol.js.map

package/dist/session/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","names":[],"sources":["../../src/session/protocol.ts"],"sourcesContent":["import type { CameraOrder, SeatCamera } from '#engine/cameraOrders'\nimport type { SystemTiming } from '#engine/scheduler'\nimport type { DataKind, DataValues } from '#engine/gameData'\nimport type { Logger } from '#engine/log'\nimport type { Command, ModCommand } from '#engine/commands'\nimport type { ChatAudience, PingId } from '#engine/talk'\nimport type { Cost, DamageType, EffectShape, ResourceId, Stats } from '#engine/defs'\nimport type { EntityId, PlayerId } from '#engine/entity'\nimport type { FormationUnit } from '#engine/formation'\nimport type { Vec2 } from '#engine/math'\nimport type { SaidLine } from '#engine/dialog'\nimport type { Message } from '#engine/messages'\nimport type { ObjectiveState, ObjectiveStatus } from '#engine/objectives'\nimport type { ShownTimer } from '#engine/timers'\nimport type { WorldSave } from '#engine/save'\nimport type { Registry } from '#engine/registry'\nimport type { Inspection, InspectTarget, LoggedEvent, WorldListing } from '#engine/inspect'\nimport type { Lane } from '#engine/lanes'\nimport type { MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map'\nimport type { Terrain } from '#engine/terrain'\nimport type { TerrainPatch } from '#engine/ground'\nimport type { MessageKind } from '#engine/world'\nimport type { ScoreLineState, ScoreState } from '#engine/score'\n\n/**\n * What travels between the simulation and a player's screen.\n *\n * A client never touches the world. It gets snapshots of what its player is allowed\n * to know and sends commands back. Today both ends live in the same page, later the\n * simulation runs on a server, and nothing on the client has to change for that.\n * Everything in here is plain data for that reason: it has to survive being sent.\n */\n\n/**\n * An item in a building's production queue, as the screen is told of it\n *\n * @beta\n */\nexport interface QueueItemState {\n\t/** What the item is: a unit being trained, an upgrade researched, a hero revived or a morph into another type */\n\tkind: 'unit' | 'upgrade' | 'revive' | 'morph'\n\t/** The id of the unit type, upgrade or hero the item makes */\n\tid: string\n\t/** 0..1 */\n\tprogress: number\n}\n\n/**\n * An ability of the player's own unit as the owner's screen is told of it: level, cooldown, charges and autocast\n *\n * @beta\n */\nexport interface AbilityInfo {\n\t/** The ability's id */\n\tid: string\n\t/** The ability's level, from 1 */\n\tlevel: number\n\t/** Seconds until it can be used again */\n\tcooldown: number\n\t/** Uses left, of an ability with charges, while it holds fewer than it can (all of them when left out: `chargesLeft`) */\n\tcharges?: number\n\t/** Seconds until the next use is back, while it holds fewer than it can */\n\trefill?: number\n\t/** Whether the ability is set to cast by itself */\n\tautocast: boolean\n\t/**\n\t * What the game's `canCast` hook decided, where it is not what the declared costs say: a reason it cannot be used\n\t * now, or null for one it can be used for all that (\"free while Clearcasting\"). Left out when there is nothing to add\n\t */\n\tdecided?: Message | null\n\t/** The game's own state of the ability (`AbilityState.data`), where it has any */\n\tdata?: Record<string, unknown>\n\t/**\n\t * Its window to be cast again, while it is open (`AbilityDef.recast`): seconds `left` of `total`, and how many\n\t * recasts are left in it (`count`)\n\t *\n\t * @beta\n\t */\n\trecast?: { left: number; total: number; count: number }\n}\n\n/**\n * An ability of a unit as everyone who sees it may be told (`RuleSettings.hud.shareAbilities`): what it is and its\n * level, and how much of its cooldown is left where the rules share that too\n *\n * @beta\n */\nexport interface SharedAbility {\n\t/** The ability's id */\n\tid: string\n\t/** Its level: 1 and up, those not learned are not told */\n\tlevel: number\n\t/**\n\t * Seconds until it can be used again: with `shareAbilities: 'cooldowns'` alone. Whole seconds, rounded up, from a\n\t * host (`quantize`): the plate counts down between\n\t */\n\tcooldown?: number\n}\n\n/**\n * Something a unit carries\n *\n * @beta\n */\nexport interface CarriedItem {\n\t/** Which one of the unit's items, for commands */\n\tid: number\n\t/** The item type's id */\n\titem: string\n\t/** Uses left of the item */\n\tcharges: number\n\t/** Seconds until it can be used again */\n\tcooldown: number\n\t/**\n\t * Uses left of the ability it casts, where that has charges (`AbilityDef.charges`) and holds fewer than it can: all\n\t * of them when left out. None, and it cannot be used until one comes back\n\t */\n\tuses?: number\n}\n\n/**\n * What everyone who sees a unit is told of its items (`inventorySlots`' snapshot): what it carries; its owner and their\n * allies the slots too, for commands\n *\n * @beta\n */\nexport interface InventoryInfo {\n\t/** The items it carries, by id: anyone who sees the unit sees that */\n\titems: string[]\n\t/** One entry per slot, null for the empty ones: for its owner and their allies */\n\tslots?: (CarriedItem | null)[]\n}\n\n/**\n * What a worker's owner and their allies are told of what it carries (`gathering`'s snapshot)\n *\n * @beta\n */\nexport interface GatheringInfo {\n\t/** How much of it */\n\tcarrying: number\n\t/** What it is that it carries, or last gathered. Null for a worker that has not gathered anything yet */\n\tkind: ResourceId | null\n}\n\n/**\n * What a building's owner and their allies are told of what it makes (`productionQueue`'s snapshot): its queue and where\n * what comes out goes; and everyone who sees it, how far it is in turning into another type\n *\n * @beta\n */\nexport interface ProductionInfo {\n\t/** What it makes, the first being made: for its owner and their allies */\n\tqueue?: QueueItemState[]\n\t/** Where what it makes goes once out: for its owner and their allies */\n\trally?: Vec2\n\t/** 0..1 while it turns into another type (`upgradeTo`, `UnitTypeDef.upgradesTo`): what every player who sees it sees */\n\tupgrade?: number\n\t/** The type it turns into, while it does */\n\tupgradeTo?: string\n}\n\n/**\n * An item lying on the ground\n *\n * @beta\n */\nexport interface GroundItemState {\n\t/** The ground item's id, which a pick-up order names */\n\tid: number\n\t/** The item type's id */\n\titem: string\n\t/** Where it lies, east-west */\n\tx: number\n\t/** Where it lies, north-south */\n\tz: number\n}\n\n/**\n * One item type a shop has for sale, with how many are left and how far the next is\n *\n * @beta\n */\nexport interface StockInfo {\n\t/** The item type's id */\n\titem: string\n\t/** How many are left. Left out for what a shop never runs out of */\n\tcount?: number\n\t/** 0..1 towards the next one, when the shop is not full */\n\trestock: number\n}\n\n/**\n * A purchase of a hero's that its player may still undo (`purchases`, `undoBuy`), with the seconds left to\n *\n * @beta\n */\nexport interface PurchaseInfo {\n\t/** The purchase's id, what the `undoBuy` command names it by */\n\tid: number\n\t/** The item type's id */\n\titem: string\n\t/** Whole seconds left to undo it */\n\tleft: number\n}\n\n/**\n * An ability a hero can put points into\n *\n * @beta\n */\nexport interface LearnableInfo {\n\t/** The ability's id */\n\tid: string\n\t/** The level it is at now, 0 when not learned */\n\tlevel: number\n\t/** The highest level the ability can be taken to */\n\tmaxLevel: number\n\t/** Hero level needed for the next level of the ability */\n\tneeds: number\n\t/** Whether a point can go into it right now */\n\tavailable: boolean\n}\n\n/**\n * A hero's experience: what it has, at what the level it is at started and at what the next one does (`HeroSent.xp`)\n *\n * @beta\n */\nexport interface XpInfo {\n\t/** Experience in total, whole */\n\txp: number\n\t/** What the level it is at took */\n\tlevelXp: number\n\t/** What the next level takes */\n\tnextXp: number\n}\n\n/**\n * A hero of the player, for the row of portraits. Fallen ones are in here too\n *\n * @beta\n */\nexport interface HeroSummary {\n\t/** The hero's entity id */\n\tid: number\n\t/** The hero's unit type id */\n\ttype: string\n\t/** The hero's level */\n\tlevel: number\n\t/** Whether the hero is alive; a fallen one is in the row all the same */\n\talive: boolean\n\t/** 0..1 */\n\thealth: number\n\t/** The hero's mana now */\n\tmana: number\n\t/** Skill points the hero has not spent */\n\tpoints: number\n\t/** 0..1 while being brought back: at an altar, or coming back by itself (`respawnPack`) */\n\treviving?: number\n\t/** Seconds until it comes back by itself, while it waits to (`respawnPack`) */\n\trespawnIn?: number\n\t/** What bringing it back would cost */\n\treviveCost?: Cost\n}\n\n/**\n * The part of an entity only its owner and their allies get to know\n *\n * @beta\n */\nexport interface OwnEntityState {\n\t/** Another player's, which this one may command: its owner shares control with them (`world.shareControl`) */\n\tshared?: boolean\n\t/** Inside something, like a worker in a mine */\n\thidden: boolean\n\t/** Type of the order being carried out */\n\torder: string | null\n\t/** What it is about to build, for a build order */\n\tbuild?: string\n\t/** Orders in the queue, the current one included */\n\torders: number\n\t/** Whether the unit is set not to fight back or chase (passive stance) */\n\tpassive: boolean\n\t/** Whether the unit is in a fight now */\n\tfighting: boolean\n\t/** Where it is walking to right now */\n\tgoal?: Vec2\n\t/** Destinations of the orders waiting in the queue: none while nothing waits */\n\twaypoints?: Vec2[]\n\t/** The unit's abilities with their cooldowns and charges, for its owner's command card */\n\tabilities?: AbilityInfo[]\n}\n\n/**\n * A unit, building, resource or other entity as the screen is told of it\n *\n * @beta\n */\nexport interface EntityState {\n\t/** The entity's id, which commands and orders name it by */\n\tid: number\n\t/** The id of its unit type */\n\ttype: string\n\t/** The player who owns it */\n\towner: PlayerId\n\t/** Where it stands, east-west, in world units */\n\tx: number\n\t/** Where it stands, north-south, in world units */\n\tz: number\n\t/** The way it faces, in radians; 0 is along +z */\n\tfacing: number\n\t/** Its health now */\n\thealth: number\n\t/** The stats that are not what its type starts with. Whoever sees a unit can tell what it is capable of */\n\tstats?: Partial<Stats>\n\t/** What its shields still hold */\n\tshield?: number\n\t/** On its way through the air: from where to where, and how high it rises in between */\n\tleap?: { from: Vec2; to: Vec2; height: number }\n\t/** False for a structure that is out of sight and shown the way it was last seen */\n\tvisible: boolean\n\t/** Left out when it is what the unit type says */\n\tmaxHealth?: number\n\t/** Its mana now; left out when it has none */\n\tmana?: number\n\t/** Its largest mana when that is not what its type says */\n\tmaxMana?: number\n\t/** Ids of the buffs on it */\n\tbuffs?: string[]\n\t/** How many of each of its buffs that stack it carries, for the ones it carries any of */\n\tstacks?: Record<string, number>\n\t/**\n\t * Seconds left of each of its `buffs`, in their order (whole seconds, rounded up, from a host: the plate counts\n\t * down between); -1 for one kept up by an aura or a passive (`BuffInstance.kept`) or that lasts until it is\n\t * taken off. Where the rules share them (`RuleSettings.hud.shareBuffTimes`)\n\t *\n\t * @beta\n\t */\n\tbuffTimes?: number[]\n\t/**\n\t * The abilities it has learned, for whoever sees it, its side's or not, where the rules share them\n\t * (`RuleSettings.hud.shareAbilities`). Its side has them in `own.abilities` all the same\n\t *\n\t * @beta\n\t */\n\tabilities?: SharedAbility[]\n\t/** What is left in a resource */\n\tresource?: number\n\t/** The resource it stands on (`UnitTypeDef.builtOn`, a cursed mine on a gold mine), by id */\n\ton?: number\n\t/** Doing nothing until woken, like a creep sleeping through the night */\n\tasleep?: boolean\n\t/**\n\t * It has an order to carry out: left out while it stands idle. What a cinematic's waits go by (`arrived`), for any\n\t * unit it directs; anyone in sight of it can see it walk or swing\n\t */\n\tbusy?: boolean\n\t/** How big it is drawn, when that is not 1 */\n\tscale?: number\n\t/** Which of the models of its type it is drawn with, when the map says */\n\tlook?: string\n\t/** Drawn as this type, in this owner's colour, while it is what its own type and owner say (`SpawnOptions.looksLike`) */\n\tlikeness?: { type: string; owner: PlayerId }\n\t/** Seconds left and seconds in all, for what is gone by itself after a while, like a ward */\n\tlifetime?: { left: number; total: number }\n\t/**\n\t * Invisible to enemies right now, or camouflaged (`BuffDef.camouflage`: seen by them only from near). Whoever gets this\n\t * sees it all the same: it is theirs, or they found it, or they are near\n\t */\n\tunseen?: boolean\n\t/** Components of game modules and mods that are sent to this player (see `Component.replicate`), by id */\n\tcomponents?: Record<string, unknown>\n\t/** The name the map or the rules gave it (`world.named`), for whoever knows of it: \"the gate\", \"the hero\" */\n\tname?: string\n\t/** What only its owner and their allies are told of it */\n\town?: OwnEntityState\n}\n\n/**\n * A player as the screen is told of them: name, team, colour, resources and their standing to the player it is for\n *\n * @beta\n */\nexport interface PlayerState {\n\t/** The player's id */\n\tid: PlayerId\n\t/** The name shown for the player */\n\tname: string\n\t/** The player's team number; players on one team are allies */\n\tteam: number\n\t/** The player's colour as RGB, each 0..1 */\n\tcolor: [number, number, number]\n\t/** Whether the player is a neutral one, owner of mines and the like */\n\tneutral: boolean\n\t/** Whether they are the creeps: hostile to everyone, but no one's rival */\n\tcreeps?: boolean\n\t/** The race they play (`raceOf`): left out in a game without races */\n\trace?: string\n\t/** Whether the player is out of the game */\n\tdefeated: boolean\n\t/** What they are to the player the snapshot is for: by their teams, or as the rules set it (`setRelation`) */\n\trelation: 'self' | 'ally' | 'enemy' | 'neutral'\n\t/**\n\t * What the player the snapshot is for shares with this ally (`shareWith`): their units' control, and their team's\n\t * sight (always, for an ally of their team). Left out for who is not an ally\n\t */\n\tshared?: { control: boolean; vision: boolean }\n\t/** Only filled in for the player the snapshot is for */\n\town?: {\n\t\t/** What the player has of each resource, by resource id */\n\t\tresources: Record<ResourceId, number>\n\t\tsupplyUsed: number\n\t\tsupplyCap: number\n\t\t/** The game's other pools of supply, by name (`RuleSettings.supply.pools`): left out in a game with none */\n\t\tsupplies?: Record<string, { used: number; cap: number }>\n\t\t/** What the size of the army costs in income */\n\t\tupkeep: { tier: number; name: string; income: number }\n\t\tupgrades: Record<string, number>\n\t\tresearching: string[]\n\t\t/** Types of the finished buildings the player has, with what those count as */\n\t\ttech: string[]\n\t\theroes: HeroSummary[]\n\t\t/** What the player is set to do, in a mission. Empty in a game without objectives */\n\t\tobjectives: ObjectiveState[]\n\t\t/** The timers the rules show the player (`world.timers.show`): their words and the tick each goes off at */\n\t\ttimers?: ShownTimer[]\n\t\t/**\n\t\t * What the game's `requirement` hook decided, where it differs from what the requirements say (see\n\t\t * `PlayerFacts.unlocks`): by unit or structure type, and `upgrade:<id>` for the next level. Left out without one\n\t\t */\n\t\tunlocks?: Record<string, Message | null>\n\t\t/**\n\t\t * What the game's `available` hook decided, where it differs from what their race says (see\n\t\t * `PlayerFacts.availability`): by unit or structure type, and `upgrade:<id>`. Left out without one\n\t\t */\n\t\tavailability?: Record<string, boolean>\n\t}\n}\n\n/**\n * A projectile in flight as the screen is told of it: where it is, who shot it and what kind of damage it carries\n *\n * @beta\n */\nexport interface ProjectileState {\n\t/** The projectile's id */\n\tid: number\n\t/** Where it is, east-west, in world units */\n\tx: number\n\t/** Where it is, north-south, in world units */\n\tz: number\n\t/** The type of what shot it, known even when the shooter is out of sight: what it looks like */\n\tkind: string\n\t/** The player whose unit shot it */\n\towner: PlayerId\n\t/** Whether the hit it carries is a critical one */\n\tcrit: boolean\n\t/** The type of damage it deals on landing */\n\tdamageType: DamageType\n\t/** A look the rules gave it (see `Projectile.look`) */\n\tlook?: string\n\t/** Entity it was fired by, when that one is known to the player */\n\tsource?: number\n\t/** Entity it is after, when that one is known to the player */\n\ttarget?: number\n\t/** Where it was fired from and where it comes down, for shots that are lobbed at a spot */\n\tfrom?: Vec2\n\t/** Where a lobbed shot comes down */\n\tto?: Vec2\n}\n\n/**\n * What an ability sent on its way, like a tornado\n *\n * @beta\n */\nexport interface MissileState {\n\t/** The missile's id */\n\tid: number\n\t/** The id of the ability that sent it */\n\tability: string\n\t/** The level of the ability when it was sent */\n\tlevel: number\n\t/** Entity that sent it, when that one is known to the player */\n\tsource?: number\n\t/** Where it is, east-west, in world units */\n\tx: number\n\t/** Where it is, north-south, in world units */\n\tz: number\n\t/** How far from its centre it hits things, in world units */\n\tradius: number\n\t/** The way it is heading, in radians */\n\theading: number\n\t/** How far it is with taking shape, 0..1, while it has not set off yet */\n\tforming?: number\n\t/** How much of its way it has come, 0..1, for the ones that go a known way */\n\tprogress?: number\n\t/** How high above the ground its arc carries it now, for what is thrown in one (`EffectFields.arc`) */\n\tarc?: number\n\t/** On its way back to the caster (`EffectFields.returns`): what is drawn of it may face the way it went out */\n\treturning?: boolean\n\t/** Its owner turns it as it flies (`EffectFields.steer`): told to its side alone, whose screen steers it (the `steer` command) */\n\tsteered?: boolean\n\t/**\n\t * Which effect of the ability it is, by its place there (`effectIndex`): what the screen draws it with\n\t * (`AbilityLook.effects`). Left out for one not written in the ability\n\t *\n\t * @beta\n\t */\n\teffect?: number\n}\n\n/**\n * An area of an ability on the ground the player is told of (`Snapshot.areas`): a zone for its life, or a delayed blast\n * until it goes off (a telegraph), with its shape (`EffectArea`), its place and the seconds left\n *\n * @beta\n */\nexport interface AreaState {\n\t/** A zone (`zone`), or effects that wait to go off there (`after`): `delayed` */\n\tkind: 'zone' | 'delayed'\n\t/** A zone's id, the same as long as it lasts. None for a delayed blast */\n\tid?: number\n\t/** The ability whose it is */\n\tability: string\n\t/** The ability's level */\n\tlevel: number\n\t/** Which effect of the ability it is (the `zone`, the `after`), by its place there (`effectIndex`) */\n\teffect?: number\n\t/** Who cast it, where the player knows them */\n\tsource?: number\n\t/** Its shape: circle, cone, line, rect, ring, arc or cross (`EffectCommon.shape`) */\n\tshape: EffectShape\n\t/** Where it is laid: its middle (circle, ring, rect, cross), or where it goes off from (cone, line, arc) */\n\tx: number\n\t/** Where it is laid along z */\n\tz: number\n\t/** The way it faces, radians as a unit's `facing` */\n\theading: number\n\t/** Of a circle, a ring and an arc: how far out it reaches */\n\tradius: number\n\t/** Of a cone, a line, a rect and a cross: how long it is */\n\tlength?: number\n\t/** Of a line, a rect and a cross: how far out on either side; of a ring and an arc, how thick */\n\twidth?: number\n\t/** Of a cone and an arc: how wide it opens, in radians */\n\tangle?: number\n\t/** Seconds left: of a zone, until it ends; of a delayed blast, until it goes off */\n\tleft: number\n\t/** Of the player's side */\n\tours?: boolean\n\t/** The unit a zone goes with (`follow`) */\n\tfollows?: number\n\t/** The name a delayed blast's arrival goes by (`impact`) */\n\timpact?: string\n}\n\n/**\n * What the players are told happened during a tick, which cannot be read from the state afterwards: each kind by its\n * `type` (design review E7). The engine's are told by its replications (`replicateEvent(key, type, tell)`, typed by\n * this entry); a pack's or a game's own added by declaration merging, as `OrderStates` is. A screen's handlers are\n * keyed by the same names (`SessionEventOf`)\n *\n * @beta\n */\nexport interface SessionEvents {\n\t/**\n\t * Something died. What killed it (`killer`, `killerType`, `from`, where it stood) when the player sees it; how:\n\t * an attack of the killer's, the blow's damage type, the ability, how much too much, a critical strike, and what\n\t * the rules made of it (`how`, set in the `death` hook: `'exploded'`). For the screen to show it its way\n\t */\n\tdeath: {\n\t\ttype: 'death'\n\t\tid: number\n\t\tfrom?: Vec2\n\t\tkiller?: number\n\t\tkillerType?: string\n\t\tattack: boolean\n\t\tdamageType?: DamageType\n\t\tability?: string\n\t\toverkill?: number\n\t\tcrit?: boolean\n\t\thow?: string\n\t\t/** Why, when it was not of damage (`DeathReason`): `cancelled`, `expired`, a game's own word */\n\t\treason?: string\n\t\t/** The blow's words of the game's own (`DamageOptions.tags`) */\n\t\ttags?: string[]\n\t}\n\t/**\n\t * Cells of one of the game's layers (`Terrain.cells`) were set to `value` (`world.setCells`): the session's ground has\n\t * it already, for the screen to draw again. Told where the player's team sees the cells, and as they come into its sight\n\t * where it does not (`TeamMemory.cells`): an observer is told of all. `over`: the seconds it eases into the value\n\t * over, where the rules said (grass growing back); not said as cells come into sight. `seen`: they came into sight\n\t * as they are, changed out of it before (a fire that burnt there a while): not as they change now\n\t */\n\tcells: { type: 'cells'; layer: string; at: number[]; value: number; over?: number; seen?: true }\n\t/**\n\t * A part of the ground was reshaped (`world.reshapeGround`, the editor's Play here): the session's ground has it\n\t * already, for the screen to draw again. Told to everyone\n\t */\n\tground: { type: 'ground'; patch: TerrainPatch }\n\t/**\n\t * Something the player does not see moved in a layer of cells where the player sees the ground (`ConcealmentOptions.rustle`):\n\t * where, and whether it stepped in. Not who: for the screen to shake the bushes there\n\t *\n\t * @beta\n\t */\n\trustle: { type: 'rustle'; layer: string; x: number; z: number; entered?: boolean }\n\t/**\n\t * A gust of wind the rules blew at a place the player sees (`gust`, `WindGust`): where, how far around, how hard,\n\t * which way (outwards from its middle when left out) and for how long. For the screen to bend the grass and bushes\n\t * there (`client.gust`)\n\t *\n\t * @beta\n\t */\n\tgust: { type: 'gust'; x: number; z: number; radius: number; strength: number; around?: number; lasts?: number }\n\t/** What the map looks like beyond its ground, as it is now (`world.setEnvironment`), and the seconds to ease into it over */\n\tenvironment: { type: 'environment'; environment: MapEnvironment; over?: number }\n\t/**\n\t * A definition changed while the game runs (`world.redefine`), a copy made with `copyOf`: a screen with a registry of\n\t * its own puts it in. Told to everyone\n\t */\n\tredefined: { type: 'redefined'; kind: DataKind; definition: string; values: DataValues }\n\t/** An attack started, at `target` when the player sees it */\n\t/** `weapon`: which of its attacks swings, by place (`UnitTypeDef.attacks`); the first when left out */\n\tattack: { type: 'attack'; id: number; target?: number; weapon?: number }\n\t/** An attack called off before its blow, of a unit the player sees (`swingCancelled`): the screen cuts it to the walk */\n\tattackCancelled: { type: 'attackCancelled'; id: number }\n\t/** Damage dealt to an entity the player sees: by whom when the player sees that too, with what, how much */\n\tdamage: {\n\t\ttype: 'damage'\n\t\tid: number\n\t\tamount: number\n\t\tdamageType: DamageType\n\t\tsource?: number\n\t\tsourceType?: string\n\t\tattack: boolean\n\t\tcrit: boolean\n\t\t/** The ability that dealt it, where the player sees the source (`source`) */\n\t\tability?: string\n\t\ttags?: string[]\n\t}\n\t/** Health given back to an entity the player sees */\n\theal: { type: 'heal'; id: number; amount: number; source?: number }\n\t/**\n\t * A buff put on an entity the player sees (`on`), put on again at another level (`renewed`), or taken off or run\n\t * out. Once as it begins and once as it ends: a renewal at the same level is not told\n\t */\n\tbuff: { type: 'buff'; id: number; buff: string; on: boolean; level?: number; renewed?: boolean; source?: number }\n\t/** A unit came out of `building`, where the player sees that too */\n\ttrained: { type: 'trained'; id: number; building?: number }\n\t/** A structure was put down to be built, to go up over `buildTime` seconds as builders work (`EntityState.construction`) */\n\tconstructionStarted: { type: 'constructionStarted'; id: number; buildTime: number }\n\t/** A structure was finished (or put down whole, `UnitTypeDef.construction: 'instant'`) */\n\tbuilt: { type: 'built'; id: number }\n\t/** A construction was called off by its owner: it dies next, its death's reason `cancelled` */\n\tconstructionCancelled: { type: 'constructionCancelled'; id: number }\n\t/** A building started to turn into another type (`to`) over `time` seconds (`EntityState.upgrade`) */\n\tupgradeStarted: { type: 'upgradeStarted'; id: number; to: string; time: number }\n\t/** That was called off */\n\tupgradeCancelled: { type: 'upgradeCancelled'; id: number; to: string }\n\t/** An entity became another type (`from`: what it was): an upgrade done, a morph */\n\tmorphed: { type: 'morphed'; id: number; from: string }\n\t/** A hero was brought back */\n\trevived: { type: 'revived'; id: number }\n\t/** An entity picked an item up */\n\tpicked: { type: 'picked'; id: number; item: string }\n\t/** Research of the player or an ally finished */\n\tresearched: { type: 'researched'; upgrade: string; level: number; building: number }\n\t/** A shot arrived: at its target when it had one, missing (`miss`), or struck critically */\n\tshot: { type: 'shot'; id: number; x: number; z: number; target?: number; miss: boolean; crit: boolean }\n\t/** A channelled ability started to be kept up (`on`, for `duration` seconds), or ended: done, or `interrupted` */\n\tchannel: { type: 'channel'; id: number; ability: string; on: boolean; duration?: number; interrupted?: boolean }\n\t/** What an ability sent on its way struck an entity */\n\tmissileHit: { type: 'missileHit'; missile: number; target: number }\n\t/** A critical strike landed on the entity */\n\tcrit: { type: 'crit'; id: number; amount: number }\n\t/** An attack up a cliff went wide, at this spot */\n\tmiss: { type: 'miss'; x: number; z: number }\n\t/** A shot that hits an area came down */\n\timpact: { type: 'impact'; x: number; z: number; radius: number }\n\t/** A worker struck what it is mending */\n\twork: { type: 'work'; id: number }\n\t/** A worker struck what it is gathering from */\n\tchop: { type: 'chop'; id: number; target: number }\n\t/** An ability went off. `radius` is there for the ones that hit an area */\n\tlevelUp: { type: 'levelUp'; id: number; level: number }\n\t/** Experience a hero of the player's or an ally's earned, and the level it is at after it */\n\txp: { type: 'xp'; id: number; amount: number; level: number }\n\t/**\n\t * Mana of a unit of the player's or an ally's spent on a cast (`amount` below 0, `ability` the one cast) or given by\n\t * an effect (above 0). Not regeneration\n\t */\n\tmana: { type: 'mana'; id: number; amount: number; ability?: string }\n\t/** A pool of the game's own on a unit of the player's or an ally's changed (`resourceChanged`) */\n\tresource: { type: 'resource'; id: number; kind: string; amount: number; reason?: string }\n\t/** Gold for a kill */\n\tbounty: { type: 'bounty'; x: number; z: number; amount: number }\n\t/** Someone started to cast. `duration` is how long until it goes off */\n\twindup: { type: 'windup'; id: number; ability: string; level: number; x: number; z: number; duration: number }\n\t/** A wind-up called off before it went off (stunned, killed, ordered elsewhere): what it showed goes. `ability` where known */\n\tcastCancelled: { type: 'castCancelled'; id: number; ability?: string }\n\t/** `id`: the caster, where the player sees it (not where only the spot is seen). `charged`: it went off charged, see `charge` on the ability */\n\tcast: { type: 'cast'; id?: number; ability: string; level: number; x: number; z: number; target?: number; radius?: number; charged?: boolean }\n\t/**\n\t * What an ability set off arrived somewhere: a missile hit, a rush ended, the time was up. `id`: the caster, where the\n\t * player sees it. `from`: where it went off from, when not the caster (a ball, a shadow: `EffectContext.origin`)\n\t */\n\tstrike: {\n\t\ttype: 'strike'\n\t\tid?: number\n\t\tability: string\n\t\tlevel: number\n\t\tx: number\n\t\tz: number\n\t\ttarget?: number\n\t\tradius?: number\n\t\timpact?: string\n\t\tfrom?: { x: number; z: number }\n\t\t/** Which effect of the ability arrived (a missile, a delay, a zone at its end), by its place there (`effectIndex`) */\n\t\teffect?: number\n\t}\n\t/** Something to tell the player. The client finds the words for it, see `Message` */\n\tmessage: { type: 'message'; message: Message; kind: MessageKind; seconds?: number }\n\t/** A command the player sent (`seq`, what `send` gave) was carried out: refused, with why, or not */\n\tcommand: { type: 'command'; seq: number; refusal?: Message }\n\t/** An objective of the player was given (`was` undefined), got further along, or was done or failed */\n\tobjective: { type: 'objective'; objective: ObjectiveState; was?: ObjectiveStatus }\n\t/** Someone says a line to the player: who, what, and for how long (see `world.dialog`) */\n\tline: { type: 'line'; line: SaidLine }\n\t/** The line was skipped: it ends now */\n\tlineEnded: { type: 'lineEnded'; id: number }\n\t/** One of the view's cinematics plays (see `playCinematic`) */\n\tcinematic: { type: 'cinematic'; cinematic: string; hold: boolean; skippable: boolean; params?: Record<string, unknown> }\n\t/** The rules cue the cinematic playing (see `cueCinematic`) */\n\tcinematicCue: { type: 'cinematicCue'; cue: string; params?: Record<string, unknown> }\n\t/** The rules pan or shake this player's camera (see `cameraFor`) */\n\tcamera: { type: 'camera' } & Pick<CameraOrder, 'pan' | 'shake'>\n\t/**\n\t * One of the view's effects plays, as the rules said (`world.fx`): `id` is the rules' handle on it, `fx` its name,\n\t * at a place (`x`, `y`, `z`) or on an entity (`on`, at a `point`), its knobs, the seed of its random parts\n\t */\n\tfx: {\n\t\ttype: 'fx'\n\t\tid: number\n\t\tfx: string\n\t\tx?: number\n\t\ty?: number\n\t\tz?: number\n\t\ton?: number\n\t\tpoint?: string\n\t\tparams?: Record<string, unknown>\n\t\tseed: number\n\t\toverFog?: boolean\n\t\t/** The other end, for one drawn between two (`FxOptions.toward`): an entity, where the player knows it */\n\t\ttoward?: number\n\t\t/** Or a place, east-west */\n\t\ttx?: number\n\t\t/** And north-south */\n\t\ttz?: number\n\t}\n\t/** An effect the rules played stops (`world.stopFx`) */\n\tfxStop: { type: 'fxStop'; id: number; fade?: number }\n\t/** A player of the side marked a spot of the map, or any player for everyone (`to`, see `ping`) */\n\t/** `by`: the name of who watches, for one of theirs (`to: 'observers'`) */\n\tping: { type: 'ping'; player: PlayerId; x: number; z: number; kind: PingId; to: ChatAudience; by?: string }\n\t/** A line of chat for the player: of their side, or to everyone (see `chat`) */\n\t/** `by`: the name of who watches, for a line of theirs (`to: 'observers'`) */\n\tchat: { type: 'chat'; player: PlayerId; text: string; to: ChatAudience; by?: string }\n\t/** An event of the game's own that goes to the screen (see `defineEvent`): its id, and what it says */\n\tgame: { type: 'game'; event: string; payload: unknown }\n}\n\n/**\n * Things that happened during a tick and cannot be read from the state afterwards: one of `SessionEvents`\n *\n * @beta\n */\nexport type SessionEvent = SessionEvents[keyof SessionEvents]\n\n/**\n * How the game stands for the player\n *\n * @beta\n */\nexport type Outcome = 'playing' | 'victory' | 'defeat'\n\n/**\n * Everything one player knows about the game at the end of a tick\n *\n * @beta\n */\nexport interface Snapshot {\n\t/** The tick number the snapshot was taken at */\n\ttick: number\n\t/**\n\t * The switches of the debug tools as they stand, for a player who may use them (`world.debugPlayers`): `explored`,\n\t * the whole map explored (`debug.explore`)\n\t */\n\tdebug?: { noCooldowns: boolean; noManaCosts: boolean; invulnerable: boolean; speed: number; explored?: boolean }\n\t/** Hour of the day, 0..24, in a game with days and nights */\n\thour?: number\n\t/** How the game stands for the player: still playing, a victory or a defeat */\n\toutcome: Outcome\n\t/** The entities the player may know of, as of this tick */\n\tentities: EntityState[]\n\t/** Every player of the game, with what the receiving player may know of each */\n\tplayers: PlayerState[]\n\t/** Projectiles in flight the player can see */\n\tprojectiles: ProjectileState[]\n\t/** Missiles in flight the player can see */\n\tmissiles: MissileState[]\n\t/** Items on the ground, where the player can see the ground */\n\titems: GroundItemState[]\n\t/** Spots someone sees for a while. Everyone can tell, not only whoever it is */\n\treveals: RevealState[]\n\t/**\n\t * The areas of abilities on the ground the player is told of: zones and delayed blasts, their side's and others' where\n\t * they see them. None when left out\n\t *\n\t * @beta\n\t */\n\tareas?: AreaState[]\n\t/** Corpses where the player can see the ground, by the id of who died there (see `raiseDead`). None when left out */\n\tcorpses?: CorpseState[]\n\t/** What happened since the last snapshot that the player is told of, oldest first */\n\tevents: SessionEvent[]\n\t/** What the rules said of the player's camera that lasts, a part of the map it stays in (see `cameraFor`). None when they said none */\n\tcamera?: SeatCamera\n\t/** What the game tells the player about itself, see `Rules.report` */\n\treport?: Record<string, unknown>\n\t/**\n\t * The score of the players the player is told of (`RuleSettings.score`: `live`, then `end`), told again at most once\n\t * in `refresh` seconds. None in a game that counts nothing\n\t *\n\t * @beta\n\t */\n\tscore?: ScoreState\n\t/**\n\t * The score's timeline, of the same players: told again at each point of it (`ScoreSettings.every`)\n\t *\n\t * @beta\n\t */\n\tscoreLine?: ScoreLineState\n}\n\n/**\n * A corpse as the player sees it: the id the unit had, of what type, where\n *\n * @beta\n */\nexport interface CorpseState {\n\t/** The id the unit had when alive */\n\tid: number\n\t/** The unit type it was */\n\ttype: string\n\t/** Where it lies, east-west */\n\tx: number\n\t/** Where it lies, north-south */\n\tz: number\n}\n\n/**\n * A spot revealed to a team for a while, as the screen is told of it\n *\n * @beta\n */\nexport interface RevealState {\n\t/** The reveal's id */\n\tid: number\n\t/** Centre of the revealed spot, east-west */\n\tx: number\n\t/** Centre of the revealed spot, north-south */\n\tz: number\n\t/** How far from the centre it reveals, in world units */\n\tradius: number\n\t/** Seconds it goes on */\n\tleft: number\n\t/** The player's team is the one that sees it */\n\tours: boolean\n}\n\n/** A creep camp. Where they are is part of the map, which everyone knows */\n/**\n * A deposit of the game's money, as the map shows it (`GameSession.mines`)\n *\n * @beta\n */\nexport interface MineInfo {\n\t/** The mine's entity id */\n\tid: number\n\t/** Where it stands, east-west */\n\tx: number\n\t/** Where it stands, north-south */\n\tz: number\n}\n\n/**\n * A camp of creeps as the player knows it: where, how strong and whether it is cleared\n *\n * @beta\n */\nexport interface CampInfo {\n\t/** The camp's id */\n\tid: number\n\t/** Where its middle is, east-west */\n\tx: number\n\t/** Where its middle is, north-south */\n\tz: number\n\t/** Levels of its creeps added up */\n\tlevel: number\n\t/** Whether the player has seen that the camp is empty */\n\tcleared: boolean\n}\n\n/**\n * What the player's team sees of the map. The arrays are per cell, row by row\n *\n * @beta\n */\nexport interface FogState {\n\t/** Cells across the map, east-west */\n\twidth: number\n\t/** Cells across the map, north-south */\n\tdepth: number\n\t/** Changes whenever the arrays did */\n\tversion: number\n\t/** The whole map is lit, a debug switch */\n\trevealed: boolean\n\t/** Per cell, row by row: non-zero where the team sees the cell now */\n\tvisible: Uint8Array\n\t/** Per cell, row by row: non-zero where the team has seen the cell at some time */\n\texplored: Uint8Array\n}\n\ntype WithoutPlayer<T> = T extends unknown ? Omit<T, 'player'> : never\n\n/**\n * A command as the client writes it. Who it comes from is decided by the session, never by the sender\n *\n * @beta\n */\nexport type PlayerCommand = WithoutPlayer<Command> | ModCommand\n\n/**\n * Whether a command is one of the engine's of a kind, narrowed to its shape (`isCommand(sent, 'order')`: its units and\n * its order): what reads a command it did not write, a game's own (`ModCommand`) passed over\n *\n * @beta\n */\nexport function isCommand<K extends Command['type']>(command: PlayerCommand, type: K): command is Extract<WithoutPlayer<Command>, { type: K }> {\n\treturn command.type === type\n}\n\n/**\n * What the debug tools of a client see of the simulation: an entity as the rules have it, and the events and hooks of\n * the last seconds. Plain data, as the snapshots are, so that it works the same with a simulation somewhere else: the\n * client says what it wants to follow, and reads what came back last\n *\n * @beta\n */\nexport interface SessionDebug {\n\t/** Follows an entity, a player or the world, or nothing. Its inspection comes back from then on */\n\tinspect(target: InspectTarget | null): void\n\t/** What is followed, as it stood when last heard of. Null when nothing is followed, or it is gone */\n\treadonly inspection: Inspection | null\n\t/** Changes a number, or a switch (a boolean), of what is followed, where its inspection shows it (`InspectedSection.path` and the key) */\n\tset(path: (string | number)[], value: number | boolean): void\n\t/** Whether the list of everything in the world comes back. Off until asked for: the world can be big */\n\tlisting: boolean\n\t/** Every player and entity of the world, out of sight, hidden and scenery too, as when last heard of. Null while not listing */\n\treadonly world: WorldListing | null\n\t/** Whether the events and hooks are logged. Off until asked for: logging costs a little */\n\tlogging: boolean\n\t/** The events and hooks of the last seconds, oldest first */\n\tlog(): readonly LoggedEvent[]\n\t/** Forgets what was logged so far */\n\tclearLog(): void\n}\n\n/**\n * What a session can do besides being a seat, each where it can (`GameSession.can`): a game played in this page holds\n * its pace and saves, a game in a worker of it says its timing too, a seat a computer plays from serves its brain. Asked\n * for as `session.can.pace?.advance()`: there or not\n *\n * @beta\n */\nexport interface SessionCan {\n\t/** The pace, where it is this player's to set: a game played in this page, in its thread or in a worker of it */\n\treadonly pace?: SessionPace\n\t/** Saves of the world as it stands, and the last checkpoint: a game played in this page */\n\treadonly saves?: SessionSaves\n\t/** The debug tools' view of the simulation, where the session allows it */\n\treadonly inspect?: SessionDebug\n\t/** Where the time of a simulation run elsewhere in this page went of late: a worker (S54) */\n\treadonly timing?: SessionTiming\n\t/** What a computer player's brain reads besides the snapshot: a seat in the simulation's own thread */\n\treadonly computer?: SessionComputer\n}\n\n/**\n * The pace a session holds the game at (`SessionCan.pace`)\n *\n * @beta\n */\nexport interface SessionPace {\n\t/** 1 as it goes, 0 held (a pause menu, a cinematic that has the game wait) */\n\tspeed: number\n\t/** Moves a held game on by `ticks` (one when left out): a step */\n\tadvance(ticks?: number): void\n}\n\n/**\n * Saves of the world a session plays (`SessionCan.saves`)\n *\n * @beta\n */\nexport interface SessionSaves {\n\t/** A save of the world as it stands: at once in this thread, a message there and back in a worker */\n\tsave(): Promise<WorldSave>\n\t/**\n\t * The last moment the rules marked to start again from (`world.checkpoint`), with what it is called, and a save of\n\t * the world as it stood: a scene can load it for \"Retry from wave 6\"\n\t */\n\treadonly checkpoint?: { label: Message; save: WorldSave }\n}\n\n/**\n * Where the time of a simulation run elsewhere went of late (`SessionCan.timing`)\n *\n * @beta\n */\nexport interface SessionTiming {\n\t/**\n\t * Milliseconds a tick took, evened out, the longest, what sending the page what changed took, what the page took to\n\t * take it in, and each system's share (`world.scheduler.timing()`) while they are measured (`profile`)\n\t */\n\ttiming(): { tick: number; tickMax: number; send: number; receive?: number; systems?: SystemTiming[] } | undefined\n\t/** Measures the simulation's systems, or stops (it costs a little): what the stats window asks while it is open */\n\tprofile?(on: boolean): void\n}\n\n/**\n * What a computer player's seat gives its brain besides the snapshot (`SessionCan.computer`)\n *\n * @beta\n */\nexport interface SessionComputer {\n\t/**\n\t * Where the game's money is mined (a resource of `Registry.currency`: gold mines), as a player knows from the map,\n\t * under the fog too: what a computer player looks to for another hall\n\t */\n\tmines(): readonly MineInfo[]\n\t/** The lanes of the map (`lanesOf`), as everyone knows them from the map: what a computer player of lanes walks with its waves */\n\tlanes(): readonly Lane[]\n\t/**\n\t * What happened since the last snapshot, not yet given in one: a copy. The brain's save keeps what it heard since it\n\t * last thought (`restoreEvents`), so that a game loaded from the save hears it too\n\t */\n\tpendingEvents(): SessionEvent[]\n\t/** Takes back what `pendingEvents` gave, ahead of what has happened since: in a game loaded from a save */\n\trestoreEvents(events: readonly SessionEvent[]): void\n}\n\n/**\n * A seat in a game: the only thing a client needs to play\n *\n * @beta\n */\nexport interface GameSession {\n\t/** The player this seat plays, or watches from the side of */\n\treadonly playerId: PlayerId\n\t/** The team of that player */\n\treadonly team: number\n\t/** The map and the game data are the same for everyone and known up front */\n\treadonly terrain: Terrain\n\t/**\n\t * What the map looks like beyond its ground, for the screen: its water, sky, weather. Nothing when it does not say.\n\t * As it was when the session began: what the rules change after comes as `environment` events\n\t */\n\treadonly environment?: MapEnvironment\n\t/** The scenery of the map, for the screen: none when it has none (see `MapDoodad`) */\n\treadonly doodads: readonly MapDoodad[]\n\t/** The regions of the map, for the screen: what mist in places lies over by name (see `MapRegion`, `AreaRef`) */\n\treadonly regions: readonly MapRegion[]\n\t/** The views of the map saved under names, for cinematics and a player's first view (see `MapCamera`) */\n\treadonly cameras: readonly MapCamera[]\n\t/** The paths of the map (a road), for the screen: a cinematic's camera on a rail along one (see `MapPath`) */\n\treadonly paths: readonly MapPath[]\n\t/** The definitions of the game the session runs, the same for everyone */\n\treadonly registry: Registry\n\t/** Simulation ticks per second */\n\treadonly tickRate: number\n\t/**\n\t * What the game says about what it does (`World.log`), where the session has it: a game played in the page. A\n\t * server's game says it on the server, and a player is not given it\n\t */\n\treadonly log?: Logger\n\t/**\n\t * Why the game ended on an error in its rules, once it has (`World.failure`): what the player is told. A game that\n\t * failed does not go on; a client says so, and offers what there is to offer\n\t */\n\treadonly failure?: { message: string } | null\n\t/** How far the current frame is between the last two snapshots, 0..1 */\n\treadonly alpha: number\n\n\t/** State to start from */\n\tsnapshot(): Snapshot\n\t/** Lets time pass. Returns the snapshots that came in since the last call, oldest first */\n\tupdate(dt: number): Snapshot[]\n\t/** Sends a command, to be carried out at the next tick. What it gives is told back with how it went (a `command` event) */\n\tsend(command: PlayerCommand): number\n\t/** The player's team's fog now, per cell */\n\tfog(): FogState\n\t/** The creep camps the player knows of, with whether each is cleared */\n\tcamps(): readonly CampInfo[]\n\n\t/** Whether the player could build this here, as far as they can tell */\n\tcanPlace(unitType: string, point: Vec2): boolean\n\t/**\n\t * Which cells of the ground a building would cover there are in the way, as far as the player can tell, row by row\n\t * from its corner (`placementCells`): what a preview draws cell by cell. None for one built on a resource, or where\n\t * the session does not say @beta\n\t */\n\tplaceCells?(unitType: string, point: Vec2): readonly boolean[] | undefined\n\t/**\n\t * Where a group of units would stand if sent to a point in a formation, turned to face a way (`facing`: the way a\n\t * right-click was dragged): the ghosts of that drag. By the formation's id, or the one the rules would pick (the\n\t * session's own where it knows the rules, `rows` where not). Worked out from what the player's screen knows, over the\n\t * ground the player knows; the `formation` hook does not run in it @beta\n\t */\n\tformationPlaces?(\n\t\tunits: readonly (FormationUnit & { readonly flying?: boolean })[],\n\t\tpoint: Vec2,\n\t\tfacing?: number,\n\t\tformation?: string\n\t): Map<EntityId, Vec2>\n\t/** Route a unit would take, over the ground the player knows */\n\tfindPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null\n\n\t/**\n\t * What this kind of session can do besides being a seat (`SessionCan`): hold the pace, save, show the debug tools,\n\t * tell its timing, serve a computer player. A seat over a wire can none of it; a game in this page most of it\n\t */\n\treadonly can: SessionCan\n\n\t/** Whether the player only watches, and sees everything (every player's resources among it): see `LocalSession.observer` */\n\treadonly observer?: boolean\n\t/** Milliseconds a message takes to the simulation and back, where it runs elsewhere. Nothing in the page */\n\treadonly ping?: number\n\n\t/** Stops the session and lets go of what it holds */\n\tdispose(): void\n}\n\n/**\n * The version of what goes over the wire between a host and its players: the messages here and in `session/remote.ts`,\n * and how deltas are made (`session/delta.ts`). The host says it in its welcome and a player says it when joining a\n * server; a player of another version is refused with a reason, not left to fail somewhere strange. Raised by one on\n * any change of their shape, which a game's own data (`Registry.dataHash`) does not show\n *\n * @beta\n */\nexport const PROTOCOL_VERSION = 13\n\n/**\n * What a player is told when the host's version of the wire is not its own (`PROTOCOL_VERSION`)\n *\n * @internal\n */\nexport function protocolMismatch(host: unknown, player: number = PROTOCOL_VERSION): string {\n\treturn `The host runs another version of the engine (protocol ${typeof host === 'number' ? host : 'unknown'}, this player's is ${player}): update the game`\n}\n\n/**\n * Reads a message that came over a wire: an object with a `type` that is a string, or nothing. What is not JSON, or is\n * JSON of another shape (`null`, a number, a list), is nothing, so that a peer that sends anything at all makes whoever\n * reads it drop the message, not fall over. The other fields are still the sender's word: check each before it is used\n *\n * @internal\n */\nexport function readMessage(text: string): ({ type: string } & Record<string, unknown>) | undefined {\n\tlet message: unknown\n\ttry {\n\t\tmessage = JSON.parse(text)\n\t} catch {\n\t\treturn undefined\n\t}\n\tif (typeof message !== 'object' || message === null || Array.isArray(message)) return undefined\n\tconst { type } = message as { type?: unknown }\n\treturn typeof type === 'string' ? (message as { type: string } & Record<string, unknown>) : undefined\n}\n\n/**\n * A number that is a number: not `NaN`, not infinite, not a string of digits\n *\n * @internal\n */\nexport const isFiniteNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value)\n\n/**\n * A game of a server, as its list says it (`GET /games`): its room (what to connect to, `ws://host:port/<room>`; none for\n * a server of one game), the game and mode, where it is at, its seats taken and free, who watches, and its settings\n * (the map, among them, where the mode offers one)\n *\n * @beta\n */\nexport interface GameListing {\n\t/** The room name to connect to (`ws://host:port/<room>`); empty for a server of one game */\n\troom: string\n\t/** The id of the game module the room runs */\n\tgame: string\n\t/** The id of the mode the game runs */\n\tmode: string\n\t/** Where the game is: in its lobby, on, or ended */\n\tphase: 'lobby' | 'game' | 'ended'\n\t/** Seats players hold, seats nobody holds a player could, seats the computer plays */\n\tplayers: number\n\t/** Seats nobody holds that a player could take */\n\tfree: number\n\t/** Seats the computer plays */\n\tcomputer: number\n\t/** Connections watching without a seat */\n\twatchers: number\n\t/** The game's settings now, by name, such as the map */\n\tsettings: Record<string, string>\n\t/** Whether it takes no new games: stopping */\n\tdraining: boolean\n\t/** How its players are rated, on average, where the server keeps ratings (`Ratings`) */\n\trating?: number\n}\n\n/**\n * A kind of game a server lets players make a room of, as its list says it (`GET /games`'s `kinds`): what to ask\n * `POST /games` for (`{ kind: id, settings }`), what it is called, and the settings it offers (a map, among them)\n *\n * @beta\n */\nexport interface GameKindListing {\n\t/** The kind's id, which `POST /games` is asked for as `kind` */\n\tid: string\n\t/** What the kind is called for players */\n\tname: string\n\t/** Where to wait to be matched with others for it (`ws://host:port/<queue>`), and how many wait now, of how many it takes. None without matchmaking */\n\tqueue?: string\n\t/** How many players wait in the queue for this kind now */\n\twaiting?: number\n\t/** How many players it takes to make a room of this kind */\n\tneeded?: number\n\t/** The settings the kind offers by name, each with its label, its options and its default */\n\tsettings: Record<string, { label: string; options: string[]; default: string }>\n}\n"],"mappings":";;;;;;;AAu7BA,SAAgB,UAAqC,SAAwB,MAAkE;CAC9I,OAAO,QAAQ,SAAS;AACzB;;;;;;;;;AAmNA,IAAa,mBAAmB;;;;;;AAOhC,SAAgB,iBAAiB,MAAe,SAAA,IAA2C;CAC1F,OAAO,yDAAyD,OAAO,SAAS,WAAW,OAAO,UAAU,qBAAqB,OAAO;AACzI;;;;;;;;AASA,SAAgB,YAAY,MAAwE;CACnG,IAAI;CACJ,IAAI;EACH,UAAU,KAAK,MAAM,IAAI;CAC1B,QAAQ;EACP;CACD;CACA,IAAI,OAAO,YAAY,YAAY,YAAY,QAAQ,MAAM,QAAQ,OAAO,GAAG,OAAO,KAAA;CACtF,MAAM,EAAE,SAAS;CACjB,OAAO,OAAO,SAAS,WAAY,UAAyD,KAAA;AAC7F;;;;;;AAOA,IAAa,kBAAkB,UAAoC,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK"}

package/dist/session/remote.d.ts

@@ -1,7 +1,8 @@
 import { type GameHostMessage, type HostToPlayer, type ServerToPlayer } from './wire';
 import type { GameMap, MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map';
-import type { PlayerId } from '#engine/entity';
-import type { GameModule } from '#engine/game';
+import type { EntityId, PlayerId } from '#engine/entity';
+import { type FormationUnit } from '#engine/formation';
+import type { Rules } from '#engine/game';
 import { BuildGrid } from '#engine/grid';
 import type { Vec2 } from '#engine/math';
 import type { Navigation } from '#engine/navigation/navigation';
@@ -17,11 +18,13 @@ import { type CampInfo, type FogState, type GameSession, type PlayerCommand, typ
  * @beta
  */
 export interface Transport {
+    /** Sends one text message to the other end */
     send(message: string): void;
     /** What comes in from the other end. One handler: a later one takes the place of the one before */
     onMessage(handler: (message: string) => void): void;
     /** Told when the other end closes */
     onClose(handler: () => void): void;
+    /** Closes the connection; the other end's `onClose` handler is told */
     close(): void;
 }
 /**
@@ -32,6 +35,7 @@ export interface Transport {
 export interface LoopbackEnd extends Transport {
     /** Characters sent, a byte each as the JSON goes over a WebSocket of mostly ASCII */
     readonly bytesSent: number;
+    /** How many messages have been sent through this end */
     readonly messagesSent: number;
 }
 /**
@@ -85,13 +89,17 @@ export interface PlayerLimits {
 export interface HostTiming {
     /** When the counting started, `performance.now()` */
     since: number;
+    /** How many simulation ticks were stepped in the period */
     ticks: number;
     /** Milliseconds the ticks took, added up, and the longest */
     tickTime: number;
+    /** The longest a single tick took, in milliseconds */
     tickMax: number;
     /** Rounds of sending everyone what changed */
     sends: number;
+    /** Milliseconds the rounds of sending took, added up */
     sendTime: number;
+    /** The longest a single round of sending took, in milliseconds */
     sendMax: number;
     /**
      * Where the sending's milliseconds went, added up over the seats: what each player may know taken from the world
@@ -115,14 +123,18 @@ export interface HostTiming {
     bytes: number;
     /**
      * Those characters by what they carry, when the host counts them (`SessionHostOptions.bytesByKey`): each field of
-     * the entities added and changed (`entity.hp`, `entity.own.abilities`), the other parts (`rest.players`, `rest.fog`),
+     * the entities added and changed (`entity.health`, `entity.own.abilities`), the other parts (`rest.players`, `rest.fog`),
      * `events`, `removed`, and the rest (ids, brackets) as `other`. They add up to `bytes`
      *
      * @beta
      */
     keys?: Record<string, number>;
 }
-/** @beta */
+/**
+ * What a `SessionHost` is made with: its send rate, catching-up limit, watchdog and error callbacks and whether it owns its world
+ *
+ * @beta
+ */
 export interface SessionHostOptions {
     /** Snapshots a second sent to each player, at most: the simulation runs at its tick rate all the same. 20 when left out */
     sendRate?: number;
@@ -199,6 +211,7 @@ export interface SessionHostOptions {
  * @beta
  */
 export declare class SessionHost {
+    /** The world the host steps and sends its players views of */
     readonly world: World;
     private readonly seats;
     private accumulator;
@@ -208,7 +221,9 @@ export declare class SessionHost {
     private readonly sendEvery;
     /** Simulation speed multiplier, 0 pauses */
     speed: number;
-    constructor(world: World, options?: SessionHostOptions);
+    constructor(
+    /** The world the host steps and sends its players views of */
+    world: World, options?: SessionHostOptions);
     private readonly onError?;
     private readonly stopFailed;
     private readonly dropSilentAfter;
@@ -227,13 +242,16 @@ export declare class SessionHost {
      * of chat and their pings, which go to who watches alone (`observers`, said by `name`); and with `observer` they see
      * everything, from `player`'s side. `allow` decides on each command before it goes in: a limit of how many, a game
      * paused. One it lets go is answered, refused (the `command` event of its `seq`): with what it gives for why, or
-     * `cannotDoThat` for `false`
+     * `cannotDoThat` for `false`. `inOrder` for a transport that loses nothing and keeps the order (a worker's messages):
+     * each frame is the base of the next once it went, with no answer waited for, so the player always gets what changed
+     * since the frame it has, and takes it in without looking over the rest
      */
     connect(player: PlayerId, transport: Transport, options?: {
         readOnly?: boolean;
         observer?: boolean;
         allow?: () => boolean | MessageRef;
         name?: string;
+        inOrder?: boolean;
     }): void;
     /** The ground the world started as, whole, in parts small enough to go one at a time: made the first time one is asked for */
     private groundParts;
@@ -300,6 +318,7 @@ export declare class SessionHost {
     private forget;
     /** Runs the world by the clock, `rate` updates a second, until `stop` or `dispose` */
     start(rate?: number): void;
+    /** Stops stepping the world by the clock; does nothing if it was not started */
     stop(): void;
     /** Whether it runs by the clock */
     get running(): boolean;
@@ -330,6 +349,18 @@ export declare class ClientWorld {
     resourceAt(kind: string, cellX: number, cellZ: number, w: number, d: number): boolean;
     /** Brings the structures up to date with a snapshot: those in it stand, those no longer in it are gone */
     sync(snapshot: Snapshot): void;
+    /**
+     * Brings the structures up to date with a snapshot made on the one before it, from what came and went alone: the
+     * last `added` of its entities (`apply` puts those that came after the rest), and the ids of those `removed`. What
+     * `sync` does, without looking over every entity of the map
+     */
+    change(snapshot: Snapshot, added: number, removed: readonly number[]): void;
+    /** Puts a structure on the map, where it is not on it yet: whether it was put */
+    private stand;
+    /** Takes a structure off the map */
+    private release;
+    /** Takes off those gone, gives the ground back to what stood on them, and has the navmesh take in what changed */
+    private settle;
 }
 /**
  * The host said no, with why: to come back to a game that is over, or a player let go. Trying again does not help
@@ -337,8 +368,11 @@ export declare class ClientWorld {
  * @beta
  */
 export declare class SessionRefused extends Error {
+    /** Why the host refused, in words */
     readonly reason: string;
-    constructor(reason: string);
+    constructor(
+    /** Why the host refused, in words */
+    reason: string);
 }
 /**
  * A player's seat at a world that runs elsewhere, over a transport (see `connect`). It rebuilds what the host sends
@@ -361,16 +395,27 @@ export declare class RemoteSession implements GameSession {
     /** The debug tools' view of the world, for a player the host lets use them (the welcome's `debug`) */
     protected get debugView(): SessionDebug | undefined;
     private readonly remoteDebug?;
+    /** The player this seat plays, as the host welcomed it */
     readonly playerId: PlayerId;
+    /** The team of that player; updated when a snapshot says it changed */
     team: number;
+    /** The ground, built from the welcome and the parts the host sent */
     readonly terrain: Terrain;
+    /** The map's look (sky, mist, light) from the welcome, when it has one */
     readonly environment?: MapEnvironment;
+    /** The map's scenery objects from the welcome */
     readonly doodads: readonly MapDoodad[];
+    /** The map's named regions from the welcome */
     readonly regions: readonly MapRegion[];
+    /** The map's named camera positions from the welcome */
     readonly cameras: readonly MapCamera[];
+    /** The map's named paths from the welcome */
     readonly paths: readonly MapPath[];
+    /** The definitions of the game, from the rules the player connected with */
     readonly registry: Registry;
+    /** Simulation ticks per second the host runs at, from the welcome */
     readonly tickRate: number;
+    /** How far, 0..1, the shown tick is between the last two snapshots, for blending the drawing */
     alpha: number;
     /** What the player knows by tick, for the deltas to come: from the base of the last one on */
     private readonly frames;
@@ -391,6 +436,8 @@ export declare class RemoteSession implements GameSession {
     protected interval: number;
     /** How far off the time snapshots arrive at is from the ticks between them, in seconds, evened out */
     protected jitter: number;
+    /** Seconds between two snapshots' arrivals, evened out: a seek's come as often as any, their ticks far apart */
+    private gap;
     /** When the last snapshot arrived, and its tick */
     private arrival?;
     constructor(transport: Transport, welcome: Extract<GameHostMessage, {
@@ -422,7 +469,7 @@ export declare class RemoteSession implements GameSession {
      * Takes a new version of the game into this screen's registry (hot reload, a game in a worker): its definitions as
      * the new version has them, what the host changed of them while it ran over them again
      */
-    takeGame(game: GameModule): void;
+    takeGame(game: Rules): void;
     /** Takes in a message of the host's: what the transport hands it, and what came in while the session was made */
     receive(message: HostToPlayer): void;
     /**
@@ -470,6 +517,7 @@ export declare class RemoteSession implements GameSession {
      */
     get waiting(): number;
     private takeFog;
+    /** The newest snapshot the host sent */
     snapshot(): Snapshot;
     /** The tick the screen is shown at, between two snapshots: behind the newest by `delay` */
     get shownAt(): number;
@@ -482,10 +530,13 @@ export declare class RemoteSession implements GameSession {
      * between the last two (`alpha`). The time is the host's: the clock follows the snapshots, not the other way around
      */
     update(dt: number): Snapshot[];
+    /** Sends a command to the host and returns the number it was given, which the host's answer names; does nothing once closed */
     send(command: PlayerCommand): number;
     /** The number of the last command sent */
     private lastSeq;
+    /** The team's fog as built from what the host sent */
     fog(): FogState;
+    /** The creep camps as the newest frame has them */
     camps(): readonly CampInfo[];
     /**
      * Whether the player could build this here, as far as they can tell: on their copy of the map, with the structures
@@ -495,18 +546,29 @@ export declare class RemoteSession implements GameSession {
     /** Which cells of a building's ground are in the way, as `canPlace` sees them: on the player's copy of the map, explored */
     placeCells(unitType: string, point: Vec2): readonly boolean[] | undefined;
     /** The way a unit would walk, on the player's copy of the map: around the structures they know, and no others */
+    /** Where a group would stand sent to a point in a formation, `rows` when none is named: the rules are the host's (`GameSession.formationPlaces`) */
+    formationPlaces(units: readonly (FormationUnit & {
+        readonly flying?: boolean;
+    })[], point: Vec2, facing?: number, formation?: string): Map<EntityId, Vec2>;
+    /** A path over the ground the player has, on the air layer when `flying`; null when there is none */
     findPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null;
+    /** Stops pinging, closes the connection and frees the navigation made from the ground */
     dispose(): void;
 }
-/** @beta */
+/**
+ * What `connect` is given: the rules, navigation settings, maps, limits and a handler for the host's other messages
+ *
+ * @beta
+ */
 export interface ConnectOptions {
     /**
      * The game module the host runs: the player's side needs its data, and checks it is the very same version. Or the
      * games the player has, by id, for a host that says which it runs
      */
-    game: GameModule | Record<string, GameModule>;
+    rules: Rules | Record<string, Rules>;
+    /** Settings for the navigation the player's side builds of the ground */
     navigation?: RecastNavigationOptions;
-    /** The maps the welcome's ground may be one of (S36): the game's own (`GameModule.maps`) when left out */
+    /** The maps the welcome's ground may be one of (S36): the game's own (`Rules.maps`) when left out */
     maps?: readonly GameMap[];
     /**
      * What the player's side keeps and how often it asks: `pingEvery`, `maxJitter`, `keptSnapshots`,
@@ -523,7 +585,7 @@ export interface ConnectOptions {
  * made of. Fails when the host runs another version of the game, or of the engine's wire (`PROTOCOL_VERSION`), and
  * when the connection closes before the session is made: while the map is made from the welcome too
  *
- * @beta
+ * @public
  */
 export declare function connect(transport: Transport, options: ConnectOptions): Promise<RemoteSession>;
 /** `connect`, for a session of a kind of its own: `make` is given what a `RemoteSession` is made of */