@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/session/protocol.d.ts

@@ -0,0 +1,1155 @@
+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 { Vec2 } from '#engine/math';
+import type { SaidLine } from '#engine/dialog';
+import type { Message } from '#engine/messages';
+import type { ObjectiveState, ObjectiveStatus } from '#engine/objectives';
+import type { ShownTimer } from '#engine/timers';
+import type { WorldSave } from '#engine/save';
+import type { Registry } from '#engine/registry';
+import type { Inspection, InspectTarget, LoggedEvent, WorldListing } from '#engine/inspect';
+import type { Lane } from '#engine/lanes';
+import type { MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map';
+import type { Terrain } from '#engine/terrain';
+import type { TerrainPatch } from '#engine/ground';
+import type { MessageKind } from '#engine/world';
+import type { ScoreLineState, ScoreState } from '#engine/score';
+/**
+ * What travels between the simulation and a player's screen.
+ *
+ * A client never touches the world. It gets snapshots of what its player is allowed
+ * to know and sends commands back. Today both ends live in the same page, later the
+ * 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 */
+export interface QueueItemState {
+    kind: 'unit' | 'upgrade' | 'revive' | 'morph';
+    id: string;
+    /** 0..1 */
+    progress: number;
+}
+/** @beta */
+export interface AbilityInfo {
+    id: string;
+    level: number;
+    /** Seconds until it can be used again */
+    cooldown: number;
+    /** Uses left, of an ability with charges, while it holds fewer than it can (all of them when left out: `chargesLeft`) */
+    charges?: number;
+    /** Seconds until the next use is back, while it holds fewer than it can */
+    refill?: number;
+    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;
+}
+/**
+ * An ability of a unit as everyone who sees it may be told (`GameRules.hud.shareAbilities`): what it is and its
+ * level, and how much of its cooldown is left where the rules share that too
+ *
+ * @beta
+ */
+export interface SharedAbility {
+    /** The ability's id */
+    id: string;
+    /** Its level: 1 and up, those not learned are not told */
+    level: number;
+    /**
+     * Seconds until it can be used again: with `shareAbilities: 'cooldowns'` alone. Whole seconds, rounded up, from a
+     * host (`quantize`): the plate counts down between
+     */
+    cooldown?: number;
+}
+/**
+ * Something a unit carries
+ *
+ * @beta
+ */
+export interface CarriedItem {
+    /** Which one of the unit's items, for commands */
+    id: number;
+    item: string;
+    charges: number;
+    /** Seconds until it can be used again */
+    cooldown: number;
+    /**
+     * Uses left of the ability it casts, where that has charges (`AbilityDef.charges`) and holds fewer than it can: all
+     * of them when left out. None, and it cannot be used until one comes back
+     */
+    uses?: number;
+}
+/**
+ * What everyone who sees a unit is told of its items (`inventorySlots`' snapshot): what it carries; its owner and their
+ * allies the slots too, for commands
+ *
+ * @beta
+ */
+export interface InventoryInfo {
+    /** The items it carries, by id: anyone who sees the unit sees that */
+    items: string[];
+    /** One entry per slot, null for the empty ones: for its owner and their allies */
+    slots?: (CarriedItem | null)[];
+}
+/**
+ * What a worker's owner and their allies are told of what it carries (`gathering`'s snapshot)
+ *
+ * @beta
+ */
+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;
+}
+/**
+ * What a building's owner and their allies are told of what it makes (`productionQueue`'s snapshot): its queue and where
+ * what comes out goes; and everyone who sees it, how far it is in turning into another type
+ *
+ * @beta
+ */
+export interface ProductionInfo {
+    /** What it makes, the first being made: for its owner and their allies */
+    queue?: QueueItemState[];
+    /** Where what it makes goes once out: for its owner and their allies */
+    rally?: Vec2;
+    /** 0..1 while it turns into another type (`upgradeTo`, `UnitTypeDef.upgradesTo`): what every player who sees it sees */
+    upgrade?: number;
+    /** The type it turns into, while it does */
+    upgradeTo?: string;
+}
+/**
+ * An item lying on the ground
+ *
+ * @beta
+ */
+export interface GroundItemState {
+    id: number;
+    item: string;
+    x: number;
+    z: number;
+}
+/** @beta */
+export interface StockInfo {
+    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;
+}
+/**
+ * An ability a hero can put points into
+ *
+ * @beta
+ */
+export interface LearnableInfo {
+    id: string;
+    level: number;
+    maxLevel: number;
+    /** Hero level needed for the next level of the ability */
+    needs: number;
+    /** Whether a point can go into it right now */
+    available: boolean;
+}
+/**
+ * A hero's experience: what it has, at what the level it is at started and at what the next one does (`HeroSent.xp`)
+ *
+ * @beta
+ */
+export interface XpInfo {
+    /** Experience in total, whole */
+    xp: number;
+    /** What the level it is at took */
+    levelXp: number;
+    /** What the next level takes */
+    nextXp: number;
+}
+/**
+ * A hero of the player, for the row of portraits. Fallen ones are in here too
+ *
+ * @beta
+ */
+export interface HeroSummary {
+    id: number;
+    type: string;
+    level: number;
+    alive: boolean;
+    /** 0..1 */
+    hp: number;
+    mana: number;
+    points: number;
+    /** 0..1 while being brought back: at an altar, or coming back by itself (`withRespawn`) */
+    reviving?: number;
+    /** Seconds until it comes back by itself, while it waits to (`withRespawn`) */
+    respawnIn?: number;
+    /** What bringing it back would cost */
+    reviveCost?: Cost;
+}
+/**
+ * The part of an entity only its owner and their allies get to know
+ *
+ * @beta
+ */
+export interface OwnEntityState {
+    /** Another player's, which this one may command: its owner shares control with them (`world.shareControl`) */
+    shared?: boolean;
+    /** Inside something, like a worker in a mine */
+    hidden: boolean;
+    /** Type of the order being carried out */
+    order: string | null;
+    /** What it is about to build, for a build order */
+    build?: string;
+    /** Orders in the queue, the current one included */
+    orders: number;
+    passive: boolean;
+    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[];
+    abilities?: AbilityInfo[];
+}
+/** @beta */
+export interface EntityState {
+    id: number;
+    type: string;
+    owner: PlayerId;
+    x: number;
+    z: number;
+    facing: number;
+    hp: 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 */
+    shield?: number;
+    /** On its way through the air: from where to where, and how high it rises in between */
+    leap?: {
+        from: Vec2;
+        to: Vec2;
+        height: number;
+    };
+    /** 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;
+    mana?: number;
+    maxMana?: number;
+    /** Ids of the buffs on it */
+    buffs?: string[];
+    /** How many of each of its buffs that stack it carries, for the ones it carries any of */
+    stacks?: Record<string, number>;
+    /**
+     * 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`)
+     *
+     * @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
+     *
+     * @beta
+     */
+    abilities?: SharedAbility[];
+    /** What is left in a resource */
+    resource?: number;
+    /** The resource it stands on (`UnitTypeDef.builtOn`, a cursed mine on a gold mine), by id */
+    on?: number;
+    /** Doing nothing until woken, like a creep sleeping through the night */
+    asleep?: 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;
+    /** 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 */
+    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;
+    own?: OwnEntityState;
+}
+/** @beta */
+export interface PlayerState {
+    id: PlayerId;
+    name: string;
+    team: number;
+    color: [number, number, number];
+    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;
+    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';
+    /**
+     * What the player the snapshot is for shares with this ally (`shareWith`): their units' control, and their team's
+     * sight (always, for an ally of their team). Left out for who is not an ally
+     */
+    shared?: {
+        control: boolean;
+        vision: boolean;
+    };
+    /** 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>;
+        supplyUsed: number;
+        supplyCap: number;
+        /** The game's other pools of supply, by name (`GameRules.supply.pools`): left out in a game with none */
+        supplies?: Record<string, {
+            used: number;
+            cap: number;
+        }>;
+        /** What the size of the army costs in income */
+        upkeep: {
+            tier: number;
+            name: string;
+            income: number;
+        };
+        upgrades: Record<string, number>;
+        researching: string[];
+        /** Types of the finished buildings the player has, with what those count as */
+        tech: string[];
+        heroes: HeroSummary[];
+        /** What the player is set to do, in a mission. Empty in a game without objectives */
+        objectives: ObjectiveState[];
+        /** The timers the rules show the player (`world.timers.show`): their words and the tick each goes off at */
+        timers?: ShownTimer[];
+        /**
+         * What the game's `requirement` hook decided, where it differs from what the requirements say (see
+         * `PlayerFacts.unlocks`): by unit or structure type, and `upgrade:<id>` for the next level. Left out without one
+         */
+        unlocks?: Record<string, Message | null>;
+        /**
+         * What the game's `available` hook decided, where it differs from what their race says (see
+         * `PlayerFacts.availability`): by unit or structure type, and `upgrade:<id>`. Left out without one
+         */
+        availability?: Record<string, boolean>;
+    };
+}
+/** @beta */
+export interface ProjectileState {
+    id: number;
+    x: number;
+    z: number;
+    /** The type of what shot it, known even when the shooter is out of sight: what it looks like */
+    kind: string;
+    owner: PlayerId;
+    crit: boolean;
+    damageType: DamageType;
+    /** A look the rules gave it (see `Projectile.look`) */
+    look?: string;
+    /** Entity it was fired by, when that one is known to the player */
+    source?: number;
+    /** Entity it is after, when that one is known to the player */
+    target?: number;
+    /** Where it was fired from and where it comes down, for shots that are lobbed at a spot */
+    from?: Vec2;
+    to?: Vec2;
+}
+/**
+ * What an ability sent on its way, like a tornado
+ *
+ * @beta
+ */
+export interface MissileState {
+    id: number;
+    ability: string;
+    level: number;
+    /** Entity that sent it, when that one is known to the player */
+    source?: number;
+    x: number;
+    z: number;
+    radius: number;
+    /** The way it is heading, in radians */
+    heading: number;
+    /** How far it is with taking shape, 0..1, while it has not set off yet */
+    forming?: number;
+    /** How much of its way it has come, 0..1, for the ones that go a known way */
+    progress?: number;
+    /** How high above the ground its arc carries it now, for what is thrown in one (`EffectFields.arc`) */
+    arc?: number;
+}
+/**
+ * What the players are told happened during a tick, which cannot be read from the state afterwards: each kind by its
+ * `type` (design review E7). The engine's are told by its replications (`replicateEvent(key, type, tell)`, typed by
+ * this entry); a pack's or a game's own added by declaration merging, as `OrderStates` is. A screen's handlers are
+ * keyed by the same names (`SessionEventOf`)
+ *
+ * @beta
+ */
+export interface SessionEvents {
+    /**
+     * Something died. What killed it (`killer`, `killerType`, `from`, where it stood) when the player sees it; how:
+     * an attack of the killer's, the blow's damage type, the ability, how much too much, a critical strike, and what
+     * the rules made of it (`how`, set in the `death` hook: `'exploded'`). For the screen to show it its way
+     */
+    death: {
+        type: 'death';
+        id: number;
+        from?: Vec2;
+        killer?: number;
+        killerType?: string;
+        attack: boolean;
+        damageType?: DamageType;
+        ability?: string;
+        overkill?: number;
+        crit?: boolean;
+        how?: string;
+        /** Why, when it was not of damage (`DeathReason`): `cancelled`, `expired`, a game's own word */
+        reason?: string;
+        /** The blow's words of the game's own (`DamageOptions.tags`) */
+        tags?: string[];
+    };
+    /**
+     * 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
+     */
+    cells: {
+        type: 'cells';
+        layer: string;
+        at: number[];
+        value: number;
+    };
+    /**
+     * A part of the ground was reshaped (`world.reshapeGround`, the editor's Play here): the session's ground has it
+     * already, for the screen to draw again. Told to everyone
+     */
+    ground: {
+        type: 'ground';
+        patch: TerrainPatch;
+    };
+    /**
+     * Something the player does not see moved in a layer of cells where the player sees the ground (`ConcealmentOptions.rustle`):
+     * where, and whether it stepped in. Not who: for the screen to shake the bushes there
+     *
+     * @beta
+     */
+    rustle: {
+        type: 'rustle';
+        layer: string;
+        x: number;
+        z: number;
+        entered?: boolean;
+    };
+    /** 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';
+        environment: MapEnvironment;
+        over?: number;
+    };
+    /**
+     * A definition changed while the game runs (`world.redefine`), a copy made with `copyOf`: a screen with a registry of
+     * its own puts it in. Told to everyone
+     */
+    redefined: {
+        type: 'redefined';
+        kind: DataKind;
+        definition: string;
+        values: DataValues;
+    };
+    /** An attack started, at `target` when the player sees it */
+    /** `weapon`: which of its attacks swings, by place (`UnitTypeDef.attacks`); the first when left out */
+    attack: {
+        type: 'attack';
+        id: number;
+        target?: number;
+        weapon?: number;
+    };
+    /** Damage dealt to an entity the player sees: by whom when the player sees that too, with what, how much */
+    damage: {
+        type: 'damage';
+        id: number;
+        amount: number;
+        damageType: DamageType;
+        source?: number;
+        sourceType?: string;
+        attack: boolean;
+        crit: boolean;
+        /** The ability that dealt it, where the player sees the source (`source`) */
+        ability?: string;
+        tags?: string[];
+    };
+    /** Health given back to an entity the player sees */
+    heal: {
+        type: 'heal';
+        id: number;
+        amount: number;
+        source?: number;
+    };
+    /**
+     * A buff put on an entity the player sees (`on`), put on again at another level (`renewed`), or taken off or run
+     * out. Once as it begins and once as it ends: a renewal at the same level is not told
+     */
+    buff: {
+        type: 'buff';
+        id: number;
+        buff: string;
+        on: boolean;
+        level?: number;
+        renewed?: boolean;
+        source?: number;
+    };
+    /** A unit came out of `building`, where the player sees that too */
+    trained: {
+        type: 'trained';
+        id: number;
+        building?: number;
+    };
+    /** A structure was put down to be built, to go up over `buildTime` seconds as builders work (`EntityState.construction`) */
+    constructionStarted: {
+        type: 'constructionStarted';
+        id: number;
+        buildTime: number;
+    };
+    /** A structure was finished (or put down whole, `UnitTypeDef.construction: 'instant'`) */
+    built: {
+        type: 'built';
+        id: number;
+    };
+    /** A construction was called off by its owner: it dies next, its death's reason `cancelled` */
+    constructionCancelled: {
+        type: 'constructionCancelled';
+        id: number;
+    };
+    /** A building started to turn into another type (`to`) over `time` seconds (`EntityState.upgrade`) */
+    upgradeStarted: {
+        type: 'upgradeStarted';
+        id: number;
+        to: string;
+        time: number;
+    };
+    /** That was called off */
+    upgradeCancelled: {
+        type: 'upgradeCancelled';
+        id: number;
+        to: string;
+    };
+    /** An entity became another type (`from`: what it was): an upgrade done, a morph */
+    morphed: {
+        type: 'morphed';
+        id: number;
+        from: string;
+    };
+    /** A hero was brought back */
+    revived: {
+        type: 'revived';
+        id: number;
+    };
+    /** An entity picked an item up */
+    picked: {
+        type: 'picked';
+        id: number;
+        item: string;
+    };
+    /** Research of the player or an ally finished */
+    researched: {
+        type: 'researched';
+        upgrade: string;
+        level: number;
+        building: number;
+    };
+    /** A shot arrived: at its target when it had one, missing (`miss`), or struck critically */
+    shot: {
+        type: 'shot';
+        id: number;
+        x: number;
+        z: number;
+        target?: number;
+        miss: boolean;
+        crit: boolean;
+    };
+    /** A channelled ability started to be kept up (`on`, for `duration` seconds), or ended: done, or `interrupted` */
+    channel: {
+        type: 'channel';
+        id: number;
+        ability: string;
+        on: boolean;
+        duration?: number;
+        interrupted?: boolean;
+    };
+    /** What an ability sent on its way struck an entity */
+    missileHit: {
+        type: 'missileHit';
+        missile: number;
+        target: number;
+    };
+    /** A critical strike landed on the entity */
+    crit: {
+        type: 'crit';
+        id: number;
+        amount: number;
+    };
+    /** An attack up a cliff went wide, at this spot */
+    miss: {
+        type: 'miss';
+        x: number;
+        z: number;
+    };
+    /** A shot that hits an area came down */
+    impact: {
+        type: 'impact';
+        x: number;
+        z: number;
+        radius: number;
+    };
+    /** A worker struck what it is mending */
+    work: {
+        type: 'work';
+        id: number;
+    };
+    /** A worker struck what it is gathering from */
+    chop: {
+        type: 'chop';
+        id: number;
+        target: number;
+    };
+    /** An ability went off. `radius` is there for the ones that hit an area */
+    levelUp: {
+        type: 'levelUp';
+        id: number;
+        level: number;
+    };
+    /** Experience a hero of the player's or an ally's earned, and the level it is at after it */
+    xp: {
+        type: 'xp';
+        id: number;
+        amount: number;
+        level: number;
+    };
+    /**
+     * 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
+     * an effect (above 0). Not regeneration
+     */
+    mana: {
+        type: 'mana';
+        id: number;
+        amount: number;
+        ability?: string;
+    };
+    /** A pool of the game's own on a unit of the player's or an ally's changed (`resourceChanged`) */
+    resource: {
+        type: 'resource';
+        id: number;
+        kind: string;
+        amount: number;
+        reason?: string;
+    };
+    /** Gold for a kill */
+    bounty: {
+        type: 'bounty';
+        x: number;
+        z: number;
+        amount: number;
+    };
+    /** Someone started to cast. `duration` is how long until it goes off */
+    windup: {
+        type: 'windup';
+        id: number;
+        ability: string;
+        level: number;
+        x: number;
+        z: number;
+        duration: number;
+    };
+    /** `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';
+        id?: number;
+        ability: string;
+        level: number;
+        x: number;
+        z: number;
+        target?: number;
+        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 */
+    strike: {
+        type: 'strike';
+        id?: number;
+        ability: string;
+        level: number;
+        x: number;
+        z: number;
+        target?: number;
+        radius?: number;
+        impact?: string;
+    };
+    /** Something to tell the player. The client finds the words for it, see `Message` */
+    message: {
+        type: 'message';
+        message: Message;
+        kind: MessageKind;
+        seconds?: number;
+    };
+    /** A command the player sent (`seq`, what `send` gave) was carried out: refused, with why, or not */
+    command: {
+        type: 'command';
+        seq: number;
+        refusal?: Message;
+    };
+    /** An objective of the player was given (`was` undefined), got further along, or was done or failed */
+    objective: {
+        type: 'objective';
+        objective: ObjectiveState;
+        was?: ObjectiveStatus;
+    };
+    /** Someone says a line to the player: who, what, and for how long (see `world.dialog`) */
+    line: {
+        type: 'line';
+        line: SaidLine;
+    };
+    /** The line was skipped: it ends now */
+    lineEnded: {
+        type: 'lineEnded';
+        id: number;
+    };
+    /** One of the view's cinematics plays (see `playCinematic`) */
+    cinematic: {
+        type: 'cinematic';
+        cinematic: string;
+        hold: boolean;
+        skippable: boolean;
+        params?: Record<string, unknown>;
+    };
+    /** The rules cue the cinematic playing (see `cueCinematic`) */
+    cinematicCue: {
+        type: 'cinematicCue';
+        cue: string;
+        params?: Record<string, unknown>;
+    };
+    /**
+     * One of the view's effects plays, as the rules said (`world.effect`): `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: {
+        type: 'fx';
+        id: number;
+        fx: string;
+        x?: number;
+        y?: number;
+        z?: number;
+        on?: number;
+        point?: string;
+        params?: Record<string, unknown>;
+        seed: number;
+        overFog?: boolean;
+    };
+    /** An effect the rules played stops (`world.stopEffect`) */
+    fxStop: {
+        type: 'fxStop';
+        id: number;
+        fade?: number;
+    };
+    /** A player of the side marked a spot of the map, or any player for everyone (`to`, see `ping`) */
+    /** `by`: the name of who watches, for one of theirs (`to: 'observers'`) */
+    ping: {
+        type: 'ping';
+        player: PlayerId;
+        x: number;
+        z: number;
+        kind: PingKind;
+        to: ChatAudience;
+        by?: string;
+    };
+    /** A line of chat for the player: of their side, or to everyone (see `chat`) */
+    /** `by`: the name of who watches, for a line of theirs (`to: 'observers'`) */
+    chat: {
+        type: 'chat';
+        player: PlayerId;
+        text: string;
+        to: ChatAudience;
+        by?: string;
+    };
+    /** An event of the game's own that goes to the screen (see `defineEvent`): its id, and what it says */
+    game: {
+        type: 'game';
+        event: string;
+        payload: unknown;
+    };
+}
+/**
+ * Things that happened during a tick and cannot be read from the state afterwards: one of `SessionEvents`
+ *
+ * @beta
+ */
+export type SessionEvent = SessionEvents[keyof SessionEvents];
+/**
+ * How the game stands for the player
+ *
+ * @beta
+ */
+export type Outcome = 'playing' | 'victory' | 'defeat';
+/**
+ * Everything one player knows about the game at the end of a tick
+ *
+ * @beta
+ */
+export interface Snapshot {
+    tick: number;
+    /**
+     * The switches of the debug tools as they stand, for a player who may use them (`world.debugPlayers`): `explored`,
+     * the whole map explored (`debug.explore`)
+     */
+    debug?: {
+        noCooldowns: boolean;
+        noManaCosts: boolean;
+        invulnerable: boolean;
+        speed: number;
+        explored?: boolean;
+    };
+    /** Hour of the day, 0..24, in a game with days and nights */
+    hour?: number;
+    outcome: Outcome;
+    entities: EntityState[];
+    players: PlayerState[];
+    projectiles: ProjectileState[];
+    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[];
+    /** Corpses where the player can see the ground, by the id of who died there (see `raiseDead`). None when left out */
+    corpses?: CorpseState[];
+    events: SessionEvent[];
+    /** What the game tells the player about itself, see `GameModule.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
+     * 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`)
+     *
+     * @beta
+     */
+    scoreLine?: ScoreLineState;
+}
+/**
+ * A corpse as the player sees it: the id the unit had, of what type, where
+ *
+ * @beta
+ */
+export interface CorpseState {
+    id: number;
+    type: string;
+    x: number;
+    z: number;
+}
+/** @beta */
+export interface RevealState {
+    id: number;
+    x: number;
+    z: number;
+    radius: number;
+    /** Seconds it goes on */
+    left: number;
+    /** The player's team is the one that sees it */
+    ours: boolean;
+}
+/** A creep camp. Where they are is part of the map, which everyone knows */
+/**
+ * A deposit of the game's money, as the map shows it (`GameSession.mines`)
+ *
+ * @beta
+ */
+export interface MineInfo {
+    id: number;
+    x: number;
+    z: number;
+}
+/** @beta */
+export interface CampInfo {
+    id: number;
+    x: number;
+    z: number;
+    /** Levels of its creeps added up */
+    level: number;
+    /** Whether the player has seen that the camp is empty */
+    cleared: boolean;
+}
+/**
+ * What the player's team sees of the map. The arrays are per cell, row by row
+ *
+ * @beta
+ */
+export interface FogState {
+    width: number;
+    depth: number;
+    /** Changes whenever the arrays did */
+    version: number;
+    /** The whole map is lit, a debug switch */
+    revealed: boolean;
+    visible: Uint8Array;
+    explored: Uint8Array;
+}
+type WithoutPlayer<T> = T extends unknown ? Omit<T, 'player'> : never;
+/**
+ * A command as the client writes it. Who it comes from is decided by the session, never by the sender
+ *
+ * @beta
+ */
+export type PlayerCommand = WithoutPlayer<Command> | ModCommand;
+/**
+ * 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
+ */
+export declare function isCommand<K extends Command['type']>(command: PlayerCommand, type: K): command is Extract<WithoutPlayer<Command>, {
+    type: K;
+}>;
+/**
+ * What the debug tools of a client see of the simulation: an entity as the rules have it, and the events and hooks of
+ * the last seconds. Plain data, as the snapshots are, so that it works the same with a simulation somewhere else: the
+ * client says what it wants to follow, and reads what came back last
+ *
+ * @beta
+ */
+export interface SessionDebug {
+    /** Follows an entity, a player or the world, or nothing. Its inspection comes back from then on */
+    inspect(target: InspectTarget | null): void;
+    /** What is followed, as it stood when last heard of. Null when nothing is followed, or it is gone */
+    readonly inspection: Inspection | null;
+    /** Changes a number, or a switch (a boolean), of what is followed, where its inspection shows it (`InspectedSection.path` and the key) */
+    set(path: (string | number)[], value: number | boolean): void;
+    /** Whether the list of everything in the world comes back. Off until asked for: the world can be big */
+    listing: boolean;
+    /** Every player and entity of the world, out of sight, hidden and scenery too, as when last heard of. Null while not listing */
+    readonly world: WorldListing | null;
+    /** Whether the events and hooks are logged. Off until asked for: logging costs a little */
+    logging: boolean;
+    /** The events and hooks of the last seconds, oldest first */
+    log(): readonly LoggedEvent[];
+    /** Forgets what was logged so far */
+    clearLog(): void;
+}
+/**
+ * What a session can do besides being a seat, each where it can (`GameSession.can`): a game played in this page holds
+ * 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
+ * for as `session.can.pace?.advance()`: there or not
+ *
+ * @beta
+ */
+export interface SessionCan {
+    /** 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 */
+    readonly pace?: SessionPace;
+    /** Saves of the world as it stands, and the last checkpoint: a game played in this page */
+    readonly saves?: SessionSaves;
+    /** The debug tools' view of the simulation, where the session allows it */
+    readonly inspect?: SessionDebug;
+    /** Where the time of a simulation run elsewhere in this page went of late: a worker (S54) */
+    readonly timing?: SessionTiming;
+    /** What a computer player's brain reads besides the snapshot: a seat in the simulation's own thread */
+    readonly computer?: SessionComputer;
+}
+/**
+ * The pace a session holds the game at (`SessionCan.pace`)
+ *
+ * @beta
+ */
+export interface SessionPace {
+    /** 1 as it goes, 0 held (a pause menu, a cinematic that has the game wait) */
+    speed: number;
+    /** Moves a held game on by `ticks` (one when left out): a step */
+    advance(ticks?: number): void;
+}
+/**
+ * Saves of the world a session plays (`SessionCan.saves`)
+ *
+ * @beta
+ */
+export interface SessionSaves {
+    /** A save of the world as it stands: at once in this thread, a message there and back in a worker */
+    save(): Promise<WorldSave>;
+    /**
+     * The last moment the rules marked to start again from (`world.checkpoint`), with what it is called, and a save of
+     * the world as it stood: a scene can load it for "Retry from wave 6"
+     */
+    readonly checkpoint?: {
+        label: Message;
+        save: WorldSave;
+    };
+}
+/**
+ * Where the time of a simulation run elsewhere went of late (`SessionCan.timing`)
+ *
+ * @beta
+ */
+export interface SessionTiming {
+    /**
+     * Milliseconds a tick took, evened out, the longest, what sending the page what changed took, what the page took to
+     * take it in, and each system's share (`world.scheduler.timing()`) while they are measured (`profile`)
+     */
+    timing(): {
+        tick: number;
+        tickMax: number;
+        send: number;
+        receive?: number;
+        systems?: SystemTiming[];
+    } | undefined;
+    /** Measures the simulation's systems, or stops (it costs a little): what the stats window asks while it is open */
+    profile?(on: boolean): void;
+}
+/**
+ * What a computer player's seat gives its brain besides the snapshot (`SessionCan.computer`)
+ *
+ * @beta
+ */
+export interface SessionComputer {
+    /**
+     * Where the game's money is mined (a resource of `Registry.currency`: gold mines), as a player knows from the map,
+     * under the fog too: what a computer player looks to for another hall
+     */
+    mines(): readonly MineInfo[];
+    /** The lanes of the map (`lanesOf`), as everyone knows them from the map: what a computer player of lanes walks with its waves */
+    lanes(): readonly Lane[];
+    /**
+     * What happened since the last snapshot, not yet given in one: a copy. The brain's save keeps what it heard since it
+     * last thought (`restoreEvents`), so that a game loaded from the save hears it too
+     */
+    pendingEvents(): SessionEvent[];
+    /** Takes back what `pendingEvents` gave, ahead of what has happened since: in a game loaded from a save */
+    restoreEvents(events: readonly SessionEvent[]): void;
+}
+/**
+ * A seat in a game: the only thing a client needs to play
+ *
+ * @beta
+ */
+export interface GameSession {
+    readonly playerId: PlayerId;
+    readonly team: number;
+    /** The map and the game data are the same for everyone and known up front */
+    readonly terrain: Terrain;
+    /**
+     * What the map looks like beyond its ground, for the screen: its water, sky, weather. Nothing when it does not say.
+     * As it was when the session began: what the rules change after comes as `environment` events
+     */
+    readonly environment?: MapEnvironment;
+    /** The scenery of the map, for the screen: none when it has none (see `MapDoodad`) */
+    readonly doodads: readonly MapDoodad[];
+    /** The regions of the map, for the screen: what mist in places lies over by name (see `MapRegion`, `AreaRef`) */
+    readonly regions: readonly MapRegion[];
+    /** The views of the map saved under names, for cinematics and a player's first view (see `MapCamera`) */
+    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[];
+    readonly registry: Registry;
+    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
+     * server's game says it on the server, and a player is not given it
+     */
+    readonly log?: Logger;
+    /**
+     * Why the game ended on an error in its rules, once it has (`World.failure`): what the player is told. A game that
+     * failed does not go on; a client says so, and offers what there is to offer
+     */
+    readonly failure?: {
+        message: string;
+    } | null;
+    /** How far the current frame is between the last two snapshots, 0..1 */
+    readonly alpha: number;
+    /** State to start from */
+    snapshot(): Snapshot;
+    /** Lets time pass. Returns the snapshots that came in since the last call, oldest first */
+    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;
+    fog(): FogState;
+    camps(): readonly CampInfo[];
+    /** Whether the player could build this here, as far as they can tell */
+    canPlace(unitType: string, point: Vec2): boolean;
+    /**
+     * Which cells of the ground a building would cover there are in the way, as far as the player can tell, row by row
+     * from its corner (`placementCells`): what a preview draws cell by cell. None for one built on a resource, or where
+     * the session does not say @beta
+     */
+    placeCells?(unitType: string, point: Vec2): readonly boolean[] | undefined;
+    /** Route a unit would take, over the ground the player knows */
+    findPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null;
+    /**
+     * What this kind of session can do besides being a seat (`SessionCan`): hold the pace, save, show the debug tools,
+     * tell its timing, serve a computer player. A seat over a wire can none of it; a game in this page most of it
+     */
+    readonly can: SessionCan;
+    /** Whether the player only watches, and sees everything (every player's resources among it): see `LocalSession.observer` */
+    readonly observer?: boolean;
+    /** Milliseconds a message takes to the simulation and back, where it runs elsewhere. Nothing in the page */
+    readonly ping?: number;
+    dispose(): void;
+}
+/**
+ * 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
+ */
+export declare const PROTOCOL_VERSION = 13;
+/**
+ * A game of a server, as its list says it (`GET /games`): its room (what to connect to, `ws://host:port/<room>`; none for
+ * a server of one game), the game and mode, where it is at, its seats taken and free, who watches, and its settings
+ * (the map, among them, where the mode offers one)
+ *
+ * @beta
+ */
+export interface GameListing {
+    room: string;
+    game: string;
+    mode: string;
+    phase: 'lobby' | 'game' | 'ended';
+    /** Seats players hold, seats nobody holds a player could, seats the computer plays */
+    players: number;
+    free: number;
+    computer: number;
+    watchers: number;
+    settings: Record<string, string>;
+    /** Whether it takes no new games: stopping */
+    draining: boolean;
+    /** How its players are rated, on average, where the server keeps ratings (`Ratings`) */
+    rating?: number;
+}
+/**
+ * A kind of game a server lets players make a room of, as its list says it (`GET /games`'s `kinds`): what to ask
+ * `POST /games` for (`{ kind: id, settings }`), what it is called, and the settings it offers (a map, among them)
+ *
+ * @beta
+ */
+export interface GameKindListing {
+    id: string;
+    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;
+    waiting?: number;
+    needed?: number;
+    settings: Record<string, {
+        label: string;
+        options: string[];
+        default: string;
+    }>;
+}
+export {};