@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/components.d.ts

@@ -0,0 +1,184 @@
+import type { Entity, PlayerId } from './entity';
+import type { MapFieldDef } from './mapFields';
+import type { Registry } from './registry';
+import type { World } from './world';
+/**
+ * Components are typed state a game module or a mod keeps where the engine has no field for it: on an entity
+ * (`entity.get(key)`), for the whole world (`world.state(key)`) or for each player (`player.state(key)`). The engine's
+ * own parts are components too (`core.`: what a shop sells, an illusion's source), so that a game pays for what it uses
+ * and nothing else.
+ *
+ * A component is plain data, so that it goes into a save with the rest of the world (see `saveWorld`): numbers,
+ * text, lists and plain objects, with other entities by id.
+ *
+ * `T` is what the component holds; `S` is what a player's snapshot carries of it (`snapshot`), `T` itself when it is
+ * sent as it is
+ *
+ * @beta
+ */
+export interface Component<T, S = T> {
+    readonly id: string;
+    /** What it starts as. Needed for world and player state, which is there from the moment it is asked for */
+    readonly default?: () => T;
+    /**
+     * Who gets an entity's component in their snapshot (`EntityState.components`), for a game's view to show:
+     * the player it belongs to, their allies too, or everyone who sees the entity. Nobody when left out
+     */
+    readonly replicate?: Audience;
+    /**
+     * `false` for what is the app's, not the game's rules (where the screen is played from, a tool's own): kept in the
+     * app's saves, but left out of a scenario (`scenarioOfWorld`), which is loaded where only the game is (a test)
+     */
+    readonly portable?: boolean;
+    /**
+     * What a player's snapshot carries of it, worked out for each player told (`replicate`): a part of it, rounded,
+     * or shaped for the screen (a shop's stock with how far the next one is, not the seconds left). A copy of the whole
+     * value when left out. What it returns is plain data; `undefined` sends nothing to that player
+     *
+     * @beta
+     */
+    snapshot?(value: T, entity: Entity, view: SnapshotView): S | undefined;
+    /**
+     * Whether two snapshots of it say the same, for the delta a player is sent (`same`): field by field, as the
+     * component knows its shape. Compared as text (`JSON.stringify`) when left out, which costs with a big value
+     *
+     * @beta
+     */
+    same?(a: S, b: S): boolean;
+    /**
+     * Filed in the world's index (`world.index.with(key)`, always kept), and by owner too (`'owner'`:
+     * `world.index.with(key, player)`) for what a player asks for often (their heroes), so a system goes through what
+     * has the component and nothing else
+     *
+     * @beta
+     */
+    readonly index?: boolean | 'owner';
+    /**
+     * A field of the map editor's for it: what is placed on a map starts with the component set to what the field says
+     * (`MapObject.data[id]`, under the component's own id), the editor's Inspector shows it for what `for` names, and
+     * the game has it from the moment the world is made, with nothing to copy over in a `mapObject` hook
+     *
+     * @beta
+     */
+    readonly field?: ComponentFieldDef;
+    /**
+     * What an entity starts with of it, as it is made (`World.spawn`), by its type: a building that makes things gets
+     * its queue, a unit that carries its slots. Run for every entity made, the engine's parts first and in their order,
+     * before the `made` hook; what it does not want of an entity, it leaves alone
+     *
+     * @beta
+     */
+    readonly onSpawn?: (entity: Entity, world: World) => void;
+    /**
+     * What is called off of it as the entity leaves its owner: it dies (before the `death` hook), or is given to
+     * another (`World.setOwner`). Run for an entity that has it
+     *
+     * @beta
+     */
+    readonly onLeave?: (entity: Entity, world: World) => void;
+    /**
+     * Whether a structure that has it stands open now, in nobody's way (a gate opened): what puts the world back from a
+     * save leaves it out of the ways as it was. The part that opens and shuts it takes it out and puts it back as it
+     * goes (`World.nav`). Run for an entity that has it
+     *
+     * @beta
+     */
+    passable?(value: T, entity: Entity): boolean;
+    /**
+     * What a save keeps of it, where that is not its value as it is (plain data: numbers, text, lists, plain objects): a
+     * `Map` as its entries, an effect as where it is in its ability. Its value as it is when left out, which has to be
+     * plain data then
+     *
+     * @beta
+     */
+    save?(value: T, world: World): unknown;
+    /** It again, of what `save` gave, as a save is loaded: the save's value as it is when left out @beta */
+    load?(saved: unknown, registry: Registry): T;
+    /**
+     * The ids of the game's definitions a save of it names (of what `save` gave, or its value): what a save is checked
+     * for before a world is made of it, so that one naming what the game no longer has is refused all at once, saying
+     * what (`SaveMissing`)
+     *
+     * @beta
+     */
+    refs?(saved: unknown): SavedRefs;
+}
+/**
+ * The ids of the game's definitions a component's saved value names, by kind (`Component.refs`)
+ *
+ * @beta
+ */
+export interface SavedRefs {
+    units?: readonly string[];
+    abilities?: readonly string[];
+    buffs?: readonly string[];
+    items?: readonly string[];
+    upgrades?: readonly string[];
+}
+/** @beta */
+export type Audience = 'owner' | 'allies' | 'everyone';
+/**
+ * A map field of a component's: as a game's own field on a map (`MapFieldDef`), its id the component's
+ *
+ * @beta
+ */
+export type ComponentFieldDef = Omit<MapFieldDef, 'id'>;
+/**
+ * Who a snapshot is being made for, as a component shapes its part of it
+ *
+ * @beta
+ */
+export interface SnapshotView {
+    readonly world: World;
+    /** The player it is made for; `undefined` for an observer */
+    readonly player: PlayerId | undefined;
+    /** Whether the entity is the player's own */
+    readonly own: boolean;
+    /** Whether the entity's owner is the player, or an ally of theirs (an observer is everyone's) */
+    readonly ally: boolean;
+    readonly observer: boolean;
+    /** Whether the player's team can see another entity right now (`SessionView.knows`): what else of it the part may name */
+    readonly knows: (entity: Entity) => boolean;
+    /** Whether an owner is the player or an ally of theirs (`SessionView.isAlly`) */
+    readonly isAlly: (owner: PlayerId) => boolean;
+    /** Whether the player's team sees a spot of the map right now (`SessionView.sees`) */
+    readonly sees: (x: number, z: number) => boolean;
+}
+/**
+ * What `defineComponent` takes: everything of a component but its id
+ *
+ * @beta
+ */
+export type ComponentOptions<T, S = T> = Omit<Component<T, S>, 'id' | 'slot'>;
+/**
+ * A typed key for state of a game's own: `const wave = defineComponent<WaveState>('td.waves', { default: () => ... })`.
+ * Give it a prefix of the game's or the mod's: the engine's own are `core.`. A game lists its own
+ * (`GameModule.components`), and its world finds them by id in its registry: another game of the process may have one
+ * of the same id, and a module loaded again (as a dev server does) defines it again.
+ *
+ * With `snapshot` and `same` the component shapes what players are sent of it and how a change is found; with `index`
+ * it is filed for systems to go through; with `field` the map editor sets it
+ *
+ * @beta
+ */
+export declare function defineComponent<T, S = T>(id: string, options?: ComponentOptions<T, S>): Component<T, S>;
+/**
+ * What a snapshot carries of a component, typed: `snapshotOf(entity.state, shopStock)` on a screen, or in a computer
+ * player's view. `undefined` when the player was not told it
+ *
+ * @beta
+ */
+export declare function snapshotOf<T, S>(state: {
+    components?: Record<string, unknown>;
+}, component: Component<T, S>): S | undefined;
+/**
+ * State kept by component, for the world or a player. Asking for one that is not there yet makes it from the
+ * component's default
+ */
+export declare class StateStore {
+    /** By component id. Plain data, for a save */
+    readonly values: Record<string, unknown>;
+    get<T>(key: Component<T, unknown>): T;
+    set<T>(key: Component<T, unknown>, value: T): void;
+    has(key: Component<unknown, unknown>): boolean;
+}

package/dist/computers.d.ts

@@ -0,0 +1,108 @@
+import type { PlayerId } from './entity';
+import type { World } from './world';
+import type { AiOptions } from './ai/options';
+import type { Brain, BrainDef } from './ai/brain';
+import type { ComputerPlayer, ComputerSystem } from './ai/computer';
+/**
+ * How a brain is seated at a player (`BrainDef.seat`): the system the seat is, a computer thinking in it. What
+ * `defineBrain` and `defineComputer` give a brain, so that the core seats it without knowing how
+ *
+ * @beta
+ */
+export type BrainSeat = (world: World, player: PlayerId, options: AiOptions) => ComputerSystem;
+/**
+ * What a seat is asked for (`world.computers.seat(player, request)`): the brain (one of the game's, `defineBrain`, or
+ * its id; the first the game lists when left out) and what it is seated with (`AiOptions`)
+ *
+ * @beta
+ */
+export interface SeatRequest extends AiOptions {
+    /** The brain, or its id (one the game lists in `GameModule.brains`): the first the game lists when left out */
+    brain?: BrainDef | string;
+}
+/**
+ * A seat as a save keeps it (`core.computers`): the brain by id, and the data part of its options
+ *
+ * @beta
+ */
+export interface ComputerSeat {
+    /** The brain's id. Left out for the first brain the game lists */
+    brain?: string;
+    /** What it was seated with, the data of it (`AiOptions`) */
+    options: Record<string, unknown>;
+}
+/**
+ * Who the computer plays, by player, with what they were seated with: in the world, so that a save keeps it and a
+ * loaded game seats them again by itself (`world.computers`)
+ */
+export declare const computerSeats: import("./components").Component<Record<string, ComputerSeat>, Record<string, ComputerSeat>>;
+/**
+ * What every seat of the world is given where its request says nothing (`world.computers.defaults`): data only, kept in
+ * the world so a save has it, and a computer seated after a load gets it too
+ */
+export declare const computerDefaults: import("./components").Component<Record<string, unknown>, Record<string, unknown>>;
+/**
+ * The computer players of a world: who is seated, kept in the world and in a save (`core.computers`), so that a game
+ * loaded from a save has them back without the game's doing, and how the game reaches a seated brain while it plays
+ * (`tell`, `pause`, `get`)
+ *
+ * @beta
+ */
+export declare class Computers {
+    private readonly world;
+    /** The seats, by player, in the order they were taken */
+    private readonly seats;
+    constructor(world: World);
+    /**
+     * Seats the computer at a player, and remembers it: a game loaded from a save of this one has it back, with its memory
+     * (`restore`). `request.brain` is one of the game's (`defineBrain`; one listed in `GameModule.brains` is found again by
+     * its id for a load, one that is not is kept by id only, and a load without it warns and leaves the seat empty), or
+     * its id, or left out for the first brain the game lists. Of the rest of the request (`AiOptions`), the data is kept
+     * (numbers, lists, names); a function given in it is dropped from the save, said in the log, and a load has what the
+     * brain's definition gives: a game that wants its function back after a load puts it in the brain it lists in
+     * `GameModule.brains`. A player seated already is unseated first. What thinks in it is a `Brain` unless the brain was
+     * made otherwise (`defineComputer`: say which)
+     */
+    seat<C extends ComputerPlayer = Brain>(player: PlayerId, request?: SeatRequest): ComputerSystem<C>;
+    /**
+     * What every computer seated from now on is given where its request says nothing (`AiOptions`, data only: a
+     * difficulty, a personality), over what the map says of the player (`MapPlayer.data.ai`): a campaign's difficulty,
+     * set before a mission seats its computers. Kept in the world, so a save has it. Those seated already keep what they
+     * were seated with
+     */
+    get defaults(): Readonly<Pick<AiOptions, 'difficulty' | 'personality'>>;
+    set defaults(defaults: Pick<AiOptions, 'difficulty' | 'personality'>);
+    /** Takes the computer out of a player's seat, and out of what a save remembers. False where none was seated */
+    unseat(player: PlayerId): boolean;
+    /** The seat the computer plays a player from, while it does */
+    get(player: PlayerId): ComputerSystem | undefined;
+    /** The players the computer plays, in the order they were seated */
+    list(): PlayerId[];
+    /**
+     * Tells a computer player a word, with data to go with it: what a mission's script says to its brain
+     * (`world.computers.tell(ENEMY, 'raid', { at })`), taken by a rule of the brain's (`when.told`). False where nobody is
+     * seated there, or what is seated takes no words
+     */
+    tell(player: PlayerId, word: string, data?: unknown): boolean;
+    /** Has a computer player sit still until `resume`: kept in a save. False where none is seated, or it cannot be paused */
+    pause(player: PlayerId): boolean;
+    /** Has a paused computer player think again */
+    resume(player: PlayerId): boolean;
+    private setPaused;
+    /** The system a player's seat is: the brain's own seat (`BrainDef.seat`), the first brain the game lists where none is named. Throws for a game that lists none */
+    private seated;
+    /**
+     * The brain a player is seated with where the seat names none, by id: the map's for the player (`MapAi.brain`, where
+     * the map gives the player to the computer), else its race's (`GameAi.races[race].brain`), else the game's defaults'
+     * (`GameAi.defaults.brain`). Nothing where none says: the game's first brain
+     */
+    private brainFor;
+    /** A brain by id: one the game lists (`GameModule.brains`) */
+    brain(id: string): BrainDef | undefined;
+    /**
+     * Seats again the computers a save remembers, in a world loaded from it: what `loadWorld` does before the game's
+     * `afterLoad`. One the game seated already is left as it is; one whose brain is not to be found (seated by an object
+     * the game does not list) is left empty, and the log says so
+     */
+    restore(): void;
+}

package/dist/concealment.d.ts

@@ -0,0 +1,61 @@
+import type { Entity } from './entity';
+import type { GamePack } from './packs/pack';
+import type { World } from './world';
+/**
+ * Hiding places painted on a map, as a layer of cells (`CellLayerDef`): tall grass, a forest's edge. Who stands in one
+ * is seen by another team only from inside the same patch of it (the cells of the layer that touch, sides or corners),
+ * or from close by (`reach`). An attacker in one is seen by whom it hits for a moment, as anyone is (`expose`), and
+ * what detects the invisible (`entity.detected`) sees it too. A game turns it on, on as many layers as it likes:
+ *
+ *     export const rules = { ...myGame, packs: [withConcealment({ layer: 'bush' })] }
+ *
+ * Everything that asks what a team sees (`world.isVisibleTo`) goes by it: what units pick to attack, the commands a
+ * player may give, the fog's memory, and each player's snapshots, so the computer player and the players over a wire
+ * see what the rules let them. Nothing is saved: it is worked out from the layer and where everyone stands
+ *
+ * @beta
+ */
+export interface ConcealmentOptions {
+    /** The layer of cells that hides (`Terrain.cells`): any cell of it with a value other than 0 */
+    layer: string;
+    /** How near, in cells, someone of another team has to be to see into it from outside: 2 when left out */
+    reach?: number;
+    /**
+     * What it hides: units on the ground, of anyone, when left out (not structures, not what flies). A game's own, to hide
+     * heroes only or let some types never hide
+     */
+    hides?: (world: World, entity: Entity) => boolean;
+    /**
+     * Whether a team sees a hidden entity anyway, after what the patch and `reach` make of it: a ward, a scout's ability.
+     * Asked only of what would otherwise be hidden
+     */
+    seenBy?: (world: World, entity: Entity, team: number) => boolean;
+    /**
+     * Whether one hidden in it gives itself away by moving, as the brush of a hero arena game shakes: the teams that do not see it are
+     * told where it moves in it and steps into it (a `rustle` event, where they see the ground; not who), and their
+     * screens shake the bushes there. `true` for every team, a function to say for each (`team`), no when left out:
+     * a hidden unit shakes nothing on the screens of those who do not see it
+     */
+    rustle?: boolean | ((world: World, entity: Entity, team: number) => boolean);
+    /** How often one moving in it is told again, in seconds: 0.3 when left out. Stepping in is told at once */
+    rustleEvery?: number;
+    /** The id of its hook and its system, to replace or leave out: `concealment:<layer>` when left out */
+    id?: string;
+}
+/**
+ * The patch of a layer an entity stands in, 1 and up, or 0 where it stands in none (`ConcealmentOptions`). For a
+ * game's rules and screen: who is in the grass
+ *
+ * @beta
+ */
+export declare function patchAt(world: World, layer: string, x: number, z: number): number;
+/**
+ * A game where what stands in a layer of cells is hidden from the teams that are not in it with them (see
+ * `ConcealmentOptions`): a `visible` hook, and a system that works out who has someone in which patch at the start of
+ * every tick (the same in every copy of the game, whoever asks what in between). On as many layers as it is given
+ *
+ * @beta
+ */
+export declare function withConcealment(options: ConcealmentOptions): GamePack;
+/** One hidden moving in a layer: where the player sees the ground, to whom the rules tell it, a shake of the bushes */
+export declare const toldRustle: import("./replication").ReplicatedEvent;