@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/aiTesting.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Testing a computer player (AI plan, E3): what a game's tests of its brains are written with, in
+ * `@v12-engine/engine/testing` beside `testWorld` and `run`. A brain is tested as it plays, through the world it sits in:
+ *
+ *     const world = await testWorld(myGame)
+ *     world.computers.seat(ENEMY, { enemyBases: [home], brain: myBrain })
+ *     const watch = watchComputer(world, ENEMY)        // its invariants, every think
+ *     run(world, 120)
+ *     expectDecision(thinkOnce(world, ENEMY), 'ai.attack')
+ *     watch.assert()                                     // no rule broken
+ *
+ * `thinkOnce` has a seated brain think now and gives its report; `expectDecision` says a goal runs, or why not in
+ * words; `watchComputer` checks the invariants of `ai/checks.ts` after every think (a unit in one squad, gold spent
+ * once, finite numbers, commands about what it sees, no churn, nothing stuck) and keeps what it decided; `fairPlay` is
+ * the one about seeing; `recordDecisions` keeps every computer's decisions for a replay's side file; `checkComputerSave`
+ * is the seventh invariant: a game saved and loaded decides the same from then on. These take the world, which a test
+ * may: the brains under test never do.
+ */
+import { type AiCheckOptions, type AiViolation } from './ai/checks';
+import { Brain } from './ai/brain';
+import type { GoalReport } from './ai/goals';
+import { type AiDecision, type AiReport } from './ai/report';
+import type { PlayerId } from './entity';
+import { type GameModule } from './game';
+import type { PlayerCommand, Snapshot } from './session/protocol';
+import type { World } from './world';
+/**
+ * The brain that plays a player, where one is seated (`world.computers.seat`): none where nobody is, or where what is
+ * seated is not a brain (`defineComputer`)
+ *
+ * @beta
+ */
+export declare function brainOf(world: World, player: PlayerId): Brain | undefined;
+/**
+ * Has the brain at a player think now, all of it (a think its budget slices over ticks is run to its end), over a new
+ * picture of the game, and gives its report: what a test reads after setting a scene. Its commands land at the next
+ * tick, as a think's do. A think the seat would have had is not skipped: this one is beside them
+ *
+ * @beta
+ */
+export declare function thinkOnce(world: World, player: PlayerId): AiReport;
+/**
+ * Says that a goal runs, as of a report (`thinkOnce`, `Brain.report`): it is picked and holds what it claimed. Throws
+ * where it does not, with its row in words (`Brain.explain`): what each consideration answered and what kept it out.
+ * Gives the goal's row. With `picked: false`, says it does not run
+ *
+ *     expectDecision(thinkOnce(world, ENEMY), 'ai.defend')
+ *
+ * @beta
+ */
+export declare function expectDecision(report: AiReport, goal: string, options?: {
+    picked?: boolean;
+}): GoalReport;
+/**
+ * A computer player followed over a run (`watchComputer`): the rules it broke, what it decided and sent, and, where
+ * asked, what an observer saw at each of its thinks
+ *
+ * @beta
+ */
+export interface ComputerWatch {
+    /** The brain watched */
+    readonly brain: Brain;
+    /** Every invariant it broke, in the order found (`ai/checks.ts`) */
+    readonly violations: readonly AiViolation[];
+    /** What it decided while watched, oldest first: every line, not only the last fifty its log keeps */
+    readonly decisions: readonly AiDecision[];
+    /** Its thinks while watched */
+    readonly thinks: number;
+    /** Commands it sent while watched */
+    readonly commands: number;
+    /** Throws, listing them, where it broke any rule */
+    assert(): void;
+    /** Stops watching */
+    stop(): void;
+}
+/**
+ * How a computer player is watched (`watchComputer`): which invariants and how long things may go on (`AiCheckOptions`),
+ * and what to be shown at each think
+ *
+ * @beta
+ */
+export interface WatchOptions extends AiCheckOptions {
+    /**
+     * Shown, at the end of each of its thinks, the game as an observer sees it (everything, no fog) and the brain: for a
+     * look at what it does (a test that writes frames, a page that draws them). An observer's seat is made only when given
+     */
+    observe?: (snapshot: Snapshot, brain: Brain) => void;
+    /** Each command as it sends it */
+    sent?: (command: PlayerCommand, brain: Brain) => void;
+}
+/**
+ * Follows the brain at a player from now on: after every think, the invariants of `ai/checks.ts` (a unit in one squad
+ * and one hold, gold spent once, finite numbers, commands about what it sees, no order sent again to a unit still at
+ * it, builders, tasks, holds and wants that end), with what it decided and sent. A broken rule is kept, not thrown,
+ * unless `onViolation` throws: `assert` at the end says them all
+ *
+ * @beta
+ */
+export declare function watchComputer(world: World, player: PlayerId, options?: WatchOptions): ComputerWatch;
+/**
+ * Whether a computer player played fair over a run (`fairPlay`): every command it sent named what its own snapshot
+ * had, and how many the game refused
+ *
+ * @beta
+ */
+export interface FairPlay {
+    /** Commands that named an entity it did not see, or a place off the map */
+    readonly unfair: readonly AiViolation[];
+    /** Commands the game refused while watched (a unit that could not do it, a place it could not build at) */
+    readonly refused: number;
+    /** Throws where it sent any command about what it did not see */
+    assert(): void;
+    stop(): void;
+}
+/**
+ * Follows the brain at a player from now on for fair play: that it never sends a command about an entity its snapshot
+ * did not have (a fog leak: its seat's session would drop the command, so a game shows nothing; this says it), and
+ * counts what the game refused
+ *
+ * @beta
+ */
+export declare function fairPlay(world: World, player: PlayerId): FairPlay;
+/**
+ * One thing a computer player decided, with whose: a line of a replay's side file (`recordDecisions`)
+ *
+ * @beta
+ */
+export interface RecordedDecision extends AiDecision {
+    player: PlayerId;
+    /** The brain's id */
+    brain: string;
+}
+/**
+ * The decisions of every computer of a world, as they are made (`recordDecisions`): plain data, for a side file beside a
+ * replay of commands, read back by whoever wonders why the computer did what the replay shows
+ *
+ * @beta
+ */
+export interface DecisionRecorder {
+    /** Every decision so far, in the order made */
+    readonly decisions: readonly RecordedDecision[];
+    stop(): void;
+}
+/**
+ * Keeps the decisions of every brain seated at a world, from now on, those seated later included (looked for at each
+ * tick, by a system of its own that keeps nothing in a save)
+ *
+ * @beta
+ */
+export declare function recordDecisions(world: World): DecisionRecorder;
+/**
+ * Where a game saved and loaded first decided otherwise than the game it was saved from (`checkComputerSave`): the
+ * decision each made at that place in their logs. `null` where they decided alike to the end
+ *
+ * @beta
+ */
+export interface DecisionsApart {
+    /** How many decisions since the save they shared before this one */
+    index: number;
+    /** The game that went on from the save */
+    saved?: RecordedDecision;
+    /** The game loaded from it */
+    loaded?: RecordedDecision;
+}
+/**
+ * The seventh invariant of a computer player: a game saved at tick `from` and loaded makes the same decisions from then
+ * on as the game it was saved from, under the same commands. Makes the world with `make` (its computers seated, as a
+ * game seats them), runs it to `from`, saves it as a file would keep it and loads that with `game`, then runs both to
+ * `ticks` and compares what every computer decided. What lost rng, tasks or memory in a restore shows as
+ *
+ *     expect(await checkComputerSave(() => duel(), { from: 600, ticks: 2400, game: melee })).toBeNull()
+ *
+ * @beta
+ */
+export declare function checkComputerSave(make: () => World | Promise<World>, options: {
+    from: number;
+    ticks: number;
+    game: GameModule;
+}): Promise<DecisionsApart | null>;

package/dist/areas.d.ts

@@ -0,0 +1,149 @@
+import type { Entity } from './entity';
+import type { Vec2 } from './math';
+import type { System } from './registry';
+import type { World } from './world';
+import type { MapRegion } from './map';
+/**
+ * Where an area is on the map: a circle, a rectangle by its middle and size, or a polygon by its corners round a middle
+ * of its own (`points`, each from `x` and `z`, three or more, in order round it: moving the middle moves it whole)
+ *
+ * @beta
+ */
+export type AreaShape = {
+    kind: 'circle';
+    x: number;
+    z: number;
+    radius: number;
+} | {
+    kind: 'rect';
+    x: number;
+    z: number;
+    width: number;
+    depth: number;
+} | {
+    kind: 'polygon';
+    x: number;
+    z: number;
+    points: Vec2[];
+};
+/**
+ * The box round a shape: its least and greatest x and z on the map
+ *
+ * @beta
+ */
+export declare function shapeBounds(shape: AreaShape): {
+    x0: number;
+    z0: number;
+    x1: number;
+    z1: number;
+};
+/**
+ * How much ground a shape covers, in cells
+ *
+ * @beta
+ */
+export declare function shapeArea(shape: AreaShape): number;
+/**
+ * A shape as a circle or a rectangle: a polygon as the rectangle round it. For what draws only those (mist, clouds and
+ * weather in a region of the map)
+ *
+ * @beta
+ */
+export declare function shapeAsBox(shape: AreaShape): Exclude<AreaShape, {
+    kind: 'polygon';
+}>;
+/**
+ * A shape moved to stand at a point and sized `scale` times: a prefab's area where the prefab is put
+ *
+ * @beta
+ */
+export declare function shapeAt(shape: AreaShape, at: Vec2, scale?: number): AreaShape;
+/**
+ * Where something of the map is, by a shape of its own or by a region of the map, named: mist, clouds and weather in
+ * places (`MapMistArea.shape`). By the region, it is where the region is, moved with it, and is the rules' too
+ *
+ * @beta
+ */
+export type AreaRef = AreaShape | {
+    region: string;
+};
+/**
+ * The shape an `AreaRef` stands for: its own, or the named region's among the map's. Nothing for a region that is
+ * not there
+ *
+ * @beta
+ */
+export declare function areaShapeOf(ref: AreaRef, regions: readonly MapRegion[]): AreaShape | undefined;
+/**
+ * A named part of the map that the rules watch: who walks into it and out of it (`enteredArea`, `leftArea` events),
+ * and who is in it now (`world.areas`). Units count, by where their middle is; buildings, scenery and units inside
+ * something do not. Given in `GameModule.areas`
+ *
+ * @beta
+ */
+export interface AreaDef {
+    /** Shared by every game, like other ids: give it a prefix of the game's (`'td.gate'`) */
+    id: string;
+    shape: AreaShape;
+}
+/**
+ * Typed help for writing an area
+ *
+ * @beta
+ */
+export declare const defineArea: (def: AreaDef) => AreaDef;
+/**
+ * Whether a point is in a shape
+ *
+ * @beta
+ */
+export declare function inShape(shape: AreaShape, point: Vec2): boolean;
+/**
+ * The radius of a circle round the whole shape from its middle (`x`, `z`): what the spatial index is asked for
+ *
+ * @beta
+ */
+export declare function shapeReach(shape: AreaShape): number;
+/** Who is in each area, by id: kept in the world, so that a save knows, and nobody walks in twice after loading */
+export declare const inside: import("./components").Component<Record<string, number[]>, Record<string, number[]>>;
+/** Areas added while the game runs (`areas.add`): kept in the world, so that a save has them */
+export declare const added: import("./components").Component<AreaDef[], AreaDef[]>;
+/**
+ * The areas of a world, and who is in them
+ *
+ * @beta
+ */
+export declare class Areas {
+    private readonly world;
+    private readonly byId;
+    /** Kept between ticks, not made anew */
+    private readonly found;
+    private readonly now;
+    constructor(world: World, defs: readonly AreaDef[]);
+    /** The areas of the game, then those added while it runs */
+    get all(): Iterable<AreaDef>;
+    get size(): number;
+    get(id: string): AreaDef;
+    /** Whether there is an area of that id */
+    has(id: string): boolean;
+    private find;
+    private added;
+    /**
+     * Adds an area while the game runs: a zone a spell leaves, a ring that closes in, a part of the map a quest opens.
+     * Who is in it is found at the end of the tick, and walks in then. One of the same id, added before, is replaced
+     */
+    add(def: AreaDef): void;
+    /** Takes away an area added while the game runs. Who was in it leaves it (`leftArea`). False when there was none */
+    remove(id: string): boolean;
+    /** Whether the entity was in the area when the areas were last looked at: the end of the last tick's movement */
+    contains(id: string, entity: Entity): boolean;
+    /** Who is in the area, as of the last look */
+    inside(id: string): Entity[];
+    private idsIn;
+    /** Looks who is in each area now, and tells who walked in and who walked out. What died in one is just gone */
+    update(): void;
+    /** Who is in one area now, against who was */
+    private look;
+}
+/** Watches the areas, after everyone has moved. Does nothing in a game without any */
+export declare const areaSystem: System;

package/dist/attacks.d.ts

@@ -0,0 +1,66 @@
+import type { AttackDef, AttackStats, Layer, Stats, UnitTypeDef } from '#engine/defs';
+import { type Entity } from '#engine/entity';
+import type { World } from '#engine/world';
+/**
+ * Whether an attack that is for these targets is for this one
+ *
+ * @beta
+ */
+export declare function reaches(targets: AttackDef['targets'], target: {
+    def: UnitTypeDef;
+}, layer?: Layer): boolean;
+/**
+ * How hard, how fast or how far an attack hits, from the attacker's stats: the stat the attack names
+ * (`AttackDef.stats`), or the unit's own (`attackDamage`, `attackSpeed`, `attackRange`). The unit's own for no attack
+ *
+ * @beta
+ */
+export declare function attackStat(stats: Readonly<Stats>, attack: AttackDef | undefined, which: keyof AttackStats): number;
+/**
+ * The first of an attacker's attacks that reaches the target where it is (its `targets`), by place, or -1 for none:
+ * the engine's `GameRules.combat.pickAttack`
+ *
+ * @beta
+ */
+export declare function defaultPickAttack(world: World, attacker: Entity, target: Entity): number;
+/**
+ * Whether a target is too near for one of an attacker's attacks (`AttackDef.minRange`), by place in its attacks: within
+ * its dead zone, edge to edge
+ *
+ * @beta
+ */
+export declare function tooNear(attacker: Entity, target: Entity, weapon: number): boolean;
+/**
+ * Which of an attacker's attacks it uses against a target, by place in `UnitTypeDef.attacks`, as the game's rules pick
+ * it (`GameRules.combat.pickAttack`): -1 for none, its attacks reach not where the target is
+ *
+ * @beta
+ */
+export declare function pickAttack(world: World, attacker: Entity, target: Entity): number;
+/**
+ * The farthest any attack of a type looks for enemies by itself (`AttackDef.acquisitionRange`): the engine's
+ * `GameRules.combat.acquisitionRange`. 0 for what does not attack
+ *
+ * @beta
+ */
+export declare function farthestAcquisition(def: UnitTypeDef): number;
+/**
+ * How far the farthest of a unit's attacks reaches, by its stats (its `attackRange`, or a stat an attack names): what
+ * it may hit anything from. 0 for what does not attack
+ *
+ * @beta
+ */
+export declare function farthestReach(def: UnitTypeDef, stats: Readonly<Stats>): number;
+/**
+ * How far an attacker's attack reaches a target: the range of the one it uses against it (`pickAttack`), the first's
+ * when none does
+ *
+ * @beta
+ */
+export declare function rangeAgainst(world: World, attacker: Entity, target: Entity): number;
+/**
+ * The first of a type's attacks that can be told to attack the ground (`AttackDef.ground`), by place, or -1 for none
+ *
+ * @beta
+ */
+export declare function groundAttack(def: UnitTypeDef): number;

package/dist/attributes.d.ts

@@ -0,0 +1,66 @@
+import type { StatChange } from './defs';
+import type { Entity } from './entity';
+import type { GamePack } from './packs/pack';
+import type { World } from './world';
+/**
+ * The attributes pack's id
+ *
+ * @beta
+ */
+export declare const ATTRIBUTES = "core.attributes";
+/**
+ * One of the three attributes, each a stat of its own id
+ *
+ * @beta
+ */
+export type Attribute = 'strength' | 'agility' | 'intelligence';
+/**
+ * The three attributes, in the order a hero's panel shows them
+ *
+ * @beta
+ */
+export declare const ATTRIBUTE_KEYS: readonly Attribute[];
+/**
+ * What a point of each attribute gives, as classic RTS games have it: strength 25 health and 0.05 health a second, agility 0.3
+ * armor and 2% attack speed, intelligence 15 mana and 0.05 mana a second
+ *
+ * @beta
+ */
+export declare const CLASSIC_ATTRIBUTES: Readonly<Record<Attribute, StatChange>>;
+/**
+ * What the attributes pack is made with (`withAttributes`)
+ *
+ * @beta
+ */
+export interface AttributesOptions {
+    /** What a point of each attribute gives: the classic ones (`CLASSIC_ATTRIBUTES`) for those left out */
+    perPoint?: Partial<Record<Attribute, StatChange>>;
+    /** What a point of a unit's primary attribute gives besides: 1 attack damage when left out */
+    primary?: StatChange;
+    /** A unit's primary attribute, in code: its type's `hero.primary` when left out, none for a unit that has none */
+    primaryOf?: (world: World, entity: Entity) => Attribute | undefined;
+}
+/**
+ * What a unit has of each attribute, everything counted (its type, its level, items, buffs, research): its stats'
+ * `strength`, `agility` and `intelligence`
+ *
+ * @beta
+ */
+export declare function attributesOf(world: World, entity: Entity): Record<Attribute, number>;
+/**
+ * A unit's primary attribute, as the attributes pack of its game says it (`AttributesOptions.primaryOf`, else its type's
+ * `hero.primary`); none in a game without the pack
+ *
+ * @beta
+ */
+export declare function primaryAttribute(world: World, entity: Entity): Attribute | undefined;
+/**
+ * Hero attributes, as in classic RTS games: strength, agility and intelligence are stats (`ATTRIBUTE_KEYS`), and every point
+ * of them adds to the others (`AttributesOptions.perPoint`, `CLASSIC_ATTRIBUTES` when left out), the primary one's
+ * to the attack too (`hero.primary`, `primaryOf`). What a unit has of them is what it has of any stat: its type's
+ * `stats`, its hero's `growth` by level, items' `bonus`, buffs, research and the `stats` hook, all of it added up
+ * before the points are turned into the rest. A game without it has no attributes
+ *
+ * @beta
+ */
+export declare function withAttributes(options?: AttributesOptions): GamePack;