@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/gameData.d.ts

@@ -0,0 +1,325 @@
+import type { DamageTable } from './rules';
+import type { AiProfile } from './ai/profiles';
+import { type AbilityDef, type BuffDef, type ItemDef, type ResourceDef, type UnitTypeDef, type UpgradeDef, type UpkeepTier } from './defs';
+import { type Check } from './fields';
+import type { GameModule } from './game';
+import type { RaceDef } from './races';
+import type { Registry } from './registry';
+/**
+ * The kinds of definition a game's data is kept for, by the field of the game module they are listed in
+ *
+ * @beta
+ */
+export declare const DATA_KINDS: readonly ['units', 'abilities', 'buffs', 'items', 'upgrades', 'races'];
+/** @beta */
+export type DataKind = (typeof DATA_KINDS)[number];
+/**
+ * What a definition of each kind must have besides its id and its name, as the type says (`UnitTypeDef.radius`...),
+ * with what one made of nothing starts as (`NEW_DEFINITION`: the Data panel's New, from empty). A unit type is a unit
+ * unless its `kind` says otherwise
+ *
+ * @beta
+ */
+export declare const REQUIRED_FIELDS: Readonly<Record<DataKind, Readonly<DataValues>>>;
+/**
+ * What a definition in a `data.json` says to be one of its own, made of nothing, where the game has none by its id
+ * (`{ "new": true, "name": "Peon", "stats": { "health": 220 } }`): what its kind must have (`REQUIRED_FIELDS`), its
+ * name its id until it says, with what else is said over it. A unit type's `kind` is taken from it too
+ *
+ * @beta
+ */
+export declare const NEW_DEFINITION = "new";
+/**
+ * A definition made of nothing, by an id: what its kind must have (`REQUIRED_FIELDS`), named by its id
+ *
+ * @beta
+ */
+export declare function blankDefinition<K extends DataKind>(kind: K, id: string, unitKind?: string): DataDefs[K];
+/**
+ * A definition of each kind
+ *
+ * @beta
+ */
+export interface DataDefs {
+    units: UnitTypeDef;
+    abilities: AbilityDef;
+    buffs: BuffDef;
+    items: ItemDef;
+    upgrades: UpgradeDef;
+    races: RaceDef;
+}
+/**
+ * What a field of the data can hold: a number, words, yes or no
+ *
+ * @beta
+ */
+export type DataValue = number | string | boolean;
+/**
+ * What a field can be set to: one of those, a list of words (ids: the abilities of a unit, what a building trains), or a
+ * list of things whole (the effects of an ability: a `rows` field)
+ *
+ * @beta
+ */
+export type FieldValue = DataValue | string[] | DataValues[];
+/**
+ * What a definition in a `data.json` is a copy of, when the game has none by its id: `{ "copyOf": "footman", "name":
+ * "Champion" }` is a footman by another name. The copy is the definition it names, with what else is said over it,
+ * and knows what it is a copy of (`basedOn`)
+ *
+ * @beta
+ */
+export declare const COPY_OF = "copyOf";
+/**
+ * Values of a definition, as its own fields nest them: `{ stats: { health: 420 }, cost: { gold: 135 } }`. What a
+ * `data.json` keeps of each definition, and what `world.redefine` is given. A list of things by place (a unit's attacks)
+ * is written as a list or as its places (`{ attacks: { 0: { damagePoint: 0.5 } } }`), each over the thing there. A list
+ * of things changed whole (an ability's effects, the units a race's start adds: a `rows` field) written as places goes
+ * over the things there, and written as a list is the list: those things, in that order, each in full
+ *
+ * @beta
+ */
+export interface DataValues {
+    [field: string]: DataValue | DataValue[] | DataValues | DataValues[];
+}
+/**
+ * The values of a game's definitions, by kind and id: what its `data.json` holds. `removed` takes definitions of the
+ * game's out, by kind (the Data panel's Delete): what still names one is the rules' check's to say (`checkRules`)
+ *
+ * @beta
+ */
+export type GameData = Partial<Record<DataKind, Record<string, DataValues>>> & {
+    removed?: Partial<Record<DataKind, string[]>>;
+    /**
+     * How the game's computers play each race (campaign plan AR4), by race id: each a whole profile, in the place of the
+     * code's (`GameModule.ai.races`). What the editor's Data panel writes of a race's AI
+     */
+    ai?: {
+        races?: Record<string, AiProfile>;
+    };
+    /** The rules as data (campaign plan RC7), laid over the game's (`DataRules`): what the Data panel's Rules writes */
+    rules?: DataRules;
+};
+/**
+ * The rules a `data.json` may say (campaign plan RC7), each over the game's: the damage table whole, the supply's and
+ * the heroes' numbers, the resources and the upkeep's tiers whole (in place of `GameModule.resources`, `upkeep`)
+ *
+ * @beta
+ */
+export interface DataRules {
+    combat?: {
+        damageTable?: DamageTable;
+    };
+    supply?: {
+        max?: number;
+        pools?: Record<string, {
+            name: string;
+            max: number;
+        }>;
+    };
+    heroes?: {
+        maxHeroes?: number;
+        maxHeroLevel?: number;
+        xpRange?: number;
+    };
+    resources?: ResourceDef[];
+    upkeep?: UpkeepTier[];
+}
+/**
+ * Why rules said as data are not, where they are first wrong: nothing for rules that are
+ *
+ * @beta
+ */
+export declare function dataRulesProblem(rules: unknown): string | undefined;
+/**
+ * A field of a definition the editor may change, and how it shows it
+ *
+ * @beta
+ */
+export interface EditableField {
+    /** Where it is in the definition, by its fields: `stats.health`, `cost.gold`, `bounty.0` (a place in a list) */
+    path: string;
+    /** What it is called in the editor: the last part of its path, when left out */
+    name?: string;
+    /**
+     * What it holds. What the definition has there now, when left out (a number where it has nothing). A `list` is of
+     * words, in order: ids of the kind `of` says, when it says. An `id` is one id of the kind `of` says (the hall a race
+     * starts with), picked from what the game has of that kind. `rows` is a list of things, each with fields of its own
+     * (`effects.0.amount`), added, taken out and put in another order whole: an ability's effects
+     */
+    kind?: 'number' | 'integer' | 'text' | 'boolean' | 'choice' | 'list' | 'id' | 'rows';
+    /** Of a `list` or an `id`: the kind of definition its words are ids of (`abilities` for a unit's abilities) */
+    of?: DataKind;
+    /**
+     * Of a `list`: one id or a list of them (a building's `upgradesTo`). Shown as a list either way; a list of one is
+     * kept as the one id
+     */
+    one?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** What a `choice` can be */
+    options?: readonly string[];
+    /** Of `rows` of effects: the types a row can be, those the game has (`defineEffect`). A row of no type when left out */
+    types?: readonly string[];
+    /** The heading it is shown under: the first part of its path, when left out (`stats`, `cost`) */
+    group?: string;
+    /** A line about it, shown when the pointer is over it */
+    hint?: string;
+}
+/**
+ * A field as the editor shows it: everything said
+ *
+ * @beta
+ */
+export interface DataField extends EditableField {
+    name: string;
+    kind: NonNullable<EditableField['kind']>;
+    group: string;
+}
+/**
+ * Which fields of a kind of definition can be changed: `all` of them (every number, word and yes or no in the
+ * definition, as it has them, but its id and kind), some (their paths, or fields said in full), or none (nothing, or
+ * an empty list). A function says it for each definition, as it is now: null for none
+ *
+ * @beta
+ */
+export type EditableFields<D = unknown> = 'all' | readonly (string | EditableField)[] | ((def: D) => 'all' | readonly (string | EditableField)[] | null);
+/**
+ * What of a game's data the editor can change, by kind (`GameModule.editable`). `all` for every field of every definition
+ *
+ * @beta
+ */
+export type EditableData = 'all' | {
+    [K in DataKind]?: EditableFields<DataDefs[K]>;
+};
+/**
+ * What is at a path of a definition, or undefined
+ *
+ * @beta
+ */
+export declare function valueAt(def: unknown, path: string): unknown;
+/**
+ * Values with one field set, nested as the path says: `nested('stats.health', 420)` is `{ stats: { health: 420 } }`
+ *
+ * @beta
+ */
+export declare function nested(path: string, value: FieldValue): DataValues;
+/**
+ * The fields an effect of a type has, by their path in it: those its type reads (`defineEffect`'s `fields`), then those
+ * every effect may have (`EffectCommon`). Only those every effect may have, for a type the game has not
+ *
+ * @beta
+ */
+export declare function effectFields(game: Pick<GameModule, 'effects'> | null | undefined, type: string): EditableField[];
+/**
+ * The types of effect a game has (`defineEffect`): the engine's and its own, in order of their names
+ *
+ * @beta
+ */
+export declare function effectTypesOf(game: Pick<GameModule, 'effects'> | null | undefined): string[];
+/**
+ * The fields of a definition the editor may change, as the game says (`GameModule.editable`), each with what it
+ * holds and the heading it goes under. None for a game that says nothing of that kind
+ *
+ * @beta
+ */
+export declare function editableFields<K extends DataKind>(game: (Pick<GameModule, 'editable'> & Partial<Pick<GameModule, 'effects' | 'stats'>>) | null | undefined, kind: K, def: DataDefs[K]): DataField[];
+/**
+ * A value as a field takes it, or the reason it does not
+ *
+ * @beta
+ */
+export declare function fitValue(field: DataField, value: unknown): {
+    value: FieldValue;
+} | {
+    error: string;
+};
+/**
+ * A definition with values over it: a copy, the parts the values go into copied too, the rest (its functions, its
+ * lists of things) shared with the one it was made from. Values by place (`{ attacks: { 0: { damagePoint: 0.5 } } }`)
+ * go into the list there, or make one where there is none. Nothing of the definition given is changed
+ *
+ * @beta
+ */
+export declare function withValues<D>(def: D, values: DataValues): D;
+/**
+ * Values merged: what `b` says over what `a` says, at any depth. Places said over a list go into it (`{ 0: { amount:
+ * 50 } }` over a list of effects); a list said is the list
+ *
+ * @beta
+ */
+export declare function mergeValues(a: DataValues, b: DataValues): DataValues;
+/**
+ * Only the values of the fields that can be changed, each as its field takes it. What is not is left out and said:
+ * a field the game no longer lets be changed, a value of another kind
+ *
+ * @beta
+ */
+export declare function editableValues(fields: readonly DataField[], values: DataValues, said?: (why: string) => void): DataValues;
+/**
+ * The game with what its `data.json` says over what its code says: `export default withData(game, dataFile)`. Only
+ * the fields the game lets be changed (`GameModule.editable`) are taken, and of the kind each holds; anything else in
+ * the file is left out, and said in the log. The game given is not changed
+ *
+ * @beta
+ */
+export declare function withData(game: GameModule, file: unknown): GameModule;
+/**
+ * What a world's definitions were changed to while it runs (`world.redefine`), by kind and id: kept with the world
+ * and in its save, so that a load has them again
+ *
+ * @beta
+ */
+export declare const redefinitions: import("./components").Component<GameData, GameData>;
+/**
+ * A definition changed while the game runs: what it is now
+ *
+ * @beta
+ */
+export declare const definitionChanged: import("./events").EventKey<{
+    kind: DataKind;
+    id: string;
+    values?: DataValues;
+}>;
+/**
+ * Puts a definition with values over it into the registry, in the place of the one there: what is made of it from
+ * then on is made of the new one. False for a definition the game does not have
+ *
+ * @beta
+ */
+export declare function redefineIn(registry: Registry, kind: DataKind, id: string, values: DataValues): boolean;
+/**
+ * A new definition, a copy of one the registry has, by an id it has nothing by: what it is drawn as is the one it is
+ * a copy of (`basedOn`) until the game gives it a look of its own. False for one it does not have, or an id it has
+ *
+ * @beta
+ */
+export declare function copyDefinition(registry: Registry, kind: DataKind, from: string, id: string): boolean;
+/**
+ * Takes a definition out of the registry (the Data panel's Delete): what is made of it from then on is not. False for
+ * one it has not. Not for a world that runs: its units of the type are there
+ *
+ * @beta
+ */
+export declare function removeDefinition(registry: Registry, kind: DataKind, id: string): boolean;
+/**
+ * The definition of a kind and id in the registry, as it is now, or undefined
+ *
+ * @beta
+ */
+export declare function definitionIn<K extends DataKind>(registry: Registry, kind: K, id: string): DataDefs[K] | undefined;
+/**
+ * Every definition of a kind the registry has
+ *
+ * @beta
+ */
+export declare function definitionsIn<K extends DataKind>(registry: Registry, kind: K): DataDefs[K][];
+/** Puts what a save kept of the definitions changed while it ran back into the registry: before its entities are made */
+export declare function restoreRedefinitions(registry: Registry, kept: unknown): void;
+/** A path into a definition: names and places, joined by dots */
+/** A path into a definition, as the Data panel names a field: `stats.health` */
+export declare const pathCheck: Check<string>;
+/** A value of a field the Data panel may set: a number, words, yes or no, a list of words, or a list of things whole */
+export declare const valueCheck: Check<FieldValue>;
+/** A definition changed while the game runs (`world.redefine`): to everyone, whose screens read the definitions */
+export declare const toldRedefined: import("./replication").ReplicatedEvent;

package/dist/gameFiles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A file of a game's own data that its rules read as they run and a panel edits (`defineGameFile`): a campaign's waves,
+ * a tower defence's paths. Each world's registry holds what it was read as (`registry.file`), so two games on one page
+ * or two rooms of a server each play their own, and the editor's panel changes the one its game plays
+ * (`registry.setFile`); the file itself is the game's, written by the editor and taken again as code is (`hotRules`)
+ */
+/**
+ * A file of the game's own data, and how it is read
+ *
+ * @beta
+ */
+export interface GameFileDef<T> {
+    /** Unique in the game: the file's name, as the editor writes it (`waves.json`) */
+    readonly id: string;
+    /** What the file says, as the game was built with it (an imported JSON file) */
+    readonly data: unknown;
+    /** What the rules read of it: checked, with what is not of its shape left out */
+    read(data: unknown): T;
+}
+/**
+ * A file of the game's own data, for `GameModule.files`: `defineGameFile('waves.json', wavesFile, readWaves)`, read by
+ * the rules with `world.registry.file(waves)`
+ *
+ * @beta
+ */
+export declare function defineGameFile<T>(id: string, data: unknown, read: (data: unknown) => T): GameFileDef<T>;

package/dist/gates.d.ts

@@ -0,0 +1,28 @@
+import type { World } from './world';
+/**
+ * A gate opened or shut while the game runs: every screen hears it, to draw it open or shut
+ *
+ * @beta
+ */
+export declare const gateChanged: import("./events").EventKey<{
+    name: string;
+    open: boolean;
+}>;
+/**
+ * Puts the gates of the map in the world as they are: shut ones in the way of what walks. When the world is made from
+ * the map, and again when it is loaded from a save, which keeps which are open but not the obstacles
+ */
+export declare function setUpGates(world: World): void;
+/**
+ * Whether a gate of the map is open, by its name. Nothing for a name that is no gate
+ *
+ * @beta
+ */
+export declare function isGateOpen(world: World, name: string): boolean | undefined;
+/**
+ * Opens or shuts a gate of the map by its name, while the game runs: what walks goes through it or around, and every
+ * screen draws it so (`gateChanged`). False when the map has no gate by that name
+ *
+ * @beta
+ */
+export declare function setGate(world: World, name: string, open: boolean): boolean;