@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/session/share.d.ts

@@ -0,0 +1,78 @@
+import type { PlayerId } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * What the relay tells pages besides the game itself
+ *
+ * @beta
+ */
+export type RelayNotice = 
+/** To a sharing page: it shares under `key` now */
+{
+    type: 'shared';
+    key: string;
+}
+/** To a sharing page: another page shares under that key already */
+ | {
+    type: 'taken';
+    key: string;
+}
+/** To a sharing page: someone watches, by the id the relay gave them */
+ | {
+    type: 'watcher';
+    id: number;
+}
+/** To a sharing page: what a watcher said (that it got a tick, a ping) */
+ | {
+    type: 'from';
+    watcher: number;
+    text: string;
+}
+/** To a sharing page: a watcher left */
+ | {
+    type: 'gone';
+    watcher: number;
+}
+/** To a watcher: nothing is shared under the key right now. The game comes once it is */
+ | {
+    type: 'waiting';
+    key: string;
+}
+/** To a watcher: the game shared ended. The next one under the key comes when it is shared */
+ | {
+    type: 'ended';
+    key: string;
+};
+/** @beta */
+export interface ShareOptions {
+    /** The relay's address, `ws://host:port` */
+    url: string;
+    /** What watchers ask for: the same for every game of a campaign, so they stay from one mission to the next */
+    key: string;
+    /** What it is, for the relay's log */
+    name: string;
+    /** Whose side watchers see it from: they get that player's lines and cinematics, and see everything besides */
+    player: PlayerId;
+    /** Snapshots a second to each watcher. 20 when left out */
+    sendRate?: number;
+}
+/**
+ * A game shared for watching (`shareGame`)
+ *
+ * @beta
+ */
+export interface SharedGame {
+    /** `shared` once the relay has it; `taken` when another page shares under the key; `closed` once it is over */
+    readonly state: 'shared' | 'taken' | 'closed';
+    /** How many watch it now */
+    readonly watchers: number;
+    /** Told whenever the state or the number of watchers changes */
+    onChange(handler: () => void): void;
+    /** Stops sharing: the watchers are told it ended */
+    close(): void;
+}
+/**
+ * Shares the page's world through a relay, for others to watch. Fails when the relay cannot be reached
+ *
+ * @beta
+ */
+export declare function shareGame(world: World, options: ShareOptions): Promise<SharedGame>;

package/dist/session/socket.d.ts

@@ -0,0 +1,8 @@
+import type { Transport } from './remote';
+/**
+ * The player's end of a connection to a server, over a WebSocket: what `connect` and a server's lobby talk through.
+ * Resolves once the connection is open; fails when it cannot be made
+ *
+ * @beta
+ */
+export declare function openSocket(url: string): Promise<Transport>;

package/dist/session/wire.d.ts

@@ -0,0 +1,153 @@
+/**
+ * What goes over the wire between a host and a player, both layers of it in one place (design review E11): the game's
+ * (`GameHostMessage`, `GameCommandMessage`: a `SessionHost` and a `RemoteSession`) and a server's lobby beside it
+ * (`LobbyServerMessage`, `LobbyPlayerMessage`: a `GameServer`). One union each way (`HostToPlayer`, `PlayerToHost`),
+ * discriminated by `type` (no type is both a game's and a lobby's), read with a shape check (`readHostMessage`,
+ * `readPlayerMessage`), and `PROTOCOL_VERSION` is of all of it
+ */
+import type { GameData } from '#engine/gameData';
+import type { Inspection, InspectTarget, LoggedEvent, WorldListing } from '#engine/inspect';
+import type { PlayerId } from '#engine/entity';
+import type { GameResult, ServerHooks, ServerSeat } from '#engine/game';
+import type { SavedGround } from '#engine/ground';
+import type { MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map';
+import type { Delta } from './delta';
+import type { RelayNotice } from './share';
+/**
+ * What the host sends a player
+ *
+ * @beta
+ */
+export type GameHostMessage = {
+    type: 'welcome';
+    /** The version of the wire the host speaks (`PROTOCOL_VERSION`): a player of another refuses the game */
+    protocol: number;
+    player: PlayerId;
+    tickRate: number;
+    /** The game module the world runs, by id, and the version of its data (`Registry.dataHash`): the player's has to be the same */
+    game: string;
+    hash: string;
+    /**
+     * The ground: all of it, or the map of the game it started as and what changed of it since (S36). A player
+     * without that map asks for it (`ground`), and is sent it in parts
+     */
+    terrain: SavedGround;
+    /** What the map looks like beyond its ground, for the screen */
+    environment?: MapEnvironment;
+    /** Its scenery, for the screen */
+    doodads?: MapDoodad[];
+    /** Its regions, for the screen: what mist in places lies over by name */
+    regions?: MapRegion[];
+    /** Its views saved under names */
+    cameras?: MapCamera[];
+    /** Its paths, for a cinematic's camera on a rail */
+    paths?: MapPath[];
+    /** What its definitions were changed to while it ran (`world.redefine`), copies and all: put in the player's registry */
+    redefinitions?: GameData;
+    /** Everything the player knows, as a delta without a base */
+    first: Delta;
+    /** The player only watches, and sees everything */
+    observer?: boolean;
+    /** The player may use the debug tools (`world.debugPlayers`): the host follows the world for them (`debug`) */
+    debug?: true;
+} | {
+    type: 'pong';
+    at: number;
+}
+/** A part of the ground a world started as, for a player who does not have its map: `text` of `parts`, joined, is a `TerrainSave` */
+ | {
+    type: 'ground';
+    part: number;
+    parts: number;
+    text: string;
+}
+/** The game ended on an error in its rules (`World.failure`): what the players are told of it */
+ | {
+    type: 'failed';
+    message: string;
+} | ({
+    type: 'delta';
+} & Delta)
+/** The debug tools' view of the world (`SessionDebug`), for a player who may use them and follows something: every tenth of a second */
+ | {
+    type: 'debug';
+    inspection: Inspection | null;
+    world: WorldListing | null;
+    log: readonly LoggedEvent[];
+};
+/**
+ * What the debug tools of a screen ask of a world elsewhere (`SessionDebug`), as said over the wire or to a worker
+ *
+ * @beta
+ */
+export interface DebugAsk {
+    inspect?: InspectTarget | null;
+    set?: {
+        path: (string | number)[];
+        value: number | boolean;
+    };
+    listing?: boolean;
+    logging?: boolean;
+    clearLog?: true;
+}
+/**
+ * What the server tells everyone connected, as it changes
+ *
+ * @beta
+ */
+export type LobbyServerMessage = {
+    type: 'lobby';
+    mode: string;
+    game: string;
+    phase: 'lobby' | 'game' | 'ended';
+    seats: ServerSeat[];
+    settings: Record<string, string>;
+    /** What the game offers to set (`ServerHooks.settings`) */
+    offered: NonNullable<ServerHooks['settings']>;
+    /** What the game offers to set for each seat (`ServerHooks.seatSettings`, and a race: `seatSettingsOf`) */
+    seatOffered: NonNullable<ServerHooks['seatSettings']>;
+} | {
+    type: 'seated';
+    player: PlayerId;
+    token: string;
+}
+/** A line said in the lobby (`lobbyChat`): by whom, their seat where they have one */
+ | {
+    type: 'lobbyChat';
+    player?: PlayerId;
+    name: string;
+    text: string;
+} | {
+    type: 'watching';
+    player: PlayerId;
+} | {
+    type: 'full';
+} | {
+    type: 'refused';
+    reason: string;
+}
+/** The game paused, or going on: by a player (`player`, for `seconds` at most) or by an admin (no player) */
+ | {
+    type: 'paused';
+    paused: boolean;
+    player?: PlayerId;
+    seconds?: number;
+} | {
+    type: 'result';
+    result: GameResult;
+};
+/**
+ * What a player is told besides the game: a server's lobby, a pause, the result, or, watching through a relay, that
+ * nothing is shared yet or that the game watched ended
+ *
+ * @beta
+ */
+export type ServerToPlayer = LobbyServerMessage | Extract<RelayNotice, {
+    type: 'waiting' | 'ended';
+}>;
+/**
+ * Everything a host, a server or a relay sends a player
+ *
+ * @beta
+ */
+export type HostToPlayer = GameHostMessage | ServerToPlayer;

package/dist/session/worker.d.ts

@@ -0,0 +1,227 @@
+import type { PlayerId } from '#engine/entity';
+import { type GameModule } from '#engine/game';
+import { type LogEntry, Logger } from '#engine/log';
+import type { GameMap } from '#engine/map';
+import type { Message } from '#engine/messages';
+import { type NavigationBuild } from '#engine/navigation/builds';
+import { type WorldSave } from '#engine/save';
+import type { World } from '#engine/world';
+import type { SystemTiming } from '#engine/scheduler';
+import type { SessionCan, SessionDebug } from './protocol';
+import { type ConnectOptions, RemoteSession } from './remote';
+/**
+ * What a worker is, as far as a game goes: a page's `Worker`, or Node's `worker_threads` one
+ *
+ * @beta
+ */
+export interface WorldWorkerLike {
+    postMessage(message: unknown, transfer?: unknown[]): void;
+    addEventListener?(type: 'message' | 'error', listener: (event: {
+        data?: unknown;
+        message?: string;
+    }) => void): void;
+    removeEventListener?(type: 'message' | 'error', listener: (event: {
+        data?: unknown;
+        message?: string;
+    }) => void): void;
+    on?(type: 'message' | 'error', listener: (value: unknown) => void): void;
+    off?(type: 'message' | 'error', listener: (value: unknown) => void): void;
+}
+/**
+ * Where a worker hears and answers: a page's worker scope, or Node's `parentPort`
+ *
+ * @beta
+ */
+export interface WorldPort {
+    postMessage(message: unknown, transfer?: unknown[]): void;
+    addEventListener?(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    on?(type: 'message', listener: (value: unknown) => void): void;
+}
+/**
+ * What the page says a game in a worker is made from: plain data, which is all that crosses
+ *
+ * @beta
+ */
+export interface WorkerGame {
+    /** A map of the game: the world is made from it. Or a save to go on from (`from`); or neither, where the worker makes its world in code */
+    map?: GameMap;
+    from?: WorldSave;
+    /** Who the player at the screen is: as the worker says (`ServeWorldOptions.player`), then the map's first with a start, when left out */
+    player?: PlayerId;
+    seed?: number;
+    /** Whether the player may use the debug tools, and sees everything from the start */
+    debug?: boolean;
+    reveal?: boolean;
+    /** Anything else the worker's own code is to know (`start`, `world`): plain data */
+    args?: unknown;
+}
+/**
+ * What the worker's file gives besides the game: its code that runs on the world, which cannot be sent
+ *
+ * @beta
+ */
+export interface ServeWorldOptions {
+    /** A world made in code, where the page gives neither a map nor a save: generated ground, players of its own */
+    world?: (context: {
+        rules: GameModule;
+        seed: number;
+        args: unknown;
+        log: Logger;
+    }) => World | Promise<World>;
+    /** What the game does once a new world is made, before anyone plays: as `launch`'s `start`, which a worker's game has here */
+    start?: (world: World, context: {
+        player: PlayerId;
+        map?: GameMap;
+        args: unknown;
+    }) => void | Promise<void>;
+    /** Who the player at the screen is, where the page does not say */
+    player?: (world: World, map?: GameMap) => PlayerId;
+    /** Where it hears: the worker's own scope when left out (a page's worker); Node's `parentPort` in a worker thread */
+    port?: WorldPort;
+    /**
+     * A new version of the game, loaded again in the worker as the page asks (hot reload: the page's game took one, and
+     * a worker has no hot reload of its own). The game's module imported anew, so that the dev server gives it as it is
+     * now: `(version) => import(/* @vite-ignore *\/ `./index.ts?t=${version}`).then((module) => module.myGame)` (a path
+     * from the worker's file). Only ever asked for in the dev server. Without it, a game in the worker keeps the version it began with
+     */
+    reload?: (version: number) => Promise<GameModule | undefined> | GameModule | undefined;
+}
+/** What goes between the page and the worker besides the session's own text */
+type ToWorker = ({
+    vg: 'start';
+} & WorkerGame) | {
+    vg: 'stop';
+} | {
+    vg: 'reload';
+} | {
+    vg: 'speed';
+    speed: number;
+} | {
+    vg: 'advance';
+    ticks: number;
+} | {
+    vg: 'save';
+    id: number;
+} | {
+    vg: 'navigation';
+    id: number;
+    build: NavigationBuild;
+} | {
+    vg: 'profile';
+    on: boolean;
+};
+type FromWorker = {
+    vg: 'ready';
+    player: PlayerId;
+} | {
+    vg: 'refused';
+    message: string;
+    stack?: string;
+} | {
+    vg: 'saved';
+    id: number;
+    save?: WorldSave;
+    error?: string;
+} | {
+    vg: 'built';
+    id: number;
+    data?: Uint8Array;
+    error?: string;
+} | {
+    vg: 'checkpoint';
+    label: Message;
+    save: WorldSave;
+} | {
+    vg: 'log';
+    entry: LogEntry;
+} | {
+    vg: 'timing';
+    tick: number;
+    tickMax: number;
+    send: number;
+    systems: SystemTiming[];
+};
+/**
+ * What a game's worker file does: `serveWorld(game, { start })`. It waits for the page to say what to play (a map, a
+ * save, or nothing for a world made here in code), makes the world, runs it by the clock, and seats the page's player
+ * at it. A new game asked for ends the one before: a restart is the same worker, its navigation built already
+ *
+ * @beta
+ */
+export declare function serveWorld(first: GameModule, options?: ServeWorldOptions): void;
+/**
+ * A seat at a game run in a worker of this page (`workerSession`): a `RemoteSession` whose host is a message away,
+ * with what a game played in the page has besides: its pace held and stepped (`speed`, `advance`), a save of it
+ * (`save`), the checkpoint to start again from, what it says in its log, the debug tools' view, and where its time went
+ *
+ * @beta
+ */
+export declare class WorkerSession extends RemoteSession {
+    /** What the world says (`World.log`), said again here: the page shows it with its own */
+    log: Logger;
+    checkpoint?: {
+        label: Message;
+        save: WorldSave;
+    };
+    /** The debug tools' view of the world, where they are on: over the session's own words, as a server's is */
+    get debug(): SessionDebug | undefined;
+    /** Its pace held and stepped, saves of it, the debug tools' view where they are on, and where its time went and in which systems */
+    readonly can: SessionCan;
+    private pace;
+    private timed?;
+    /** Milliseconds the page took to take in what the worker sent, each time, evened out: its share of a game run there */
+    received: number;
+    private postToWorker;
+    private readonly saves;
+    private nextSave;
+    private stopHearing;
+    /** What `workerSession` gives it once it is made: the way to the worker, and what stops hearing it */
+    wire(post: (message: ToWorker) => void, log: Logger, stop: () => void): void;
+    /** What the worker said that is not the session's own text */
+    heard(said: FromWorker): void;
+    /**
+     * How far behind the newest tick the screen is shown, in ticks: one, and room for how unevenly they come (a tick
+     * that took long comes late). Less than over a wire, where two are kept in hand: there is no line to stall here
+     */
+    get delay(): number;
+    get speed(): number;
+    set speed(speed: number);
+    advance(ticks?: number): void;
+    /**
+     * Asks the worker to take a new version of the game (hot reload): it loads the game again itself, as its file says
+     * (`serveWorld` `reload`), and puts it into its world
+     */
+    reloadGame(): void;
+    save(): Promise<WorldSave>;
+    timing(): {
+        tick: number;
+        tickMax: number;
+        send: number;
+        receive: number;
+        systems: SystemTiming[];
+    } | undefined;
+    /** Ends the game in the worker. The worker is the page's: it stays, for the next game, until the page ends it */
+    dispose(): void;
+}
+/**
+ * What a seat at a worker's game is asked for: what to play (`WorkerGame`), and what `connect` takes
+ *
+ * @beta
+ */
+export interface WorkerSessionOptions extends WorkerGame, Pick<ConnectOptions, 'navigation' | 'maps'> {
+    game: GameModule;
+    /** The logger what the world says is said under, in the page: the root one when left out */
+    log?: Logger;
+}
+/**
+ * Plays a game in a worker, and seats this page's player at it: the worker's file calls `serveWorld` with the same
+ * game. Settles once the world is made there and its welcome is in; fails with what the worker said went wrong
+ *
+ *     const session = await workerSession(new Worker(new URL('./game.worker.ts', import.meta.url), { type: 'module' }), { game, map })
+ *
+ * @beta
+ */
+export declare function workerSession(worker: WorldWorkerLike, options: WorkerSessionOptions): Promise<WorkerSession>;
+export {};

package/dist/shared.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Rules the simulation and a player's screen both need, written once. Each works on plain facts that a world
+ * entity and a client's view of one can both give, so the screen greys out a button for the very reason the
+ * simulation would refuse it, and a game's own rules (items 9 to 11) reach both alike.
+ *
+ * The simulation has the last word all the same: the screen may know less than it does (a buff it is not told
+ * of, a step it has not seen yet), and only uses these to say something sooner.
+ */
+import { type AbilityDef, type Cost, type EntityKind, type Layer, type UnitTypeDef } from './defs';
+import { type Message } from './messages';
+import { type Purse } from './player';
+import type { Registry } from './registry';
+/**
+ * Who a target is to the one using an ability on it
+ *
+ * @beta
+ */
+export type Relation = 'self' | 'ally' | 'enemy' | 'neutral';
+/**
+ * What there is to know about a target, for whether an ability may be used on it
+ *
+ * @beta
+ */
+export interface TargetFacts {
+    kind: EntityKind;
+    layer: Layer;
+    hero: boolean;
+    invulnerable: boolean;
+    relation: Relation;
+    /** Immune to spells (see `UnitTypeDef.spellImmune`): no ability touches it but its own, and those that get through */
+    spellImmune?: boolean;
+}
+/**
+ * Why an ability may not be used on a target, or undefined when it may
+ *
+ * @beta
+ */
+export declare function targetRefusal(ability: AbilityDef, target: TargetFacts): Message | undefined;
+/**
+ * How far away the target of an ability may be: what it says, and for some as far as the caster's attacks reach on top
+ *
+ * @beta
+ */
+export declare const abilityReach: (ability: AbilityDef, level: number, attackRange: number) => number;
+/**
+ * What there is to know about an ability and its user, for whether it can be used right now
+ *
+ * @beta
+ */
+export interface ReadyFacts {
+    /** 0 for one not learned yet */
+    level: number;
+    /** Seconds until it can be used again */
+    cooldown: number;
+    /** Uses left, of an ability with charges (`chargesLeft`): none, and it is not ready */
+    charges?: number;
+    mana: number;
+    hp: number;
+    maxHp: number;
+    /** It comes from something carried: items ask for no mana, and silence does not stop them */
+    item?: boolean;
+    /** One of the spells the hero brought along rather than learned: silence does not stop those either */
+    spell?: boolean;
+    silenced?: boolean;
+    /** The debug switch that makes abilities cost nothing */
+    noManaCosts?: boolean;
+    /** What the simulation's `canCast` hook decided instead, when it told the screen: a reason, or null for none */
+    decided?: Message | null;
+}
+/**
+ * How many uses an ability with charges has left (`AbilityDef.charges`), at its level: what its state says, or all it
+ * holds when that says nothing. Undefined for an ability without charges
+ *
+ * @beta
+ */
+export declare function chargesLeft(ability: AbilityDef, state: {
+    level: number;
+    charges?: number;
+}): number | undefined;
+/**
+ * Why an ability cannot be used right now, or undefined when it can
+ *
+ * @beta
+ */
+export declare function abilityRefusal(ability: AbilityDef, facts: ReadyFacts): Message | undefined;
+/**
+ * What there is to know about a player, for whether they can make something
+ *
+ * @beta
+ */
+export interface PlayerFacts {
+    resources: Readonly<Purse>;
+    supplyUsed: number;
+    supplyCap: number;
+    /** The game's other pools of supply, by name (`GameRules.supply.pools`): left out in a game with none */
+    supplies?: Readonly<Record<string, {
+        used: number;
+        cap: number;
+    }>>;
+    /** Unit types they have, finished, which is what requirements ask for */
+    tech: ReadonlySet<string> | readonly string[];
+    /** Types of the heroes they have, fallen ones and ones being made included */
+    heroes: readonly string[];
+    /**
+     * What the simulation's `requirement` hook decided, where it differs from what the requirements say: by unit or
+     * structure type, and `upgrade:<id>` for the next level of research. A reason, or null for "may, for all that"
+     */
+    unlocks?: Record<string, Message | null>;
+    /** The race they play (`raceOf`): left out in a game without races */
+    race?: string;
+    /**
+     * What the simulation's `available` hook decided, where it differs from what their race says (`availableTo`): by
+     * unit or structure type, and `upgrade:<id>`
+     */
+    availability?: Record<string, boolean>;
+}
+/**
+ * Whether a worker gathers a kind of resource at all (`harvester.kinds`): the game's `canHarvest` hook may refuse it a
+ * resource all the same (`canHarvest`)
+ *
+ * @beta
+ */
+export declare const gathers: (def: Pick<UnitTypeDef, 'harvester'>, kind: string) => boolean;
+/**
+ * Whether something of a race (`UnitTypeDef.race`, `UpgradeDef.race`) is a player's to make as their race goes: what is
+ * of no race is everyone's, and a player of none (the neutral players, the creeps, any in a game without races) may
+ * make anything. The `available` hook has the last word (`isAvailable`)
+ *
+ * @beta
+ */
+export declare const availableTo: (def: {
+    readonly race?: string;
+}, race: string | undefined) => boolean;
+/**
+ * Whether a player may make something at all, as the simulation decided (`availability`, by `key`) or else as their
+ * race goes: what is not is left off their buttons
+ *
+ * @beta
+ */
+export declare function availableToPlayer(def: {
+    readonly race?: string;
+}, player: Pick<PlayerFacts, 'race' | 'availability'>, key: string): boolean;
+/**
+ * Why something may not be made as far as what it requires goes: as the simulation decided (`unlocks`), or by the finished buildings it requires
+ *
+ * @beta
+ */
+export declare function requirementRefusal(requires: readonly string[] | undefined, player: Pick<PlayerFacts, 'tech' | 'unlocks'>, key: string): Message | undefined;
+/**
+ * What stands in the way of a cost, or undefined when the player can pay it
+ *
+ * @beta
+ */
+export declare function costRefusal(resources: Readonly<Purse>, cost: Cost | undefined): Message | undefined;
+/**
+ * Why a player cannot have a unit made, or undefined when they can, as far as they and the unit type go: whether
+ * the building has room, and what a game's hooks say (they can change the cost), is for the simulation. In the order the
+ * player is told
+ *
+ * @beta
+ */
+export declare function trainRefusal(registry: Registry, def: UnitTypeDef, player: PlayerFacts, options?: {
+    cost?: boolean;
+    tech?: boolean;
+}): Message | undefined;
+/**
+ * What a shop pays for an item: a part of its price, and of what is left of it for what runs out
+ *
+ * @beta
+ */
+export declare function sellValue(registry: Registry, item: string, charges: number): number;