@v12-engine/engine 0.1.0 → 0.4.0

package/dist/createGame.d.ts

@@ -0,0 +1,306 @@
+import type { AbilityDef, BuffDef, ItemDef, ResourceDef, StatDef, UnitTypeDef, UpgradeDef } from './defs';
+import type { AreaDef } from './areas';
+import type { BrainDef } from './ai/brain';
+import type { CellLayerDef } from './cellLayers';
+import type { CommandDef } from './commands';
+import { type Component, type ComponentOptions } from './components';
+import type { EffectType } from './abilities/effects';
+import { type EventKey } from './events';
+import type { FormationDef } from './formation';
+import type { Rules } from './game';
+import type { GameFileDef } from './gameFiles';
+import type { GamePack } from './packs/pack';
+import type { HookHandler, HookKey, HookName } from './hooks';
+import type { HotContext } from './hotReload';
+import type { GameMap } from './map';
+import type { ObjectiveDef } from './objectives';
+import type { PlayerId } from './entity';
+import type { PrefabDef } from './prefabs';
+import type { RaceDef } from './races';
+import type { OrderBehavior, SystemDef } from './registry';
+import type { RuleSettingsInit } from './rules';
+import type { RulesProblem } from './rulesCheck';
+import { type SequenceDef, type Step } from './sequences';
+import type { Targeting } from './targeting';
+import type { TileDef } from './tiles';
+import { type TimerDef, type TimerInfo } from './timers';
+import type { TunableDef } from './tunables';
+import type { World } from './world';
+/**
+ * What a game's start is told (`Game.onStart`): the map its world was made from, the player at the screen (in a page),
+ * the lobby's settings (on a server), and whether the world is new (`fresh`) or loaded from a save, which has
+ * everything a start gives already. Each host says what it knows; the rest is left out
+ *
+ * @public
+ */
+export interface GameStartContext {
+    /** The map the world was made from; none for a world made in code */
+    map?: GameMap;
+    /** The player at the screen, in a page */
+    player?: PlayerId;
+    /** What the lobby set, on a server */
+    settings?: Record<string, string>;
+    /** Whether the world is new: false for one loaded from a save. True when left out */
+    fresh?: boolean;
+}
+/**
+ * What a game does once a world is made, before anyone plays (`Game.onStart`, a mission's `onStart`): computer
+ * players seated, a mission given, the first wave sent
+ *
+ * @public
+ */
+export type GameStart = (world: World, context: GameStartContext) => void | Promise<void>;
+/**
+ * A game's maps by name (`Game.maps`): each the map, or what fetches it as it is first asked for (`mapsFrom` of a lazy
+ * glob), so that a page carries none of a map it does not open
+ *
+ * @public
+ */
+export type GameMaps = Readonly<Record<string, GameMap | (() => Promise<GameMap>)>>;
+/**
+ * What a game is made with (`createGame`): its id and name, and any field of the module underneath (`Rules`) said at
+ * once: a whole `Rules` is a game too (`createGame(rules)`). What is registered on the game after comes after what is
+ * given here
+ *
+ * @public
+ */
+export interface GameInit extends Partial<Rules> {
+    /** The game's id, which a save, a map (`GameMap.game`) and a server know it by */
+    id: string;
+    /** What the player sees the game called */
+    name: string;
+    /**
+     * Packs of content to play it with in a page, by URL (`'/packs/gnomes/pack.json'`): fetched as a game of it is got
+     * ready, before its world is made, and composed in this order (the client's `mergePacks`). A server plays its own
+     * (`readPacks`). None when left out
+     */
+    contentPacks?: readonly string[];
+    /**
+     * What is done, as its view is fetched in a page, about a view that names what the rules do not have (the client's
+     * `checkGame`): a warning for each when left out, an error with all of them (`'throw'`), or nothing (`false`)
+     */
+    checkView?: 'warn' | 'throw' | false;
+}
+/**
+ * Where a listener or a hook's handler registered on a game or a mission goes by: an id of its own, in the place of the
+ * one made for it (`<game>.on.<event>.<n>`, `<game>.<mission>.before.<hook>.<n>`), and a priority for a hook (lower
+ * runs first: `before` is -1 and `after` 1 when left out, the engine's own handlers 0)
+ *
+ * @public
+ */
+export interface HandlerOptions {
+    /** Its id, under the game's (or the mission's): `'gate'` is `<game>.gate`. Made for it when left out */
+    id?: string;
+    /** A hook handler's priority: lower runs first. -1 for `before`, 1 for `after` when left out */
+    priority?: number;
+}
+/**
+ * What a mission registers its parts with (`Game.mission`): each part's id is made of the game's, the mission's and its
+ * own (`'raze'` in the mission `homecoming` of `my-game` is `my-game.homecoming.raze`), and the parts go into the game's
+ * rules, so that a save finds them by those ids. Its `onStart` runs where the world's map is one it `plays`, or as it is
+ * `start`ed
+ *
+ * @public
+ */
+export interface Mission {
+    /** Its id, the game's and its own: `my-game.homecoming` */
+    readonly id: string;
+    /** The id of a part of it, by its own name: `my-game.homecoming.raze` for `'raze'` */
+    idOf(name: string): string;
+    /** An objective of the mission (`defineObjective`), its id made of the mission's */
+    objective(def: ObjectiveDef): ObjectiveDef;
+    /** A sequence of steps of the mission (`defineSequence`), its id made of the mission's, listed in the rules */
+    sequence<D = undefined>(def: {
+        id: string;
+        steps: (Step<D> | readonly Step<D>[])[];
+    }): SequenceDef<D>;
+    /** A timer of the mission (`defineTimer`), its id made of the mission's, listed in the rules */
+    timer<T = undefined>(def: {
+        id: string;
+        run: (world: World, data: T, timer: TimerInfo) => void;
+    }): TimerDef<T>;
+    /** State the mission keeps (`defineComponent`), its id made of the mission's, listed in the rules */
+    component<T, S = T>(def: {
+        id: string;
+    } & ComponentOptions<T, S>): Component<T, S>;
+    /** A part of the map the mission watches (`AreaDef`), its id made of the mission's, listed in the rules */
+    area(def: AreaDef): AreaDef;
+    /** How the mission reacts to an event: a listener of the rules (`defineListener`), its id under the mission's */
+    on<T>(event: EventKey<T>, run: (world: World, payload: T) => void, options?: HandlerOptions): Mission;
+    /** A handler of a hook that runs before the engine's own (priority -1), its id under the mission's */
+    before<K extends HookName>(hook: K, run: HookHandler<K>, options?: HandlerOptions): Mission;
+    /** A handler of a game's own hook (`HookKey`) that runs before the rest, its id under the mission's */
+    before<T>(hook: HookKey<T>, run: (world: World, event: T) => void, options?: HandlerOptions): Mission;
+    /** A handler of a hook that runs after the engine's own (priority 1), its id under the mission's */
+    after<K extends HookName>(hook: K, run: HookHandler<K>, options?: HandlerOptions): Mission;
+    /** A handler of a game's own hook (`HookKey`) that runs after the rest, its id under the mission's */
+    after<T>(hook: HookKey<T>, run: (world: World, event: T) => void, options?: HandlerOptions): Mission;
+    /** What the mission does as a world of it starts: its objectives given, its sequences started (`fresh` says whether to) */
+    onStart(run: GameStart): Mission;
+    /** The maps it is played on, by their name (`GameMap.name`) or their name in `Game.maps`: a world made from one starts it */
+    plays(...maps: string[]): Mission;
+    /** Starts it on a world: its `onStart` in the order given. What a campaign's scene calls, knowing whether the world is new */
+    start(world: World, context?: GameStartContext): void | Promise<void>;
+}
+/**
+ * A game: one object everything of it is registered on, which every host takes (`createGame`). Its rules are made
+ * from what it holds (`toRules()`, the module underneath that a server, a test and a worker run); its view is fetched as
+ * a page first needs it (`view(() => import('./view'))`, `toView()`), so that the rules are read where nothing draws
+ * (a server, a test) without the client. Each method that registers a definition gives it back
+ *
+ *     export const game = createGame({ id: 'td', name: 'Tower defense' })
+ *     export const archer = game.unit({ id: 'archer', name: 'Archer', kind: 'unit', stats: { health: 200 } })
+ *     game.on(entityDied, (world, { entity }) => { … })
+ *     game.onStart((world, { map }) => { … })
+ *     game.maps(mapsFrom(import.meta.glob('./maps/*.vgmap.json', { import: 'default' })))
+ *     game.view(() => import('./view'))
+ *
+ * @public
+ */
+export interface Game<V = unknown> {
+    /** The game's id (`Rules.id`): what a save, a map, a replay and a server call it by */
+    readonly id: string;
+    /** What the player sees the game called (`Rules.name`) */
+    readonly name: string;
+    /** Packs of content to play it with in a page, by URL (`GameInit.contentPacks`) */
+    readonly contentPacks: readonly string[];
+    /** What a page does about a view that does not fit the rules as it fetches it (`GameInit.checkView`) */
+    readonly checkView: 'warn' | 'throw' | false;
+    /** Whether a view was given (`view`): a game without one has rules alone, for a server or a test */
+    readonly hasView: boolean;
+    /** A unit type (`UnitTypeDef`), building or resource alike */
+    unit<T extends UnitTypeDef>(def: T): T;
+    /** An ability (`AbilityDef`) */
+    ability<T extends AbilityDef>(def: T): T;
+    /** A buff (`BuffDef`) */
+    buff<T extends BuffDef>(def: T): T;
+    /** An item (`ItemDef`) */
+    item<T extends ItemDef>(def: T): T;
+    /** An upgrade (`UpgradeDef`) */
+    upgrade<T extends UpgradeDef>(def: T): T;
+    /** A side players can play (`RaceDef`) */
+    race<T extends RaceDef>(def: T): T;
+    /** What players have amounts of and pay with (`ResourceDef`) */
+    resource<T extends ResourceDef>(def: T): T;
+    /** A stat of the game's own (`StatDef`) */
+    stat<T extends StatDef>(def: T): T;
+    /** A system of the game's own (`SystemDef`): after the core ones unless it says a phase; one named as a core one takes its place */
+    system<T extends SystemDef>(def: T): T;
+    /** An order type (`OrderBehavior`), or one in the place of a core one of its type */
+    order<T extends OrderBehavior>(def: T): T;
+    /** State of its own (`defineComponent`), listed so that a world, a save and a snapshot find it */
+    component<T extends Component<any, any>>(component: T): T;
+    /** A command of its own (`defineCommand`), or one in the place of a core one */
+    command<T extends CommandDef>(def: T): T;
+    /** An event of its own (`defineEvent`), listed so that a world finds it */
+    event<T extends EventKey<any>>(key: T): T;
+    /** A part of the map the rules watch (`AreaDef`) */
+    area<T extends AreaDef>(def: T): T;
+    /** A group of things spawned as one (`definePrefab`) */
+    prefab<T extends PrefabDef>(def: T): T;
+    /** Something set to go off later (`defineTimer`) */
+    timer<T extends TimerDef<any>>(def: T): T;
+    /** A script of steps (`defineSequence`) */
+    sequence<T extends SequenceDef<any>>(def: T): T;
+    /** A file of its own data its rules read (`defineGameFile`) */
+    file<T extends GameFileDef<any>>(def: T): T;
+    /** A brain of its computer players (`defineBrain`): the first given is what a seat that names none gets */
+    brain<T extends BrainDef>(def: T): T;
+    /** What the ground can be painted with (`TileDef`), in order */
+    tile<T extends TileDef>(def: T): T;
+    /** A type of effect of its own (`defineEffect`), or one in the place of the engine's of its type */
+    effect<T extends EffectType>(def: T): T;
+    /** A way of aiming of its own (`defineTargeting`) */
+    targeting<T extends Targeting>(def: T): T;
+    /** A formation of its own (`FormationDef`) */
+    formation<T extends FormationDef>(def: T): T;
+    /** A number of its rules to tune while it plays (`defineTunable`) */
+    tunable<T extends TunableDef>(def: T): T;
+    /** A layer of cells of its own (`CellLayerDef`) */
+    cellLayer<T extends CellLayerDef>(def: T): T;
+    /** A part of the rules it opts into (`GamePack`: `heroesPack()`), before its own */
+    pack(pack: GamePack): Game<V>;
+    /** Its numbers that are not about any one unit (`RuleSettingsInit`), laid over what was said before, group by group */
+    settings(settings: RuleSettingsInit): Game<V>;
+    /** How the game reacts to an event, the engine's or its own: a listener (`defineListener`), its id made for it */
+    on<T>(event: EventKey<T>, run: (world: World, payload: T) => void, options?: HandlerOptions): Game<V>;
+    /** A handler of a hook that runs before the engine's own (priority -1): one that may say no (`event.cancel()`) */
+    before<K extends HookName>(hook: K, run: HookHandler<K>, options?: HandlerOptions): Game<V>;
+    /** A handler of a game's own hook (`HookKey`) that runs before the rest */
+    before<T>(hook: HookKey<T>, run: (world: World, event: T) => void, options?: HandlerOptions): Game<V>;
+    /** A handler of a hook that runs after the engine's own (priority 1): one that reads or changes what they made of it */
+    after<K extends HookName>(hook: K, run: HookHandler<K>, options?: HandlerOptions): Game<V>;
+    /** A handler of a game's own hook (`HookKey`) that runs after the rest */
+    after<T>(hook: HookKey<T>, run: (world: World, event: T) => void, options?: HandlerOptions): Game<V>;
+    /** What the game does once a world is made, before anyone plays; each given runs, in order, before a mission's */
+    onStart(run: GameStart): Game<V>;
+    /** A mission: its parts registered through `setup` with ids made of the game's and the mission's (`Mission`) */
+    mission(id: string, setup: (mission: Mission) => void): Mission;
+    /** Its maps by name, laid over those given before; the first is the one a game is on when nothing says which */
+    maps(maps: GameMaps): Game<V>;
+    /**
+     * Its view (how it looks and sounds: the client's `GameView`), or what fetches it as a page first needs it:
+     * `() => import('./view')` (a module whose `view` or `default` is the view). Given so, nothing of the client is part
+     * of what imports the game, which a server and a test do
+     */
+    view(view: V | (() => Promise<unknown>)): Game<V>;
+    /**
+     * What does not fit: the rules against themselves (`checkRules`), ids given twice among what was registered (one
+     * takes the other's place unseen), and each map (fetched where it is lazy) against the rules: a type it places that
+     * no unit type is, a map of another game. A save or a map naming an id that nothing registered is what this finds
+     * before it is played
+     */
+    check(): Promise<RulesProblem[]>;
+    /**
+     * The module underneath (`Rules`): what the hosts run. The same object each time; what is registered after it was
+     * made is put into it in place
+     */
+    toRules(): Rules;
+    /** The view, fetched the first time it is asked for. Throws when none was given */
+    toView(): Promise<V>;
+    /** Its start: the `onStart`s given, then the mission whose map the world was made from. None when it has neither */
+    toStart(): GameStart | undefined;
+    /** Its maps by name, as given (`maps`) */
+    toMaps(): GameMaps;
+    /** A map of it by name (the first when left out), fetched where it is lazy, as a copy: a game changes nothing of the next one's */
+    loadMap(name?: string): Promise<GameMap>;
+}
+/**
+ * Whether something is a game made by `createGame`, rather than the module underneath (`Rules`)
+ *
+ * @public
+ */
+export declare function isGame(value: unknown): value is Game<unknown>;
+/**
+ * The module underneath what a host is given: a game's (`toRules()`), or the module itself
+ *
+ * @beta
+ */
+export declare function rulesOf(game: Game<unknown> | Rules): Rules;
+/**
+ * The start of what a host is given, where it says none of its own: a game's (`toStart()`); a module has none
+ *
+ * @beta
+ */
+export declare function startOf(game: Game<unknown> | Rules): GameStart | undefined;
+/**
+ * Makes a game: one object its units, abilities, systems, hooks and listeners, missions, maps and view are registered
+ * on, which every host takes (`Game`). `init` is its id and name, and any field of the module underneath said at once:
+ * `createGame(rules)` makes a game of a module written whole
+ *
+ * @public
+ */
+export declare function createGame<V = unknown>(init: GameInit): Game<V>;
+/**
+ * A game's module's new version, taken while it runs (hot reload), as `hotRules` takes a module's: at the end of the
+ * module that makes the game, the call to Vite written out as it is (Vite finds a module that takes its own new
+ * versions by it):
+ *
+ *     if (import.meta.hot) import.meta.hot.accept((module) => hotGame(import.meta.hot, game, module?.game))
+ *
+ * The rules the hosts were given are made the new version's in place (`hotRules`); the view, a module of its own, takes
+ * its own (the client's `hotView`). What does not go loads the page again
+ *
+ * @public
+ */
+export declare function hotGame(hot: HotContext | undefined, current: Game<unknown>, next: unknown): void;