@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/micro.d.ts

@@ -0,0 +1,278 @@
+import { type UnitTypeDef } from '#engine/defs';
+import type { PlayerId } from '#engine/entity';
+import { type Vec2 } from '#engine/math';
+import type { Registry } from '#engine/registry';
+import type { EntityState, LearnableInfo, Snapshot } from '#engine/session/protocol';
+import type { Brain } from './brain';
+import { type AiModuleDef } from './module';
+import { type AiCondition } from './rules';
+import { type Squad } from './squads';
+import { UnitSet } from './view';
+/**
+ * What a computer player sees as it weighs an ability, for the ability's `ai` to decide with (`AbilityDef.ai`)
+ *
+ * @beta
+ */
+export interface AbilityAiView {
+    snapshot: Snapshot;
+    registry: Registry;
+    playerId: PlayerId;
+    /** Enemy units it sees, near enough to the caster to matter */
+    enemies: EntityState[];
+    /** Its own and allied units that fight, near the caster */
+    friends: EntityState[];
+}
+/**
+ * One rule of who is worth hitting first (`MicroOptions.targets`): what it picks out, how much it adds, when it counts.
+ * Plain data
+ *
+ * @beta
+ */
+export interface TargetRule {
+    /**
+     * What it picks out: a role (`caster`, `hero`, `siege`, `worker`, `healer`), `building`, a tag (`ranged`, the game's
+     * own), or a unit type by id
+     */
+    match: string;
+    /** What it adds to the worth of what it picks out: 1 when left out. Rules add up; a foe no rule names is worth 1 */
+    weight?: number;
+    /** When it counts: a condition (`AiCondition`, as data or a function). Always when left out */
+    when?: AiCondition;
+}
+/**
+ * Who a squad hits, in code (`MicroOptions.targets`): of the foes in its fight, the one; nothing to leave the units to
+ * themselves this time
+ *
+ * @beta
+ */
+export type TargetPicker = (ai: Brain, squad: Squad, foes: UnitSet) => EntityState | undefined;
+/**
+ * Where to use an ability, in code (`MicroOptions.spells`, by ability id): where (`point`) and on whom (`target`),
+ * `null` for not now, `undefined` to leave it to what the kit works out from the effects. `foes` are the enemies within
+ * the ability's reach of the caster, `friends` its own and its allies' fighters near it
+ *
+ * @beta
+ */
+export type SpellAim = (ai: Brain, caster: EntityState, foes: readonly EntityState[], friends: readonly EntityState[], level: number) => {
+    point: Vec2;
+    target?: number;
+} | null | undefined;
+/**
+ * A hero the brain means to have (`MicroOptions.heroes`): which, what it learns in what order, what it buys
+ *
+ * @beta
+ */
+export interface HeroPlan {
+    /** The hero's unit type */
+    type: string;
+    /**
+     * The order its skills are learned in, each level a line (`['stomp', 'holyLight', 'stomp', …]`); past the end, or
+     * left out, the ultimate as soon as it can be had and then whatever is furthest behind. Or a function: the skill to
+     * learn next of those it may, by id
+     */
+    skills?: string[] | ((ai: Brain, hero: EntityState, learnable: readonly LearnableInfo[]) => string | undefined);
+    /** What it shops for, in place of the brain's `shopping` */
+    items?: ShoppingItem[];
+    /** The chance it is made at all, 0 to 1 (1 when left out): rolled once, with the brain's numbers, and remembered */
+    chance?: number;
+}
+/**
+ * A line of a hero's shopping list (`MicroOptions.shopping`, `HeroPlan.items`): an item to carry, how many, when
+ *
+ * @beta
+ */
+export interface ShoppingItem {
+    /** The item, by id */
+    item: string;
+    /** How many of it to carry: 1 when left out */
+    count?: number;
+    /** When it is wanted: a condition. Always when left out */
+    when?: AiCondition;
+}
+/**
+ * A line of what a brain hires (`MicroOptions.hiring`): a unit a place hires out, how many of it to have, when
+ *
+ * @beta
+ */
+export interface HiringItem {
+    /** The unit type, by id: one a place that hires lists (`UnitTypeDef.hires`) */
+    unit: string;
+    /** How many of it to have: 1 when left out */
+    count?: number;
+    /** When it is wanted: a condition. Always when left out */
+    when?: AiCondition;
+}
+/**
+ * How a brain fights (`BrainDef.micro`, the seat's `AiOptions.micro` over it, the `micro()` module's own under both):
+ * whom it hits first, whether its ranged units kite, when its units flee, how it casts, what it buys, how its siege is
+ * used, which heroes it makes. Every field has a data form a save keeps; the function forms are the brain's to give
+ * again
+ *
+ * @beta
+ */
+export interface MicroOptions {
+    /**
+     * Who is worth hitting first, as ranked rules (`TargetRule`), or a function that picks (`TargetPicker`). The kit's
+     * when left out: casters 2, heroes 1.5 (with `targetHeroes`), siege 1, healers 2, over the type's declared
+     * `UnitTypeDef.ai.priority`; among those alike, the weakest, the nearest
+     */
+    targets?: TargetRule[] | TargetPicker;
+    /** Whether heroes are worth hitting first (the classic Target Heroes): yes when left out */
+    targetHeroes?: boolean;
+    /** Seconds a squad keeps hitting the rival it was told to before another is chosen: 4 */
+    focusEvery?: number;
+    /**
+     * Whether ranged units step back from the melee closing on them, when they are the faster: `'ranged'` (or `true`)
+     * when left out, `false` never
+     */
+    kite?: boolean | 'ranged';
+    /** The share of its health under which a unit leaves the fight for safety (the classic Units Flee): 0.25. `false` never */
+    unitsFlee?: number | false;
+    /** The same for heroes (Heroes Flee): 0.35. `false` never */
+    heroesFlee?: number | false;
+    /** The share of its health at which a unit that fled is back: 0.8 */
+    returnAt?: number;
+    /** Whether the hurt go home to heal between fights, not only out of one (Remove Injuries): no when left out */
+    removeInjuries?: boolean;
+    /** Whether a unit that fled stays out until healed, however long (Ignore Injured): no when left out, so one nothing heals (or that heals too slowly to wait a minute for) comes back once safe */
+    ignoreInjured?: boolean;
+    /**
+     * Where to use abilities, by ability id (`SpellAim`): before the ability's own `ai`, and before what the kit works
+     * out from its effects. `false` casts nothing: what is on autocast looks after itself
+     */
+    spells?: Record<string, SpellAim> | false;
+    /** Whether a potion is drunk when it is needed: yes when left out */
+    potions?: boolean;
+    /** Whether what lies about is picked up (Take Items): yes when left out */
+    takeItems?: boolean;
+    /** Whether heroes buy from a shop in reach (Buy Items): yes when left out, where there is a shop and a list */
+    buyItems?: boolean;
+    /**
+     * What a hero shops for, in order (`ShoppingItem`), or a function that names the item a hero should buy next (none
+     * for nothing). The cheapest item whose ability heals, one of it, when left out; `false` nothing
+     */
+    shopping?: ShoppingItem[] | ((ai: Brain, hero: EntityState) => string | undefined) | false;
+    /** Whether it hires units at a place that hires in reach (a tavern, a mercenary camp: `UnitTypeDef.hires`): yes when left out, where there is one */
+    hireUnits?: boolean;
+    /**
+     * What it hires, in order (`HiringItem`), or a function that names the unit to hire next of those a place offers (none
+     * for nothing). When left out: no hero, the strongest soldier for its price, with money to spare (150 past it) and
+     * supply free, four at the most. `false` nothing
+     */
+    hiring?: HiringItem[] | ((ai: Brain, offered: readonly UnitTypeDef[]) => string | undefined) | false;
+    /** Whether siege units shoot buildings when they may and stay behind the squad (Smart Artillery): yes when left out */
+    smartArtillery?: boolean;
+    /**
+     * The heroes to make, in order (`HeroPlan`: which, its skills, its items, a chance), or a function that picks the
+     * next of those that could be made. The first that can be made, and the ultimate first, when left out
+     */
+    heroes?: HeroPlan[] | ((ai: Brain, candidates: readonly UnitTypeDef[]) => UnitTypeDef | string | undefined);
+}
+/**
+ * What the micro module remembers between thinks, as a save keeps it
+ *
+ * @beta
+ */
+export interface MicroMemory {
+    v: 1;
+    /** Whom each squad hits, by squad name: the foe and since when */
+    focus: Record<string, {
+        target: number;
+        since: number;
+    }>;
+    /** When each unit last stepped back, by unit id */
+    kited: Record<string, number>;
+    /** Each unit that fled, by id: the squad it left, since when, where to, and why */
+    fled: Record<string, {
+        squad?: string;
+        since: number;
+        to: Vec2;
+        why: 'hurt' | 'injured';
+    }>;
+    /** What each siege unit was told to shoot, by unit id */
+    siege: Record<string, {
+        target: number;
+        since: number;
+    }>;
+    /** What each hero is on its way to buy, by hero id */
+    shopping: Record<string, {
+        shop: number;
+        item: string;
+        since: number;
+    }>;
+    /** Who is on their way to hire what, by the id of the unit sent: the place that hires, the unit type, since when */
+    hiring?: Record<string, {
+        place: number;
+        unit: string;
+        since: number;
+    }>;
+    /** The chance of each hero plan as it was rolled, by its place in the list */
+    rolled: Record<string, boolean>;
+}
+/**
+ * The fights as the report shows them (`AiReport.micro`): each squad in one, its foes, its odds, whom it hits; the
+ * units that fled; the heroes and what each learns next; who shops for what
+ *
+ * @beta
+ */
+export interface MicroReport {
+    fights: {
+        squad: string;
+        foes: number;
+        odds: number;
+        /** Whom the squad hits: the foe, its type, since when */
+        target?: {
+            id: number;
+            type: string;
+            since: number;
+        };
+        /** Its units that stepped back this think */
+        kiting: number[];
+        /** Its siege units told to shoot a building this think */
+        siege: number[];
+    }[];
+    fleeing: {
+        unit: number;
+        type: string;
+        health: number;
+        to: [number, number];
+        since: number;
+        why: 'hurt' | 'injured';
+    }[];
+    heroes: {
+        id: number;
+        type: string;
+        level: number;
+        next?: string;
+    }[];
+    shopping: {
+        hero: number;
+        item: string;
+        shop: number;
+        since: number;
+    }[];
+    /** Who is on their way to hire what: the unit sent, the place, the unit type, since when */
+    hiring: {
+        by: number;
+        place: number;
+        unit: string;
+        since: number;
+    }[];
+    /** Abilities cast last think */
+    cast: number;
+    /** Thinks whose fights it left alone, slips of its profile's `mistakes` */
+    slipped?: number;
+}
+/**
+ * The micro module: the fights of the brain's squads each think, after the squads sent and watched their tasks
+ * (`ai.micro.think`): focus fire, kiting, siege, fleeing and coming back, spells, items, the heroes' skills. With how it
+ * fights where the brain's definition and the seat's options say nothing (`MicroOptions`)
+ *
+ * @beta
+ */
+export declare const micro: (options?: MicroOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        micro?: MicroMemory;
+    }
+}

package/dist/ai/mission.d.ts

@@ -0,0 +1,195 @@
+import { type Vec2 } from '#engine/math';
+import type { EntityState } from '#engine/session/protocol';
+import { type Brain, type BrainDef, type BrainExtension } from './brain';
+import { type AiModuleDef } from './module';
+import type { AiRole } from './roles';
+import { type AiAction, type AiCondition } from './rules';
+import type { UnitSet } from './view';
+/**
+ * Where a mission's part is: a point, or a name the map or the rules gave an entity (`world.named`) or a region of the
+ * map
+ *
+ * @beta
+ */
+export type MissionPlace = Vec2 | string;
+/**
+ * Which of its units a part takes, as data: those named (`named`), of a type, a role or a tag, near a place (`near`,
+ * `within`), at most so many (`count`, the nearest the part's place first). Its fighters (soldiers and heroes) where
+ * none of `named`, `type`, `role`, `tag` is given
+ *
+ * @beta
+ */
+export interface MissionUnitsData {
+    /** Entities the map or the rules named (`world.named`): those of them that are its own */
+    named?: string[];
+    /** Of a type, or of any of a list */
+    type?: string | string[];
+    role?: AiRole;
+    tag?: string;
+    /** Near a place */
+    near?: MissionPlace;
+    /** How near `near` (the part's reach when left out) */
+    within?: number;
+    /** At most so many, the nearest the part's place first */
+    count?: number;
+}
+/**
+ * Which of its units a part takes: data (`MissionUnitsData`), or a function choosing from those it may have
+ * (`available`: what no goal holds, and what goals it may take from hold)
+ *
+ * @beta
+ */
+export type MissionUnits = MissionUnitsData | ((ai: Brain, available: UnitSet) => Iterable<EntityState>);
+/**
+ * What every part of a mission takes
+ *
+ * @beta
+ */
+export interface MissionPartOptions {
+    /**
+     * Its id: the module's, the goal's and the squad's, what the report and the log name it by. `mission.<part>:<place>`
+     * when left out (`mission.hold:camp`); give one where two parts of a kind share a place
+     */
+    id?: string;
+    /** Which of its units it takes, once, as it is first picked: those at its place when left out (its fighters for `fleeWhen`) */
+    units?: MissionUnits;
+    /** Whether units that come later and fit `units` are taken too: no when left out (`waveFrom` always takes what comes) */
+    refill?: boolean;
+    /** Only while this holds: the part lets go of its units while it does not (a condition, as data or a function) */
+    when?: AiCondition;
+    /** What it is worth against the brain's other goals: 1 when left out (10 for `fleeWhen`) */
+    weight?: number;
+}
+/**
+ * What a part remembers between thinks, as a save keeps it: its own units, and what its kind adds (an ambush's spring,
+ * a wave's count)
+ *
+ * @beta
+ */
+export interface MissionPartMemory {
+    v: 1;
+    /** Whether it took its units yet: they are taken once */
+    took: boolean;
+    /** Its own units, by id: what it takes back after a word or a rule had them */
+    units: number[];
+    /** An ambush: the tick it sprang at, while sprung; how many times it sprang; whether its `then` was done */
+    sprung?: number;
+    times?: number;
+    acted?: boolean;
+    /** A wave: how many were sent; the tick the last went at (or the part began at) */
+    sent?: number;
+    last?: number;
+    /** `surrenderWhen`: whether it gave up */
+    done?: boolean;
+}
+/**
+ * The mission brain's definition: a brain's (`BrainDef`) with the parts given as `modules`, after the ones every mission
+ * has. Its `id` is what a save remembers the seat by: list the brain in `GameModule.brains`
+ *
+ * @beta
+ */
+export interface MissionBrainDef extends BrainExtension {
+    id: string;
+}
+/**
+ * Its units hold a place: they go there, fight what comes within its reach (`radius`, or the region's size, else 10),
+ * and go back once it is gone. Its units: those at the place as it is first picked (within its reach and a little), or
+ * what `units` say
+ *
+ * @beta
+ */
+export declare function holdPosition(place: MissionPlace, options?: MissionPartOptions & {
+    radius?: number;
+}): AiModuleDef;
+/**
+ * Its units walk a round of places, one after the other and back to the first, fighting what they meet on the way. Its
+ * units: those near the first place as it is first picked, or what `units` say. Places it does not know are passed over
+ *
+ * @beta
+ */
+export declare function patrol(points: readonly MissionPlace[], options?: MissionPartOptions): AiModuleDef;
+/**
+ * Its units stay by an entity, by its name (`world.named`) or its id: a unit they follow, a building they hold round
+ * (within `radius`, 12 when left out), fighting what comes near it. While the entity stands: once it is gone, its units
+ * are let go of. Its units: those near it as it is first picked (within 20), or what `units` say
+ *
+ * @beta
+ */
+export declare function guard(entity: string | number, options?: MissionPartOptions & {
+    radius?: number;
+}): AiModuleDef;
+/**
+ * What an ambush does once the fight it sprang is over: `return` to its place and wait again (the default), `stay`
+ * where it is, or an action (a word it tells itself, `{ say: 'attack' }`, or a function of the brain), done once
+ *
+ * @beta
+ */
+export type AmbushThen = 'return' | 'stay' | AiAction;
+/**
+ * Its units wait at a place on hold (they hit what walks into reach and move for nothing), and spring once a rival's
+ * unit comes within `radius` of it (or once `trigger` holds): they go for the intruders, fighting what they meet. Once
+ * that fight is over, `then` (`AmbushThen`). `once`: it springs the first time only. Its units: those at the place as it
+ * is first picked, or what `units` say
+ *
+ * @beta
+ */
+export declare function ambush(place: MissionPlace, options?: MissionPartOptions & {
+    radius?: number;
+    trigger?: AiCondition;
+    then?: AmbushThen;
+    once?: boolean;
+}): AiModuleDef;
+/**
+ * Where a wave goes: a place (a point, or a name), or a function of the brain. The nearest building of a rival's it
+ * knows of when left out, else the nearest rival it sees, else the first base the seat was told (`AiOptions.enemyBases`)
+ *
+ * @beta
+ */
+export type MissionTarget = MissionPlace | ((ai: Brain) => Vec2 | undefined);
+/**
+ * The units that come out of a spawner (what the mission's own rules spawn there, or what a building there trains),
+ * gathered there and sent as a wave: once there are as many as `group` says (a number, or so many of each type or
+ * role: `{ footman: 4, caster: 1 }`; 4 when left out), or, with `every`, every so many seconds with what has gathered
+ * (at least `minForces` of the group: a share, any when left out). A wave goes for `target` (`MissionTarget`) and, once
+ * that is cleared, for the next it knows of. `first`: seconds before the first wave may go (`every`, else none). Nothing
+ * is trained or built: a mission with no economy feeds it
+ *
+ * @beta
+ */
+export declare function waveFrom(source: MissionPlace, options?: Omit<MissionPartOptions, 'units' | 'refill'> & {
+    group?: number | Record<string, number>;
+    every?: number;
+    minForces?: number;
+    first?: number;
+    target?: MissionTarget;
+    radius?: number;
+}): AiModuleDef;
+/**
+ * When the condition holds, its units run: to `to` (a place), else home, else away from the nearest rival; and stand
+ * there while it holds. Once it no longer does, they are let go of, and the parts that had them take them back. An
+ * urgent goal worth 10: it takes its units from any other. Its units: its fighters, or what `units` say
+ *
+ * @beta
+ */
+export declare function fleeWhen(condition: AiCondition, options?: Omit<MissionPartOptions, 'refill'> & {
+    to?: MissionPlace;
+}): AiModuleDef;
+/**
+ * When the condition holds, the computer gives up: the engine's `surrender` command, as a player's, once. Out of the
+ * game as if beaten
+ *
+ * @beta
+ */
+export declare function surrenderWhen(condition: AiCondition, options?: {
+    id?: string;
+}): AiModuleDef;
+/**
+ * A computer player for a mission: a brain (`defineBrain`) of what every mission's computer has (its rules, the words
+ * every brain may be told, the goals' picker, squads, micro) and the parts it is given (`modules`: `holdPosition`,
+ * `patrol`, `guard`, `ambush`, `waveFrom`, `fleeWhen`, `surrenderWhen`, any module of the kit's or of its own). Nothing
+ * builds, trains, gathers, scouts or answers raids on its bases unless a module for it is given (`economy()`,
+ * `scouting()`, `defence()`). Everything else of `BrainDef` as for any brain (`goals`, `micro`, `without`, `knowledge`)
+ *
+ * @beta
+ */
+export declare function missionBrain(def: MissionBrainDef): BrainDef;

package/dist/ai/missionRules.d.ts

@@ -0,0 +1,18 @@
+import { type MissionRule } from '#engine/missionRules';
+import type { GamePack } from '#engine/packs/pack';
+/**
+ * Mission rules as data (campaign plan MS1): the rules a map keeps (`MissionRule`, under `GameMap.data.rules`, written
+ * in the editor's Rules panel) run as the game plays, `rules` of the game's own code beside them. Each `when` a
+ * condition of the computer players' language holds (`docs/ai.md`), asked as a player, `do`es its actions
+ * (`MissionActionData`: an objective of the map's given, done or failed, a line said, a cinematic played, a prefab
+ * spawned, a computer told, a relation set, a timer started, win, lose). Checked once a second; what the rules
+ * remember is in the world's state, so a save mid-mission has it. The code reaches the rules with `tellRules` and hears
+ * them fire as `ruleFired`; the map's checks say what is wrong with them (`checkMissionRules`). Of `@v12-engine/engine/ai`, as
+ * a condition is asked of a watcher seated as the computer players are (`ruleWatcher`); the map objectives pack
+ * (`mapObjectives`) goes with it, for the objectives a rule gives
+ *
+ * @beta
+ */
+export declare function missionRules(options?: {
+    rules?: MissionRule[];
+}): GamePack;

package/dist/ai/module.d.ts

@@ -0,0 +1,116 @@
+/**
+ * A module of a brain (`AiModule`): one part of a think, made for each brain (`defineModule`). Apart from the brain
+ * (`brain.ts`), which is made of them, so that a module and an area of the kit import this and the brain's type only,
+ * and the brain imports no module back
+ */
+import type { Brain } from './brain';
+import type { AiReport } from './report';
+/**
+ * One named part of a computer player's think (`defineBrain`'s `modules`). Modules run in their order each think, over
+ * the same picture of the game, each reading it through the brain it is handed (`ai.snapshot`, later `ai.view`) and
+ * acting through `ai.send`. A module is made for each brain (`AiModuleDef`: a function of the brain), so that what it
+ * keeps in itself is one seat's. What it remembers between thinks goes through `save` and `restore`, as plain data
+ *
+ * @beta
+ */
+export interface AiModule {
+    /** Unique in a brain: what its memory is kept under, what the timing and the debug tools name it by */
+    id: string;
+    /**
+     * The version of what it remembers (`save`): 1 when left out. Raised when the shape of it changes; a load that finds
+     * memory of another version gives it to `migrate`, or starts the module afresh where there is none
+     */
+    version?: number;
+    /** Runs once in so many thinks, for work that does not need doing every think. Every think when left out */
+    everyThinks?: number;
+    /** With `everyThinks`, the think in each round it runs at: modules with the same `every` and other offsets spread the work */
+    offset?: number;
+    /**
+     * When in a think it runs (`AiPhase`): the brain runs its modules phase by phase, as listed within each. Left out,
+     * in the phase of the module listed before it (the first phase for the first)
+     */
+    phase?: AiPhase;
+    /**
+     * Ids of modules of the brain this one runs ahead of, for what one phase needs within itself. Ids of modules the
+     * brain does not have are passed over
+     */
+    before?: string[];
+    /** Ids of modules of the brain this one runs after, within its phase */
+    after?: string[];
+    /**
+     * Ids this module's memory was kept under before it was called what it is: a save made then gives it back under
+     * the old id, and it is read as this module's (through `migrate` where the version differs too)
+     */
+    wasCalled?: string[];
+    /** Its part of the think */
+    think(ai: Brain): void;
+    /** What it remembers between thinks, as plain data for a save. Nothing (`undefined`) for a module that remembers nothing */
+    save?(): unknown;
+    /** Takes back what `save` gave, in a game loaded from a save */
+    restore?(data: unknown): void;
+    /**
+     * Brings what an earlier version of the module saved (`from`: its version) up to what this one takes. Nothing
+     * (`undefined`) says it cannot be brought up, and the module starts afresh; so does a module without `migrate`
+     */
+    migrate?(data: unknown, from: number): unknown;
+    /**
+     * What it is thinking, as plain data, for the debug tools: what the report has no part for, kept under the module's
+     * id in its `sections` (`Brain.report`)
+     */
+    inspect?(): unknown;
+    /**
+     * Writes its part of the report (`Brain.report`), where the report has a part for it: a kit's module fills the part
+     * it names (its squads, its plans). Plain data only
+     */
+    report?(report: AiReport): void;
+    /** Lets go of what it holds outside the brain when the computer is unseated */
+    dispose?(): void;
+}
+/**
+ * The phases of a think, in the order they run (`AiModule.phase`): `hear` what it was told and its rules, `sense`
+ * what threatens it and its team, `plan` its economy, buildings and training, `decide` what its own goals are, `act`
+ * the picker, the squads and the waves, `fight` the micro
+ *
+ * @beta
+ */
+export declare const AI_PHASES: readonly ['hear', 'sense', 'plan', 'decide', 'act', 'fight'];
+/**
+ * A phase of a think (`AI_PHASES`)
+ *
+ * @beta
+ */
+export type AiPhase = (typeof AI_PHASES)[number];
+/**
+ * What finds a module of a brain with its shape (`ai.module(key)`): its id, typed. The kit's are `MELEE_ARMY` and
+ * `LANES`; a game makes its own with `moduleKey`
+ *
+ * @beta
+ */
+export interface ModuleKey<M extends AiModule> {
+    readonly id: string;
+    /** The shape the module has: never set, for the type alone */
+    readonly shape?: M;
+}
+/**
+ * A key to a module of a game's own (`ai.module(key)` gives it with its shape)
+ *
+ * @beta
+ */
+export declare function moduleKey<M extends AiModule>(id: string): ModuleKey<M>;
+/**
+ * A module of a brain: made for each brain by a function of it, so that two brains never share one; or one as it is,
+ * for a module that keeps nothing. A function made with `defineModule` carries the module's id before it is made,
+ * which is how `BrainDef.without` names it
+ *
+ * @beta
+ */
+export type AiModuleDef = AiModule | (((ai: Brain) => AiModule) & {
+    id?: string;
+});
+/**
+ * A module made for each brain by a function of it, with its id known before it is made: what a brain's `without`
+ * leaves out by name (`meleeBrain.with({ without: ['scouting'] })`). The kit's modules are all defined so
+ *
+ * @beta
+ */
+export declare function defineModule(id: string, make: (ai: Brain) => AiModule): AiModuleDef;

package/dist/ai/options.d.ts

@@ -0,0 +1,61 @@
+import type { Vec2 } from '#engine/math';
+import type { GoalDef } from './goals';
+import type { ThinkBudgetOptions } from './budget';
+import type { RolesFinder } from './roles';
+import type { AiSettings } from './settings';
+import type { StrengthFormula } from './strength';
+/**
+ * What a computer player is seated with (`world.computers.seat`): where its rivals started, its
+ * difficulty, its personality and its settings (`Brain.options`). The data in it (numbers, lists, names) is kept
+ * in a save with the seat; a function given as an option is not (`world.computers.seat` says what becomes of it)
+ *
+ * @beta
+ */
+export interface AiOptions {
+    /** Where opponents started. Known to everyone at the start of a game, as in classic RTS games. A brain that goes by what it sees does without */
+    enemyBases?: Vec2[];
+    /** Seconds between thinks. What the brain says when left out: its profile's (the difficulty's), 1 for a brain that says nothing */
+    every?: number;
+    /**
+     * How much of a think one tick may do (`ThinkBudgetOptions`): so many of the brain's modules, so many units looked at
+     * as they say, a think with more going on at the next tick over the same picture of the game, so that no tick does
+     * all of it; and the milliseconds a module is warned over. Counted in work, never in milliseconds, so that the game is
+     * the same on every machine. Over the profile's (`AiProfile.budget`); a number is the modules a tick. Everything in
+     * one tick when left out. Data
+     */
+    budget?: number | ThinkBudgetOptions;
+    /**
+     * Goals of the game's own, picked with the engine's each turn (`ai.goals`): a goal that scores itself from
+     * considerations and claims units (`defineGoal`). A raid on workers, holding a hill, escorting a caravan. Code: not kept
+     * in a save; a brain's own goals are (`meleeBrain.with({ goals })`, `GameModule.brains`)
+     */
+    goals?: GoalDef[];
+    /**
+     * How hard it plays (`easy`, `normal`, `hard`, `insane`, or a game's own: `GameModule.ai.difficulties`): how often it thinks, when it first attacks
+     * and how many it sends, how far it comes to defend, how many workers it keeps, how many commands a think, how often
+     * it slips, whether it sees through the fog (`insane`). A layer of the profile (`AiProfile`): the personality's, the
+     * map's and the seat's settings go over it. `normal` when left out
+     */
+    difficulty?: string;
+    /**
+     * How it likes to play (`balanced`, `rusher`, `turtle`, `expander`, `harasser`, or a game's own: `GameModule.ai.personalities`):
+     * the weights of its goals, when it attacks and expands, its towers. Over the difficulty. `balanced` when left out
+     */
+    personality?: string;
+    /**
+     * The seat's own settings (`AiSettings`, keyed by area: `{ economy: { workers: 6 }, army: { firstAttack: 90 },
+     * flags: { kite: false } }`): the top layer, over the personality and the map's (`MapAi.settings`). Data, but for a
+     * flag given as a function
+     */
+    settings?: AiSettings;
+    /**
+     * What the game's unit types are for, found the game's way (`RolesFinder`): in place of what the kit infers from
+     * the definitions (`inferRoles`); what a type declares (`UnitTypeDef.ai`) goes over either. Code: not kept in a save
+     */
+    roles?: RolesFinder;
+    /**
+     * How strong a unit is, in place of the kit's formula (`defaultStrength`): what `odds`, `matchup`, the threat map and
+     * `UnitSet.strength()` are made of. Being code, it is not kept in a save: a brain's own goes in `BrainDef.strength`
+     */
+    strength?: StrengthFormula;
+}