@v12-engine/engine 0.1.1 → 0.4.0

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 import type { AdvanceState, AlongPath, AttackGroundState, AttackState, FollowState, HoldState, PatrolState } from './orders/basic';
 import type { GameFileDef } from './gameFiles';
-import type { ReplicatedEvent, SnapshotPart } from './replication';
+import type { ReplicatedEvent, SnapshotField } from './replication';
 import { type DataDefs, type DataKind } from './gameData';
 import { Definitions } from './definitions';
 import type { BuildState, RepairState, WorkState } from './orders/build';
@@ -12,22 +12,27 @@ import type { RaceDef } from './races';
 import type { Logger } from './log';
 import type { Component } from './components';
 import { type EventKey } from './events';
-import type { EffectHandler, EffectKind } from './abilities/effects';
+import type { EffectHandler, EffectType } from './abilities/effects';
+import type { Targeting } from './targeting';
 import type { CommandDef } from './commands';
-import { type AbilityDef, type BuffDef, type DayCycle, type ItemDef, type ResourceDef, type ResourceKind, type StatDef, type Stats, type UnitTypeDef, type UpgradeDef, type UpkeepTier } from './defs';
+import { type AbilityDef, type BuffDef, type DayCycle, type ItemDef, type ResourceDef, type ResourceId, type StatDef, type Stats, type TagDef, type UnitTypeDef, type UpgradeDef, type UpkeepTier } from './defs';
 import type { Entity, EntityId, Order, PlayerId } from './entity';
 import type { Vec2 } from './math';
-import type { StatPart } from './stats';
+import type { StatField } from './stats';
 import type { FormationDef } from './formation';
-import type { AssembledGame, GameModule } from './game';
-import { type GameRules } from './rules';
+import type { AssembledGame, Rules } from './game';
+import { type RuleSettings } from './rules';
 import type { TileDef } from './tiles';
 import type { PrefabDef } from './prefabs';
 import type { TunableDef } from './tunables';
 import type { World } from './world';
 import type { CellLayerDef } from './cellLayers';
 import type { ResolvedScore } from './score';
-/** @beta */
+/**
+ * Where an order stands after an update: still `running`, `done`, or `failed`
+ *
+ * @beta
+ */
 export type OrderStatus = 'running' | 'done' | 'failed';
 /**
  * What an order can be given, every order's field in one: for what reads an order of any type (the queue, a save, a
@@ -36,12 +41,16 @@ export type OrderStatus = 'running' | 'done' | 'failed';
  * @beta
  */
 export interface OrderParams {
+    /** The entity an order is aimed at: to attack, follow, harvest from, repair, board or load */
     target?: EntityId;
+    /** The point an order is aimed at, in world coordinates */
     point?: Vec2;
     /** Type to build, for build orders */
     unitType?: string;
     /** Ability to use, for cast orders */
     ability?: string;
+    /** For an ability aimed along two points (`vector`): the second, the way it goes from `point` */
+    to?: Vec2;
     /** An item: the one to use, drop or hand over by its place in the inventory, or the one on the ground to pick up */
     item?: number;
     /** Direction to face at the end. Commands fill this in with the direction of travel */
@@ -79,26 +88,47 @@ export interface OrderParams {
  * @beta
  */
 export interface OrderInits {
+    /** What a `move` order is given (`Order.init`): point, facing, target, together and speedCap: where to, which way to face at the end, an entity to go to, group pace */
     move: Pick<OrderParams, 'point' | 'facing' | 'target' | 'together' | 'speedCap'>;
+    /** What a `hold` order is given (`Order.init`): facing: which way to face while holding */
     hold: Pick<OrderParams, 'facing'>;
+    /** What a `attack` order is given (`Order.init`): the target to attack and the facing to keep */
     attack: Pick<OrderParams, 'target' | 'facing'>;
+    /** What a `attackMove` order is given (`Order.init`): the point to advance to, fighting what it meets, and the facing at the end */
     attackMove: Pick<OrderParams, 'point' | 'facing'>;
+    /** What a `followPath` order is given (`Order.init`): the map path to follow by name and which end (`towards`) to go to */
     followPath: Pick<OrderParams, 'path' | 'towards'>;
+    /** What a `attackPath` order is given (`Order.init`): the map path to advance along, fighting, and which end (`towards`) to go to */
     attackPath: Pick<OrderParams, 'path' | 'towards'>;
+    /** What a `patrolPath` order is given (`Order.init`): the map path to patrol along and which end (`towards`) to start towards */
     patrolPath: Pick<OrderParams, 'path' | 'towards'>;
+    /** What a `patrol` order is given (`Order.init`): the point to patrol to and back from, and the facing */
     patrol: Pick<OrderParams, 'point' | 'facing'>;
+    /** What a `follow` order is given (`Order.init`): the entity to follow */
     follow: Pick<OrderParams, 'target'>;
+    /** What a `attackGround` order is given (`Order.init`): the point to attack and optionally an entity there */
     attackGround: Pick<OrderParams, 'point' | 'target'>;
-    cast: Pick<OrderParams, 'ability' | 'item' | 'target' | 'point'>;
+    /** What a `cast` order is given (`Order.init`): the ability, an item to use, the target, the point and the second point (`to`) of a vector ability */
+    cast: Pick<OrderParams, 'ability' | 'item' | 'target' | 'point' | 'to'>;
+    /** What a `harvest` order is given (`Order.init`): the resource entity to gather from */
     harvest: Pick<OrderParams, 'target'>;
+    /** What a `return` order is given (`Order.init`): the hall to hand in at; the resource to go back to when left out */
     return: Pick<OrderParams, 'target'>;
+    /** What a `build` order is given (`Order.init`): the unit type to build, the point and the facing of the site */
     build: Pick<OrderParams, 'unitType' | 'point' | 'facing'>;
+    /** What a `construct` order is given (`Order.init`): the unfinished building to work on */
     construct: Pick<OrderParams, 'target'>;
+    /** What a `repair` order is given (`Order.init`): the building to repair */
     repair: Pick<OrderParams, 'target'>;
+    /** What a `pickUp` order is given (`Order.init`): the item on the ground to pick up (`target`) and the inventory slot */
     pickUp: Pick<OrderParams, 'target' | 'item'>;
+    /** What a `dropItem` order is given (`Order.init`): the inventory slot to drop, and the point or the unit to drop it at */
     dropItem: Pick<OrderParams, 'item' | 'point' | 'target'>;
+    /** What a `board` order is given (`Order.init`): the transport to board */
     board: Pick<OrderParams, 'target'>;
+    /** What a `load` order is given (`Order.init`): the unit for a transport to load */
     load: Pick<OrderParams, 'target'>;
+    /** What a `unload` order is given (`Order.init`): the point to unload the cargo at */
     unload: Pick<OrderParams, 'point'>;
 }
 /**
@@ -117,7 +147,7 @@ export type OrderInit<Type extends string = string> = {
     type: Type;
     /**
      * The formation units ordered to a point together take, by id (`FormationDef`): the engine's `rows`, `circle`,
-     * `square` or `none`, or a game's own. What the rules say (`GameRules.movement.formation`: `rows`) when left out
+     * `square` or `none`, or a game's own. What the rules say (`RuleSettings.movement.formation`: `rows`) when left out
      */
     formation?: string;
 } & OrderInitOf<Type>;
@@ -128,9 +158,10 @@ export type OrderInit<Type extends string = string> = {
  * `State` is what it keeps in the order (`Order.state`), every field optional: the order starts with none of them.
  * `OrderStates` names each order type's, for `registry.order(type)` to hand back the behaviour typed
  *
- * @beta
+ * @public
  */
 export interface OrderBehavior<State extends object = Record<string, any>, Init extends object = OrderParams> {
+    /** The order type this behaviour handles, the key of `registry.order` and of `Order.type` */
     type: string;
     /** Units ordered to a point together are spread out in a formation instead of all walking to the same spot */
     formation?: boolean;
@@ -138,6 +169,7 @@ export interface OrderBehavior<State extends object = Record<string, any>, Init
     accepts(world: World, entity: Entity, init: Init): boolean;
     /** Called once when the order reaches the front of the queue */
     start?(world: World, entity: Entity, order: Order<State, Init>): void;
+    /** Runs each tick while the order is at the front; returns whether it is still running, done or failed. `dt` is the tick's seconds */
     update(world: World, entity: Entity, order: Order<State, Init>, dt: number): OrderStatus;
     /** Called when the order finishes or is interrupted, to undo anything it left behind */
     end?(world: World, entity: Entity, order: Order<State, Init>): void;
@@ -147,8 +179,8 @@ export interface OrderBehavior<State extends object = Record<string, any>, Init
      */
     committed?(order: Order<State, Init>): boolean;
     /**
-     * Whether the unit stands waiting by a fight for a spot in it (an attack-move held up): an ally on its way may ask it
-     * aside (`rules.movement.makesWay`). Never, when left out
+     * Whether the unit stands waiting by a fight for a spot in it (an attack or an attack-move held up: `holdOff`): an
+     * ally on its way may ask it aside (`settings.movement.makesWay`). Never, when left out
      */
     waiting?(order: Order<State, Init>): boolean;
     /** Whether the unit keeps something up that being stunned breaks off (a channelled ability). Never, when left out */
@@ -178,25 +210,45 @@ export type OrderFact = 'committed' | 'waiting' | 'channelling' | 'building';
  * @beta
  */
 export interface OrderStates {
+    /** What a `move` order keeps in `Order.state` */
     move: NoState;
+    /** What a `hold` order keeps in `Order.state` */
     hold: HoldState;
+    /** What a `attack` order keeps in `Order.state` */
     attack: AttackState;
+    /** What a `attackMove` order keeps in `Order.state` */
     attackMove: AdvanceState;
+    /** What a `followPath` order keeps in `Order.state` */
     followPath: AlongPath;
+    /** What a `attackPath` order keeps in `Order.state` */
     attackPath: AlongPath & AdvanceState;
+    /** What a `patrol` order keeps in `Order.state` */
     patrol: PatrolState;
+    /** What a `follow` order keeps in `Order.state` */
     follow: FollowState;
+    /** What a `attackGround` order keeps in `Order.state` */
     attackGround: AttackGroundState;
+    /** What a `cast` order keeps in `Order.state` */
     cast: CastState;
+    /** What a `harvest` order keeps in `Order.state` */
     harvest: HarvestState;
+    /** What a `return` order keeps in `Order.state` */
     return: HarvestState;
+    /** What a `build` order keeps in `Order.state` */
     build: BuildState;
+    /** What a `construct` order keeps in `Order.state` */
     construct: WorkState;
+    /** What a `repair` order keeps in `Order.state` */
     repair: RepairState;
+    /** What a `pickUp` order keeps in `Order.state` */
     pickUp: ItemOrderState;
+    /** What a `dropItem` order keeps in `Order.state` */
     dropItem: ItemOrderState;
+    /** What a `board` order keeps in `Order.state` */
     board: BoardState;
+    /** What a `load` order keeps in `Order.state` */
     load: LoadState;
+    /** What a `unload` order keeps in `Order.state` */
     unload: UnloadState;
 }
 /**
@@ -221,7 +273,7 @@ export type SystemPhase = 'commands' | 'decide' | 'move' | 'resolve' | 'cleanup'
  * Something that runs every tick, or every few: moves units, lands attacks, works out what each team sees.
  * When it runs is worked out once, from its phase, then from what it says it comes before and after.
  *
- * @beta
+ * @public
  */
 export interface System {
     /** Unique in a world. A game's system with the name of a core one takes its place */
@@ -230,6 +282,7 @@ export interface System {
     phase?: SystemPhase;
     /** Names of systems in the same phase this one runs ahead of, or after */
     before?: string[];
+    /** Names of systems in the same phase this one runs after */
     after?: string[];
     /** Runs once in so many ticks, for work that does not need doing every tick. Every tick when left out */
     every?: number;
@@ -241,9 +294,11 @@ export interface System {
      */
     update?(world: World, dt: number): void;
     /**
-     * What `each` is run for (OB5): every actor (`'actors'`, when left out), what has a component, in the order of its
-     * id as a walk through the actors would meet it (`EntityIndex.ordered`: a system about a few, like the buildings
-     * that train, does not look at every unit and tree), or the actors a test says yes to
+     * What `each` is run for (OB5): every unit (`'units'`, when left out, in `World.units`' order), what has a component,
+     * in the order of its id (`EntityIndex.ordered`: a system about a few, like the buildings that train, does not look
+     * at every unit and tree), or the units a test says yes to. The two orders differ for scenery woken into a unit
+     * (`Spawning.wake`), which `World.units` has last: moving a system from one to the other can change which of two
+     * equals goes first, unless it breaks ties by id
      *
      * @beta
      */
@@ -264,20 +319,20 @@ export interface System {
     restore?(world: World, data: unknown): void;
 }
 /**
- * What a system runs `each` for (`System.over`): every actor, what has a component, or the actors a test says yes to
+ * What a system runs `each` for (`System.over`): every unit, what has a component, or the units a test says yes to
  *
  * @beta
  */
-export type SystemOver = 'actors' | Component<unknown, unknown> | ((entity: Entity, world: World) => boolean);
+export type SystemOver = 'units' | Component<unknown, unknown> | ((entity: Entity, world: World) => boolean);
 /**
  * A system, or what makes one for each world: for a system that keeps state of its own, which belongs to one game
  *
- * @beta
+ * @public
  */
 export type SystemDef = System | ((world: World) => System);
 /**
- * What is thrown for a component or an event of its own that a game uses without listing it (`GameModule.components`,
- * `GameModule.events`): no world finds it by its id, so a save, a snapshot or the index would lose it
+ * What is thrown for a component or an event of its own that a game uses without listing it (`Rules.components`,
+ * `Rules.events`): no world finds it by its id, so a save, a snapshot or the index would lose it
  *
  * @beta
  */
@@ -296,30 +351,38 @@ export declare class UnlistedError extends Error {
     /** The id of the game that used it */
     game: string);
 }
-/** @beta */
+/**
+ * The registry of a game's definitions and behaviours: unit types, abilities, orders, systems, buffs and the rest, by id
+ *
+ * @public
+ */
 export declare class Registry {
-    /** The game's unit types, buildings and resources (`GameModule.units`) */
+    /** The game's unit types, buildings and resources (`Rules.units`) */
     readonly units: Definitions<UnitTypeDef>;
     /** The orders units can be given, the engine's and the game's, by type */
     readonly orders: Definitions<OrderBehavior<Record<string, any>, OrderParams>>;
-    /** How groups line up (`GameModule.formations`) */
+    /** How groups line up (`Rules.formations`) */
     readonly formations: Definitions<FormationDef>;
-    /** The game's research (`GameModule.upgrades`) */
+    /** The game's research (`Rules.upgrades`) */
     readonly upgrades: Definitions<UpgradeDef>;
-    /** Every ability there is, of units, heroes and items alike (`GameModule.abilities`) */
+    /** Every ability there is, of units, heroes and items alike (`Rules.abilities`) */
     readonly abilities: Definitions<AbilityDef>;
-    /** The game's buffs (`GameModule.buffs`) */
+    /** The game's buffs (`Rules.buffs`) */
     readonly buffs: Definitions<BuffDef>;
-    /** The game's items (`GameModule.items`) */
+    /** The game's items (`Rules.items`) */
     readonly items: Definitions<ItemDef>;
-    /** The game's races, in its order (`GameModule.races`): none in a game without */
+    /** The tags of the game's items named and given a look (`Rules.tags`): a tag none names is its own word */
+    readonly tags: Definitions<TagDef>;
+    /** The game's races, in its order (`Rules.races`): none in a game without */
     readonly races: Definitions<RaceDef>;
-    /** The game's prefabs (`GameModule.prefabs`) */
+    /** The game's prefabs (`Rules.prefabs`) */
     readonly prefabs: Definitions<PrefabDef>;
     /** The commands a world takes, the engine's and the game's, by type */
     readonly commands: Definitions<CommandDef<import("./fields").Fields>>;
     /** What each type of an ability's effect does, by type */
-    readonly effects: Definitions<EffectKind<keyof import("./defs").EffectTypes>>;
+    readonly effects: Definitions<EffectType<keyof import("./defs").EffectTypes>>;
+    /** A game's own ways of aiming an ability (`Rules.targetings`), by name */
+    readonly targetings: Definitions<Targeting>;
     /**
      * The kinds of definition a game's data is kept for (`DataKind`), each its collection: what the Data panel, mods,
      * saves and a game's reload walk, one loop each
@@ -327,11 +390,11 @@ export declare class Registry {
     readonly kinds: {
         readonly [K in DataKind]: Definitions<DataDefs[K]>;
     };
-    /** The components the game lists (`GameModule.components`), and those its app keeps in its worlds, by id */
+    /** The components the game lists (`Rules.components`), and those its app keeps in its worlds, by id */
     private readonly components;
     /** The engine's own components (`coreComponents`) and the listed, by id: what `component` finds, in one look */
     private readonly known;
-    /** The events of its own the game lists (`GameModule.events`), by id */
+    /** The events of its own the game lists (`Rules.events`), by id */
     private readonly events;
     /** Takes in the components and events a game lists. Throws for an id that is there twice, another way */
     defineParts(components: readonly Component<unknown>[], events: readonly EventKey<unknown>[]): void;
@@ -340,8 +403,9 @@ export declare class Registry {
     /** A component of this game by its id, as something of the world uses it: throws for one the game does not list (`UnlistedError`) */
     used(id: string): Component<unknown>;
     /**
-     * An event of the game's own by its id: listed, or the engine's (`core.`). One of a game's that it does not list
-     * throws (`UnlistedError`)
+     * An event of the game's own by its id: listed, or the engine's (`core.`), as the engine defined it. One of a game's
+     * that it does not list throws (`UnlistedError`). Never another game's: a process may hold more than one, each
+     * defining an id its own way (E7)
      */
     event(id: string): EventKey<unknown> | undefined;
     /**
@@ -366,7 +430,7 @@ export declare class Registry {
     /** Id of the game module it was made from */
     game: string;
     /** The game module it was made from */
-    module: GameModule | null;
+    module: Rules | null;
     private hashed?;
     /** What identifies the game exactly, mods and code included (see `gameHash`). Worked out the first time it is asked for */
     get hash(): string;
@@ -376,9 +440,9 @@ export declare class Registry {
      * check they share: the two run builds of the same code that print it differently
      */
     get dataHash(): string;
-    /** The version of what the game keeps in a save (`GameModule.saves.version`): 1 for a game that says none */
+    /** The version of what the game keeps in a save (`Rules.saves.version`): 1 for a game that says none */
     get saveVersion(): number;
-    /** The game's own stats, next to the engine's (`GameModule.stats`) */
+    /** The game's own stats, next to the engine's (`Rules.stats`) */
     stats: StatDef[];
     /** The game put together with its packs (`assembleGame`): set as the registry is made of it */
     assembly: AssembledGame | null;
@@ -391,18 +455,18 @@ export declare class Registry {
     /** Whether a structure stands open now, in nobody's way, by its parts (`Component.passable`): a gate opened */
     standsOpen(entity: Entity): boolean;
     /** What the game's packs add to a unit's stats (`GamePack.stats`): a hero's growth */
-    statParts: StatPart[];
+    statFields: StatField[];
     /** How each event of the world is told to a player, the engine's then the packs' (`replicateEvent`), in order */
     replications: readonly ReplicatedEvent[];
-    /** The parts of a player's snapshot, the engine's then the packs' (`SnapshotPart`), in order */
-    snapshotParts: readonly SnapshotPart[];
-    /** What the game counts of its players (`GameRules.score`), its stats made: null for a game that counts nothing */
+    /** The parts of a player's snapshot, the engine's then the packs' (`SnapshotField`), in order */
+    snapshotFields: readonly SnapshotField[];
+    /** What the game counts of its players (`RuleSettings.score`), its stats made: null for a game that counts nothing */
     score: ResolvedScore | null;
-    /** What each of the game's own files was read as (`GameModule.files`), by id */
+    /** What each of the game's own files was read as (`Rules.files`), by id */
     private files;
-    /** The game's own files (`GameModule.files`), by id */
+    /** The game's own files (`Rules.files`), by id */
     private fileDefs;
-    /** What the rules read of a file of the game's own data (`GameModule.files`): throws for one the game does not list */
+    /** What the rules read of a file of the game's own data (`Rules.files`): throws for one the game does not list */
     file<T>(def: GameFileDef<T>): T;
     /** Puts what a file of the game's is read as, for this registry's world alone: the editor's panel, as it is edited */
     setFile<T>(def: GameFileDef<T>, value: T): void;
@@ -410,11 +474,11 @@ export declare class Registry {
     fileDef(id: string): GameFileDef<unknown> | undefined;
     /** A prefab of the game's by id, for `world.spawnPrefab`; throws for one there is not */
     prefab(id: string): PrefabDef;
-    /** What the ground can be painted with, in the order of their indices: the first is 1 (`GameModule.tiles`) */
+    /** What the ground can be painted with, in the order of their indices: the first is 1 (`Rules.tiles`) */
     tiles: TileDef[];
-    /** The game's layers of cells (`GameModule.cellLayers`): what `Terrain.cells` is keyed by, with what each means */
+    /** The game's layers of cells (`Rules.cellLayers`): what `Terrain.cells` is keyed by, with what each means */
     cellLayers: CellLayerDef[];
-    /** The numbers of the rules to be tuned while the game plays (`GameModule.tunables`) */
+    /** The numbers of the rules to be tuned while the game plays (`Rules.tunables`) */
     tunables: TunableDef[];
     /** A tunable by id, or nothing for one the game does not have */
     tunable(id: string): TunableDef | undefined;
@@ -426,11 +490,11 @@ export declare class Registry {
     statKeys: string[];
     /** Every stat of the game at 0, its own at their default: what base stats start from */
     statDefaults: Readonly<Stats>;
-    /** The game's numbers that are not about any one unit (`GameModule.rules`) */
-    rules: Readonly<GameRules>;
+    /** The game's numbers that are not about any one unit (`Rules.settings`) */
+    settings: Readonly<RuleSettings>;
     /** Null for a game where it is always day */
     day: DayCycle | null;
-    /** What the game tells each player about itself, see `GameModule.report`. Asked by the session that runs the world */
+    /** What the game tells each player about itself, see `Rules.report`. Asked by the session that runs the world */
     report: ((world: World, player: PlayerId) => Record<string, unknown>) | null;
     /** The resources of the game, in the order players are shown them */
     resources: ResourceDef[];
@@ -438,11 +502,11 @@ export declare class Registry {
      * The resource prices, bounties, revives and sales are in: the game's money. Null for a game without one,
      * where there is nothing of that kind to pay with
      */
-    currency: ResourceKind | null;
+    currency: ResourceId | null;
     /** The command type, or undefined for one the game does not have: commands come from outside, and may name anything */
     command(type: string): CommandDef | undefined;
     /** The definition of a resource, or undefined for one the game does not have */
-    resource(id: ResourceKind): ResourceDef | undefined;
+    resource(id: ResourceId): ResourceDef | undefined;
     /** A unit type by id: throws for one the game does not have (`units`) */
     unit(id: string): UnitTypeDef;
     /** An upgrade by id: throws for one the game does not have (`upgrades`) */