@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/ai/checks.d.ts

@@ -0,0 +1,115 @@
+import type { PlayerId } from '#engine/entity';
+import { type PlayerCommand } from '#engine/session/protocol';
+import type { Brain, BrainWatcher } from './brain';
+/**
+ * The name of a rule every computer player keeps (`checkBrain`): see the table in `ai/checks.ts`
+ *
+ * @beta
+ */
+export type AiInvariant = 'squads' | 'purse' | 'finite' | 'commands' | 'churn' | 'ends';
+/**
+ * Every invariant, in the order they are checked
+ *
+ * @beta
+ */
+export declare const AI_INVARIANTS: readonly AiInvariant[];
+/**
+ * A rule a computer player broke, at a think: which, whose, when, and what exactly, in words
+ *
+ * @beta
+ */
+export interface AiViolation {
+    invariant: AiInvariant;
+    player: PlayerId;
+    /** The tick of the think's picture of the game */
+    tick: number;
+    message: string;
+}
+/**
+ * Seconds a thing may go on before the `ends` invariant says it is stuck (`AiCheckOptions.limits`)
+ *
+ * @beta
+ */
+export interface AiEndLimits {
+    /** A worker on its way to build, not yet begun: 120 when left out (the build plan gives up on a site after 60) */
+    builder?: number;
+    /** A squad's task in one phase (going, gathering, fighting): 300 when left out. A squad holding a place or going with a unit never times out */
+    task?: number;
+    /** Money held under one name, think after think: 600 when left out */
+    reservation?: number;
+    /**
+     * A want of the build plan that cannot be got to (a requirement out of reach), or one that does not stand finding no
+     * spot or builder: 600 when left out. A standing want waiting for room is no fault
+     */
+    want?: number;
+}
+/**
+ * How a brain is checked (`checkBrain`, `watchComputer`)
+ *
+ * @beta
+ */
+export interface AiCheckOptions {
+    /** The invariants to check: all of them when left out */
+    invariants?: readonly AiInvariant[];
+    /** How long a thing may go on before it counts as stuck (`ends`) */
+    limits?: AiEndLimits;
+    /** Told of each broken rule as it is found. Where none is given, `checkBrain` throws at the first */
+    onViolation?: (violation: AiViolation) => void;
+}
+/** Seconds within which an order sent again for the same thing is churn: what `AiStats.churn` counts by too */
+export declare const CHURN_WINDOW = 5;
+/**
+ * What an order to a unit is for, as a key: its kind, its target, its place to the cell. Two orders with the same key
+ * are the same order. None for a command that is not an order to units (a train, a ping, a game's own)
+ */
+export declare function orderKey(command: PlayerCommand): string | undefined;
+/**
+ * Checks a brain against the invariants after each of its thinks, through what it is watched by (`Brain.watch`): what
+ * `checkBrain` makes, and keeps the broken rules in `violations`
+ *
+ * @beta
+ */
+export declare class BrainChecks implements BrainWatcher {
+    readonly brain: Brain;
+    private readonly options;
+    /** Every rule found broken, in the order found */
+    readonly violations: AiViolation[];
+    private readonly invariants;
+    private readonly limits;
+    /** What it sent since its last think ended */
+    private commands;
+    /** The last order each unit was sent, with the tick of the think */
+    private readonly orders;
+    /** Since when each thing that has to end has been going on, by a key of what it is */
+    private readonly since;
+    /** What was said stuck already: once a time it is stuck, not every think after */
+    private readonly said;
+    constructor(brain: Brain, options?: AiCheckOptions);
+    sent(command: PlayerCommand): void;
+    thought(): void;
+    /** A unit in at most one squad and one hold: two would give it two orders a think */
+    private squads;
+    /** What the think spent and what its builders will pay never more than what it had: else the same gold went twice */
+    private purse;
+    /** Every number a decision is made of is a number: a `NaN` compares false with everything and picks silently */
+    private finite;
+    /** A command about what its picture of the game has: its own units by theirs, anyone else's as seen, places on the map */
+    private command;
+    /** No order sent again for the same thing to a unit still at it: a unit told the same every think stops and starts */
+    private churn;
+    /** Builders, tasks, holds of money and blocked wants each end in time */
+    private ends;
+}
+/**
+ * Checks a brain against the invariants after each of its thinks from now on: throws at the first broken rule, or tells
+ * `onViolation` of each. Returns the checks (their `violations`) and the way to stop: what `watchComputer` does for a
+ * seat, and every brain does by itself while `debugChecks.ai` is on
+ *
+ *     const checks = checkBrain(brain, { onViolation: (each) => found.push(each) })
+ *
+ * @beta
+ */
+export declare function checkBrain(brain: Brain, options?: AiCheckOptions): {
+    checks: BrainChecks;
+    stop: () => void;
+};

package/dist/ai/computer.d.ts

@@ -0,0 +1,166 @@
+import type { PlayerId } from '#engine/entity';
+import type { System } from '#engine/registry';
+import { LocalSession } from '#engine/session/local';
+import type { World } from '#engine/world';
+import type { AiOptions } from './options';
+import { Brain, type BrainContext, type BrainDef } from './brain';
+import type { ThinkBudgetOptions } from './budget';
+import { type TeamBoard } from './team';
+import { type AiProfile } from './profiles';
+import { type AiSettings } from './settings';
+/**
+ * A computer player: whatever plays a seat of a world from what it sees, through commands as a player does. The
+ * engine's own is a `Brain` of modules (`defineBrain`), the melee player among them; a game gives its own in code
+ * (`defineComputer`, listed in `GameModule.brains`). `think` is asked about once a second (`createComputerSystem`); `save` and `restore` keep what
+ * it remembers through a save
+ *
+ * @beta
+ */
+export interface ComputerPlayer {
+    think(): void;
+    save?(): unknown;
+    restore?(memory: unknown): void;
+    /** What it is thinking, as plain data: what the debug tools show of the player it plays (its goal, its scores) */
+    inspect?(): unknown;
+    /** Whether a think is under way across ticks (a brain's budget): it is asked to think on at the next tick */
+    readonly busy?: boolean;
+    /** Whether it sits still (`world.computers.pause`). A player without the field cannot be paused */
+    paused?: boolean;
+    /** Takes in a word from the game (`world.computers.tell`), with the tick it is told at */
+    tell?(word: string, data: unknown, tick: number): void;
+    /** Lets go of what it holds outside its seat, once unseated */
+    dispose?(): void;
+}
+/**
+ * Milliseconds a computer player's thinks took: for the report and the stats panel, never for a decision
+ *
+ * @beta
+ */
+export interface ComputerTiming {
+    /** The last think, all its ticks where it was sliced */
+    last: number;
+    /** Averaged over its thinks */
+    average: number;
+    /** The longest think there was */
+    longest: number;
+    /** Ticks the last think took: 1, unless the brain's budget sliced it over ticks */
+    ticks?: number;
+    /** By module, averaged, while the world profiles (`Scheduler.profiling`): a brain's */
+    modules?: Record<string, number>;
+    /** By module, the most one pass of it took, always: a brain's. What `ThinkBudgetOptions.warnAfterMs` is measured against */
+    longestByModule?: Record<string, number>;
+    /** Of a think, what taking the picture of the game took (the seat's `snapshot()`), averaged, while the world profiles: a brain's */
+    snapshot?: number;
+    /** Of a think, what reading the picture into the view took (`AiView`), averaged, while the world profiles: a brain's */
+    view?: number;
+    /** Of a think, what bringing the brain's knowledge up to date took, averaged, while the world profiles: a brain's */
+    knowledge?: number;
+}
+/**
+ * The system a computer player plays from: it is asked to think about once a second (`every`, in seconds), each seat
+ * at another tick of it, to spread the work; it is named for its seat (`ai-<player>`), which a save keeps what it
+ * remembers by
+ *
+ * @beta
+ */
+export interface ComputerSystem<C extends ComputerPlayer = ComputerPlayer> extends System {
+    readonly computer: C;
+    /** The player it plays */
+    readonly player: PlayerId;
+    /** The seat it plays through */
+    readonly session: LocalSession;
+    /** Milliseconds its thinks took: the last, an average, the longest, and by module while the world profiles */
+    timing(): ComputerTiming;
+    /** Lets go of its seat: the session's listeners, what the computer player holds. The world stays */
+    dispose(): void;
+}
+/**
+ * How a seat asks its computer player to think (`createComputerSystem`)
+ *
+ * @beta
+ */
+export interface ComputerSeatOptions {
+    /** Seconds between thinks: 1 when left out */
+    every?: number;
+    /**
+     * How much of a think one tick may do (`ThinkBudgetOptions`: modules a tick, units looked at a tick as the modules say,
+     * the milliseconds a module is warned over), or the modules a tick as a number: a think with more goes on at the next
+     * tick, over the same picture. Everything in one tick when left out
+     */
+    budget?: number | ThinkBudgetOptions;
+    /** The tick in each round the seat thinks at: seven times the player's id when left out, so that seats think at different moments */
+    offset?: number;
+    /**
+     * What the seat's picture of the game carries: `lean`, what a computer reads (the entities, the players, the items, the
+     * deaths, damage, pings, chat and the game's own events) and none of what a screen needs (projectiles, missiles,
+     * corpses, reveals, the effects and the rest of the events), which is cheaper to take and to hear; `full`, everything a
+     * player's seat gets. `full` when left out here; a brain's seat is `lean` unless its definition says otherwise
+     * (`BrainDef.snapshot`)
+     */
+    snapshot?: 'lean' | 'full';
+    /**
+     * Whether the seat sees everything, as an observer does (`LocalSession`'s `observer`): the one way a computer sees
+     * through the fog, for a profile with `vision: 'all'` (insane). Its own seat's sight when left out
+     */
+    observer?: boolean;
+    /**
+     * How well the seat plays (`AiProfile`): its `handicap` (what its workers bring in, the health of what it has, the
+     * damage it deals, how long what it makes takes, made more or less through hooks that go with the seat) and `vision: 'all'` (it sees everything, as `observer`). A brain's seat and a game's
+     * own computer (`defineComputer`) are both given the profile of their difficulty
+     */
+    profile?: AiProfile;
+    /** Called as the seat is taken away (`dispose`): to undo what seating did outside the computer (a hook added) */
+    onDispose?: () => void;
+}
+/**
+ * Seats a computer player at a world: made of a session of its own (it sees what that player sees, and plays through
+ * commands, so it cannot cheat), asked to think about once a second. `make` is handed the session and what a brain
+ * takes besides (`BrainContext`: a seed of its own, the budget, whether the world profiles). Add the result to the
+ * world (`world.addSystem`), or seat through `world.computers.seat`, which remembers it for a save
+ *
+ * @beta
+ */
+export declare function createComputerSystem<C extends ComputerPlayer>(world: World, playerId: PlayerId, make: (session: LocalSession, context: BrainContext) => C, options?: ComputerSeatOptions): ComputerSystem<C>;
+/**
+ * The boards of the teams' computers (`TeamBoard`, AI plan C5), by team: in the world, so that a save keeps the
+ * requests and the plan of an attack together, and never replicated, so that no player gets it in a snapshot
+ *
+ * @beta
+ */
+export declare const aiTeams: import("#engine/components").Component<Record<string, TeamBoard>, Record<string, TeamBoard>>;
+/**
+ * Seats a brain at a world as one of its players, asked to think as its definition or the options say (`every`), with
+ * the budget the options give. Add the result to the world, or go through `world.computers.seat`
+ *
+ * @beta
+ */
+export declare function createBrainSystem(world: World, playerId: PlayerId, brain: BrainDef, options?: AiOptions): ComputerSystem<Brain>;
+/**
+ * A computer player of the game's own that is not made of modules (a `ComputerPlayer`: anything that thinks), as a brain
+ * the game lists (`GameModule.brains`) and seats as it does any (`world.computers.seat(player, { brain })`): found again
+ * by its id when a save is loaded. `make` is handed the seat's session, its context and what it was seated with, the
+ * map's under the seat's; it thinks as often as those say (`every`, 1 second when left out)
+ *
+ * @beta
+ */
+export declare function defineComputer<C extends ComputerPlayer>(id: string, make: (session: LocalSession, context: BrainContext, options: AiOptions) => C): BrainDef;
+/**
+ * What a map says of how its computer player plays (`MapPlayer.data.ai`, decision 6 of the AI plan), for a player the map
+ * gives the computer (`controller: 'computer'`): a difficulty and a personality by name, and settings (`AiSettings`:
+ * its flags, its build order as `plans.order`, its waves as `waves.waves`, any area's numbers). Plain data, as the map's
+ * file holds it
+ *
+ * @beta
+ */
+export interface MapAi {
+    /** The brain the player is seated with, by id (`GameModule.brains`): over its race's (`GameAi.races`), under the seat's */
+    brain?: string;
+    difficulty?: string;
+    personality?: string;
+    settings?: AiSettings;
+    /**
+     * Settings by the race the player plays (`GameModule.races`), over `settings`: for a player whose race the lobby
+     * chooses or draws (`random`), a build order or waves for each
+     */
+    races?: Record<string, AiSettings>;
+}

package/dist/ai/defence.d.ts

@@ -0,0 +1,108 @@
+import { type Vec2 } from '#engine/math';
+import { type AiModuleDef } from './module';
+import type { Base, UnitSet } from './view';
+/**
+ * How a brain defends its bases (`BrainDef.defence`, the seat's `AiOptions.defence` over it, the `defence()` module's
+ * own under both). Data, kept in a save
+ *
+ * @beta
+ */
+export interface DefenceOptions {
+    /** How near one of its buildings a rival's unit is an intruder: the seat's `defendRadius`, else 16 */
+    radius?: number;
+    /**
+     * The odds of the fight (`Strength.odds`) the defenders sent against a raid are to have: two in three when left out
+     * (about four tenths stronger than the raid)
+     */
+    odds?: number;
+    /**
+     * Whether a raid more than what is at home can meet brings the army home (the goal is urgent: it takes squads out,
+     * whole, once it scores past what they are on): yes when left out
+     */
+    recall?: boolean;
+    /** Towers a base wants once raided `towerAfter` times: 1 when left out. 0 for none */
+    towers?: number;
+    /** Raids at one base before it wants towers: 2 when left out */
+    towerAfter?: number;
+    /** The tower to build, by type id: the cheapest of the `tower` role its workers build when left out */
+    tower?: string;
+    /** Seconds a base stands clear before a raid on it is over: 15 when left out */
+    quiet?: number;
+}
+/**
+ * What the defence remembers between thinks, as a save keeps it: each base's raids
+ *
+ * @beta
+ */
+export interface DefenceMemory {
+    v: 1;
+    /** By base (the id of what it is around): where, how many raids, the one on now (since when), when last seen, the strongest */
+    raids: Record<string, {
+        at: Vec2;
+        count: number;
+        since?: number;
+        last: number;
+        most: number;
+    }>;
+}
+/**
+ * The intruders at one base, as the defence sees them this think (`ai.defence.raids()`)
+ *
+ * @beta
+ */
+export interface Raid {
+    /** The base raided */
+    base: Base;
+    /** What the defence remembers it by: the id of what the base is around */
+    key: string;
+    /** The rivals' units there */
+    intruders: UnitSet;
+    /** Their strength together (`Strength.of`) */
+    strength: number;
+}
+/**
+ * The defence as the report shows it (`AiReport.defence`): the raids on now with what answers each, every base's raids
+ * so far, the towers it wants
+ *
+ * @beta
+ */
+export interface DefenceReport {
+    raids: {
+        at: [number, number];
+        intruders: number[];
+        strength: number;
+        squad?: string;
+        defenders: number;
+        since: number;
+        count: number;
+    }[];
+    bases: {
+        at: [number, number];
+        raids: number;
+        last: number;
+    }[];
+    towers: {
+        at: [number, number];
+        want: string;
+        status: string;
+    }[];
+}
+/**
+ * The id of the defence's goal: what a game weighs it by (`AiOptions.weigh`)
+ *
+ * @beta
+ */
+export declare const DEFEND = "defend";
+/**
+ * The defence module: the raids on the bases counted each think, the towers a raided base wants (`ai.defence.think`),
+ * and the `defend` goal put on the brain's picker, which answers each raid with a squad of its own. With how it defends
+ * where the brain's definition and the seat's options say nothing (`DefenceOptions`)
+ *
+ * @beta
+ */
+export declare const defence: (options?: DefenceOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        defence?: DefenceMemory;
+    }
+}

package/dist/ai/define.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A brain defined (`defineBrain`): checked, given its `with` for variants, and its seat (`BrainDef.seat`), which is the
+ * kit's (`createBrainSystem`). Apart from the brain itself (`brain.ts`), which the seat is made of
+ */
+import type { BrainDef, BrainExtension } from './brain';
+/**
+ * A brain as `defineBrain` gives it: with its `with`, for variants of it
+ *
+ * @beta
+ */
+export interface DefinedBrain extends BrainDef {
+    with(more: BrainExtension): DefinedBrain;
+}
+/**
+ * Defines a brain: what a computer player is made of, to seat at a world (`world.computers.seat(player, { ...options, brain })`,
+ * `world.computers.seat`) and to list in `GameModule.brains`, for a save to find it by its id. Modules that keep state
+ * are given as functions of the brain, as systems are of the world
+ *
+ * @beta
+ */
+export declare function defineBrain(def: BrainDef): DefinedBrain;

package/dist/ai/economy.d.ts

@@ -0,0 +1,129 @@
+import { type ResourceKind } from '#engine/defs';
+import { type Vec2 } from '#engine/math';
+import type { EntityState } from '#engine/session/protocol';
+import { type Brain } from './brain';
+import { type AiModuleDef } from './module';
+import { type AiCondition } from './rules';
+import type { Base } from './view';
+/**
+ * How many workers a base wants on each resource (`EconomyOptions.workersPer`): as numbers by resource id, or a
+ * function of the base (`index` 0 is home)
+ *
+ * @beta
+ */
+export type WorkersPer = Partial<Record<ResourceKind, number>> | ((ai: Brain, base: Base, index: number) => Partial<Record<ResourceKind, number>>);
+/**
+ * How a brain runs its economy (`BrainDef.economy`, the seat's `AiOptions.economy` over it, the `economy()` module's
+ * own under both). Every field has a data form a save keeps; the function forms are the brain's to give again
+ *
+ * @beta
+ */
+export interface EconomyOptions {
+    /** Workers on the game's money at each base, where `workersPer` says nothing of it: 8 when left out */
+    workers?: number;
+    /** Workers on the other resource, at home only, where `workersPer` says nothing of it: 3 when left out */
+    lumberjacks?: number;
+    /**
+     * Workers on each resource at each base (`WorkersPer`): `{ gold: 5, lumber: 3 }` at every base, or a function of the
+     * base for one that differs (home, an expansion). What it leaves out is `workers` and `lumberjacks`
+     */
+    workersPer?: WorkersPer;
+    /** Whether a base wants no more workers on a deposit than it serves (see the file's comment): yes when left out */
+    saturate?: boolean;
+    /** Whether its halls train workers up to what the bases want: yes when left out */
+    trainWorkers?: boolean;
+    /**
+     * Workers trained past what the bases want, to build with: a worker sent to build is off the mine meanwhile, and a
+     * mine with only as many as it serves would gather less. 1 when left out
+     */
+    builders?: number;
+    /** Halls to have past the first, each by a mine nobody has a hall at: the seat's `expansions`, else none */
+    expansions?: number;
+    /**
+     * When it may expand: a condition (`AiCondition`, as data or a function). Four minutes in and with a building that
+     * trains soldiers, when left out
+     */
+    expandWhen?: AiCondition;
+    /** Whether workers a raid is on walk to a base no enemy is at, and back once theirs is clear: yes when left out */
+    workersFlee?: boolean;
+}
+/**
+ * What the economy remembers between thinks, as a save keeps it: the workers that fled a raid
+ *
+ * @beta
+ */
+export interface EconomyMemory {
+    v: 1;
+    /** Each worker that fled, by id: the base it fled (its middle), where to, since when, and since when its base stood clear */
+    fled: Record<string, {
+        from: Vec2;
+        to: Vec2;
+        since: number;
+        clear?: number;
+    }>;
+    /**
+     * Workers more on the other resource at home, while it runs short with the money piling up (AI2): one more each
+     * `BLOCKED` seconds it stays so, at most `MORE_AT_MOST`, one fewer each twice that once it is not. Since when it has
+     * been short (`since`) or not (`easy`), and who was sent to it lately (`moved`)
+     */
+    material?: {
+        more: number;
+        since?: number;
+        easy?: number;
+        moved?: Record<string, number>;
+    };
+}
+/**
+ * One base as the economy sees it (`ai.economy.bases()`, the report): its deposits, what they serve, the workers it
+ * wants and has on each resource
+ *
+ * @beta
+ */
+export interface EconomyBase {
+    /** The view's base */
+    base: Base;
+    /** Its deposits it gathers from, by resource: those of the money with a hall by them (or something of its own on them), the rest near it */
+    deposits: Partial<Record<ResourceKind, EntityState[]>>;
+    /** How many workers its deposits of each resource serve at once */
+    serves: Partial<Record<ResourceKind, number>>;
+    /** How many it wants on each resource: what it is to have, no more than what is served where it saturates */
+    wants: Partial<Record<ResourceKind, number>>;
+    /** The workers at work on each resource at it, by id */
+    working: Partial<Record<ResourceKind, number[]>>;
+}
+/**
+ * The economy as the report shows it (`AiReport.economy.bases`, `fled`): each base with what it wants and has, the
+ * workers that fled, how many it trains, what the next expansion waits for
+ *
+ * @beta
+ */
+export interface EconomyReport {
+    bases: {
+        at: [number, number];
+        hall: number;
+        workers: Record<ResourceKind, [working: number, wants: number, serves: number]>;
+    }[];
+    fled: {
+        unit: number;
+        from: [number, number];
+        since: number;
+    }[];
+    /** Workers it has, those queued counted, and what its bases want together */
+    workers: [have: number, want: number];
+    /** Where the next hall goes, and what it waits for: the build plan's status of the want */
+    expansion?: string;
+}
+/**
+ * The economy module: the workers base by base each think (`ai.economy.think`): builders to sites, workers off a raid and
+ * back, the idle where they are missing, the spare moved, the other resource's gatherers, what the money is gathered at,
+ * workers trained, another hall wanted. With how it runs where the brain's definition and the seat's options say nothing
+ * (`EconomyOptions`)
+ *
+ * @beta
+ */
+export declare const economy: (options?: EconomyOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        economy?: EconomyMemory;
+    }
+}

package/dist/ai/geometry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The small words of the AI kit (design review B13): a point as plain data, as a pair for a report, as a decision
+ * writes it, and the counts and articles of a decision's line. One copy, for every module and area
+ */
+import type { Vec2 } from '#engine/math';
+/**
+ * A point as plain data, for a save or a task's data: `{ x, z }` and nothing else
+ *
+ * @beta
+ */
+export declare const point: (at: Vec2) => Vec2;
+/**
+ * A point as a report has it: `[x, z]`, rounded
+ *
+ * @beta
+ */
+export declare const pair: (at: Vec2) => [number, number];
+/**
+ * A point as a decision writes it: `(40, 60)`
+ *
+ * @beta
+ */
+export declare const where: (at: Vec2) => string;
+/**
+ * Units counted as a decision writes them: `1 unit`, `3 units`
+ *
+ * @beta
+ */
+export declare const plural: (n: number) => string;
+/**
+ * A thing as a decision writes it, with its article: `a farm`, `an altar`
+ *
+ * @beta
+ */
+export declare const an: (thing: string) => string;