@v12-engine/engine 0.1.0 → 0.4.0

package/dist/game.d.ts

@@ -1,34 +1,36 @@
 import type { CellLayerDef } from './cellLayers';
 import type { GameFileDef } from './gameFiles';
-import { type ReplicatedEvent, type SnapshotPart } from './replication';
+import { type ReplicatedEvent, type SnapshotField } 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 { EffectType } from './abilities/effects';
+import type { Targeting } from './targeting';
 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 StartingBase } from './start';
+import { type AbilityDef, type BuffDef, type DayCycle, type ItemDef, type ResourceDef, type ResourceId, type StatDef, type TagDef, type UnitTypeDef, type UpgradeDef, type UpkeepTier } from './defs';
+import type { ChosenDefaults } from './defaultSets';
 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 { StatField } 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 RuleSettingsInit } from './rules';
 import type { Terrain } from './terrain';
 import { type SaveRules, type WorldSave } from './save';
 import { World, type WorldChecks } from './world';
@@ -38,7 +40,7 @@ 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`),
+ * units ended up. Within a phase, in this order. A module can do without any of them by name (`Rules.withoutSystems`),
  * or put its own in place of one by giving a system the same name
  *
  * @beta
@@ -48,10 +50,12 @@ 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
+ * @public
  */
-export interface GameModule {
+export interface Rules {
+    /** The game's id, which a save and a server know it by */
     id: string;
+    /** What the player sees the game called */
     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;
@@ -66,38 +70,63 @@ export interface GameModule {
      * (`MAX_MAP_PLAYERS`). A map with more is refused, saying so, not cut
      */
     maxPlayers?: number;
+    /** The unit types of the game */
     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[];
+    /** The upgrades of the game; none when left out */
     upgrades?: UpgradeDef[];
+    /** The abilities of the game; none when left out */
     abilities?: AbilityDef[];
+    /** The buffs of the game; none when left out */
     buffs?: BuffDef[];
+    /** The items of the game; none when left out */
     items?: ItemDef[];
+    /**
+     * The tags of its items named and given a look, and which of them a shop filters by (`TagDef`). A tag no
+     * definition names still works, shown as its word. None when left out
+     *
+     * @beta
+     */
+    tags?: TagDef[];
+    /**
+     * The default sets the game took (`useDefaults`), what it chose of each, and how to choose again (what a
+     * `data.json`'s `defaults` does). Set by `useDefaults`, never by hand
+     *
+     * @beta
+     */
+    defaults?: ChosenDefaults;
     /** 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;
+    currency?: ResourceId;
+    /** The tiers of upkeep, by supply used; none when left out */
     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;
+    settings?: RuleSettingsInit;
     /**
      * 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[];
+    effects?: EffectType[];
+    /**
+     * Ways of aiming an ability of the game's own (`defineTargeting`), next to the engine's (`AimKind`): named by an
+     * ability's `target`
+     */
+    targetings?: Targeting[];
     /** 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`)
+     * (`OrderInit.formation`), and the rules' where it does not (`RuleSettings.movement.formation`)
      */
     formations?: FormationDef[];
     /** Commands of the game's own, made with `defineCommand`, or replacements for the core ones */
@@ -107,7 +136,7 @@ export interface GameModule {
     /** 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
+     * The parts of the rules the game opts into, with what they bring (`GamePack`): `[heroesPack()]` 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
      *
@@ -168,8 +197,8 @@ export interface GameModule {
     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;
+    /** What a player starts a map with, for players the map places nothing for: a hall and workers as data, or a function (`StartingBase`) */
+    startingBase?: StartingBase;
     /**
      * 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
@@ -211,14 +240,15 @@ export interface GameModule {
      * 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`
+     * the game's `data.json`, which the game reads over its code with `layData`
      */
     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
+     * crowd makes room for at first (`maxAgents`), the sizes it is cut for (`radii`: `'auto'` unless said, a navigation for
+     * each size of ground unit the game has). What a world is made with (`CreateWorldOptions.navigation`) goes over it
      */
-    navigation?: RecastNavigationOptions;
+    navigation?: GameNavigationOptions;
     /**
      * 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.
@@ -257,8 +287,11 @@ export interface GameModule {
  * @beta
  */
 export interface ServerSeat {
+    /** The player the seat is for */
     player: PlayerId;
+    /** The name shown for who sits there */
     name: string;
+    /** Whether a computer player plays the seat */
     ai: boolean;
     /** Whether someone is connected to it right now */
     connected: boolean;
@@ -272,6 +305,7 @@ export interface ServerSeat {
     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;
+    /** The rating of who sits there in the mode, where the server keeps ratings */
     rating?: number;
     /** A vote to let who sits there go (`kick`), in the lobby: how many voted, and how many it takes */
     kick?: {
@@ -285,7 +319,9 @@ export interface ServerSeat {
  * @beta
  */
 export interface GameResult {
+    /** The id of the game that was played */
     game: string;
+    /** The id of the mode it was played in */
     mode: string;
     /** The winning team, or null for a game that was stopped */
     winner: number | null;
@@ -293,12 +329,13 @@ export interface GameResult {
     duration: number;
     /** What the players were told, for a game that ended on an error and not by its rules (`World.failure`) */
     failed?: string;
+    /** Every seat with how it ended for it */
     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
+ * What a game does on a server (`Rules.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
@@ -329,6 +366,7 @@ export interface ServerHooks {
  * @beta
  */
 export interface LobbySetting {
+    /** What the setting is called in the lobby */
     label: string;
     /** What can be chosen, as it is kept */
     options: string[];
@@ -339,13 +377,21 @@ export interface LobbySetting {
     /** Of a seat: no two seats may hold the same (a colour). One held by another seat is not chosen */
     unique?: boolean;
 }
-/** @beta */
+/**
+ * What a new world is made from: terrain, rules, players, seed and navigation
+ *
+ * @beta
+ */
 export interface CreateWorldOptions extends WorldChecks {
+    /** The terrain the world stands on */
     terrain: Terrain;
-    game: GameModule;
+    /** The game's rules the world runs */
+    rules: Rules;
+    /** The players of the world, in order */
     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 of the world's random numbers: the same seed gives the same game; 1 when left out */
     seed?: number;
     /**
      * Simulation steps per second: 30 when left out. A save made at another rate is refused (`loadWorld`), so a game
@@ -354,16 +400,17 @@ export interface CreateWorldOptions extends WorldChecks {
      * @beta
      */
     tickRate?: number;
-    navigation?: RecastNavigationOptions;
+    /** Options for how the world's units find their way, over the game's (`Rules.navigation`) */
+    navigation?: GameNavigationOptions;
     /**
-     * Components the app keeps in the world beside the game's own (`GameModule.components`): what is the app's, not
+     * Components the app keeps in the world beside the game's own (`Rules.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`) */
+    /** What becomes of a part of the game that throws, where the game does not say (`Rules.onError`) */
     onError?: ErrorPolicy;
 }
 /**
@@ -375,29 +422,36 @@ export interface CreateWorldOptions extends WorldChecks {
  * @beta
  */
 export interface AssembledGame {
-    readonly game: GameModule;
+    /** The game the assembly is made of */
+    readonly rules: Rules;
     /** 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[];
+    /** The hooks of the packs and the game */
     readonly hooks: readonly HookDef[];
+    /** The listeners of the packs and the game */
     readonly listeners: readonly ListenerDef[];
     /** The packs' kinds of effects (`GamePack.effects`), before the game's own */
-    readonly effects: readonly EffectKind[];
+    readonly effects: readonly EffectType[];
+    /** The timers of the packs and the game */
     readonly timers: readonly TimerDef[];
+    /** The components of the engine, packs and game */
     readonly components: readonly Component<unknown, unknown>[];
+    /** The events of the packs and the game */
     readonly events: readonly EventKey<unknown>[];
-    readonly statParts: readonly StatPart[];
-    /** The stats of the game: its packs' (`GamePack.stats`), then its own (`GameModule.stats`) */
+    /** The fields of stats the packs and the game add */
+    readonly statFields: readonly StatField[];
+    /** The stats of the game: its packs' (`GamePack.stats`), then its own (`Rules.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 packs' parts of the players' snapshots (`GamePack.snapshotFields`) */
+    readonly snapshotFields: readonly SnapshotField[];
     /** The game's rules with what each pack lays over them, in order */
-    readonly rules: RulesInit;
+    readonly settings: RuleSettingsInit;
     /** 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`) */
@@ -411,15 +465,45 @@ export interface AssembledGame {
  *
  * @beta
  */
-export declare function assembleGame(game: GameModule): AssembledGame;
+export declare function assembleGame(game: Rules): 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`)
  *
+ * @public
+ */
+export declare function createRegistry(game: Rules, own?: readonly Component<unknown, unknown>[]): Registry;
+/**
+ * How a game's worlds find their way (`Rules.navigation`): `RecastNavigationOptions`, with `radii` also `'auto'`
+ * (the default) or `false`
+ *
  * @beta
  */
-export declare function createRegistry(game: GameModule, own?: readonly Component<unknown, unknown>[]): Registry;
-/** @beta */
+export type GameNavigationOptions = Omit<RecastNavigationOptions, 'radii'> & {
+    /**
+     * The sizes the ground is cut for. `'auto'` (when left out): the ground units' radii in three groups, up to 0.5, up
+     * to 0.75 and over, a navigation for each group the game has a unit type in (the first cut for 0.5 at least, the
+     * others for their group's largest radius), so an ogre keeps from walls as far as it needs where a footman still
+     * fits through a gap. `false`: one navigation cut for `agentRadius` (0.5), as it was. A list: a navigation for
+     * each size, a unit on the one for the biggest size it is not smaller than. Each size has its own crowd (see
+     * `SizedNavigation`)
+     */
+    radii?: number[] | 'auto' | false;
+};
+/**
+ * The sizes the ground units of a game are cut for (`radii: 'auto'`): their radii in groups (up to 0.5, up to 0.75,
+ * over), each cut for its largest radius (the first for 0.5 at least), a group only where a unit type falls in it. Each
+ * with the radius of the biggest unit it takes, `upTo`. What flies or sails has navigation of its own
+ */
+export declare function autoNavigationSizes(registry: Registry): {
+    radius: number;
+    upTo: number;
+}[];
+/**
+ * Makes a world from terrain, rules and players; resolves once it is ready to step
+ *
+ * @public
+ */
 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
@@ -428,25 +512,26 @@ export declare function createWorld(options: CreateWorldOptions): Promise<World>
  */
 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;
+    rules: Rules;
     /**
      * 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;
+    /** Options for how the world's units find their way, over the game's (`Rules.navigation`) */
+    navigation?: GameNavigationOptions;
     /** 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
+     * those (`Rules.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 */
+    /** The maps a save's ground may be one of (S36): the game's own (`Rules.maps`) when left out */
     maps?: readonly GameMap[];
 }
 /**
@@ -455,15 +540,21 @@ export interface LoadWorldOptions extends WorldChecks {
  * 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
+ * @public
  */
 export declare function loadWorld(saved: WorldSave, options: LoadWorldOptions): Promise<World>;
-/** @beta */
-export interface MapWorldOptions {
+/**
+ * What a world made from a map is made from: the map, the rules, and what the lobby chose for the players
+ *
+ * @beta
+ */
+export interface MapWorldOptions extends WorldChecks {
+    /** The map the world is made from: its terrain, players and what it places */
     map: GameMap;
-    game: GameModule;
+    /** The game's rules the world runs */
+    rules: Rules;
     /**
-     * The race each player plays, by player (`GameModule.races`): one of the game's, or `random`. Chosen in a lobby, a
+     * The race each player plays, by player (`Rules.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>>;
@@ -476,8 +567,10 @@ export interface MapWorldOptions {
      * 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 of the world's random numbers: the same seed gives the same game */
     seed?: number;
-    navigation?: RecastNavigationOptions;
+    /** Options for how the world's units find their way, over the game's (`Rules.navigation`) */
+    navigation?: GameNavigationOptions;
     /** 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` */
@@ -490,12 +583,12 @@ export interface MapWorldOptions {
  * 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
+ * @public
  */
 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
+ * Players a map of the game may have (`Rules.maxPlayers`): 8 when it says nothing, never more than the fog keeps apart
  *
  * @beta
  */
-export declare const maxPlayersOf: (game: GameModule) => number;
+export declare const maxPlayersOf: (game: Rules) => number;