@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/game.d.ts

@@ -0,0 +1,501 @@
+import type { CellLayerDef } from './cellLayers';
+import type { GameFileDef } from './gameFiles';
+import { type ReplicatedEvent, type SnapshotPart } from './replication';
+import type { PrefabDef } from './prefabs';
+import type { MapGenerator } from './generate';
+import type { ErrorPolicy } from './errors';
+import type { Logger, LogLevel } from './log';
+import type { Component } from './components';
+import type { EventKey } from './events';
+import type { EffectKind } from './abilities/effects';
+import { type FormationDef } from './formation';
+import { type CommandDef } from './commands';
+import { type TunableDef } from './tunables';
+import type { EditableData } from './gameData';
+import type { HookDef } from './hooks';
+import { type RaceDef } from './races';
+import { type StartDef } from './start';
+import { type AbilityDef, type BuffDef, type DayCycle, type ItemDef, type ResourceDef, type ResourceKind, type StatDef, type UnitTypeDef, type UpgradeDef, type UpkeepTier } from './defs';
+import { type RecastNavigationOptions } from './navigation/recast';
+import type { PlayerId } from './entity';
+import type { BrainDef } from './ai/brain';
+import type { GameAi } from './ai/profiles';
+import type { GamePack } from './packs/pack';
+import type { StatPart } from './stats';
+import type { MapProblem } from './mapFields';
+import { type MapEditorDef } from './mapFields';
+import { type TileDef } from './tiles';
+import { type GameMap } from './map';
+import type { PlayerInit } from './player';
+import { type OrderBehavior, Registry, type System, type SystemDef } from './registry';
+import { type RulesInit } from './rules';
+import type { Terrain } from './terrain';
+import { type SaveRules, type WorldSave } from './save';
+import { World, type WorldChecks } from './world';
+import { type AreaDef } from './areas';
+import { type SequenceDef } from './sequences';
+import { type TimerDef } from './timers';
+import type { ListenerDef } from './events';
+/**
+ * The systems the engine brings along, by phase: decisions first, then movement, then everything that reacts to where
+ * units ended up. Within a phase, in this order. A module can do without any of them by name (`GameModule.withoutSystems`),
+ * or put its own in place of one by giving a system the same name
+ *
+ * @beta
+ */
+export declare const coreSystems: readonly System[];
+/**
+ * A game module is the data and rules of one kind of game. The engine knows nothing
+ * about peasants or town halls, it gets all of that from here.
+ *
+ * @beta
+ */
+export interface GameModule {
+    id: string;
+    name: string;
+    /** `major.minor.patch`, for mods to say which versions of the game they work with. 1.0.0 when left out */
+    version?: string;
+    /** The mods on it, with their versions, when it was made with `composeGame` */
+    mods?: {
+        id: string;
+        version: string;
+        hash?: string;
+    }[];
+    /**
+     * Players a map of the game may have, besides the neutral and the creeps: 8 when left out, 32 at most
+     * (`MAX_MAP_PLAYERS`). A map with more is refused, saying so, not cut
+     */
+    maxPlayers?: number;
+    units: UnitTypeDef[];
+    /**
+     * The sides players can play, each with its own roster (`UnitTypeDef.race`): none when left out, and with that no
+     * race anywhere. The first is what a player plays when nobody chose
+     */
+    races?: RaceDef[];
+    upgrades?: UpgradeDef[];
+    abilities?: AbilityDef[];
+    buffs?: BuffDef[];
+    items?: ItemDef[];
+    /** What players have amounts of and pay with, in the order they are shown. None when left out */
+    resources?: ResourceDef[];
+    /** The resource prices, bounties, revives and sales are in. The first resource when left out */
+    currency?: ResourceKind;
+    upkeep?: UpkeepTier[];
+    /** Stats of the game's own, next to the engine's (`CoreStats`). Units, buffs, items and upgrades change them, and abilities scale with them, like any other */
+    stats?: StatDef[];
+    /** Day and night. Always day when left out */
+    day?: DayCycle;
+    /** The numbers of the game that are not about any one unit, like the supply cap. The engine's for those left out */
+    rules?: RulesInit;
+    /**
+     * Kinds of effects abilities can have, next to the ones the engine knows (`defineEffect`): one of a type the engine has
+     * takes its place
+     */
+    effects?: EffectKind[];
+    /** Extra order types, or replacements for the core ones */
+    orders?: OrderBehavior[];
+    /**
+     * Formations of its own for units ordered to a point together (`FormationDef`), next to the engine's `rows`,
+     * `circle`, `square` and `none`, or in place of one of the same id. Which an order takes is the order's to say
+     * (`OrderInit.formation`), and the rules' where it does not (`GameRules.movement.formation`)
+     */
+    formations?: FormationDef[];
+    /** Commands of the game's own, made with `defineCommand`, or replacements for the core ones */
+    commands?: CommandDef[];
+    /** Types of the engine's own commands, or a pack's, the module does without (`coreCommands`, `heroCommands`) @beta */
+    withoutCommands?: string[];
+    /** Types of the engine's own orders, or a pack's, the module does without: a unit is then never given one @beta */
+    withoutOrders?: string[];
+    /**
+     * The parts of the rules the game opts into, with what they bring (`GamePack`): `[withHeroes()]` for heroes, camps
+     * and shops. None when left out. The game's own commands, orders, systems and hooks come after a pack's, and one of
+     * the same id takes its place
+     *
+     * @beta
+     */
+    packs?: GamePack[];
+    /**
+     * Systems of the game's own. They run after the core ones unless they give a phase (see `System`); one with the name
+     * of a core system takes its place, and its phase too unless it gives its own. A function makes a system for each
+     * world: what keeps state between ticks has to be made that way, or every game made from the module shares it
+     */
+    systems?: SystemDef[];
+    /** Names of the engine's own systems the module does without (see `coreSystems`) */
+    withoutSystems?: string[];
+    /** Handlers of hooks: how the module takes part in damage, deaths, orders. One with the id of a core one takes its place */
+    hooks?: HookDef[];
+    /** Ids of the engine's own hook handlers the module does without, like `bounty` (see `coreHooks`) */
+    withoutHooks?: string[];
+    /** How the game reacts to events, the engine's and its own (see `defineListener`) */
+    listeners?: ListenerDef[];
+    /**
+     * The state of its own the game keeps (see `defineComponent`): on entities, players and the world. Given here as
+     * timers and listeners are, so that a world knows who is told which (`replicate`) from its own game, and not from
+     * whatever else the process has loaded. One used without being listed is an error (`UnlistedError`): no world
+     * finds it, so a save or a snapshot would lose it
+     */
+    components?: Component<any>[];
+    /** The events of its own the game emits (see `defineEvent`): given here for the same reason */
+    events?: EventKey<any>[];
+    /** Parts of the map the rules watch: who walks in and out (see `AreaDef`) */
+    areas?: AreaDef[];
+    /** Groups of things the game spawns as one (see `definePrefab`, `world.spawnPrefab`); a designer's from the editor through `prefabsFrom` */
+    prefabs?: PrefabDef[];
+    /** What the game sets to go off later (see `defineTimer`): given here, so that a save finds them by id */
+    timers?: TimerDef[];
+    /** Scripts of steps the game starts, like a mission's (see `defineSequence`): given here, so that a save finds them */
+    sequences?: SequenceDef[];
+    /** Files of the game's own data its rules read as they run, and a panel edits (see `defineGameFile`, `registry.file`) */
+    files?: GameFileDef<unknown>[];
+    /** Decides who is out and who won. The last team with a building, when left out. Null for a game nobody can lose */
+    victory?: SystemDef | null;
+    /**
+     * How its saves outlive its patches (`SaveRules`): the version of what it keeps in a save, the steps that bring an
+     * older save up to it, and what becomes of a save made with other rules. A game that declares it, even empty, loads
+     * the saves made before a patch; one that does not refuses every save not made with its very rules, as a test wants
+     */
+    saves?: SaveRules;
+    /**
+     * Runs once a world is loaded from a save, everything put back: for what a game keeps outside the world, to make
+     * again from what is in it
+     */
+    afterLoad?: (world: World) => void;
+    /**
+     * Runs as a world takes a new version of the game while it runs (hot reload, `reloadGame`), the new version's: for
+     * what the game made of the old one (a cache of its definitions, a state worked out of them), to make again. What
+     * else hears it: `world.events.on(gameReloaded, …)`, and a screen's `GameView.on`
+     */
+    onReload?: (world: World) => void;
+    /** What the game does on a server, around its games: who joins and leaves, the start and the end (see `ServerHooks`) */
+    server?: ServerHooks;
+    /** What a player starts a map with, for players the map places nothing for: a hall and workers as data, or a function (`StartDef`) */
+    start?: StartDef;
+    /**
+     * The brains of its computer players (`defineBrain`), given here as components and timers are, so that a save that
+     * remembers a seat by its brain's id (`world.computers.seat`) finds the brain again when loaded. The first is what a
+     * seat that names no brain gets: `meleeBrain` of `@v12-engine/engine/ai` for a game played as melee, or a computer
+     * player of the game's own (`defineComputer`). None listed: the game has no computer player, and seating one throws
+     */
+    brains?: BrainDef[];
+    /**
+     * What it says of its computer players' profiles (`GameAi`, AI plan D1): difficulties and personalities of its own
+     * beside the engine's, defaults over the engine's, and whether a lobby offers each seat a difficulty and a
+     * personality (`seatSettingsOf`)
+     */
+    ai?: GameAi;
+    /**
+     * What the ground of its maps can be painted with, in order: the first is index 1 of `Terrain.tiles`, 0 being no
+     * paint (see `TileDef`). What each looks like is the view's (`GameView.ground.tiles`)
+     */
+    tiles?: TileDef[];
+    /**
+     * Its own layers of cells, for its rules to read and the editor to paint: where the bushes are (see `CellLayerDef`).
+     * Any layer can be read and set by id whether it is listed or not; listed, the editor offers it
+     */
+    cellLayers?: CellLayerDef[];
+    /** Numbers of its rules to be tuned while it plays (`defineTunable`), read with `world.tunable(id)` */
+    tunables?: TunableDef[];
+    /**
+     * The maps the game ships (S36): a world made from one of them keeps, in its save and in the welcome a server sends,
+     * only what changed of its ground, and whoever reads it finds the rest here (by its name and the ground it makes).
+     * Not in the game's hash. A map not among them, or changed since, is kept whole, as before
+     */
+    maps?: readonly GameMap[];
+    /**
+     * Its generator of maps (`MapGenerator`, `generateMap`): what the editor's New map from a generator and the page's
+     * Random map make a map with, its parameters as their sliders. None when left out: the engine's `presetGenerator`
+     * is there to take, with the game's trees and rocks
+     */
+    generator?: MapGenerator;
+    /**
+     * Which fields of its definitions the editor's Data panel may change (S61): `all`, or by kind (`units`,
+     * `abilities`, `buffs`, `items`, `upgrades`) all of them, some (their paths, `stats.health`, or fields said in full,
+     * with bounds and a kind), or each definition's own in code. None when left out. What is changed there is kept in
+     * the game's `data.json`, which the game reads over its code with `withData`
+     */
+    editable?: EditableData;
+    /**
+     * How its worlds find their way: the radius the walkable ground is cut for, how steep it may be, how many units the
+     * crowd makes room for at first (`maxAgents`). What a world is made with (`CreateWorldOptions.navigation`) goes over it
+     */
+    navigation?: RecastNavigationOptions;
+    /**
+     * What a route of a ground unit knows of the buildings in its way (determinism plan F2): `all` of them (the default),
+     * as the ground is; or only those its side has `seen`, so the way it goes in the dark says nothing of what is there.
+     * With `seen`, each side has a navigation of its own to plan on, of what it knows: a few megabytes a side on a big
+     * map. Units still walk around every building: they see one before they reach it, and plan again
+     *
+     * @beta
+     */
+    paths?: 'all' | 'seen';
+    /**
+     * How much its worlds say (`world.log`): the least an entry must matter to be said, everything when left out.
+     * Where the entries go is whoever runs the game's to say (`world.log.to`, the logger a world is made under)
+     */
+    log?: {
+        level?: LogLevel;
+    };
+    /**
+     * What becomes of a part of the game that throws (a hook's handler, a listener, a system, a timer, an order, a
+     * command): `throw` (the error goes on: tests), `end` (the game ends there, the players told), `disable` (the part
+     * is switched off and the game goes on), or a function that says which for each. When left out: a world throws, and
+     * a server and a launched game end the game (`world.errorPolicy`)
+     */
+    onError?: ErrorPolicy;
+    /** What the game brings to the map editor (see `MapEditorDef`) */
+    editor?: MapEditorDef;
+    /**
+     * What the game tells each player about itself, beyond what the engine knows: the wave a tower defense is at,
+     * a score, a countdown. Plain data that survives being sent; it goes into every snapshot as `report`, where the
+     * game's view (`GameView.hud.status`) puts it on the screen. Only what that player may know
+     */
+    report?: (world: World, player: PlayerId) => Record<string, unknown>;
+}
+/**
+ * A seat at a game on a server: a player who joined, or a computer player
+ *
+ * @beta
+ */
+export interface ServerSeat {
+    player: PlayerId;
+    name: string;
+    ai: boolean;
+    /** Whether someone is connected to it right now */
+    connected: boolean;
+    /** The team it plays for, where the mode says: who it is with and against */
+    team?: number;
+    /** Whether who sits there said they are ready, in the lobby: once every player seated is, the game starts */
+    ready?: boolean;
+    /** What is chosen for this seat (`ServerHooks.seatSettings`), by name: none where the game has no such settings */
+    settings?: Record<string, string>;
+    /** Settings of the seat the mode fixes (`ModeSeat.fixed`: a race the map gives its player), by name: not the lobby's to change */
+    fixed?: string[];
+    /** Who sits there, as they are rated (`ratedId`: a hash of their key, safe to show), and their rating in the mode where the server keeps ratings */
+    rated?: string;
+    rating?: number;
+    /** A vote to let who sits there go (`kick`), in the lobby: how many voted, and how many it takes */
+    kick?: {
+        votes: number;
+        needed: number;
+    };
+}
+/**
+ * How a game on a server ended: who won, and each seat's outcome
+ *
+ * @beta
+ */
+export interface GameResult {
+    game: string;
+    mode: string;
+    /** The winning team, or null for a game that was stopped */
+    winner: number | null;
+    /** Seconds of game time */
+    duration: number;
+    /** What the players were told, for a game that ended on an error and not by its rules (`World.failure`) */
+    failed?: string;
+    seats: (ServerSeat & {
+        outcome: 'victory' | 'defeat' | 'none';
+    })[];
+}
+/**
+ * What a game does on a server (`GameModule.server`). Only ever run there: a player's screen has none of it. The
+ * lobby's settings come to `onGameStart` as the lobby left them
+ *
+ * @beta
+ */
+export interface ServerHooks {
+    /** Settings of the lobby, by name: what can be chosen, and what is chosen until someone does */
+    settings?: Record<string, LobbySetting>;
+    /**
+     * Settings of each seat, by name: a race, a difficulty, a colour. Chosen in the lobby by who sits there, and for a
+     * seat the computer plays or nobody holds, by any player seated; each seat's (`ServerSeat.settings`) are handed to
+     * its computer player (`GameMode.ai`) and to the start (`onGameStart`)
+     */
+    seatSettings?: Record<string, LobbySetting>;
+    /** Someone took a seat in the lobby, or came back to theirs in a game (`world` then) */
+    onPlayerJoin?(seat: ServerSeat, world?: World): void;
+    /** Someone left their seat: in the lobby, or in a game (`world` then), where they may come back */
+    onPlayerLeave?(seat: ServerSeat, world?: World): void;
+    /** The game starts, with the world made and the lobby's settings */
+    onGameStart?(world: World, seats: readonly ServerSeat[], settings: Record<string, string>): void;
+    /** The game ended: who won, as plain data, before it is kept (`saveResult`) */
+    onGameEnd?(world: World, result: GameResult): void;
+    /** Keeps a game's result: in a file, a database, a ranking. A server writes it to a file of its own without */
+    saveResult?(result: GameResult): void | Promise<void>;
+}
+/**
+ * A setting of a lobby or of a seat (`ServerHooks.settings`, `seatSettings`)
+ *
+ * @beta
+ */
+export interface LobbySetting {
+    label: string;
+    /** What can be chosen, as it is kept */
+    options: string[];
+    /** What each option is shown as, where it is not the option itself */
+    labels?: Record<string, string>;
+    /** What is chosen until someone does */
+    default: string;
+    /** Of a seat: no two seats may hold the same (a colour). One held by another seat is not chosen */
+    unique?: boolean;
+}
+/** @beta */
+export interface CreateWorldOptions extends WorldChecks {
+    terrain: Terrain;
+    game: GameModule;
+    players: PlayerInit[];
+    /** The races one is drawn from for a player given `random` (`PlayerInit.race`): all of the game's when left out */
+    randomRaces?: readonly string[];
+    seed?: number;
+    /**
+     * Simulation steps per second: 30 when left out. A save made at another rate is refused (`loadWorld`), so a game
+     * that changes it starts new games
+     *
+     * @beta
+     */
+    tickRate?: number;
+    navigation?: RecastNavigationOptions;
+    /**
+     * Components the app keeps in the world beside the game's own (`GameModule.components`): what is the app's, not
+     * the game's rules (where the screen is played from, a tool's own; `Component.portable` false). Its game's and the
+     * engine's when left out: one neither lists is an error (`UnlistedError`)
+     */
+    components?: readonly Component<unknown, unknown>[];
+    /** The logger the world's own is made under (`world.log`): a server's, a page's. The root one when left out */
+    log?: Logger;
+    /** What becomes of a part of the game that throws, where the game does not say (`GameModule.onError`) */
+    onError?: ErrorPolicy;
+}
+/**
+ * A game put together with its packs (`assembleGame`): every list the engine runs, the packs' in it, in one place. A
+ * pack's parts come before the game's own, so that one of the game's of the same id or name takes its place; what the
+ * game leaves out of the engine's (`withoutCommands`, `withoutOrders`, `withoutHooks`, `withoutSystems`) it leaves out
+ * of its packs' too
+ *
+ * @beta
+ */
+export interface AssembledGame {
+    readonly game: GameModule;
+    /** The packs' commands and the game's */
+    readonly commands: readonly CommandDef[];
+    /** The packs' orders and the game's */
+    readonly orders: readonly OrderBehavior[];
+    /** The packs' systems, as given (made for each world, and left out by name then: `withoutSystems`) */
+    readonly packSystems: readonly SystemDef[];
+    readonly hooks: readonly HookDef[];
+    readonly listeners: readonly ListenerDef[];
+    /** The packs' kinds of effects (`GamePack.effects`), before the game's own */
+    readonly effects: readonly EffectKind[];
+    readonly timers: readonly TimerDef[];
+    readonly components: readonly Component<unknown, unknown>[];
+    readonly events: readonly EventKey<unknown>[];
+    readonly statParts: readonly StatPart[];
+    /** The stats of the game: its packs' (`GamePack.stats`), then its own (`GameModule.stats`) */
+    readonly stats: readonly StatDef[];
+    /** The packs' ways of telling the players of the world's events (`GamePack.replications`) */
+    readonly replications: readonly ReplicatedEvent[];
+    /** The packs' parts of the players' snapshots (`GamePack.snapshotParts`) */
+    readonly snapshotParts: readonly SnapshotPart[];
+    /** The game's rules with what each pack lays over them, in order */
+    readonly rules: RulesInit;
+    /** The game's report of a player at the end, with each pack's beside it: none where none says */
+    readonly report: ((world: World, player: PlayerId) => Record<string, unknown>) | null;
+    /** How it is won: the game's own where it says, else the last pack's that says, else the engine's (`lastTeamStanding`) */
+    readonly victory: SystemDef | null | undefined;
+    /** What the game and its packs find wrong with a map, in the editor */
+    readonly check: ((map: GameMap, registry: Registry) => MapProblem[]) | undefined;
+}
+/**
+ * A game with its packs put together (`AssembledGame`): what the registry, the systems, the hooks, the listeners and the
+ * timers of a world of it are made of. Refuses a pack without one it says it goes with (`GamePack.requires`)
+ *
+ * @beta
+ */
+export declare function assembleGame(game: GameModule): AssembledGame;
+/**
+ * Everything a game module defines, looked up by id: with the engine's own components, and those an app keeps in its
+ * worlds (`own`: `CreateWorldOptions.components`)
+ *
+ * @beta
+ */
+export declare function createRegistry(game: GameModule, own?: readonly Component<unknown, unknown>[]): Registry;
+/** @beta */
+export declare function createWorld(options: CreateWorldOptions): Promise<World>;
+/**
+ * The engine's hook handlers without the ones the module does without, then the module's own
+ *
+ * @beta
+ */
+export interface LoadWorldOptions extends WorldChecks {
+    /** The game module the save was made with, by id. A save holds no code: rules come from here */
+    game: GameModule;
+    /**
+     * The map it is loaded on (a scene that opens its map again): its definitions are laid over the game's in place
+     * of those the save kept (`GameMap.definitions`). The save's own when left out
+     */
+    map?: Pick<GameMap, 'definitions'>;
+    navigation?: RecastNavigationOptions;
+    /** Components the app keeps in the world beside the game's own, as `CreateWorldOptions.components`: those of the world saved */
+    components?: readonly Component<unknown, unknown>[];
+    /**
+     * Loads a save made with other rules of the game (its code or its mods changed since) whatever the game says of
+     * those (`GameModule.saves.onMismatch`). An older version of its saves is brought up to date all the same
+     */
+    anyVersion?: boolean;
+    /** The logger the world's own is made under, as `CreateWorldOptions.log` */
+    log?: Logger;
+    /** What becomes of a part of the game that throws, as `CreateWorldOptions.onError` */
+    onError?: ErrorPolicy;
+    /** The maps a save's ground may be one of (S36): the game's own (`GameModule.maps`) when left out */
+    maps?: readonly GameMap[];
+}
+/**
+ * A world from a save (see `saveWorld`), carrying on where it was. A save made before, by an older engine or by the
+ * game before a patch, is brought up to date first (`updateSave`), or refused with a `SaveError` that says why.
+ * Navigation is built again; units come back with the speed and destination they had, but the way they find around
+ * each other is worked out anew, so the game from there on is close to, and not quite, the one that was saved
+ *
+ * @beta
+ */
+export declare function loadWorld(saved: WorldSave, options: LoadWorldOptions): Promise<World>;
+/** @beta */
+export interface MapWorldOptions {
+    map: GameMap;
+    game: GameModule;
+    /**
+     * The race each player plays, by player (`GameModule.races`): one of the game's, or `random`. Chosen in a lobby, a
+     * page's own menu. Those left out play what the map fixes for them (`MapPlayer.race`), or the game's first
+     */
+    races?: Readonly<Record<PlayerId, string>>;
+    /** The team each player plays for, by player, over the map's (`MapPlayer.team`): chosen in a lobby */
+    teams?: Readonly<Record<PlayerId, number>>;
+    /** The colour of each player, by player, over the map's (`MapPlayer.color`): chosen in a lobby */
+    colors?: Readonly<Record<PlayerId, [number, number, number]>>;
+    /**
+     * Whether the world has the creeps player. When the map has something for it when left out: a camp, or something
+     * placed for the creeps. A world without camps that had one anyway would never be won: a team would always be left
+     */
+    creeps?: boolean;
+    seed?: number;
+    navigation?: RecastNavigationOptions;
+    /** Components the app keeps in the world beside the game's own, as `CreateWorldOptions.components` */
+    components?: readonly Component<unknown, unknown>[];
+    /** The logger the world's own is made under, as `CreateWorldOptions.log` */
+    log?: Logger;
+    /** What becomes of a part of the game that throws, as `CreateWorldOptions.onError` */
+    onError?: ErrorPolicy;
+}
+/**
+ * A world as a map lays it out: its ground, the players it has room for, and everything placed on it.
+ * Players with a start location that the map places nothing for get what the game starts everyone with.
+ * Throws for a map made for another game (`GameMap.game`).
+ *
+ * @beta
+ */
+export declare function createWorldFromMap(options: MapWorldOptions): Promise<World>;
+/**
+ * Players a map of the game may have (`GameModule.maxPlayers`): 8 when it says nothing, never more than the fog keeps apart
+ *
+ * @beta
+ */
+export declare const maxPlayersOf: (game: GameModule) => number;