@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/brain.d.ts

@@ -0,0 +1,528 @@
+import type { PlayerId } from '#engine/entity';
+import { type Logger } from '#engine/log';
+import { type AiModule, type AiModuleDef, type ModuleKey } from './module';
+import type { AiArea, AreaKey, AreaMemories } from './area';
+import type { Registry } from '#engine/registry';
+import { Rng } from '#engine/rng';
+import type { GameSession, PlayerCommand, PlayerState, SessionEvent, Snapshot } from '#engine/session/protocol';
+import type { AiOptions } from './options';
+import type { BrainSeat } from '#engine/computers';
+import { ThinkBudget, type ThinkBudgetOptions } from './budget';
+import type { ComputerPlayer } from './computer';
+import { type GoalDef, Goals, type PickingOptions } from './goals';
+import { Knowledge, type KnowledgeOptions } from './knowledge';
+import { Plans } from './plans/plans';
+import { Purse } from './plans/purse';
+import { type AiProfile } from './profiles';
+import { type AiDecision, type AiReport, type AiStats, Decisions } from './report';
+import type { AiConditionTest, AiRule } from './rules';
+import { type AiSettings } from './settings';
+import { Squads } from './squads';
+import type { TeamBoard } from './team';
+import type { Strength, StrengthFormula } from './strength';
+import type { ThreatMap } from './threat';
+import { AiView } from './view';
+/**
+ * What a computer player is made of, defined once (`defineBrain`) and seated as often as wanted
+ * (`world.computers.seat`). A game lists the brains it seats in `GameModule.brains`, so that a save that remembers a
+ * seat by its brain's id finds it again when loaded
+ *
+ * @beta
+ */
+export interface BrainDef {
+    /** Unique among the brains of a game, prefixed as components are (the engine's `core.melee`, a game's `mygame.raiders`): what a save remembers a seat by */
+    id: string;
+    /** The parts of a think, in the order they run where `before` and `after` say nothing */
+    modules: AiModuleDef[];
+    /**
+     * Modules of the list left out, by id (`meleeBrain.with({ without: ['scouting', 'melee.heroes'] })`): a variant of a
+     * brain with a part fewer. A module whose id is not known before it is made (a plain function, not `defineModule`)
+     * cannot be left out by name
+     */
+    without?: string[];
+    /**
+     * Rules of its own (`when(…).do(…)`, B2), checked each think by its `rules()` module: the melee brain's reads them
+     * (`meleeBrain.with({ rules: [...] })`); a brain of one's own gives them to its `rules()` module itself. Code,
+     * registered again with the brain
+     */
+    rules?: AiRule[];
+    /**
+     * Seconds between thinks, where the seat's options say none (`AiOptions.every`): 1 when left out. A function of the
+     * seat's options, for a brain that thinks faster on a harder difficulty
+     */
+    every?: number | ((options: AiOptions) => number);
+    /**
+     * What its picture of the game carries (`ComputerSeatOptions.snapshot`): `lean` when left out, what the kit reads (the
+     * entities, the players, the items, the deaths, damage, healing, pings, chat and the game's own events) and none of
+     * what a screen needs, which is cheaper. `full` for a brain of a game's own that reads the rest (projectiles, corpses,
+     * reveals, the other events)
+     */
+    snapshot?: 'lean' | 'full';
+    /**
+     * How it is seated at a player (`world.computers.seat`): what `defineBrain` gives it, the seat of the engine's kit
+     * (`createBrainSystem`, with what the map says of the player under the options). The engine's core seats a brain
+     * through it, and loads nothing of the kit for it
+     */
+    seat?: BrainSeat;
+    /**
+     * How it remembers what it saw (`Brain.knowledge`): how long, how much, what counts as the enemy's army. `false` for
+     * a brain that remembers nothing between thinks and would rather not pay for it (a tower defense's waves)
+     */
+    knowledge?: KnowledgeOptions | false;
+    /**
+     * How strong a unit is, in place of the kit's formula (`defaultStrength`): what `odds`, the threat map and
+     * `UnitSet.strength()` are made of. The seat's `AiOptions.strength` goes over it; this one is code the game registers
+     * again, so it is there after a load
+     */
+    strength?: StrengthFormula;
+    /** Conditions of its own, by id, for the data form (`{ is: id, args }`): over the game's of the same id (`GameAi.conditions`) */
+    conditions?: Record<string, AiConditionTest>;
+    /**
+     * What it could do, scored each think and run with what each claims (`defineGoal`, `ai.goals`): picked by the
+     * `goals()` module in its place among the modules, or by a module of the brain's own. Code, registered again with
+     * the brain: there after a load, where a goal in the seat's options is not
+     */
+    goals?: GoalDef[];
+    /** How it picks among its goals where a goal does not say for itself: the least score, the margin, the commitment */
+    picking?: PickingOptions;
+    /**
+     * Its own settings (`AiSettings`, keyed by area: how it plans, how its squads go and the tasks they may be on, how it
+     * fights, runs its economy, defends, scouts, plays with its team, its waves): the bottom layer, under the game's
+     * defaults, the difficulty, the personality, the map's and the seat's (`resolveProfile`); what its modules were made
+     * with under all of them. Code, registered again with the brain
+     */
+    settings?: AiSettings;
+    /**
+     * This brain and more: goals, modules, rules and `without` added to its own, its settings layered over its own,
+     * anything else in place of its own (`meleeBrain.with({ goals: [raid] })`, `meleeBrain.with({ id: 'mygame.camp', rules, without: ['scouting'] })`).
+     * Given by `defineBrain`
+     */
+    with?(more: BrainExtension): BrainDef;
+}
+/**
+ * What `BrainDef.with` adds to a brain: goals, modules, rules and modules left out beside its own, settings over its
+ * own, the rest in place of its own
+ *
+ * @beta
+ */
+export type BrainExtension = Partial<Omit<BrainDef, 'with'>>;
+/**
+ * A word the game told a computer player (`world.computers.tell`), waiting for a module to take it
+ *
+ * @beta
+ */
+export interface Told {
+    /** The word: what the game and the brain agreed on (`'raid'`) */
+    word: string;
+    /** What came with it: plain data */
+    data?: unknown;
+    /** The tick it was told at */
+    tick: number;
+}
+/**
+ * What a brain remembers between thinks, as a save keeps it: its own numbers, each module's memory with its version,
+ * the words it was told and not yet taken
+ *
+ * @beta
+ */
+export interface BrainMemory {
+    /** The version of this shape */
+    v: 2;
+    /** Where the brain's own numbers are in their sequence (`Rng.save`) */
+    rng: number;
+    /** How many times it has thought: what `AiModule.everyThinks` counts in */
+    thinks: number;
+    /** Whether it sits still (`world.computers.pause`) */
+    paused?: boolean;
+    /** The words it was told and no module has taken yet */
+    told: Told[];
+    /** What each module remembers, under its id, with the version it was saved as */
+    modules: Record<string, {
+        v: number;
+        data: unknown;
+    }>;
+    /**
+     * What each of its areas remembers, by the area's id (`AiArea`): its knowledge, goals, plans and squads, its economy,
+     * scouting and the rest of the kit's, a game's own. Left out by an area with nothing to remember
+     */
+    areas?: AreaMemories;
+    /** What it decided last (`Brain.decisions`): the last fifty lines, for whoever reads a save */
+    decisions?: AiDecision[];
+    /**
+     * The orders it sent lately (`Brain.sentTo`), by unit: what keeps it from telling a unit again what it is doing, in a
+     * game loaded from the save too. Left out while there are none
+     */
+    orders?: {
+        unit: number;
+        key: string;
+        tick: number;
+    }[];
+    /**
+     * What its seat heard since it last thought (`GameSession.pendingEvents`): the damage, deaths and pings its next think
+     * reads, which a game loaded from the save would not have heard otherwise
+     */
+    heard?: SessionEvent[];
+    /**
+     * A think under way across ticks as the game was saved (`BrainContext.budget`): the rest of this memory is the brain
+     * as that think began, and this is how far it had got, over what picture: each pass run so far, as the module (its
+     * index), the units the tick had looked at before it (`ThinkBudget.units`) and how many words it had been told by then
+     * (`told`). A game loaded from the save runs the
+     * same passes again under the same budget over the same picture, sending nothing (their commands are in the game
+     * already), and goes on from there as the saved game did. `slice` is the form before passes: so many modules run once each
+     */
+    thinking?: {
+        snapshot: Snapshot;
+        passes?: [module: number, units: number, heard: number][];
+        slice?: number;
+    };
+}
+/**
+ * What follows a brain's play from outside it (`Brain.watch`): the commands it sends, its thinks as each ends, what it
+ * decides. For tests and tools (`watchComputer`, `recordDecisions`, the invariants of `ai/checks.ts`): a watcher reads,
+ * it never changes what the brain does
+ *
+ * @beta
+ */
+export interface BrainWatcher {
+    /** A command it sent, as it goes (`Brain.send`): not one held back past its profile's cap */
+    sent?(command: PlayerCommand, brain: Brain): void;
+    /** A think ended, all its ticks where it was sliced: the picture it read is still `brain.view` */
+    thought?(brain: Brain): void;
+    /** It wrote a decision down (`Brain.decide`) */
+    decided?(decision: AiDecision, brain: Brain): void;
+}
+/**
+ * What a seat hands a brain as it is made, besides its session and its options (`createComputerSystem`'s `make`)
+ *
+ * @beta
+ */
+export interface BrainContext {
+    /** What the brain's own numbers start from: the world's seed and the player, as the seat works it out */
+    seed?: number;
+    /**
+     * How much of a think one tick may do (`ThinkBudgetOptions`: modules a tick, units looked at a tick, 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 of the game, so that no tick does all of it. Everything in one tick when left out
+     */
+    budget?: number | ThinkBudgetOptions;
+    /** Whether to time each module this think: on while the world's scheduler profiles. Timing never decides anything */
+    profiling?: () => boolean;
+    /**
+     * The board of its team (`TeamBoard`), shared by the computers of one team and kept by the world (`core.ai.teams`):
+     * read anew each time, for a load replaces it. A brain with none plays alone
+     */
+    team?: () => TeamBoard;
+    /**
+     * Whether every think is checked against the invariants (`checkBrain`): its world's (`world.checks.ai`), as its seat
+     * says. The process's (`debugChecks.ai`) for a brain made by hand
+     */
+    checks?: boolean;
+}
+/**
+ * A computer player made of modules (`defineBrain`), seated at a world (`world.computers.seat`). What
+ * a module is handed as it thinks (`ai`): the picture of the game (`snapshot`), the seat it plays through (`session`),
+ * its options, its numbers (`rng`), its log, and `send` for its commands. A brain is a `ComputerPlayer`: `think`, and
+ * `save` and `restore` for what it remembers
+ *
+ * @beta
+ */
+export declare class Brain implements ComputerPlayer {
+    /** What it was made from */
+    readonly def: BrainDef;
+    /** The seat it plays through: the snapshots it sees, the commands it sends */
+    readonly session: GameSession;
+    /** What it was seated with: a brain's own options read theirs from it */
+    readonly options: AiOptions;
+    /** Its modules, in the order they run */
+    readonly modules: readonly AiModule[];
+    /**
+     * Its own numbers, for whatever it leaves to chance (which base to scout first): seeded from the world's and the
+     * player's, kept in its memory, so that the same game plays the same way. Never `Math.random`
+     */
+    readonly rng: Rng;
+    /** Where it says what it does: the world's log, with the player it plays and its brain on each line */
+    readonly log: Logger;
+    /** Whether it sits still (`world.computers.pause`). Kept in a save */
+    paused: boolean;
+    /**
+     * What it sees, as of its last think: the snapshot of its seat, plain data, and the only input a brain has. Taken once
+     * a think: every module of the think reads the same picture
+     */
+    snapshot: Snapshot;
+    /**
+     * Its reading of the picture (`AiView`): the snapshot indexed once a think and asked as sets (`view.mine.idle()`,
+     * `view.enemies.near(home, 20)`), with what unit types are for (`view.roles`) and the map's facts. What a module
+     * reads the game through
+     */
+    view: AiView;
+    /**
+     * What it remembers of the enemy, the map and itself, with when (`Knowledge`): their bases and army as last seen,
+     * when each place was last looked at, its own losses and income. Brought up to date as each think begins, after the
+     * view; kept in a save
+     */
+    readonly knowledge: Knowledge;
+    /**
+     * What it could do (`Goals`): its goals scored each think from their considerations, the best given what they
+     * claim of its units and money, each run while it holds its claim. Its definition's goals and the seat's; a module
+     * adds its own (`ai.goals.add`). Picked by the `goals()` module, or by one of the brain's own in its place
+     */
+    readonly goals: Goals;
+    /**
+     * What it has to spend this think (`Purse`): its resources less what builders on their way will pay and what is
+     * held (a goal's money claim, a want saving up), rebuilt from the picture as each think begins. The one ledger:
+     * everything that spends, spends through it. `view.me.purse` is what is free
+     */
+    readonly purse: Purse;
+    /**
+     * Its plans (`Plans`): the build plan (`plans.build`: wants, the steps to each through the tech tree, spots,
+     * builders, saving up), the production plan (`plans.production`: the composition, counters, supply ahead,
+     * research), the game's build order over both, and `plans.want` to add to them. Run by the `build()` and
+     * `production()` modules, or by one of the brain's own
+     */
+    readonly plans: Plans;
+    /**
+     * Its squads (`Squads`): named groups of its units, each with a task (attack there, defend here, gather and go), made
+     * by its goals, rules and modules out of what they hold, and watched by the `squads()` module think after think:
+     * orders sent once and watched, regroups, retreats on the odds, reinforcements. Kept in a save
+     */
+    readonly squads: Squads;
+    /**
+     * How it plays (`AiProfile`), resolved (`resolveProfile`): how well it plays (the engine's, the game's, the
+     * difficulty's, the personality's, the seat's `every` and `budget`) and its settings, the brain's, the game's, the
+     * difficulty's, the personality's, the map's and the seat's each over the one before (a flag's function left out)
+     */
+    readonly profile: AiProfile;
+    /** Its settings' layers, lowest first (`ResolvedProfile.layers`): what `settings` is worked out from */
+    private readonly layers;
+    /** How many times it has thought */
+    thinks: number;
+    /**
+     * What it decided, the last fifty (`decide`): the goals picked and stopped, with the reason that weighed most, and
+     * what its modules write down. Kept in a save
+     */
+    readonly decisions: Decisions;
+    /** The board of its team, shared by its team's computers: what its seat was given (`BrainContext.team`), for its team play */
+    readonly teamBoard: BrainContext['team'];
+    /** Its areas, in the order they were made (`area`) */
+    private readonly areaList;
+    /** What a save remembered of areas not made yet, by id: taken by each as a module first asks for it */
+    private waiting;
+    /** What was worked out for this think, by key (`cache`): thrown away with the picture */
+    private readonly memo;
+    /**
+     * How strong things are (`Strength`): a unit, a group, one force against another (`odds`), what answers what
+     * (`counterFor`). The view's: the kit's formula unless the brain or the seat was given one
+     */
+    get strength(): Strength;
+    /**
+     * Where the strength is (`ThreatMap`): the friendly and the enemy strength that reaches each cell of a coarse grid
+     * over the map, by layer. Made from the think's picture when first asked; `threat.at(undefined)` is all zeros
+     */
+    get threat(): ThreatMap;
+    /** Commands it sent this think */
+    sent: number;
+    /** Commands it would have sent this think past what its profile lets a think send (`commandsPerThink`): not sent */
+    held: number;
+    /**
+     * What its play adds up to since it was seated (`AiStats`): commands sent, held and refused, seconds its fighters
+     * stood idle, orders sent again for the same thing, seconds its building waited on money. For the report and
+     * `simulate`, never for a decision; not kept in a save
+     */
+    readonly stats: AiStats;
+    /** The tick of the think before, for what is counted by the seconds between thinks */
+    private lastThink;
+    /** The last order each unit was sent, with the tick: what an order sent again for the same thing is counted against (`AiStats.churn`) */
+    private readonly lastOrders;
+    /**
+     * How much of a think one tick may do (`ThinkBudget`): so many modules, so many units looked at as the modules say
+     * (`budget.spent(n)`), the think going on at the next tick from where it stopped (`budget.later()`). Counted in work,
+     * never in milliseconds, so that the game is the same on every machine. What the seat was given (`BrainContext.budget`)
+     */
+    readonly budget: ThinkBudget;
+    /** Milliseconds each module took, averaged over thinks, by id: while the world profiles (`BrainContext.profiling`) */
+    readonly moduleTiming: Record<string, number>;
+    /** The most milliseconds each module took in one pass, by id: always, as the warning (`ThinkBudgetOptions.warnAfterMs`) is */
+    readonly moduleLongest: Record<string, number>;
+    /** Milliseconds taking the picture of the game took (the seat's `snapshot()`), averaged: while the world profiles */
+    snapshotTiming: number | undefined;
+    /** Milliseconds reading the picture into the view took (`AiView`, the ledger with it), averaged: while the world profiles */
+    viewTiming: number | undefined;
+    /** Milliseconds bringing the knowledge up to date took, averaged: while the world profiles */
+    knowledgeTiming: number | undefined;
+    /** Ticks the last think took, all its passes: 1 unless its budget sliced it */
+    thinkTicks: number;
+    /** Ticks of the think under way so far */
+    private ticksSoFar;
+    /** The modules the log has warned of taking over `warnAfterMs`, once each */
+    private readonly warned;
+    /**
+     * The passes of the think under way: each module run, with the units the tick had looked at before it. What a save in
+     * the middle of the think keeps (`BrainMemory.thinking`), kept only where the budget may slice
+     */
+    private passes;
+    private heard;
+    /** Who follows its play from outside (`watch`): none in a game, so nothing is paid for it there */
+    private watchers;
+    /** The module a think under way goes on from, at the next tick: none between thinks (`budget`) */
+    private slice;
+    /**
+     * What it remembered as the think under way began, for a think sliced across ticks: what a save taken before the
+     * think ends keeps, with how far it got (`BrainMemory.thinking`)
+     */
+    private began;
+    /** The words told it since the think under way began: a save taken before it ends keeps them beside what it began with */
+    private toldDuring;
+    /** A think a save was taken in the middle of: run again to where it was, then on, at the next tick (`restore`) */
+    private resume;
+    /** While the modules a loaded game had run already are run again: nothing is sent, said or watched */
+    private replaying;
+    /** While a pass is run again: how many of the words it was told the pass had heard then, the rest told it after */
+    private replayHeard;
+    private readonly profiling;
+    constructor(
+    /** What it was made from */
+    def: BrainDef, 
+    /** The seat it plays through: the snapshots it sees, the commands it sends */
+    session: GameSession, 
+    /** What it was seated with: a brain's own options read theirs from it */
+    options: AiOptions, context?: BrainContext);
+    /**
+     * An area of its (`AiArea`): its economy (`ai.area(Economy)`), its scouting, a game's own (`defineArea`), made the
+     * first time it is asked for, with what a save remembered of it. What its modules share beyond what every module
+     * does (`knowledge`, `goals`, `plans`, `squads`, `purse`)
+     */
+    area<T extends AiArea>(key: AreaKey<T>): T;
+    /**
+     * An area made already, by id: none where no module has asked for it. For a part of the kit that reads another's
+     * area where there is one and needs nothing of it where there is none (whether a squad's fights are the micro's)
+     */
+    made<T extends AiArea>(id: string): T | undefined;
+    /** Its areas, in the order they were made: what its memory and its report are made of */
+    areas(): readonly AiArea[];
+    /** Puts an area among its own, with what a save remembered of it */
+    private register;
+    /**
+     * Follows its play from outside (`BrainWatcher`): the commands it sends, its thinks as each ends, what it decides.
+     * Returns the way to stop. What `watchComputer` and `recordDecisions` of `@v12-engine/engine/testing` stand on
+     */
+    watch(watcher: BrainWatcher): () => void;
+    /** The player it plays */
+    get playerId(): PlayerId;
+    /** The game's definitions, as the seat has them */
+    get registry(): Registry;
+    /** The tick of its picture of the game */
+    get tick(): number;
+    /** Seconds into the game, as of its picture of it */
+    get time(): number;
+    /** The player it plays, as its picture shows them: resources, supply, tech (`own`). Nothing once out of the game. `view.me` is the same, never nothing */
+    get me(): PlayerState | undefined;
+    /** A module of its, by key with its shape (`MELEE_ARMY`, `moduleKey`), or by id */
+    module<M extends AiModule>(key: ModuleKey<M>): M | undefined;
+    module(id: string): AiModule | undefined;
+    /**
+     * What its areas play by this think (`AiSettings`): its settings' layers worked out, a flag that is a function of the
+     * brain asked now. Each area reads its own (`ai.settings.economy`), over what its module was made with
+     */
+    get settings(): AiSettings;
+    /**
+     * What was worked out once for this think, by key: a consideration asked by several goals, a set a few modules
+     * read (`ai.cache('intruders', () => ...)`). Thrown away as the next think takes its picture
+     */
+    cache<T>(key: string, compute: () => T): T;
+    /** Whether a think is under way across ticks (`budget`): the seat asks it to think on at the next tick */
+    get busy(): boolean;
+    /**
+     * One think, or one tick of it. A new picture of the game is taken, and the modules run over it in their order, as
+     * many a tick as the budget allows (`budget`): so many modules, so many units looked at as they say. A module's error
+     * is the seat's to catch, as a system's is
+     */
+    think(): void;
+    /**
+     * One pass of a module: run once, timed, and the think moved on past it, unless it stopped for the tick with more to
+     * do (`budget.later()`), in which case it is where the think goes on at the next tick. Gives whether the think may go
+     * on this tick
+     */
+    private pass;
+    /** Seconds between the think before and this one's picture: 0 for the first think */
+    private sinceLastThink;
+    /**
+     * Counts, as a think begins, what its play adds up to (`stats`): the fighters that stood idle since the last think,
+     * the commands the game refused since, and the orders it no longer needs to remember for the churn
+     */
+    private count;
+    /**
+     * Sends a command, as the player would: counted (`sent`), carried out at the next tick. Returns the command's number;
+     * -1 for one past what its profile lets a think send (`commandsPerThink`, a person's hands), which is not sent
+     */
+    send(command: PlayerCommand): number;
+    /**
+     * Counts an order sent to a unit for the same thing as its last within a few seconds (`AiStats.churn`): a unit told
+     * to attack-move there every think never arrives, it stops and starts. The squads send an order once and watch it;
+     * this is how a test or `simulate` sees that they do
+     */
+    private churn;
+    /**
+     * The last order it sent a unit lately (within a few seconds), as a key (`orderKey`: its kind, its target, its
+     * place to the cell) with the tick: what keeps a module from telling a unit again what it is already doing, when the
+     * unit changed hands (a squad of another goal) since. None for a unit told nothing lately
+     */
+    sentTo(unit: number): {
+        key: string;
+        tick: number;
+    } | undefined;
+    /**
+     * The words the game told it and no module has taken yet (`world.computers.tell`), oldest first; those of one word
+     * where given. Reading them takes nothing: `takeTold` does, as a told rule (`when.told`) does when it fires
+     */
+    told(word?: string): readonly Told[];
+    /**
+     * Writes down a decision (`decisions`), with the reason that weighed most, in words: what the report's log and the
+     * debug panel show, and the world's log at its `debug` level. `kind` says what it is about (`army`, `build`)
+     */
+    decide(line: string, about?: {
+        kind?: string;
+        goal?: string;
+    }): void;
+    /**
+     * What it is thinking, as plain data (`AiReport`): its goals with their considerations, what it knows, its roles,
+     * its economy, what it was told, what it decided, and each module's section. Made when asked: nothing in a think
+     * waits for it. What `inspect` gives, and the debug panel's AI tab draws
+     */
+    report(): AiReport;
+    /**
+     * A goal's row of the report as a sentence: what it scored and why, whether it runs and with what, or what kept it
+     * from running. Nothing for a goal the brain does not have
+     */
+    explain(goal: string): string | undefined;
+    /** Takes in a word from the game: a module takes it with `takeTold`. What the seat calls for `world.computers.tell` */
+    tell(word: string, data: unknown, tick: number): void;
+    /** Takes the words of one kind out of what it was told, oldest first, as many as `count` (all when left out): they are heard no more */
+    takeTold(word: string, count?: number): Told[];
+    /**
+     * What it remembers, for a save: its numbers, each module's memory with its version, what it was told. A think under
+     * way (`budget`) is kept as it began, with how far it got and its picture (`BrainMemory.thinking`): the game loaded
+     * from the save runs it on to its end as the saved game does
+     */
+    save(): BrainMemory;
+    /** What its areas remember, by id: those that remember anything, and what a save had of areas not made since */
+    private areaMemories;
+    /** What it remembers, but what its seat heard since it last thought */
+    private memory;
+    /**
+     * Takes back what `save` gave. A module's memory of another version goes through its `migrate`; without one, or with
+     * nothing in the save for it, the module starts afresh, and the log says so once. Memory of a module the brain no
+     * longer has is dropped, said too
+     */
+    restore(memory: BrainMemory): void;
+    /** What it is thinking, for the debug tools: its report (`report`) */
+    inspect(): AiReport;
+    /** Lets its modules go of what they hold outside the brain */
+    dispose(): void;
+}
+/**
+ * Makes a brain from its definition for a seat: the session it plays through, the options it is seated with. What
+ * a brain's seat does (`createBrainSystem`); for a seat made another way (`createComputerSystem`'s `make`)
+ *
+ * @beta
+ */
+export declare function createBrain(def: BrainDef, session: GameSession, options: AiOptions, context?: BrainContext): Brain;

package/dist/ai/budget.d.ts

@@ -0,0 +1,67 @@
+/**
+ * How much of a think one tick may do (`AiOptions.budget`, `AiProfile.budget`, `ComputerSeatOptions.budget`), counted in
+ * work and never in milliseconds: the same on every machine, so that a game with a sliced think is the same game
+ * everywhere. Nothing is limited where a field is left out
+ *
+ * @beta
+ */
+export interface ThinkBudgetOptions {
+    /**
+     * Modules of a brain a think may run in one tick: a think with more goes on at the next tick, over the same picture of
+     * the game. All of them in one tick when left out
+     */
+    modulesPerTick?: number;
+    /**
+     * Units a tick's modules may look at, as the modules say (`ai.budget.spent(n)`): a module that walks the squads or the
+     * bases stops once the tick has looked at this many, and goes on at the next tick from where it was (`later`). No
+     * limit when left out. A module that says nothing of what it looks at is never stopped by it
+     */
+    unitsPerTick?: number;
+    /**
+     * Milliseconds a module may take before the log says so (once a module, a warning): what to measure first. A module
+     * is never cut short for it. 4 when left out; `false` for never
+     */
+    warnAfterMs?: number | false;
+}
+/**
+ * The budget of the think under way, as a module reads it (`ai.budget`): what this tick may still do, and the way to say
+ * what was looked at (`spent`) and to go on at the next tick (`later`). A module that walks units looks at them a few at
+ * a time:
+ *
+ *     for (; this.cursor < squads.length; this.cursor++) {
+ *       look(squads[this.cursor])
+ *       if (!ai.budget.spent(squads[this.cursor].size) && this.cursor + 1 < squads.length) return ai.budget.later()
+ *     }
+ *
+ * @beta
+ */
+export declare class ThinkBudget {
+    /** Modules a tick may run: `Infinity` where unlimited */
+    readonly modulesPerTick: number;
+    /** Units a tick's modules may look at, as they say: `Infinity` where unlimited */
+    readonly unitsPerTick: number;
+    /** Milliseconds a module may take before the log says so: none for never */
+    readonly warnAfterMs: number | undefined;
+    /** Units looked at this tick, as the modules said (`spent`) */
+    units: number;
+    /** Whether the module running asked to go on at the next tick (`later`) */
+    deferred: boolean;
+    constructor(options?: number | ThinkBudgetOptions);
+    /** Whether the budget may slice a think over ticks at all: one that limits nothing never does, and nothing is kept for it */
+    get slices(): boolean;
+    /** Whether this tick may look at more: a module that walks units stops where it may not, and says `later` */
+    get room(): boolean;
+    /**
+     * Says the module looked at so many units (one when left out). Gives whether this tick may look at more: where it may
+     * not, a module with more to do remembers where it was and says `later`
+     */
+    spent(units?: number): boolean;
+    /**
+     * The module running stops here for this tick and is run again at the next, going on from where it remembers it was,
+     * over the same picture. Honoured where the module looked at something this tick (`spent`): one that looked at
+     * nothing and asks to go on would never end, so it is taken to be done, and the log says so
+     */
+    later(): void;
+    /** The budget as the report shows it: the limits, where there are any */
+    report(): ThinkBudgetOptions | undefined;
+}