@v12-engine/engine 0.1.1 → 0.4.0

package/dist/session/protocol.d.ts

@@ -1,10 +1,12 @@
+import type { CameraOrder, SeatCamera } from '#engine/cameraOrders';
 import type { SystemTiming } from '#engine/scheduler';
 import type { DataKind, DataValues } from '#engine/gameData';
 import type { Logger } from '#engine/log';
 import type { Command, ModCommand } from '#engine/commands';
-import type { ChatAudience, PingKind } from '#engine/talk';
-import type { Cost, DamageType, ResourceKind, Stats } from '#engine/defs';
-import type { PlayerId } from '#engine/entity';
+import type { ChatAudience, PingId } from '#engine/talk';
+import type { Cost, DamageType, EffectShape, ResourceId, Stats } from '#engine/defs';
+import type { EntityId, PlayerId } from '#engine/entity';
+import type { FormationUnit } from '#engine/formation';
 import type { Vec2 } from '#engine/math';
 import type { SaidLine } from '#engine/dialog';
 import type { Message } from '#engine/messages';
@@ -27,16 +29,28 @@ import type { ScoreLineState, ScoreState } from '#engine/score';
  * simulation runs on a server, and nothing on the client has to change for that.
  * Everything in here is plain data for that reason: it has to survive being sent.
  */
-/** @beta */
+/**
+ * An item in a building's production queue, as the screen is told of it
+ *
+ * @beta
+ */
 export interface QueueItemState {
+    /** What the item is: a unit being trained, an upgrade researched, a hero revived or a morph into another type */
     kind: 'unit' | 'upgrade' | 'revive' | 'morph';
+    /** The id of the unit type, upgrade or hero the item makes */
     id: string;
     /** 0..1 */
     progress: number;
 }
-/** @beta */
+/**
+ * An ability of the player's own unit as the owner's screen is told of it: level, cooldown, charges and autocast
+ *
+ * @beta
+ */
 export interface AbilityInfo {
+    /** The ability's id */
     id: string;
+    /** The ability's level, from 1 */
     level: number;
     /** Seconds until it can be used again */
     cooldown: number;
@@ -44,15 +58,29 @@ export interface AbilityInfo {
     charges?: number;
     /** Seconds until the next use is back, while it holds fewer than it can */
     refill?: number;
+    /** Whether the ability is set to cast by itself */
     autocast: boolean;
     /**
      * What the game's `canCast` hook decided, where it is not what the declared costs say: a reason it cannot be used
      * now, or null for one it can be used for all that ("free while Clearcasting"). Left out when there is nothing to add
      */
     decided?: Message | null;
+    /** The game's own state of the ability (`AbilityState.data`), where it has any */
+    data?: Record<string, unknown>;
+    /**
+     * Its window to be cast again, while it is open (`AbilityDef.recast`): seconds `left` of `total`, and how many
+     * recasts are left in it (`count`)
+     *
+     * @beta
+     */
+    recast?: {
+        left: number;
+        total: number;
+        count: number;
+    };
 }
 /**
- * An ability of a unit as everyone who sees it may be told (`GameRules.hud.shareAbilities`): what it is and its
+ * An ability of a unit as everyone who sees it may be told (`RuleSettings.hud.shareAbilities`): what it is and its
  * level, and how much of its cooldown is left where the rules share that too
  *
  * @beta
@@ -76,7 +104,9 @@ export interface SharedAbility {
 export interface CarriedItem {
     /** Which one of the unit's items, for commands */
     id: number;
+    /** The item type's id */
     item: string;
+    /** Uses left of the item */
     charges: number;
     /** Seconds until it can be used again */
     cooldown: number;
@@ -107,7 +137,7 @@ export interface GatheringInfo {
     /** How much of it */
     carrying: number;
     /** What it is that it carries, or last gathered. Null for a worker that has not gathered anything yet */
-    kind: ResourceKind | null;
+    kind: ResourceId | null;
 }
 /**
  * What a building's owner and their allies are told of what it makes (`productionQueue`'s snapshot): its queue and where
@@ -131,27 +161,52 @@ export interface ProductionInfo {
  * @beta
  */
 export interface GroundItemState {
+    /** The ground item's id, which a pick-up order names */
     id: number;
+    /** The item type's id */
     item: string;
+    /** Where it lies, east-west */
     x: number;
+    /** Where it lies, north-south */
     z: number;
 }
-/** @beta */
+/**
+ * One item type a shop has for sale, with how many are left and how far the next is
+ *
+ * @beta
+ */
 export interface StockInfo {
+    /** The item type's id */
     item: string;
     /** How many are left. Left out for what a shop never runs out of */
     count?: number;
     /** 0..1 towards the next one, when the shop is not full */
     restock: number;
 }
+/**
+ * A purchase of a hero's that its player may still undo (`purchases`, `undoBuy`), with the seconds left to
+ *
+ * @beta
+ */
+export interface PurchaseInfo {
+    /** The purchase's id, what the `undoBuy` command names it by */
+    id: number;
+    /** The item type's id */
+    item: string;
+    /** Whole seconds left to undo it */
+    left: number;
+}
 /**
  * An ability a hero can put points into
  *
  * @beta
  */
 export interface LearnableInfo {
+    /** The ability's id */
     id: string;
+    /** The level it is at now, 0 when not learned */
     level: number;
+    /** The highest level the ability can be taken to */
     maxLevel: number;
     /** Hero level needed for the next level of the ability */
     needs: number;
@@ -177,17 +232,23 @@ export interface XpInfo {
  * @beta
  */
 export interface HeroSummary {
+    /** The hero's entity id */
     id: number;
+    /** The hero's unit type id */
     type: string;
+    /** The hero's level */
     level: number;
+    /** Whether the hero is alive; a fallen one is in the row all the same */
     alive: boolean;
     /** 0..1 */
-    hp: number;
+    health: number;
+    /** The hero's mana now */
     mana: number;
+    /** Skill points the hero has not spent */
     points: number;
-    /** 0..1 while being brought back: at an altar, or coming back by itself (`withRespawn`) */
+    /** 0..1 while being brought back: at an altar, or coming back by itself (`respawnPack`) */
     reviving?: number;
-    /** Seconds until it comes back by itself, while it waits to (`withRespawn`) */
+    /** Seconds until it comes back by itself, while it waits to (`respawnPack`) */
     respawnIn?: number;
     /** What bringing it back would cost */
     reviveCost?: Cost;
@@ -208,23 +269,37 @@ export interface OwnEntityState {
     build?: string;
     /** Orders in the queue, the current one included */
     orders: number;
+    /** Whether the unit is set not to fight back or chase (passive stance) */
     passive: boolean;
+    /** Whether the unit is in a fight now */
     fighting: boolean;
     /** Where it is walking to right now */
     goal?: Vec2;
     /** Destinations of the orders waiting in the queue: none while nothing waits */
     waypoints?: Vec2[];
+    /** The unit's abilities with their cooldowns and charges, for its owner's command card */
     abilities?: AbilityInfo[];
 }
-/** @beta */
+/**
+ * A unit, building, resource or other entity as the screen is told of it
+ *
+ * @beta
+ */
 export interface EntityState {
+    /** The entity's id, which commands and orders name it by */
     id: number;
+    /** The id of its unit type */
     type: string;
+    /** The player who owns it */
     owner: PlayerId;
+    /** Where it stands, east-west, in world units */
     x: number;
+    /** Where it stands, north-south, in world units */
     z: number;
+    /** The way it faces, in radians; 0 is along +z */
     facing: number;
-    hp: number;
+    /** Its health now */
+    health: number;
     /** The stats that are not what its type starts with. Whoever sees a unit can tell what it is capable of */
     stats?: Partial<Stats>;
     /** What its shields still hold */
@@ -238,8 +313,10 @@ export interface EntityState {
     /** False for a structure that is out of sight and shown the way it was last seen */
     visible: boolean;
     /** Left out when it is what the unit type says */
-    maxHp?: number;
+    maxHealth?: number;
+    /** Its mana now; left out when it has none */
     mana?: number;
+    /** Its largest mana when that is not what its type says */
     maxMana?: number;
     /** Ids of the buffs on it */
     buffs?: string[];
@@ -248,14 +325,14 @@ export interface EntityState {
     /**
      * Seconds left of each of its `buffs`, in their order (whole seconds, rounded up, from a host: the plate counts
      * down between); -1 for one kept up by an aura or a passive (`BuffInstance.kept`) or that lasts until it is
-     * taken off. Where the rules share them (`GameRules.hud.shareBuffTimes`)
+     * taken off. Where the rules share them (`RuleSettings.hud.shareBuffTimes`)
      *
      * @beta
      */
     buffTimes?: number[];
     /**
      * The abilities it has learned, for whoever sees it, its side's or not, where the rules share them
-     * (`GameRules.hud.shareAbilities`). Its side has them in `own.abilities` all the same
+     * (`RuleSettings.hud.shareAbilities`). Its side has them in `own.abilities` all the same
      *
      * @beta
      */
@@ -266,34 +343,58 @@ export interface EntityState {
     on?: number;
     /** Doing nothing until woken, like a creep sleeping through the night */
     asleep?: boolean;
+    /**
+     * It has an order to carry out: left out while it stands idle. What a cinematic's waits go by (`arrived`), for any
+     * unit it directs; anyone in sight of it can see it walk or swing
+     */
+    busy?: boolean;
     /** How big it is drawn, when that is not 1 */
     scale?: number;
     /** Which of the models of its type it is drawn with, when the map says */
     look?: string;
+    /** Drawn as this type, in this owner's colour, while it is what its own type and owner say (`SpawnOptions.looksLike`) */
+    likeness?: {
+        type: string;
+        owner: PlayerId;
+    };
     /** Seconds left and seconds in all, for what is gone by itself after a while, like a ward */
     lifetime?: {
         left: number;
         total: number;
     };
-    /** Invisible to enemies right now. Whoever gets this sees it all the same: it is theirs, or they found it */
+    /**
+     * Invisible to enemies right now, or camouflaged (`BuffDef.camouflage`: seen by them only from near). Whoever gets this
+     * sees it all the same: it is theirs, or they found it, or they are near
+     */
     unseen?: boolean;
     /** Components of game modules and mods that are sent to this player (see `Component.replicate`), by id */
     components?: Record<string, unknown>;
     /** The name the map or the rules gave it (`world.named`), for whoever knows of it: "the gate", "the hero" */
     name?: string;
+    /** What only its owner and their allies are told of it */
     own?: OwnEntityState;
 }
-/** @beta */
+/**
+ * A player as the screen is told of them: name, team, colour, resources and their standing to the player it is for
+ *
+ * @beta
+ */
 export interface PlayerState {
+    /** The player's id */
     id: PlayerId;
+    /** The name shown for the player */
     name: string;
+    /** The player's team number; players on one team are allies */
     team: number;
+    /** The player's colour as RGB, each 0..1 */
     color: [number, number, number];
+    /** Whether the player is a neutral one, owner of mines and the like */
     neutral: boolean;
     /** Whether they are the creeps: hostile to everyone, but no one's rival */
     creeps?: boolean;
     /** The race they play (`raceOf`): left out in a game without races */
     race?: string;
+    /** Whether the player is out of the game */
     defeated: boolean;
     /** What they are to the player the snapshot is for: by their teams, or as the rules set it (`setRelation`) */
     relation: 'self' | 'ally' | 'enemy' | 'neutral';
@@ -308,10 +409,10 @@ export interface PlayerState {
     /** Only filled in for the player the snapshot is for */
     own?: {
         /** What the player has of each resource, by resource id */
-        resources: Record<ResourceKind, number>;
+        resources: Record<ResourceId, number>;
         supplyUsed: number;
         supplyCap: number;
-        /** The game's other pools of supply, by name (`GameRules.supply.pools`): left out in a game with none */
+        /** The game's other pools of supply, by name (`RuleSettings.supply.pools`): left out in a game with none */
         supplies?: Record<string, {
             used: number;
             cap: number;
@@ -343,15 +444,25 @@ export interface PlayerState {
         availability?: Record<string, boolean>;
     };
 }
-/** @beta */
+/**
+ * A projectile in flight as the screen is told of it: where it is, who shot it and what kind of damage it carries
+ *
+ * @beta
+ */
 export interface ProjectileState {
+    /** The projectile's id */
     id: number;
+    /** Where it is, east-west, in world units */
     x: number;
+    /** Where it is, north-south, in world units */
     z: number;
     /** The type of what shot it, known even when the shooter is out of sight: what it looks like */
     kind: string;
+    /** The player whose unit shot it */
     owner: PlayerId;
+    /** Whether the hit it carries is a critical one */
     crit: boolean;
+    /** The type of damage it deals on landing */
     damageType: DamageType;
     /** A look the rules gave it (see `Projectile.look`) */
     look?: string;
@@ -361,6 +472,7 @@ export interface ProjectileState {
     target?: number;
     /** Where it was fired from and where it comes down, for shots that are lobbed at a spot */
     from?: Vec2;
+    /** Where a lobbed shot comes down */
     to?: Vec2;
 }
 /**
@@ -369,13 +481,19 @@ export interface ProjectileState {
  * @beta
  */
 export interface MissileState {
+    /** The missile's id */
     id: number;
+    /** The id of the ability that sent it */
     ability: string;
+    /** The level of the ability when it was sent */
     level: number;
     /** Entity that sent it, when that one is known to the player */
     source?: number;
+    /** Where it is, east-west, in world units */
     x: number;
+    /** Where it is, north-south, in world units */
     z: number;
+    /** How far from its centre it hits things, in world units */
     radius: number;
     /** The way it is heading, in radians */
     heading: number;
@@ -385,6 +503,61 @@ export interface MissileState {
     progress?: number;
     /** How high above the ground its arc carries it now, for what is thrown in one (`EffectFields.arc`) */
     arc?: number;
+    /** On its way back to the caster (`EffectFields.returns`): what is drawn of it may face the way it went out */
+    returning?: boolean;
+    /** Its owner turns it as it flies (`EffectFields.steer`): told to its side alone, whose screen steers it (the `steer` command) */
+    steered?: boolean;
+    /**
+     * Which effect of the ability it is, by its place there (`effectIndex`): what the screen draws it with
+     * (`AbilityLook.effects`). Left out for one not written in the ability
+     *
+     * @beta
+     */
+    effect?: number;
+}
+/**
+ * An area of an ability on the ground the player is told of (`Snapshot.areas`): a zone for its life, or a delayed blast
+ * until it goes off (a telegraph), with its shape (`EffectArea`), its place and the seconds left
+ *
+ * @beta
+ */
+export interface AreaState {
+    /** A zone (`zone`), or effects that wait to go off there (`after`): `delayed` */
+    kind: 'zone' | 'delayed';
+    /** A zone's id, the same as long as it lasts. None for a delayed blast */
+    id?: number;
+    /** The ability whose it is */
+    ability: string;
+    /** The ability's level */
+    level: number;
+    /** Which effect of the ability it is (the `zone`, the `after`), by its place there (`effectIndex`) */
+    effect?: number;
+    /** Who cast it, where the player knows them */
+    source?: number;
+    /** Its shape: circle, cone, line, rect, ring, arc or cross (`EffectCommon.shape`) */
+    shape: EffectShape;
+    /** Where it is laid: its middle (circle, ring, rect, cross), or where it goes off from (cone, line, arc) */
+    x: number;
+    /** Where it is laid along z */
+    z: number;
+    /** The way it faces, radians as a unit's `facing` */
+    heading: number;
+    /** Of a circle, a ring and an arc: how far out it reaches */
+    radius: number;
+    /** Of a cone, a line, a rect and a cross: how long it is */
+    length?: number;
+    /** Of a line, a rect and a cross: how far out on either side; of a ring and an arc, how thick */
+    width?: number;
+    /** Of a cone and an arc: how wide it opens, in radians */
+    angle?: number;
+    /** Seconds left: of a zone, until it ends; of a delayed blast, until it goes off */
+    left: number;
+    /** Of the player's side */
+    ours?: boolean;
+    /** The unit a zone goes with (`follow`) */
+    follows?: number;
+    /** The name a delayed blast's arrival goes by (`impact`) */
+    impact?: string;
 }
 /**
  * What the players are told happened during a tick, which cannot be read from the state afterwards: each kind by its
@@ -420,13 +593,17 @@ export interface SessionEvents {
     /**
      * Cells of one of the game's layers (`Terrain.cells`) were set to `value` (`world.setCells`): the session's ground has
      * it already, for the screen to draw again. Told where the player's team sees the cells, and as they come into its sight
-     * where it does not (`TeamMemory.cells`): an observer is told of all
+     * where it does not (`TeamMemory.cells`): an observer is told of all. `over`: the seconds it eases into the value
+     * over, where the rules said (grass growing back); not said as cells come into sight. `seen`: they came into sight
+     * as they are, changed out of it before (a fire that burnt there a while): not as they change now
      */
     cells: {
         type: 'cells';
         layer: string;
         at: number[];
         value: number;
+        over?: number;
+        seen?: true;
     };
     /**
      * A part of the ground was reshaped (`world.reshapeGround`, the editor's Play here): the session's ground has it
@@ -449,6 +626,22 @@ export interface SessionEvents {
         z: number;
         entered?: boolean;
     };
+    /**
+     * A gust of wind the rules blew at a place the player sees (`gust`, `WindGust`): where, how far around, how hard,
+     * which way (outwards from its middle when left out) and for how long. For the screen to bend the grass and bushes
+     * there (`client.gust`)
+     *
+     * @beta
+     */
+    gust: {
+        type: 'gust';
+        x: number;
+        z: number;
+        radius: number;
+        strength: number;
+        around?: number;
+        lasts?: number;
+    };
     /** What the map looks like beyond its ground, as it is now (`world.setEnvironment`), and the seconds to ease into it over */
     environment: {
         type: 'environment';
@@ -473,6 +666,11 @@ export interface SessionEvents {
         target?: number;
         weapon?: number;
     };
+    /** An attack called off before its blow, of a unit the player sees (`swingCancelled`): the screen cuts it to the walk */
+    attackCancelled: {
+        type: 'attackCancelled';
+        id: number;
+    };
     /** Damage dealt to an entity the player sees: by whom when the player sees that too, with what, how much */
     damage: {
         type: 'damage';
@@ -669,6 +867,12 @@ export interface SessionEvents {
         z: number;
         duration: number;
     };
+    /** A wind-up called off before it went off (stunned, killed, ordered elsewhere): what it showed goes. `ability` where known */
+    castCancelled: {
+        type: 'castCancelled';
+        id: number;
+        ability?: string;
+    };
     /** `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 */
     cast: {
         type: 'cast';
@@ -681,7 +885,10 @@ export interface SessionEvents {
         radius?: number;
         charged?: boolean;
     };
-    /** What an ability set off arrived somewhere: a missile hit, a rush ended, the time was up. `id`: the caster, where the player sees it */
+    /**
+     * What an ability set off arrived somewhere: a missile hit, a rush ended, the time was up. `id`: the caster, where the
+     * player sees it. `from`: where it went off from, when not the caster (a ball, a shadow: `EffectContext.origin`)
+     */
     strike: {
         type: 'strike';
         id?: number;
@@ -692,6 +899,12 @@ export interface SessionEvents {
         target?: number;
         radius?: number;
         impact?: string;
+        from?: {
+            x: number;
+            z: number;
+        };
+        /** Which effect of the ability arrived (a missile, a delay, a zone at its end), by its place there (`effectIndex`) */
+        effect?: number;
     };
     /** Something to tell the player. The client finds the words for it, see `Message` */
     message: {
@@ -736,8 +949,12 @@ export interface SessionEvents {
         cue: string;
         params?: Record<string, unknown>;
     };
+    /** The rules pan or shake this player's camera (see `cameraFor`) */
+    camera: {
+        type: 'camera';
+    } & Pick<CameraOrder, 'pan' | 'shake'>;
     /**
-     * One of the view's effects plays, as the rules said (`world.effect`): `id` is the rules' handle on it, `fx` its name,
+     * One of the view's effects plays, as the rules said (`world.fx`): `id` is the rules' handle on it, `fx` its name,
      * at a place (`x`, `y`, `z`) or on an entity (`on`, at a `point`), its knobs, the seed of its random parts
      */
     fx: {
@@ -752,8 +969,14 @@ export interface SessionEvents {
         params?: Record<string, unknown>;
         seed: number;
         overFog?: boolean;
+        /** The other end, for one drawn between two (`FxOptions.toward`): an entity, where the player knows it */
+        toward?: number;
+        /** Or a place, east-west */
+        tx?: number;
+        /** And north-south */
+        tz?: number;
     };
-    /** An effect the rules played stops (`world.stopEffect`) */
+    /** An effect the rules played stops (`world.stopFx`) */
     fxStop: {
         type: 'fxStop';
         id: number;
@@ -766,7 +989,7 @@ export interface SessionEvents {
         player: PlayerId;
         x: number;
         z: number;
-        kind: PingKind;
+        kind: PingId;
         to: ChatAudience;
         by?: string;
     };
@@ -804,6 +1027,7 @@ export type Outcome = 'playing' | 'victory' | 'defeat';
  * @beta
  */
 export interface Snapshot {
+    /** The tick number the snapshot was taken at */
     tick: number;
     /**
      * The switches of the debug tools as they stand, for a player who may use them (`world.debugPlayers`): `explored`,
@@ -818,29 +1042,44 @@ export interface Snapshot {
     };
     /** Hour of the day, 0..24, in a game with days and nights */
     hour?: number;
+    /** How the game stands for the player: still playing, a victory or a defeat */
     outcome: Outcome;
+    /** The entities the player may know of, as of this tick */
     entities: EntityState[];
+    /** Every player of the game, with what the receiving player may know of each */
     players: PlayerState[];
+    /** Projectiles in flight the player can see */
     projectiles: ProjectileState[];
+    /** Missiles in flight the player can see */
     missiles: MissileState[];
     /** Items on the ground, where the player can see the ground */
     items: GroundItemState[];
     /** Spots someone sees for a while. Everyone can tell, not only whoever it is */
     reveals: RevealState[];
+    /**
+     * The areas of abilities on the ground the player is told of: zones and delayed blasts, their side's and others' where
+     * they see them. None when left out
+     *
+     * @beta
+     */
+    areas?: AreaState[];
     /** Corpses where the player can see the ground, by the id of who died there (see `raiseDead`). None when left out */
     corpses?: CorpseState[];
+    /** What happened since the last snapshot that the player is told of, oldest first */
     events: SessionEvent[];
-    /** What the game tells the player about itself, see `GameModule.report` */
+    /** 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 */
+    camera?: SeatCamera;
+    /** What the game tells the player about itself, see `Rules.report` */
     report?: Record<string, unknown>;
     /**
-     * The score of the players the player is told of (`GameRules.score`: `live`, then `end`), told again at most once
+     * The score of the players the player is told of (`RuleSettings.score`: `live`, then `end`), told again at most once
      * in `refresh` seconds. None in a game that counts nothing
      *
      * @beta
      */
     score?: ScoreState;
     /**
-     * The score's timeline, of the same players: told again at each point of it (`ScoreRules.every`)
+     * The score's timeline, of the same players: told again at each point of it (`ScoreSettings.every`)
      *
      * @beta
      */
@@ -852,16 +1091,28 @@ export interface Snapshot {
  * @beta
  */
 export interface CorpseState {
+    /** The id the unit had when alive */
     id: number;
+    /** The unit type it was */
     type: string;
+    /** Where it lies, east-west */
     x: number;
+    /** Where it lies, north-south */
     z: number;
 }
-/** @beta */
+/**
+ * A spot revealed to a team for a while, as the screen is told of it
+ *
+ * @beta
+ */
 export interface RevealState {
+    /** The reveal's id */
     id: number;
+    /** Centre of the revealed spot, east-west */
     x: number;
+    /** Centre of the revealed spot, north-south */
     z: number;
+    /** How far from the centre it reveals, in world units */
     radius: number;
     /** Seconds it goes on */
     left: number;
@@ -875,14 +1126,24 @@ export interface RevealState {
  * @beta
  */
 export interface MineInfo {
+    /** The mine's entity id */
     id: number;
+    /** Where it stands, east-west */
     x: number;
+    /** Where it stands, north-south */
     z: number;
 }
-/** @beta */
+/**
+ * A camp of creeps as the player knows it: where, how strong and whether it is cleared
+ *
+ * @beta
+ */
 export interface CampInfo {
+    /** The camp's id */
     id: number;
+    /** Where its middle is, east-west */
     x: number;
+    /** Where its middle is, north-south */
     z: number;
     /** Levels of its creeps added up */
     level: number;
@@ -895,13 +1156,17 @@ export interface CampInfo {
  * @beta
  */
 export interface FogState {
+    /** Cells across the map, east-west */
     width: number;
+    /** Cells across the map, north-south */
     depth: number;
     /** Changes whenever the arrays did */
     version: number;
     /** The whole map is lit, a debug switch */
     revealed: boolean;
+    /** Per cell, row by row: non-zero where the team sees the cell now */
     visible: Uint8Array;
+    /** Per cell, row by row: non-zero where the team has seen the cell at some time */
     explored: Uint8Array;
 }
 type WithoutPlayer<T> = T extends unknown ? Omit<T, 'player'> : never;
@@ -1039,7 +1304,9 @@ export interface SessionComputer {
  * @beta
  */
 export interface GameSession {
+    /** The player this seat plays, or watches from the side of */
     readonly playerId: PlayerId;
+    /** The team of that player */
     readonly team: number;
     /** The map and the game data are the same for everyone and known up front */
     readonly terrain: Terrain;
@@ -1056,7 +1323,9 @@ export interface GameSession {
     readonly cameras: readonly MapCamera[];
     /** The paths of the map (a road), for the screen: a cinematic's camera on a rail along one (see `MapPath`) */
     readonly paths: readonly MapPath[];
+    /** The definitions of the game the session runs, the same for everyone */
     readonly registry: Registry;
+    /** Simulation ticks per second */
     readonly tickRate: number;
     /**
      * What the game says about what it does (`World.log`), where the session has it: a game played in the page. A
@@ -1078,7 +1347,9 @@ export interface GameSession {
     update(dt: number): Snapshot[];
     /** Sends a command, to be carried out at the next tick. What it gives is told back with how it went (a `command` event) */
     send(command: PlayerCommand): number;
+    /** The player's team's fog now, per cell */
     fog(): FogState;
+    /** The creep camps the player knows of, with whether each is cleared */
     camps(): readonly CampInfo[];
     /** Whether the player could build this here, as far as they can tell */
     canPlace(unitType: string, point: Vec2): boolean;
@@ -1088,6 +1359,15 @@ export interface GameSession {
      * the session does not say @beta
      */
     placeCells?(unitType: string, point: Vec2): readonly boolean[] | undefined;
+    /**
+     * Where a group of units would stand if sent to a point in a formation, turned to face a way (`facing`: the way a
+     * right-click was dragged): the ghosts of that drag. By the formation's id, or the one the rules would pick (the
+     * session's own where it knows the rules, `rows` where not). Worked out from what the player's screen knows, over the
+     * ground the player knows; the `formation` hook does not run in it @beta
+     */
+    formationPlaces?(units: readonly (FormationUnit & {
+        readonly flying?: boolean;
+    })[], point: Vec2, facing?: number, formation?: string): Map<EntityId, Vec2>;
     /** Route a unit would take, over the ground the player knows */
     findPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null;
     /**
@@ -1099,6 +1379,7 @@ export interface GameSession {
     readonly observer?: boolean;
     /** Milliseconds a message takes to the simulation and back, where it runs elsewhere. Nothing in the page */
     readonly ping?: number;
+    /** Stops the session and lets go of what it holds */
     dispose(): void;
 }
 /**
@@ -1118,15 +1399,23 @@ export declare const PROTOCOL_VERSION = 13;
  * @beta
  */
 export interface GameListing {
+    /** The room name to connect to (`ws://host:port/<room>`); empty for a server of one game */
     room: string;
+    /** The id of the game module the room runs */
     game: string;
+    /** The id of the mode the game runs */
     mode: string;
+    /** Where the game is: in its lobby, on, or ended */
     phase: 'lobby' | 'game' | 'ended';
     /** Seats players hold, seats nobody holds a player could, seats the computer plays */
     players: number;
+    /** Seats nobody holds that a player could take */
     free: number;
+    /** Seats the computer plays */
     computer: number;
+    /** Connections watching without a seat */
     watchers: number;
+    /** The game's settings now, by name, such as the map */
     settings: Record<string, string>;
     /** Whether it takes no new games: stopping */
     draining: boolean;
@@ -1140,12 +1429,17 @@ export interface GameListing {
  * @beta
  */
 export interface GameKindListing {
+    /** The kind's id, which `POST /games` is asked for as `kind` */
     id: string;
+    /** What the kind is called for players */
     name: string;
     /** 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 */
     queue?: string;
+    /** How many players wait in the queue for this kind now */
     waiting?: number;
+    /** How many players it takes to make a room of this kind */
     needed?: number;
+    /** The settings the kind offers by name, each with its label, its options and its default */
     settings: Record<string, {
         label: string;
         options: string[];