@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/session/can.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a session can do besides being a seat (`SessionCan`), made of its own members: what a game played in this page
+ * gives, in its thread (`LocalSession`) or in a worker (`WorkerSession`)
+ */
+import type { WorldSave } from '#engine/save';
+import type { Message } from '#engine/messages';
+import type { SessionPace, SessionSaves } from './protocol';
+/** A session's pace, as `SessionCan.pace`: its own `speed` and `advance` */
+export declare function paceOf(session: {
+    speed: number;
+    advance(ticks?: number): void;
+}): SessionPace;
+/** A session's saves, as `SessionCan.saves`: its own `save` and `checkpoint` */
+export declare function savesOf(session: {
+    save(): Promise<WorldSave>;
+    readonly checkpoint?: {
+        label: Message;
+        save: WorldSave;
+    };
+}): SessionSaves;

package/dist/session/commandReplay.d.ts

@@ -0,0 +1,92 @@
+import { type Apart } from '#engine/determinism';
+import { type GameModule } from '#engine/game';
+import type { Component } from '#engine/components';
+import type { IssuedCommand } from '#engine/commands';
+import type { PlayerId } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * A game recorded as its start and its commands (`recordGame`'s `kind: 'commands'`), to run again (`playReplay`)
+ *
+ * @beta
+ */
+export interface CommandReplay {
+    format: 2;
+    kind: 'commands';
+    /** The game it is of, by id: a page plays back what it has */
+    game: string;
+    /** The rules it was played with exactly (`registry.hash`): other rules may play it otherwise */
+    rules: string;
+    /** Whose side it is seen from when played back; any side can be, as all of the game is in it */
+    player: PlayerId;
+    tickRate: number;
+    /** The tick it started and ended at */
+    from: number;
+    to: number;
+    /** The world as it was at `from`, as a save (`encodeSave`) */
+    start: string;
+    /** What its players told it, each at the tick it was given at, before that tick ran */
+    commands: [tick: number, command: IssuedCommand][];
+    /** The ticks it was saved at: a save puts the crowd back as a load does (D2), so playing back does it there too */
+    saves: number[];
+    /** The world's fingerprint (`worldFingerprint`) every `every` ticks, to tell where a game played back came apart */
+    hashes: [tick: number, hash: string][];
+    /**
+     * The world as it was every so many ticks (`recordCommands`' `checkpoints`), as saves: a replay played from a moment
+     * starts from the last one before it, not from its start. None in a replay made before there were any @beta
+     */
+    checkpoints?: [tick: number, save: string][];
+    /**
+     * The players who could use the debug commands as it was recorded (`World.debugPlayers`, which no save keeps): played
+     * back, they may again, so a game whose cheats were used (the editor's Play here, its map edits pushed) comes to the
+     * same. None when left out
+     */
+    debug?: PlayerId[];
+}
+/**
+ * A game being recorded as its commands
+ *
+ * @beta
+ */
+export interface CommandRecorder {
+    readonly ticks: number;
+    stop(): CommandReplay;
+}
+/**
+ * Records a world from now as its start and the commands given to it from outside a tick (the players', by a
+ * session or a server; a computer player's are its system's, which runs again), with its hash every `every` ticks
+ * (300, ten seconds at 30 a second, when left out). Starting takes a save of the world, as saving does (it puts the
+ * crowd back as a load does)
+ *
+ * @beta
+ */
+export declare function recordCommands(world: World, options: {
+    player: PlayerId;
+    every?: number;
+    checkpoints?: number;
+}): CommandRecorder;
+/**
+ * A replay of commands run again, to its end or a tick, with no screen: the world as it is then, the first tick whose
+ * hash differs from the one kept (none when all were the same), and what differed first at the first checkpoint
+ * (`recordCommands`' `checkpoints`) where the world was not the one recorded: the entity and its field
+ * (`entities[id 11].pos.x`), and what each held. A replay with no checkpoints says the tick alone. What a test of a
+ * replay, and a server checking one, use
+ *
+ * @beta
+ */
+export declare function runReplay(replay: CommandReplay, options: {
+    game: GameModule;
+    to?: number;
+    from?: number;
+    components?: readonly Component<unknown, unknown>[];
+}): Promise<{
+    world: World;
+    apart: number | null;
+    difference: Apart | null;
+}>;
+/**
+ * Milliseconds of a look a replay being played spends running its game on, at most: what a seek has to catch up on
+ * (minute 15 is 27,000 ticks from the start) is run a slice a look, the page drawn between them
+ *
+ * @beta
+ */
+export declare const REPLAY_SLICE = 12;

package/dist/session/debug.d.ts

@@ -0,0 +1,65 @@
+import { type Inspection, type InspectTarget, type LoggedEvent, type WorldListing } from '#engine/inspect';
+import type { World } from '#engine/world';
+import { type SessionDebug } from './protocol';
+import type { DebugAsk } from './wire';
+/** Milliseconds between two words of the debug tools' view of a world elsewhere: a server's, a worker's */
+export declare const DEBUG_EVERY = 100;
+/**
+ * The debug tools' view of a world running in the same page. What it hands out is worked out again whenever a
+ * snapshot is, and at once when the client asks for something else: a remote one would wait for the answer instead
+ */
+export declare class LocalDebug implements SessionDebug {
+    private readonly simulation;
+    inspection: Inspection | null;
+    world: WorldListing | null;
+    private target;
+    private listedAt;
+    private readonly events;
+    constructor(simulation: World);
+    inspect(target: InspectTarget | null): void;
+    set(path: (string | number)[], value: number | boolean): void;
+    get listing(): boolean;
+    set listing(on: boolean);
+    get logging(): boolean;
+    set logging(on: boolean);
+    log(): readonly LoggedEvent[];
+    clearLog(): void;
+    /** Works what is handed out again. The session does when a tick went by */
+    refresh(): void;
+    dispose(): void;
+}
+/**
+ * Does what the debug tools of a screen asked of a world here (`DebugAsk`), each field checked first: it comes from
+ * anyone who can send anything
+ */
+export declare function askDebug(view: SessionDebug, ask: Record<string, unknown>): void;
+/**
+ * The debug tools' view of a world elsewhere, a server's or a worker's: what it asked to follow, said over the wire
+ * (`DebugAsk`), and what came back last (`take`)
+ */
+export declare class RemoteDebug implements SessionDebug {
+    private readonly ask;
+    inspection: Inspection | null;
+    world: WorldListing | null;
+    private listed;
+    private logged;
+    private target;
+    private events;
+    constructor(ask: (ask: DebugAsk) => void);
+    inspect(target: InspectTarget | null): void;
+    /** Asks again for all it follows: of a world it is served from anew (a session resumed, a replay gone back) */
+    askAgain(): void;
+    set(path: (string | number)[], value: number | boolean): void;
+    get listing(): boolean;
+    set listing(on: boolean);
+    get logging(): boolean;
+    set logging(on: boolean);
+    log(): readonly LoggedEvent[];
+    clearLog(): void;
+    /** What the world's side said of what is followed */
+    take(said: {
+        inspection: Inspection | null;
+        world: WorldListing | null;
+        log: readonly LoggedEvent[];
+    }): void;
+}

package/dist/session/delay.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A watcher shown the game some seconds behind it (RV86): what the host sends goes on after the delay, so that who
+ * watches a game being played cannot tell a side where the other is now. The host is answered at once on the
+ * watcher's behalf (`ack`), as one who missed nothing: it goes on making each frame against the one before, and keeps
+ * nothing more for the delay; the watcher's own answers are not passed on, as they come late. The rest of what the
+ * watcher says (a line, a ping) goes as it is said
+ */
+import type { Transport } from './remote';
+/**
+ * The host's end of a watcher's transport, with what goes to the watcher held for `seconds` (see the top of this
+ * file). Closing it closes the watcher's, and what is held goes with it
+ *
+ * @beta
+ */
+export declare function delayed(transport: Transport, seconds: number): Transport;

package/dist/session/delta.d.ts

@@ -0,0 +1,98 @@
+import type { CampInfo, EntityState, OwnEntityState, SessionEvent, Snapshot } from './protocol';
+/**
+ * The fog of a team, as runs of the same value: 0s first, then 1s, then 0s... Few runs for a map of open fields
+ *
+ * @beta
+ */
+export interface FogMessage {
+    revealed: boolean;
+    visible: number[];
+    explored: number[];
+}
+/**
+ * What a player knows at a tick: the snapshot (without its events, which go their own way), the fog, the camps, the team
+ *
+ * @beta
+ */
+export interface Frame {
+    snapshot: Snapshot;
+    fog: FogMessage;
+    camps: CampInfo[];
+    team: number;
+}
+/** The parts of a frame besides its entities, sent when they differ from the base's */
+type Rest = Omit<Snapshot, 'tick' | 'entities' | 'events'> & {
+    fog: FogMessage;
+    camps: CampInfo[];
+    team: number;
+};
+/**
+ * A list or an object sent as the parts of it that changed (`$patch`): by index for a list as long as the one before,
+ * by key for an object, each part whole or a patch of its own, and the keys of an object that are gone (`$unset`).
+ * What a cooldown of one ability of four, or the gold of one player, sends in place of all of them
+ *
+ * @beta
+ */
+export interface WirePatch {
+    /** The parts that changed, by index or key: each the part whole, or a patch of its own */
+    $patch: Record<string, unknown>;
+    /** The keys of an object that are gone */
+    $unset?: string[];
+}
+/**
+ * An entity that changed, as a list rather than an object (what goes over the wire for each one adds up): its id, the
+ * fields that are new, those that are gone, and of what only its owner is told (`own`), the same, and its fields that
+ * changed in part, as what changed in them (`WirePatch`: one ability's cooldown). Trailing parts that say nothing are
+ * left off, the others `0`
+ *
+ * @beta
+ */
+export type EntityChange = [
+    id: number,
+    set: Partial<EntityState>,
+    unset?: (keyof EntityState)[] | 0,
+    ownSet?: Partial<OwnEntityState> | 0,
+    ownUnset?: (keyof OwnEntityState)[] | 0,
+    ownPatch?: Partial<Record<keyof OwnEntityState, WirePatch>>
+];
+/**
+ * A frame as what changed since another (`base`, a tick the player has), or all of it (`base: null`)
+ *
+ * @beta
+ */
+export interface Delta {
+    tick: number;
+    base: number | null;
+    added: EntityState[];
+    changed: EntityChange[];
+    removed: number[];
+    rest: Partial<Rest>;
+    /** The other parts that changed in part, as what changed in them (`WirePatch`: the gold of one player of four) */
+    restPatch?: Partial<Record<keyof Rest, WirePatch>>;
+    /**
+     * The batches of events the player has not said it got, each by its own number (`n`) and the tick it went out with:
+     * sent again until it does, applied once. Talk between two ticks is a batch of its own (RV14)
+     */
+    events: {
+        tick: number;
+        n: number;
+        events: SessionEvent[];
+    }[];
+}
+/**
+ * An entity's state with its numbers rounded for the wire: positions to 1/256 of a unit (16 bits over a map of 256),
+ * the facing to a 256th of a turn, health and shield up to whole points (what is alive keeps at least one), mana down
+ * (an ability is never shown ready that the simulation would refuse), what is under way to hundredths, the seconds
+ * left of buffs and of shared cooldowns up to whole seconds
+ *
+ * @beta
+ */
+export declare function quantize(state: EntityState): EntityState;
+/**
+ * Characters of a delta's text by what they carry, added to `into`: each field of an entity, of those added and those
+ * changed together (`entity.hp`; of what only its owner is told, `entity.own.abilities`), the other parts (`rest.fog`),
+ * `events`, `removed`, and what is left (ids, brackets, the tick) as `other`, so that they add up to `text`'s length.
+ * A field is its key, its value and the comma between, as `JSON.stringify` writes them
+ */
+export declare function bytesByKey(delta: Delta, text: string, into: Record<string, number>): void;
+export {};

package/dist/session/entityState.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/local.d.ts

@@ -0,0 +1,214 @@
+import type { Logger } from '#engine/log';
+import type { MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map';
+import { type Lane } from '#engine/lanes';
+import type { PlayerId } from '#engine/entity';
+import type { Vec2 } from '#engine/math';
+import type { Registry } from '#engine/registry';
+import type { Terrain } from '#engine/terrain';
+import type { World } from '#engine/world';
+import type { CampInfo, FogState, GameSession, MineInfo, PlayerCommand, SessionEvent, Snapshot, SessionCan } from './protocol';
+import type { Message } from '#engine/messages';
+import { type WorldSave } from '#engine/save';
+import { LocalDebug } from './debug';
+import { SessionView } from '#engine/replication';
+/**
+ * The events a computer player's seat hears (`forComputer`): the facts a brain reads and a save keeps for it (deaths,
+ * damage, healing, pings, chat, the game's own events) and the answers to its commands. The rest is for a screen (an
+ * attack's swing, a shot, a buff, a hammer blow, a line said), and a computer's seat is spared hearing it
+ *
+ * @beta
+ */
+export declare const COMPUTER_EVENTS: ReadonlySet<SessionEvent['type']>;
+/** @beta */
+export declare class LocalSession implements GameSession {
+    /** For tools and tests. Clients have no business here, they go through the session */
+    readonly world: World;
+    readonly playerId: PlayerId;
+    readonly terrain: Terrain;
+    readonly environment?: MapEnvironment;
+    readonly doodads: readonly MapDoodad[];
+    readonly regions: readonly MapRegion[];
+    readonly cameras: readonly MapCamera[];
+    readonly paths: readonly MapPath[];
+    readonly registry: Registry;
+    readonly tickRate: number;
+    alpha: number;
+    /** What the world says (`World.log`): a session in the page has it, and the client shows it with its own */
+    get log(): Logger;
+    /** Why the game ended on an error, once it has (`World.failure`) */
+    get failure(): {
+        message: string;
+    } | null;
+    /** Simulation speed multiplier, 0 pauses. A debug control, a real server sets the pace itself */
+    speed: number;
+    private accumulator;
+    /** Whether the team saw the whole map at the last snapshot (the debug switch): what it saw then only is forgotten after */
+    private wasRevealed;
+    /** What the player's team remembers, or an observer's own (`SessionView.memory`) */
+    private get memory();
+    /** Ids of what made it into the snapshot being put together as in sight. Kept to be cleared, not made anew */
+    private readonly inSight;
+    /** The names the map or the rules gave entities, by id, as of the snapshot being put together (`world.named`) */
+    private readonly namesNow;
+    private readonly disposers;
+    private pendingCheckpoint?;
+    checkpoint?: {
+        label: Message;
+        save: WorldSave;
+    };
+    readonly debug: LocalDebug;
+    /** Its pace, saves of its world, the debug tools' view, and what a computer player's brain reads (`SessionCan`) */
+    readonly can: SessionCan;
+    /**
+     * Who only watches, and sees everything: every entity, the whole map, every player's resources and heroes. From
+     * `playerId`'s side all the same (who is an ally, an enemy). For a server's watchers, whose commands go nowhere
+     */
+    readonly observer: boolean;
+    /**
+     * Whose seat is a computer player's (`forComputer`): its snapshots leave out projectiles, missiles, corpses, reveals
+     * and the events a brain never reads, and it listens for none of those, so twelve computers cost the world less
+     */
+    readonly forComputer: boolean;
+    /** The seat's side of the world: whose it is, what they may know, what was told to them since the last snapshot */
+    readonly view: SessionView;
+    constructor(
+    /** For tools and tests. Clients have no business here, they go through the session */
+    world: World, playerId: PlayerId, 
+    /**
+     * `debug`: the player may use the debug commands (see `world.debugPlayers`). `ownsWorld`: the world is the
+     * session's, and goes with it (`dispose`): for a game played in the page, where the session is all the screen
+     * holds of it. Not for a world others play too, or one that goes on after this session (a host's seats, the computer's).
+     * `forComputer`: the seat is a computer player's, and its snapshots carry what a brain reads and none of what a
+     * screen needs (`COMPUTER_EVENTS`): cheaper to take, and fewer of the world's events to hear.
+     * `mostEffects` (`@beta`): how many of the effects the rules play are kept for their stop, 1024 when left out
+     */
+    options?: {
+        observer?: boolean;
+        debug?: boolean;
+        ownsWorld?: boolean;
+        forComputer?: boolean;
+        mostEffects?: number;
+    });
+    /** Whether the seat is told of events of a kind: a player's seat of all of them, a computer's of what a brain reads */
+    private hears;
+    /** The player's team: theirs now, as the rules may move them to another (`setTeam`) */
+    get team(): number;
+    private isAlly;
+    /** Whether the player's team sees a spot of the map right now: an observer sees all of it */
+    private sees;
+    /** Whether the player's team can see the entity right now */
+    private knows;
+    /**
+     * What everyone in sight of an entity is told of it this tick, the same for every seat: worked out once for all
+     * the sessions of a world while a host's round of sending is on (`shareCaptures`), else for this session alone
+     */
+    private common;
+    /**
+     * What this player is told of an entity: what everyone is (`common`, shared between the seats of a host), and on a
+     * copy of it what is this player's to know: an illusion's lifetime on its own side, the components replicated to it
+     * and what they make of themselves for it, and its own part (`own`) for an ally's
+     */
+    private describe;
+    /**
+     * What the seats of this one's side are told alike this round (`Round.sides`), by entity: none outside a host's round.
+     * Set as the capture starts (`capture`)
+     */
+    private sideNow;
+    /**
+     * Which seats are told the same of an entity where nothing of it is one player's: an observer's, or a team's with the
+     * same allies among the players (relations are a pair of players', not a team's)
+     */
+    private sideKey;
+    /**
+     * Whether what this player is told of an entity is theirs alone, not their side's: a component replicated to its owner
+     * or shaping itself for each player (`Component.snapshot`), or control of another's unit shared with this player
+     */
+    private isOnePlayers;
+    /** Where in the list being captured are those that may be one player's (`SideSeen.mine`): while the first seat of a side captures */
+    private mineNow;
+    /**
+     * What the team remembers of a structure is every teammate's to be told, not this seat's: without the parts of the
+     * description shaped for one player (components replicated to the owner, or made by their `snapshot` for whoever is
+     * told), which the seat that happened to see it first would otherwise give to the whole team
+     */
+    private forTeam;
+    /** Adds what the player sees of an entity in sight to the snapshot, and remembers structures for when they are out of sight */
+    private see;
+    /** Throws when what was taken to be in sight is not what testing every entity gives. See `debugChecks` */
+    private checkSight;
+    /** The scenery the player's team sees right now */
+    private sceneryInSight;
+    /**
+     * On a map explored from the start, what stands on it and belongs to no player (trees, mines, rocks, neutral
+     * buildings, the creeps' own) known to the team from the first snapshot, as it stands, out of sight: the genre's melee
+     * maps. Once for a team (`TeamMemory.startKnown`); units, and players' buildings, only once seen
+     */
+    private knowStart;
+    private capture;
+    /** The entities in sight, and what the side remembers out of it, as the first seat of a side (or a seat on its own) sees them */
+    private seeAll;
+    /**
+     * What another seat of the side saw this round, as this one sees it: the same, but what may be this player's alone
+     * described again for them. The side's memory is the first seat's to keep
+     */
+    private seeAsSide;
+    /** The rest of a snapshot, round its entities: the players, and every feature's part (`SnapshotPart`) */
+    private finish;
+    snapshot(): Snapshot;
+    /**
+     * Moves the game on by `ticks` at the next update, however fast it goes: a step of a paused game (`speed` 0), as
+     * an editor's Step does. Ticks asked for while it runs are taken on top of its pace
+     */
+    advance(ticks?: number): void;
+    /** A save of the world as it stands (`saveWorld`): at once, as a promise for what a session elsewhere answers later */
+    save(): Promise<WorldSave>;
+    /**
+     * Runs the game on by itself, a tick at a time, as fast as the page can, until `until` holds of the world, `most`
+     * ticks have run, the game is over, or `deadline` (`performance.now()`'s) is past: what an editor's "Play to" does a
+     * slice a frame, its pace and `advance` aside. The ticks are the same ticks the game runs at its own pace, so the
+     * same game comes to the same moment. What happened in them is in the next snapshot (`update`), as after a slow frame.
+     * `until` is asked before the first tick too: what holds already runs none
+     */
+    runUntil(until: (world: World) => boolean, options?: {
+        most?: number;
+        deadline?: number;
+    }): {
+        ticks: number;
+        reached: boolean;
+        over: boolean;
+    };
+    /** What `runUntil` gives back, the debug tools' view brought up to date where it ran */
+    private ran;
+    /** Whether `runUntil` ran ticks since the last update: its next snapshot describes them, paused or not */
+    private ranOn;
+    /** A tick of the world, and the checkpoint it marked saved as the world stood at its end, not at the end of the frame */
+    private tickOnce;
+    update(dt: number): Snapshot[];
+    /** Sends a command. `seq` is the sender's own number for it, for a host passing on what a remote player numbered */
+    send(command: PlayerCommand, seq?: number): number;
+    /**
+     * The number of the last command sent: a computer's seat keeps it through a save, so the commands it sends after a
+     * load are numbered as they would have been
+     *
+     * @beta
+     */
+    lastSeq: number;
+    fog(): FogState;
+    /** Where the game's money is mined, as the map shows it, seen or not (`GameSession.mines`, `minesFor`) */
+    mines(): readonly MineInfo[];
+    /** The lanes of the map, as the map shows them (`GameSession.lanes`) */
+    lanes(): readonly Lane[];
+    /** The camps as the player knows them (`GameSession.camps`, `campsFor`): worked out once a tick */
+    camps(): readonly CampInfo[];
+    canPlace(unitType: string, point: Vec2): boolean;
+    /** Which cells of a building's ground are in the way for the player: taken, or not explored by their team (`placementCells`) */
+    placeCells(unitType: string, point: Vec2): readonly boolean[] | undefined;
+    findPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null;
+    /** What happened since the last snapshot, not yet given in one: a copy, for a computer's save */
+    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;
+    /** Whether the world goes with the session */
+    private readonly ownsWorld;
+    dispose(): void;
+}

package/dist/session/memory.d.ts

@@ -0,0 +1,27 @@
+import type { EntityId } from '#engine/entity';
+import type { EntityState } from './protocol';
+/**
+ * What a team remembers of the map: enemy structures out of sight as they were last seen, and camps found empty
+ *
+ * @beta
+ */
+export interface TeamMemory {
+    /** Structures out of sight, the way they looked when last seen, by id */
+    structures: Record<EntityId, EntityState>;
+    /** The camps the team has seen empty, by id */
+    cleared: number[];
+    /**
+     * Whether what stands on a map explored from the start and is no player's (trees, mines, neutral buildings) has been
+     * put among `structures`, as it stood when the team first looked (`FogOfWar.exploredFromStart`)
+     *
+     * @beta
+     */
+    startKnown?: boolean;
+    /**
+     * Cells of the game's layers the rules changed out of the team's sight (`world.setCells`), as the team last knew
+     * them: by layer, the value by cell. Told as they are now when they come into sight (`cellsSeen`), and gone from here
+     *
+     * @beta
+     */
+    cells?: Record<string, Record<number, number>>;
+}