@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/save.d.ts

@@ -0,0 +1,277 @@
+import type { ErrorSite, WorldFailure } from './errors';
+import { type EntityId } from './entity';
+import type { FogSave } from './fog';
+import type { GroundItem } from './items';
+import type { AgentSave } from './navigation/navigation';
+import { type EffectRef } from './effectRefs';
+import type { PlayerInit, Purse } from './player';
+import type { Registry } from './registry';
+import { type SavedGround } from './ground';
+import type { Delayed, Missile, Projectile, Reveal, World, WorldInternals, Zone } from './world';
+/**
+ * A world saved: everything it takes to carry on with a game later, somewhere else, or from the same moment more
+ * than once. Plain data, and with `encodeSave` text: what is in the world points to definitions by id, and to
+ * other entities by id.
+ *
+ * What is not in it:
+ * - the game module (`WorldSave.game` names it), which `loadWorld` is given again;
+ * - navigation, which is built again from the terrain and the structures, with the agents put back where they were;
+ * - systems added while the game ran (`World.addSystem`), like a computer player: whoever loads adds them again,
+ *   and what they keep in themselves (`System.save`) goes back into them as they are added;
+ * - state a game module keeps outside the world, like in a `WeakMap` keyed by it. Keep it in components instead
+ *   (`World.state`, `Player.state`, `Entity.get`), which are in here.
+ *
+ * Two numbers say how old a save is, and they are not the same thing. `format` is the engine's: the shape of the save
+ * itself, which the engine brings up to date by itself. `version` is the game's: what the game keeps in a save (its
+ * unit types, its components), which the game brings up to date (`GameModule.saves`). A save is read through both
+ * (`updateSave`), the engine's first
+ *
+ * @beta
+ */
+export interface WorldSave {
+    /** The shape of the save itself (`SAVE_FORMAT`): the engine's to change, and to bring an older one up to */
+    format: typeof SAVE_FORMAT;
+    /** Id of the game module the world was made with */
+    game: string;
+    /** The version of what the game keeps in a save (`GameModule.saves.version`): 1 for a game that says none */
+    version: number;
+    /**
+     * Which rules it was made with exactly, mods and code included (see `gameHash`): whether it can be loaded as it is.
+     * What a game does about a save of other rules is its own to say (`GameModule.saves.onMismatch`)
+     */
+    hash: string;
+    tickRate: number;
+    tick: number;
+    winner: number | null;
+    /** The parts of the game switched off for having thrown (`world.disabled`): off again in the world loaded. None when left out */
+    disabled?: ErrorSite[];
+    /** Why the game ended on an error (`world.failure`), for a save taken of one that did */
+    failure?: WorldFailure;
+    rng: number;
+    internals: WorldInternals;
+    cheats: World['cheats'];
+    /** The entity each object of the map became, by the object's id (`World.mapEntities`): as `[object, entity]`. None when left out */
+    mapEntities?: [number, EntityId][];
+    /** The ground: all of it, or the map the world was made from and what changed of it since (S36, format 3) */
+    terrain: SavedGround;
+    players: PlayerSave[];
+    fog: FogSave;
+    /** Where walkable space was at: movement looks for a new path when it changes */
+    navVersion: number;
+    /** Everything in the world, in the order it was put there */
+    entities: EntitySave[];
+    /** Entities that left the world but are still pointed at, like the caster of something that has yet to land */
+    detached: EntitySave[];
+    /** Ids of the entities that act, in the order they are gone through: who goes first can decide what happens */
+    actors: EntityId[];
+    /** Scenery each team sees, by team */
+    sceneryInSight: Record<number, EntityId[]>;
+    projectiles: Projectile[];
+    missiles: MissileSave[];
+    /** What missiles sent together have passed through, which they share */
+    missileHits: EntityId[][];
+    delayed: DelayedSave[];
+    zones: ZoneSave[];
+    reveals: Reveal[];
+    items: GroundItem[];
+    /** State of game modules and mods for the whole game, by component id (see `World.state`) */
+    state: Record<string, unknown>;
+    /** What systems keep in themselves (`System.save`), by their name */
+    systems?: Record<string, unknown>;
+}
+/**
+ * The format saves are written in now: a save of another is refused. The engine keeps no steps up from an older one
+ * while it and its games are made (a game's own versions have `SaveRules.migrate`)
+ *
+ * @beta
+ */
+export declare const SAVE_FORMAT = 5;
+interface PlayerSave {
+    init: PlayerInit;
+    resources: Purse;
+    supplyUsed: number;
+    supplyCap: number;
+    /** The game's other pools (`GameRules.supply.pools`): left out of a save made before there were any */
+    supplies?: Record<string, {
+        used: number;
+        cap: number;
+    }>;
+    established: boolean;
+    defeated: boolean;
+    upgrades: [string, number][];
+    upgradesVersion: number;
+    researching: string[];
+    /** State of game modules and mods for the player, by component id */
+    state: Record<string, unknown>;
+}
+/**
+ * An entity: its type, and every field it has, as plain data. `agent` is how it moves, when it does
+ *
+ * @beta
+ */
+export type EntitySave = {
+    id: EntityId;
+    type: string;
+    owner: number;
+    agent?: AgentSave;
+} & Record<string, unknown>;
+type MissileSave = Omit<Missile, 'hit' | 'effect'> & {
+    hit: number;
+    effect: EffectRef;
+};
+type DelayedSave = Omit<Delayed, 'caster' | 'ability' | 'effects'> & {
+    caster: EntityId;
+    ability: string;
+    effects: EffectRef;
+};
+type ZoneSave = Omit<Zone, 'caster' | 'ability' | 'effect'> & {
+    caster: EntityId;
+    ability: string;
+    effect: EffectRef;
+};
+/**
+ * How a world is saved (`saveWorld`)
+ *
+ * @beta
+ */
+export interface SaveWorldOptions {
+    /**
+     * Whether the world's crowd is put back from what the save keeps of it, as loading the save puts it (determinism
+     * D2): the game saved and a game loaded from the save then go on exactly the same. A save keeps where each agent is
+     * and where it goes, not the crowd's own working (the order it moves its agents in, the paths it is part way
+     * along), which cannot be put back as it was. Yes when left out; `false` for a look at the state that leaves the
+     * world as it was (`worldState`, `worldHash`)
+     *
+     * @beta
+     */
+    reseat?: boolean;
+}
+/**
+ * Saves a world, between two ticks. Throws, saying where, when something in it is not plain data
+ *
+ * @beta
+ */
+export declare function saveWorld(world: World, options?: SaveWorldOptions): WorldSave;
+/** The players of a save, as a world is made with them */
+export declare const savedPlayers: (save: WorldSave) => PlayerInit[];
+/**
+ * Fills a world just made from the game module and the terrain and players of the save with the rest of it. The save
+ * is one of the format and the version read now: an older one goes through `updateSave` first, as `loadWorld` does
+ */
+export declare function restoreWorld(world: World, save: WorldSave): void;
+/**
+ * How a game's saves outlive its patches (`GameModule.saves`). Any change to a game's rules changes which rules they
+ * are exactly (`registry.hash`), and most changes are nothing to a save: a number tuned, a bug fixed. A game that
+ * declares this loads such a save as it is. A change a save cannot be read through (a unit type renamed, a component
+ * of another shape) takes a new `version`, and a step that brings the saves made before up to it
+ *
+ * @beta
+ */
+export interface SaveRules {
+    /**
+     * The version of what the game keeps in a save: a whole number from 1, and 1 when left out. One more with every
+     * patch that saves made before have to be changed for, together with the step that changes them (`migrate`). A save
+     * says which it is of (`WorldSave.version`); one of a version newer than the game's is refused
+     */
+    version?: number;
+    /**
+     * What brings an older save up to date. A step for each version, by the version it starts from (`{ 3: … }` makes a
+     * save of version 3 one of version 4), run one after the other; or one function for all of it, told the version the
+     * save is of and the one it is to be of. A save of a version with no step after it is refused, saying so: a version
+     * with nothing to change has the step `(save) => save`
+     */
+    migrate?: Record<number, SaveMigration> | ((save: WorldSave, from: number, to: number) => WorldSave | void);
+    /**
+     * What becomes of a save of the game's version made with other rules, its code, its numbers or its mods having
+     * changed since: `load` it as it is, `refuse` it, or a function that says which, given the save and the hash of the
+     * rules now. `load` when left out
+     */
+    onMismatch?: 'load' | 'refuse' | ((save: WorldSave, hash: string) => 'load' | 'refuse');
+}
+/**
+ * A step of a game's own, from one version of its saves to the next. The save is plain data in the engine's format
+ * of now (the engine's own steps run first), and a copy: the step changes it in place, or gives another
+ *
+ * @beta
+ */
+export type SaveMigration = (save: WorldSave) => WorldSave | void;
+/**
+ * Why a save is not loaded:
+ * - `notASave`: it is not a save, or says nothing readable of its format or its version
+ * - `game`: it is another game's
+ * - `newer`: it was made by a newer version of the game, or of the engine, than this one
+ * - `noWay`: it is of an older version of the game's saves, and the game has no step from there (`SaveRules.migrate`)
+ * - `rules`: it was made with other rules, and the game does not load those (`SaveRules.onMismatch`)
+ * - `missing`: it has in it what the game no longer has (`SaveError.missing`)
+ * - `ground`: its ground is a map of the game as it was, which the game no longer has as it was (S36)
+ *
+ * @beta
+ */
+export type SaveRefusal = 'notASave' | 'game' | 'newer' | 'noWay' | 'rules' | 'missing' | 'ground';
+/**
+ * What a save has in it that the game does not have, by kind: their ids
+ *
+ * @beta
+ */
+export type SaveMissing = Partial<Record<'unit' | 'ability' | 'buff' | 'item' | 'upgrade' | 'order' | 'component' | 'timer' | 'sequence', string[]>>;
+/**
+ * A save that is not loaded, and why: for a list of saves to say, in words of its own
+ *
+ * @beta
+ */
+export declare class SaveError extends Error {
+    readonly reason: SaveRefusal;
+    /** For `missing`: what the save has that the game does not */
+    readonly missing?: SaveMissing | undefined;
+    constructor(message: string, reason: SaveRefusal, 
+    /** For `missing`: what the save has that the game does not */
+    missing?: SaveMissing | undefined);
+}
+/**
+ * What of a save says whether a game reads it, the rest of it apart: kept beside a save, for a list of them to ask with
+ *
+ * @beta
+ */
+export interface SaveHeader {
+    format: number;
+    game: string;
+    /** 1 when left out, as in a save from before games had versions of their saves */
+    version?: number;
+    hash: string;
+}
+/**
+ * The header of a save
+ *
+ * @beta
+ */
+export declare const saveHeader: (save: SaveHeader) => SaveHeader;
+/**
+ * Whether a game loads a save, as far as the save's header says (`saveHeader`): nothing, or why not. For a list of
+ * saves, which has no need to read each of them whole. What only the whole save says (something in it the game no
+ * longer has, a game that decides save by save) is found as it is loaded (`updateSave`, `loadWorld`)
+ *
+ * @beta
+ */
+export declare function saveProblem(header: SaveHeader, registry: Registry): SaveError | undefined;
+/**
+ * A save as the game reads it now, whatever it was saved by: brought up from an older version by the game's (`GameModule.saves.migrate`), each one version at a time. `loadWorld` runs
+ * it; a tool that keeps saves up to date runs it by itself. The save handed in is not changed. Throws a `SaveError`,
+ * which says why, for one that cannot be read: another game's, newer than this game, of a version the game has no
+ * step from, made with other rules by a game that refuses those (`anyVersion` loads it all the same), or with
+ * something in it the game no longer has, all of which the error names
+ *
+ * @beta
+ */
+export declare function updateSave(data: unknown, registry: Registry, options?: {
+    anyVersion?: boolean;
+}): WorldSave;
+/**
+ * A save as text. JSON, but for numbers JSON has no words for, which game state has: buffs that last forever
+ * (`Infinity`), something never hurt (`-Infinity`)
+ *
+ * @beta
+ */
+export declare function encodeSave(save: WorldSave): string;
+/** @beta */
+export declare function decodeSave(text: string): WorldSave;
+export {};

package/dist/scenario.d.ts

@@ -0,0 +1,56 @@
+import { type GameModule } from './game';
+import { type GameMap, type MapFile } from './map';
+import type { World } from './world';
+/**
+ * A situation for a test to start from, set up in the editor: a map made for it, or a world saved at the moment that
+ * matters (in the editor's play mode). Kept in the tests' scenarios (`<scenarios>/<game>/<name>.scenario.json`: `tests/scenarios` unless the project says otherwise), or in a game's folder,
+ * and loaded with what was named in the editor found by name. It says which format it was saved with, and is brought
+ * up to date like a map (`readScenario`): one that no longer loads fails its test with what is wrong
+ *
+ * @beta
+ */
+export type ScenarioFile = {
+    format: number;
+    name: string;
+    /** The game it is of, by the id of its module */
+    game: string;
+    /** What it is for, to read in a list */
+    description?: string;
+} & ({
+    kind: 'map';
+    map: MapFile;
+} | {
+    kind: 'save';
+    save: string;
+});
+/**
+ * The format scenarios are written in now
+ *
+ * @beta
+ */
+export declare const SCENARIO_FORMAT = 1;
+/**
+ * A scenario file as it is now, checked. Throws on what is wrong with it
+ *
+ * @beta
+ */
+export declare function readScenario(data: unknown): ScenarioFile;
+/**
+ * A map made for a test, as a scenario
+ *
+ * @beta
+ */
+export declare function scenarioOfMap(map: GameMap, name: string, game: string, description?: string): ScenarioFile;
+/**
+ * A world at the moment that matters, as a scenario
+ *
+ * @beta
+ */
+export declare function scenarioOfWorld(world: World, name: string, description?: string): ScenarioFile;
+/**
+ * The world of a scenario, with the game's module: a map made into a world as a game would make it (with the seed 1,
+ * so that it is the same every time), or a saved world loaded as it was
+ *
+ * @beta
+ */
+export declare function scenarioWorld(scenario: ScenarioFile, game: GameModule): Promise<World>;

package/dist/scheduler.d.ts

@@ -0,0 +1,67 @@
+import type { System, SystemPhase } from './registry';
+import type { World } from './world';
+/**
+ * The parts of a tick, in the order they run. The player commands of the tick have been applied before any of them.
+ * - `commands`: first, for what reacts to the commands, or adds some of its own
+ * - `decide`: units choose and carry out what they do: abilities, orders
+ * - `move`: everything that moves, moves
+ * - `resolve`: what follows from where things ended up: attacks land, buildings go up, units are trained
+ * - `cleanup`: bookkeeping once everything happened: what runs out, what each team sees, who won
+ *
+ * @beta
+ */
+export declare const PHASES: readonly SystemPhase[];
+/**
+ * What the scheduler measured of a system: milliseconds per tick, averaged, with the ticks it does not run counted as nothing
+ *
+ * @beta
+ */
+export interface SystemTiming {
+    name: string;
+    phase: SystemPhase;
+    ms: number;
+}
+/**
+ * Runs the systems of a world in their order, each as often as it asks. The order is worked out whenever a system
+ * is added or taken out: by phase first, then by what each says it comes `before` or `after`, then in the order
+ * they were added. Measures each one while `profiling` is on, for the stats panel.
+ *
+ * @beta
+ */
+export declare class Scheduler {
+    private readonly added;
+    private ordered;
+    private readonly timings;
+    /** Whether to time each system. Costs two clock readings per system per tick, so it is off unless someone looks */
+    profiling: boolean;
+    constructor(systems: System[]);
+    /** The systems, in the order they run */
+    get systems(): readonly System[];
+    /** Adds a system to a world that is already running, like a computer player */
+    add(system: System): void;
+    /** Takes a system out by name. False when there is none of that name */
+    remove(name: string): boolean;
+    /** Runs one tick of every system that is due. Each is given the time since it last ran */
+    run(world: World): void;
+    /** Runs a system. One that throws comes to what the world says of errors (`World.caught`): switched off, where it says so */
+    private update;
+    private readonly off;
+    /** Switches a system off: it no longer runs, and stays off when others are added */
+    disable(name: string): void;
+    /** What each system takes, in the order they run. Empty until `profiling` has been on for a while */
+    timing(): SystemTiming[];
+    private check;
+}
+/** What `order` sorts: a system, or anything else that runs in turn and says what it comes before and after (a brain's modules) */
+export interface Ordered {
+    name: string;
+    phase?: SystemPhase;
+    before?: string[];
+    after?: string[];
+}
+/**
+ * Sorts systems by phase, then by `before` and `after`, keeping the order they were given in where nothing says
+ * otherwise. Names that are not among them are passed over: what they named may have been left out of the game.
+ * The modules of a computer player's brain are put in their order by it too (`ai/brain.ts`)
+ */
+export declare function order<T extends Ordered>(systems: T[]): T[];