@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/session/remote.d.ts

@@ -0,0 +1,530 @@
+import { type GameHostMessage, type HostToPlayer, type ServerToPlayer } from './wire';
+import type { GameMap, MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map';
+import type { PlayerId } from '#engine/entity';
+import type { GameModule } from '#engine/game';
+import { BuildGrid } from '#engine/grid';
+import type { Vec2 } from '#engine/math';
+import type { Navigation } from '#engine/navigation/navigation';
+import { type RecastNavigationOptions } from '#engine/navigation/recast';
+import type { Registry } from '#engine/registry';
+import type { Terrain } from '#engine/terrain';
+import type { World } from '#engine/world';
+import { type MessageRef } from '#engine/messages';
+import { type CampInfo, type FogState, type GameSession, type PlayerCommand, type Snapshot, type SessionCan, type SessionDebug } from './protocol';
+/**
+ * One end of a connection: text in, text out, in order
+ *
+ * @beta
+ */
+export interface Transport {
+    send(message: string): void;
+    /** What comes in from the other end. One handler: a later one takes the place of the one before */
+    onMessage(handler: (message: string) => void): void;
+    /** Told when the other end closes */
+    onClose(handler: () => void): void;
+    close(): void;
+}
+/**
+ * An end of a `loopback`, which counts what it sends: for a budget of bandwidth
+ *
+ * @beta
+ */
+export interface LoopbackEnd extends Transport {
+    /** Characters sent, a byte each as the JSON goes over a WebSocket of mostly ASCII */
+    readonly bytesSent: number;
+    readonly messagesSent: number;
+}
+/**
+ * A connection inside the page, standing in for a network (`loopback`)
+ *
+ * @beta
+ */
+export interface LoopbackOptions {
+    /** Milliseconds each message takes, one way */
+    latency?: number;
+    /** Milliseconds a message may take on top of that, at random: never out of order, the way a WebSocket keeps it */
+    jitter?: number;
+    /**
+     * The share of the snapshots that never arrive, 0..1, for what a lossy connection does to the screen. Only from the
+     * host: the welcome and the player's commands always do. The events of a snapshot lost are lost with it
+     */
+    loss?: number;
+    /** Random numbers for jitter and loss: `Math.random` when left out (the simulation does not use it) */
+    random?: () => number;
+}
+/**
+ * Two ends of a connection in the page, `[client, host]`: everything sent is text, delivered after the latency the
+ * options give. The whole networked way, in one page and in tests
+ *
+ * @beta
+ */
+export declare function loopback(options?: LoopbackOptions): [LoopbackEnd, LoopbackEnd];
+/** Seconds of jitter the interpolation buffer makes room for, at most */
+export declare const MAX_JITTER = 0.2;
+/**
+ * What a player's side keeps and how often it asks, set by `ConnectOptions`: each the number it has always been when
+ * left out
+ *
+ * @beta
+ */
+export interface PlayerLimits {
+    /** Milliseconds between two pings, to measure the time to the host and back. 2000 when left out */
+    pingEvery?: number;
+    /** Seconds of jitter the interpolation buffer makes room for, at most: a spike of lateness is not waited out for good. 0.2 when left out */
+    maxJitter?: number;
+    /** Snapshots waiting for the screen, at most: past that the oldest is folded into the next. 64 when left out */
+    keptSnapshots?: number;
+    /** Events the folded snapshots carry together, at most: the newest kept. 2000 when left out */
+    keptScreenEvents?: number;
+}
+/**
+ * Where a host's time went over a while: see `SessionHost.takeTiming`
+ *
+ * @beta
+ */
+export interface HostTiming {
+    /** When the counting started, `performance.now()` */
+    since: number;
+    ticks: number;
+    /** Milliseconds the ticks took, added up, and the longest */
+    tickTime: number;
+    tickMax: number;
+    /** Rounds of sending everyone what changed */
+    sends: number;
+    sendTime: number;
+    sendMax: number;
+    /**
+     * Where the sending's milliseconds went, added up over the seats: what each player may know taken from the world
+     * (`capture`), its positions rounded (`quantize`), the fog made runs (`fog`), what changed since the frame they
+     * have (`diff`), made text (`stringify`)
+     *
+     * @beta
+     */
+    parts: {
+        capture: number;
+        quantize: number;
+        fog: number;
+        diff: number;
+        stringify: number;
+    };
+    /**
+     * Characters of the rounds' text, to every seat, before any compression of the wire
+     *
+     * @beta
+     */
+    bytes: number;
+    /**
+     * Those characters by what they carry, when the host counts them (`SessionHostOptions.bytesByKey`): each field of
+     * the entities added and changed (`entity.hp`, `entity.own.abilities`), the other parts (`rest.players`, `rest.fog`),
+     * `events`, `removed`, and the rest (ids, brackets) as `other`. They add up to `bytes`
+     *
+     * @beta
+     */
+    keys?: Record<string, number>;
+}
+/** @beta */
+export interface SessionHostOptions {
+    /** Snapshots a second sent to each player, at most: the simulation runs at its tick rate all the same. 20 when left out */
+    sendRate?: number;
+    /**
+     * Ticks one update catches up at most. A host that fell further behind (a stall, a machine too slow for the game)
+     * lets the rest go, and the game runs slower for a moment, rather than spiralling. 8 when left out
+     */
+    maxTicksPerUpdate?: number;
+    /** Told of a tick that took longer than a tick lasts, with how many milliseconds: the watchdog */
+    onSlowTick?: (milliseconds: number, tick: number) => void;
+    /**
+     * Told when stepping the world threw, running by the clock (`start`): the host has stopped by then, and what
+     * becomes of the game is whoever runs it's to say. Said in the world's log, and nothing more, when left out. An
+     * error is never a reason for the process to go
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * The world is the host's, and goes with it (`dispose`): for a server's game, or a game run in the page behind a
+     * wire. Not for a world the page plays itself and only lets others watch (`recordGame`, `shareGame`). No when left out
+     */
+    ownsWorld?: boolean;
+    /**
+     * Seconds of the game a player may go without saying it got what it was sent, before its seat is closed: what is
+     * kept for it to send again (the events it has not said it got) would grow for as long as it says nothing. 15 when
+     * left out; `Infinity` never closes one
+     */
+    dropSilentAfter?: number;
+    /**
+     * Ticks of events kept for a player who has not said they got them, at most: past that the oldest that already went
+     * are let go, not sent again. They are there already over a transport that loses nothing (a worker, a WebSocket),
+     * so this bounds only a player who goes on hearing but has stopped answering (a page frozen in the background). 600
+     * when left out
+     *
+     * @beta
+     */
+    keptEvents?: number;
+    /**
+     * Frames kept for each player to make a delta against, at most: a player who says nothing for longer is sent
+     * everything again, once, and nothing more until it answers (or its answer is overdue); an answer to a frame let go
+     * still says the player is there. 64 when left out (more than a second and a half of ticks)
+     *
+     * @beta
+     */
+    keptFrames?: number;
+    /**
+     * Bytes of the frames kept for each player, at most, summed (what each takes as the wire writes it): a player who
+     * says nothing while a thousand units fight is sent everything again sooner than `keptFrames` would. 8 MB when left
+     * out
+     *
+     * @beta
+     */
+    keptBytes?: number;
+    /**
+     * Characters of the ground in one message, for a player who does not have the map and asks for it a part at a
+     * time: well under what a connection holds. 262144 when left out
+     *
+     * @beta
+     */
+    groundPart?: number;
+    /**
+     * Whether `takeTiming` says what the characters sent were spent on, field by field (`HostTiming.keys`): what a
+     * measure of the wire asks for (`net.bench.ts`), at the cost of writing each field again. No when left out
+     *
+     * @beta
+     */
+    bytesByKey?: boolean;
+}
+/**
+ * Runs a world for players connected to it over transports: the server's job, done anywhere. It steps the world by
+ * the clock (`start`) or by hand (`update`), and at most `sendRate` times a second sends every player what changed in
+ * what they may know (`Delta`), as their `LocalSession` seat sees it: against the last tick they said they got, with
+ * the events they have not. Their commands come in as they arrive, and go in at the next tick
+ *
+ * @beta
+ */
+export declare class SessionHost {
+    readonly world: World;
+    private readonly seats;
+    private accumulator;
+    private sinceSent;
+    private timer?;
+    private last;
+    private readonly sendEvery;
+    /** Simulation speed multiplier, 0 pauses */
+    speed: number;
+    constructor(world: World, options?: SessionHostOptions);
+    private readonly onError?;
+    private readonly stopFailed;
+    private readonly dropSilentAfter;
+    private readonly keptFrames;
+    private readonly keptBytes;
+    private readonly groundPart;
+    private readonly keptEvents;
+    /** Whether the characters sent are counted by what they carry (`bytesByKey`) */
+    private readonly byKey;
+    private readonly ownsWorld;
+    private readonly maxTicks;
+    private readonly onSlowTick?;
+    /**
+     * Seats a player at the world, on the host's end of a transport. The welcome goes out at once: everything the player
+     * may know, also to one who comes back. `readOnly` for who only watches: their commands go nowhere but their lines
+     * of chat and their pings, which go to who watches alone (`observers`, said by `name`); and with `observer` they see
+     * everything, from `player`'s side. `allow` decides on each command before it goes in: a limit of how many, a game
+     * paused. One it lets go is answered, refused (the `command` event of its `seq`): with what it gives for why, or
+     * `cannotDoThat` for `false`
+     */
+    connect(player: PlayerId, transport: Transport, options?: {
+        readOnly?: boolean;
+        observer?: boolean;
+        allow?: () => boolean | MessageRef;
+        name?: string;
+    }): void;
+    /** The ground the world started as, whole, in parts small enough to go one at a time: made the first time one is asked for */
+    private groundParts;
+    private ground?;
+    /** The player has the frame of `tick`: what comes next is made against it, and what it has is not sent again */
+    private acknowledge;
+    /**
+     * Whether a player is sent nothing this round: it has no frame kept to make a delta against, and the whole one it
+     * was sent last is on its way still. Another would be as big, and come no sooner than the answer to the first
+     */
+    private holding;
+    private leave;
+    /** How many players are connected */
+    get players(): number;
+    private post;
+    /** Lets `dt` seconds pass: the ticks that fit into it, then what changed to everyone, when it is time to send */
+    update(dt: number): void;
+    /** What the debug tools of a seat follow, as the world stands: when they follow, list or log anything */
+    private sendDebug;
+    /** Moves the game on by `ticks` at the next update, however fast it goes: a step of a held game (`speed` 0) */
+    advance(ticks?: number): void;
+    /**
+     * Sends everyone what changed, when it is time to, for a world something else steps: the page's own game, shared with
+     * those who watch it (`shareGame`). `dt` is the seconds since the last call. Nothing goes while the world stands still
+     */
+    publish(dt: number): void;
+    /** The tick what changed went out at last */
+    private sentTick;
+    /** Talk was carried out since what changed went out last: it goes out with no tick to wait for (RV14) */
+    private heardOutside;
+    /** What changed to everyone, when the rate allows */
+    private sendDue;
+    /**
+     * Where the host's time went since it was last asked (`takeTiming`): ticks of the simulation, and rounds of sending
+     * everyone what changed (the snapshots, the diffs, the JSON), each in milliseconds, added up and at most
+     */
+    private timing;
+    /**
+     * Where the host's time went since it started, never counted anew: ticks and rounds of sending, with the
+     * milliseconds they took, and how long the last tick took. What a server's numbers are made of (`/metrics`)
+     */
+    readonly totals: {
+        ticks: number;
+        tickTime: number;
+        lastTick: number;
+        sends: number;
+        sendTime: number;
+    };
+    /** Where the time went since the last call, and starts counting anew: for a server to print */
+    takeTiming(): HostTiming & {
+        seconds: number;
+    };
+    /** The lists of entities told this round so far, and what each was sent as, for the seats told the same to share one (`quantizedList`) */
+    private roundEntities;
+    /** What the player knows now, as what changed since the tick they last said they got */
+    private deltaFor;
+    /**
+     * Keeps the frame a player was sent, to make the next delta against: the oldest let go past `keptFrames` of them or
+     * `keptBytes` together, the newest kept whatever it takes. A player who says nothing for long is sent everything
+     * again, once its base is no longer kept
+     */
+    private keep;
+    /** Lets go of a frame kept for a player */
+    private forget;
+    /** Runs the world by the clock, `rate` updates a second, until `stop` or `dispose` */
+    start(rate?: number): void;
+    stop(): void;
+    /** Whether it runs by the clock */
+    get running(): boolean;
+    /** Stops, and closes every connection. The world goes too, when it is the host's (`ownsWorld`) */
+    /**
+     * Stops, and lets every player go: their connections closed, unless `closeTransports` is false (a server that keeps
+     * them for its lobby, after the game)
+     */
+    dispose(options?: {
+        closeTransports?: boolean;
+    }): void;
+}
+/**
+ * What the player's side keeps of the map, to answer the screen without asking the host: a placement grid and the
+ * ways to walk of the map as it was made, with the structures the player has seen on them. What they have not seen
+ * is not there: a path preview never goes around a building in the dark, and gives it away
+ */
+export declare class ClientWorld {
+    readonly terrain: Terrain;
+    private readonly registry;
+    readonly nav: Navigation;
+    readonly air: Navigation;
+    readonly grid: BuildGrid;
+    private readonly known;
+    private readonly seen;
+    constructor(terrain: Terrain, registry: Registry, nav: Navigation, air: Navigation);
+    /** Whether a resource of a kind that it knows of covers just this ground, with nothing it knows of standing on it */
+    resourceAt(kind: string, cellX: number, cellZ: number, w: number, d: number): boolean;
+    /** Brings the structures up to date with a snapshot: those in it stand, those no longer in it are gone */
+    sync(snapshot: Snapshot): void;
+}
+/**
+ * The host said no, with why: to come back to a game that is over, or a player let go. Trying again does not help
+ *
+ * @beta
+ */
+export declare class SessionRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * A player's seat at a world that runs elsewhere, over a transport (see `connect`). It rebuilds what the host sends
+ * as changes (`Delta`) into whole snapshots, keeping the objects of what did not change, says which ticks it got, and
+ * answers the screen's questions from those and its own copy of the map (`ClientWorld`). No debug access, and no
+ * checkpoints: those belong to a simulation in the page
+ *
+ * @beta
+ */
+export declare class RemoteSession implements GameSession {
+    private transport;
+    private readonly map;
+    /** How much it keeps and how often it asks (`ConnectOptions`) */
+    protected readonly limits: PlayerLimits;
+    /**
+     * A seat over a wire can none of what a game in this page can (`SessionCan`), but the debug tools' view of the world
+     * for a player the host lets use them (`inspect`, said over the wire)
+     */
+    readonly can: SessionCan;
+    /** The debug tools' view of the world, for a player the host lets use them (the welcome's `debug`) */
+    protected get debugView(): SessionDebug | undefined;
+    private readonly remoteDebug?;
+    readonly playerId: PlayerId;
+    team: number;
+    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 player knows by tick, for the deltas to come: from the base of the last one on */
+    private readonly frames;
+    private latest;
+    private readonly incoming;
+    /** What the host's definitions were changed to while it ran (`world.redefine`), as this screen heard it */
+    private readonly redefined;
+    /** The number of the last batch of events that went to the screen (`Delta.events`): those sent again are not applied twice */
+    private eventsUpTo;
+    private readonly fogState;
+    private closed;
+    /** The tick the screen shows, between the last two snapshots given out */
+    private renderTick?;
+    /** The tick of the snapshot given out last, and of the one before it */
+    private shownTick;
+    private shownBefore;
+    /** Ticks between two snapshots, evened out */
+    protected interval: number;
+    /** How far off the time snapshots arrive at is from the ticks between them, in seconds, evened out */
+    protected jitter: number;
+    /** When the last snapshot arrived, and its tick */
+    private arrival?;
+    constructor(transport: Transport, welcome: Extract<GameHostMessage, {
+        type: 'welcome';
+    }>, registry: Registry, map: ClientWorld, 
+    /** How much it keeps and how often it asks (`ConnectOptions`) */
+    limits?: PlayerLimits);
+    /** Talks through a transport from now on: what comes in is taken, and its closing is a drop */
+    private attach;
+    /** Whether the host has gone */
+    get disconnected(): boolean;
+    /**
+     * Told when the connection drops, not by this side's leaving (`dispose`): to try again (`resume`), or to say the
+     * game is lost
+     */
+    onDisconnect?: () => void;
+    /** This side closed it: not a drop */
+    private leaving;
+    /**
+     * Goes on with the same game over a new connection, once the host has welcomed it there again (a server does, to who
+     * comes back with their seat's token): everything known sent again, and the screen catches up. What the host says
+     * besides the game before the welcome goes to `onServer`; a `refused` fails it with the reason, as does a connection
+     * that closes first, or a host that runs another game
+     */
+    resume(transport: Transport): Promise<void>;
+    /** Keeps what the host's definitions were changed to, over what was kept before */
+    private heardRedefined;
+    /**
+     * Takes a new version of the game into this screen's registry (hot reload, a game in a worker): its definitions as
+     * the new version has them, what the host changed of them while it ran over them again
+     */
+    takeGame(game: GameModule): void;
+    /** Takes in a message of the host's: what the transport hands it, and what came in while the session was made */
+    receive(message: HostToPlayer): void;
+    /**
+     * The game paused by the server, for everyone: by a player (`player`, until a time at most, in `Date.now()`'s
+     * milliseconds) or an admin (neither). Null while it goes on
+     */
+    pause: {
+        player?: PlayerId;
+        until?: number;
+    } | null;
+    /** Told each time the server pauses the game or lets it go on */
+    onPause?: (pause: {
+        player?: PlayerId;
+        until?: number;
+    } | null) => void;
+    /** Says something to the server beside the game: a lobby's message (`{ type: 'resume' }`) */
+    tell(message: {
+        type: string;
+    } & Record<string, unknown>): void;
+    /** Why the game ended on an error in its rules, once the host said so */
+    failure: {
+        message: string;
+    } | null;
+    /** Milliseconds a message takes to the host and back, evened out: measured every couple of seconds */
+    ping?: number;
+    /** Whether the player only watches, and sees everything */
+    readonly observer: boolean;
+    private pinger?;
+    /** Asks the host to answer at once, to measure the time there and back */
+    private sendPing;
+    /** Told of what the host says besides the game: a server's messages (see `ConnectOptions.onServer`) */
+    onServer?: ConnectOptions['onServer'];
+    /** Rebuilds the frame a delta makes, says it got it, and has its snapshot wait for the screen */
+    private take;
+    /**
+     * The oldest snapshot waiting let go, its events put before the next one's: the screen, when it asks again, jumps
+     * to the newest anyway. The state is in every snapshot; the events (deaths, sounds, lines said) are what would be lost
+     */
+    private fold;
+    /**
+     * Snapshots come in and not yet given to the screen (`update`): a few normally, never more than a few seconds of
+     * them, however long the screen does not ask
+     *
+     * @beta
+     */
+    get waiting(): number;
+    private takeFog;
+    snapshot(): Snapshot;
+    /** The tick the screen is shown at, between two snapshots: behind the newest by `delay` */
+    get shownAt(): number;
+    /** How far behind the newest snapshot the screen is shown, in ticks: about two snapshots, and room for the jitter */
+    get delay(): number;
+    /** Takes note of when a snapshot arrived, for how far apart they come and how unevenly */
+    private arrived;
+    /**
+     * Lets the screen's clock go on by `dt`, and gives out the snapshots it has come to, oldest first: the screen draws
+     * between the last two (`alpha`). The time is the host's: the clock follows the snapshots, not the other way around
+     */
+    update(dt: number): Snapshot[];
+    send(command: PlayerCommand): number;
+    /** The number of the last command sent */
+    private lastSeq;
+    fog(): FogState;
+    camps(): readonly CampInfo[];
+    /**
+     * Whether the player could build this here, as far as they can tell: on their copy of the map, with the structures
+     * they know, on ground they have explored. The game's own say (the `canPlace` hook) is the host's: it may still refuse
+     */
+    canPlace(unitType: string, point: Vec2): boolean;
+    /** Which cells of a building's ground are in the way, as `canPlace` sees them: on the player's copy of the map, explored */
+    placeCells(unitType: string, point: Vec2): readonly boolean[] | undefined;
+    /** The way a unit would walk, on the player's copy of the map: around the structures they know, and no others */
+    findPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null;
+    dispose(): void;
+}
+/** @beta */
+export interface ConnectOptions {
+    /**
+     * The game module the host runs: the player's side needs its data, and checks it is the very same version. Or the
+     * games the player has, by id, for a host that says which it runs
+     */
+    game: GameModule | Record<string, GameModule>;
+    navigation?: RecastNavigationOptions;
+    /** The maps the welcome's ground may be one of (S36): the game's own (`GameModule.maps`) when left out */
+    maps?: readonly GameMap[];
+    /**
+     * What the player's side keeps and how often it asks: `pingEvery`, `maxJitter`, `keptSnapshots`,
+     * `keptScreenEvents` (`PlayerLimits`)
+     *
+     * @beta
+     */
+    limits?: PlayerLimits;
+    /** What else the host says, before the game and during it: a server's lobby, a pause, the result */
+    onServer?: (message: ServerToPlayer) => void;
+}
+/**
+ * Connects to a host over a transport (the player's end of it), and waits for the welcome: what the session is
+ * made of. Fails when the host runs another version of the game, or of the engine's wire (`PROTOCOL_VERSION`), and
+ * when the connection closes before the session is made: while the map is made from the welcome too
+ *
+ * @beta
+ */
+export declare function connect(transport: Transport, options: ConnectOptions): Promise<RemoteSession>;
+/** `connect`, for a session of a kind of its own: `make` is given what a `RemoteSession` is made of */
+export declare function connectAs<S extends RemoteSession>(transport: Transport, options: ConnectOptions, make: (...made: ConstructorParameters<typeof RemoteSession>) => S): Promise<S>;

package/dist/session/replay.d.ts

@@ -0,0 +1,114 @@
+import { type CommandReplay } from './commandReplay';
+import type { PlayerId } from '#engine/entity';
+import type { GameModule } from '#engine/game';
+import type { Component } from '#engine/components';
+import type { World } from '#engine/world';
+import { type RemoteSession } from './remote';
+/**
+ * A game recorded (`recordGame`), to play back (`playReplay`): its commands, run again (`CommandReplay`), or the frames
+ * a watcher of it was sent (`FramesReplay`)
+ *
+ * @beta
+ */
+export type Replay = FramesReplay | CommandReplay;
+/**
+ * A game recorded as the frames a watcher of it was sent: only what `player` saw, and what it was sent of it
+ *
+ * @beta
+ */
+export interface FramesReplay {
+    format: 1;
+    /** The game it is of, by id: a page plays back what it has */
+    game: string;
+    /** Whose side it was seen from: their lines and cinematics, everything in sight besides */
+    player: PlayerId;
+    tickRate: number;
+    /** The tick it started and ended at */
+    from: number;
+    to: number;
+    /** What the host sent, as it sent it, with the tick of the world then */
+    frames: [tick: number, message: string][];
+}
+/**
+ * A game being recorded
+ *
+ * @beta
+ */
+export interface ReplayRecorder {
+    /** Ticks recorded so far */
+    readonly ticks: number;
+    /** Stops, and gives what was recorded */
+    stop(): Replay;
+}
+/**
+ * How a game is recorded (`recordGame`): whose side it is seen from when played back, and which kind of replay.
+ * `commands` (the default) keeps the start and what the players told it, and plays it back by running it again: a few
+ * kilobytes, every side of it, and the same to the last bit while the rules are (determinism D4). `frames` keeps what a
+ * watcher from `player`'s side was sent, `sendRate` times a second: for a game whose rules cannot be run again
+ *
+ * @beta
+ */
+export interface RecordOptions {
+    player: PlayerId;
+    kind?: 'commands' | 'frames';
+    /** Frames a second, of a `frames` replay: 10 when left out */
+    sendRate?: number;
+    /** Ticks between the hashes a `commands` replay keeps: 300 when left out */
+    every?: number;
+    /**
+     * Ticks between the checkpoints a `commands` replay keeps (the world as a save, to be played from a moment without
+     * running all before it: going back, opening it halfway). None when left out: each is as big as a save @beta
+     */
+    checkpoints?: number;
+}
+/**
+ * Records a game played in the page (`RecordOptions`): as its start and its players' commands (`kind: 'commands'`,
+ * the default: `recordCommands`), or as an observer from `player`'s side sees it, what changed `sendRate` times a
+ * second (`kind: 'frames'`). Frames are answered at once, as by a watcher who missed nothing, so what is kept is what
+ * changed and not the whole world again
+ *
+ * @beta
+ */
+export declare function recordGame(world: World, options: RecordOptions): ReplayRecorder;
+/**
+ * A replay playing (`playReplay`): its session, and its clock
+ *
+ * @beta
+ */
+export interface ReplayPlayer {
+    /** The game as it was, once the welcome is in */
+    session: Promise<RemoteSession>;
+    /** The tick of the game it is at */
+    readonly tick: number;
+    /** How fast it plays: 1 as it was played, 0 holds it */
+    speed: number;
+    /**
+     * Goes to a tick, ahead or back, run (or handed over) a slice a look (`REPLAY_SLICE`) so that the page goes on
+     * meanwhile: `behind` says how much is left. Back starts again in the same session (`RemoteSession.resume`): a
+     * replay of commands from the last checkpoint before the tick, one of frames from its start
+     */
+    skipTo(tick: number): void;
+    /** Ticks still to run (or hand over) to come to the moment asked, by a seek or a fast speed: 0 while it keeps up */
+    readonly behind: number;
+    /** Whether all of it has played */
+    readonly ended: boolean;
+    /**
+     * Of a replay of commands, the tick it came apart from the game recorded at (its hash differed: the rules changed
+     * since), or null while it has not. Never for a replay of frames
+     */
+    readonly apart?: number | null;
+    stop(): void;
+}
+/**
+ * Plays a replay back, as a watcher's session (`connect`): a replay of commands run again (`playCommands`), or what the
+ * host sent coming in as it came, by the replay's ticks; `speed` times as fast. `game` is the game module it is of, or
+ * the modules the page has, by id
+ *
+ * @beta
+ */
+export declare function playReplay(replay: Replay, options: {
+    game: GameModule | Record<string, GameModule>;
+    at?: number;
+    /** What the app kept in the world beside the game's (`CreateWorldOptions.components`): a replay of commands loads its saves with them */
+    components?: readonly Component<unknown, unknown>[];
+}): ReplayPlayer;

package/dist/session/seed.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A seed of the moment, for a game no other was (the clock: a session's, never the rules'): where every new world made without a seed of its own gets its seed
+ * (a map played in a page, on a server, in a worker). The same seed, the same game
+ *
+ * @beta
+ */
+export declare const randomSeed: () => number;