@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/threat.d.ts

@@ -0,0 +1,91 @@
+import type { Layer } from '#engine/defs';
+import { type Vec2 } from '#engine/math';
+import type { AiView } from './view';
+/**
+ * What the threat map reads at a place: the strength of the friendly units (one's own and allies') and of the enemy
+ * units (rivals' and creeps') that can reach it, and the difference
+ *
+ * @beta
+ */
+export interface Threat {
+    /** The strength of one's own and allies' units that reach the place */
+    friendly: number;
+    /** The strength of rivals' and creeps' units that reach it */
+    enemy: number;
+    /** `friendly - enemy`: above 0 where one's own side is stronger */
+    net: number;
+}
+/**
+ * A cell of the threat map with what it reads (`ThreatMap.hot`, `cells`)
+ *
+ * @beta
+ */
+export interface ThreatCell extends Threat {
+    /** The middle of the cell */
+    at: Vec2;
+    col: number;
+    row: number;
+}
+/**
+ * What a read of the map is for: the layer the thing asked about is on (`ground` when left out: what can reach things
+ * on the ground), and whether the enemy structures remembered and out of sight count too (a tower seen before)
+ *
+ * @beta
+ */
+export interface ThreatQuery {
+    layer?: Layer;
+    remembered?: boolean;
+}
+/**
+ * Where the strength is, on a coarse grid over the map (`AiView.threat`, `Brain.threat`): `at(point)` reads a place,
+ * `around(point, radius)` the worst cell near it, `hot()` the cells where the enemy is strongest near what is one's
+ * own, `cells()` every cell with something in it (for a drawing of it). Made from the view's picture when first asked,
+ * once a think; all zeros for no point, or one off the map, so that a question about "the first base known" needs no
+ * guard
+ *
+ * @beta
+ */
+export declare class ThreatMap {
+    /** The picture it is made from */
+    readonly view: AiView;
+    /** Cells across and down, and the side of one */
+    readonly cols: number;
+    readonly rows: number;
+    readonly cell = 8;
+    private seen;
+    private withRemembered;
+    constructor(
+    /** The picture it is made from */
+    view: AiView);
+    /** The grids of a reading, made when first asked */
+    private grids;
+    /** One pass over the picture: each fighter painted onto the cells it reaches, on the layers it can hit */
+    private build;
+    /** A unit's strength onto the cells within its reach: in full within its range, fading to nothing at the edge */
+    private paint;
+    private col;
+    private row;
+    /** Whether a point is on the map */
+    private onMap;
+    private read;
+    /**
+     * What reaches a place: the friendly and the enemy strength at its cell, on a layer (`ground` when left out). All
+     * zeros for no point or one off the map
+     */
+    at(point: Vec2 | undefined, query?: ThreatQuery): Threat;
+    /** The worst cell within a distance of a point: the one the most enemy strength reaches. Zeros off the map */
+    around(point: Vec2 | undefined, radius: number, query?: ThreatQuery): Threat;
+    /**
+     * Where the enemy is strongest near what is one's own: the cells that enemy strength reaches and that hold a unit or
+     * building of the player's (an ally's with `owner`), the hottest first. A raid at an expansion reads here while the
+     * main is quiet
+     */
+    hot(query?: ThreatQuery & {
+        owner?: number;
+    }): ThreatCell[];
+    /** Every cell that any strength reaches on a layer, in the grid's order: for a drawing of the map */
+    cells(query?: ThreatQuery): ThreatCell[];
+    private cellOf;
+    /** Whether a reading has been made this think: for the timing and the debug tools */
+    get built(): boolean;
+}

package/dist/ai/view.d.ts

@@ -0,0 +1,366 @@
+import type { Component } from '#engine/components';
+import type { ResourceKind, UnitTypeDef } from '#engine/defs';
+import type { PlayerId } from '#engine/entity';
+import type { EventKey } from '#engine/events';
+import type { Lane } from '#engine/lanes';
+import type { MapRegion } from '#engine/map';
+import { type Vec2 } from '#engine/math';
+import type { Message } from '#engine/messages';
+import type { ObjectiveState } from '#engine/objectives';
+import type { Registry } from '#engine/registry';
+import type { CampInfo, EntityState, GameSession, GroundItemState, HeroSummary, MineInfo, PlayerState, SessionEvent, Snapshot } from '#engine/session/protocol';
+import { type AiRole, type Roles, type RolesFinder } from './roles';
+import { Strength, type StrengthFormula } from './strength';
+import { ThreatMap } from './threat';
+/**
+ * A set of entities as the view gives them, in the snapshot's order, with the questions a brain asks as methods, each
+ * giving a set again, so that they chain: `ai.view.mine.withRole('worker').idle()`, `ai.view.enemies.near(home,
+ * 20).fighters()`. It reads as an array (`length`, `for..of`, `map`, `filter`, `find`, `some`, `every`, `forEach`,
+ * `first`, `at`; `items` is the plain array) but is not one: `map` and `filter` give plain arrays, `where` gives a set.
+ * (Not an `Array` subclass on purpose: the engines run `filter` and `find` on one several times slower, species
+ * lookup, and a think asks dozens.) A set is of one think: it reads the view it came from
+ *
+ * @beta
+ */
+export declare class UnitSet implements Iterable<EntityState> {
+    /** The view the set reads: the definitions, the roles, the grid */
+    readonly view: AiView;
+    /** The entities, as a plain array, in the snapshot's order */
+    readonly items: readonly EntityState[];
+    /** What this set remembers beside what is in sight (`known`): the structures seen before, for the view's own sets */
+    private readonly remembered;
+    /** The answers to the questions that are asked again and again, by their name */
+    private memo;
+    private idSet;
+    private strengthSum;
+    constructor(
+    /** The view the set reads: the definitions, the roles, the grid */
+    view: AiView, 
+    /** The entities, as a plain array, in the snapshot's order */
+    items?: readonly EntityState[], remembered?: EntityState[]);
+    /** How many */
+    get length(): number;
+    [Symbol.iterator](): Iterator<EntityState>;
+    /** The first of them: none in an empty set */
+    first(): EntityState | undefined;
+    /** Some of them, as an array's `slice` takes them: as a set */
+    slice(start?: number, end?: number): UnitSet;
+    /** The one at an index, from the end for a negative one */
+    at(index: number): EntityState | undefined;
+    /** As an array does: a plain array */
+    map<T>(fn: (entity: EntityState, index: number) => T): T[];
+    /** As an array does: a plain array. `where` gives a set */
+    filter(fn: (entity: EntityState, index: number) => unknown): EntityState[];
+    find(fn: (entity: EntityState, index: number) => unknown): EntityState | undefined;
+    some(fn: (entity: EntityState, index: number) => unknown): boolean;
+    every(fn: (entity: EntityState, index: number) => unknown): boolean;
+    forEach(fn: (entity: EntityState, index: number) => void): void;
+    /** A set of these, of the same view */
+    private make;
+    /** The answer to a question asked by name, worked out once */
+    private cached;
+    /** Those that satisfy a predicate, as a set */
+    where(predicate: (entity: EntityState, def: UnitTypeDef) => boolean): UnitSet;
+    /** Those of a unit type, or that count as it (`UnitTypeDef.provides`: a keep is a town hall too) */
+    ofType(type: string): UnitSet;
+    /** Those whose type has a role (`AiRole`: `'worker'`, `'hall'`, a game's own word) */
+    withRole(role: AiRole): UnitSet;
+    /** Those whose type has a tag: the kit's (`ranged`, `melee`, `hitsAir`) or the game's (`UnitTypeDef.ai.tags`) */
+    withTag(tag: string): UnitSet;
+    /** Those that fight: soldiers and heroes */
+    fighters(): UnitSet;
+    /** Those that gather and build (role `worker`) */
+    workers(): UnitSet;
+    /** The heroes among them */
+    heroes(): UnitSet;
+    /** The buildings among them, under construction too (`finished` leaves those out) */
+    buildings(): UnitSet;
+    /** The units among them: what moves, buildings and resources left out */
+    units(): UnitSet;
+    /** Those that stand finished: not under construction (a building turning into another type stands) */
+    finished(): UnitSet;
+    /** Those of mine with nothing to do: no order, and not inside something (a worker in a mine). Only one's own say what they do */
+    idle(): UnitSet;
+    /** Those in sight now: a structure seen before and out of sight is not (`EntityState.visible`) */
+    visible(): UnitSet;
+    /** Those with health left */
+    alive(): UnitSet;
+    /** Deposits of a resource with something left in them (a gold mine, a tree): for the view's `resources` */
+    ofResource(kind: ResourceKind): UnitSet;
+    /** Those of a player */
+    ofOwner(player: PlayerId): UnitSet;
+    /**
+     * Those within a distance of a point, in the snapshot's order. A big set is asked of the view's grid, a small one is
+     * scanned: the answer is the same
+     */
+    near(point: Vec2, radius: number): UnitSet;
+    /** The one nearest a point: none in an empty set. The first of two as near */
+    nearest(point: Vec2): EntityState | undefined;
+    /** The middle of them: none for an empty set */
+    centre(): Vec2 | undefined;
+    /**
+     * How strong they are together: the strength of each (`Strength.of`: by its stats and the health it has left),
+     * summed. 0 for what does not fight. Against someone in particular, ask `view.strength.odds(these, those)`
+     */
+    strength(): number;
+    /** Their ids, as a set: for "is it one of these" */
+    ids(): ReadonlySet<number>;
+    /** Whether an entity, by id, is one of these */
+    has(id: number): boolean;
+    /** These and another set's, together, in the snapshot's order, each once */
+    and(other: UnitSet): UnitSet;
+    /**
+     * These and what is remembered of them beside what is in sight: for `view.enemies`, the enemy structures seen before
+     * and out of sight now (`visible: false`), which may be gone. Ask it of the view's set before narrowing it
+     * (`view.enemies.known().buildings()`): a narrowed set remembers nothing more
+     */
+    known(): UnitSet;
+}
+/**
+ * The player a brain plays, as its picture of the game shows them: what the snapshot has of one's own player
+ * (`PlayerState.own`), beside who they are. Mutable for the think: a module that sends a `train` bumps `supplyUsed`
+ * itself, so that the next module does not queue past the cap before the command lands
+ *
+ * @beta
+ */
+export interface Me {
+    id: PlayerId;
+    name: string;
+    team: number;
+    /** The race they play (`raceOf`): left out in a game without races */
+    race?: string;
+    defeated: boolean;
+    /** What they have of each resource, by resource id */
+    resources: Record<ResourceKind, number>;
+    supplyUsed: number;
+    supplyCap: number;
+    /** The game's other pools of supply, by name (`GameRules.supply.pools`) */
+    supplies?: Record<string, {
+        used: number;
+        cap: number;
+    }>;
+    /** What the size of the army costs in income */
+    upkeep: {
+        tier: number;
+        name: string;
+        income: number;
+    };
+    upgrades: Record<string, number>;
+    researching: string[];
+    /** Types of the finished buildings the player has, with what those count as */
+    tech: string[];
+    heroes: HeroSummary[];
+    /** What the player is set to do, in a mission. Empty in a game without objectives */
+    objectives: ObjectiveState[];
+    /** What the game's `requirement` hook decided, where it differs from what the requirements say (`PlayerState.own.unlocks`) */
+    unlocks?: Record<string, Message | null>;
+    /** What the game's `available` hook decided, where it differs from what their race says (`PlayerState.own.availability`) */
+    availability?: Record<string, boolean>;
+    /**
+     * What the player gathers of each resource a minute, of late, as the brain's knowledge works it out
+     * (`Knowledge.own.income`): set by the brain after the view is made; left out for a view of no brain's
+     */
+    income?: Record<ResourceKind, number>;
+    /**
+     * What is free to spend this think, by resource: the resources less what is promised and held, less what the think
+     * spent so far (the brain's purse, `ai.purse`). Set by the brain after the view is made; left out for a view of no brain's
+     */
+    purse?: Readonly<Record<ResourceKind, number>>;
+}
+/**
+ * One of a player's bases, as the view clusters its buildings: around each building that takes deposits (a hall, what
+ * stands on a mine), or around any building where none does
+ *
+ * @beta
+ */
+export interface Base {
+    /** Where it is: the building it is around */
+    at: Vec2;
+    /** The building it is around: a hall where there is one */
+    centre: EntityState;
+    /** Its buildings, the centre among them */
+    buildings: UnitSet;
+}
+/**
+ * The events of a think, by kind (`AiView.events`): what happened in the tick of the picture that cannot be read from
+ * the state (deaths, damage, pings, the game's own)
+ *
+ * @beta
+ */
+export declare class ViewEvents {
+    /** Every event of the tick, in order */
+    readonly all: readonly SessionEvent[];
+    private byType;
+    constructor(
+    /** Every event of the tick, in order */
+    all: readonly SessionEvent[]);
+    /** The events of one kind, typed: `events.of('death')`, `events.of('ping')` */
+    of<T extends SessionEvent['type']>(type: T): Extract<SessionEvent, {
+        type: T;
+    }>[];
+    /** What an event of the game's own said this tick (`defineEvent`, replicated to this player), each time it was emitted */
+    game<T>(key: EventKey<T>): T[];
+}
+/**
+ * What the view is handed beside the snapshot: the last think's view, whose roles it keeps where the game's
+ * definitions stand, and a game's own way of finding the roles (`AiOptions.roles`)
+ *
+ * @beta
+ */
+export interface ViewOptions {
+    /** The view of the think before: what cost and did not change is kept from it (the roles, the player's reach) */
+    before?: AiView;
+    /** A game's own say on what unit types are for, in place of the kit's inference (`AiOptions.roles`) */
+    roles?: RolesFinder;
+    /** A game's own formula for how strong a unit is, in place of the kit's (`AiOptions.strength`, `BrainDef.strength`) */
+    strength?: StrengthFormula;
+}
+/**
+ * A computer player's reading of its picture of the game (`Brain.view`): the snapshot of its seat, indexed once a
+ * think and queried as sets (`UnitSet`): `mine`, `allies`, `enemies` (what is in sight now; `enemies.known()` adds
+ * the structures remembered), `hostile` (enemies and creeps), `creeps`, `neutral`, `resources`, `all`; the player's
+ * own state (`me`); what unit types are for (`roles`, `typesOf`); where things are (`near`, `home`, `bases`, `mines`,
+ * `camps`, `regions`); how strong things are (`strength`: `odds`, `matchup`, `counterFor`) and where the strength
+ * is (`threat`, the map made when first asked); what the game tells this player (`report`, `component`,
+ * `events.game`); and the map's facts (`canPlace`, `findPath`, `cellAt`). Made from the snapshot as the think begins; a set of
+ * it is good for the think
+ *
+ * @beta
+ */
+export declare class AiView {
+    /** The picture it reads: the snapshot of the seat, plain data, the only input a brain has */
+    readonly snapshot: Snapshot;
+    /** The seat, for the map's facts: the ground, the regions, the mines, the camps */
+    readonly session: GameSession;
+    /** The game's definitions, as the seat has them */
+    readonly registry: Registry;
+    /** The player it reads for */
+    readonly playerId: PlayerId;
+    /** Every entity the player knows of, in the snapshot's order: in sight, and the structures remembered */
+    readonly all: UnitSet;
+    /** The player's own units and buildings */
+    readonly mine: UnitSet;
+    /** The allies' units and buildings (one's own left out) */
+    readonly allies: UnitSet;
+    /** The enemies' units and buildings in sight now, creeps left out. `enemies.known()` adds their structures seen before */
+    readonly enemies: UnitSet;
+    /** Whatever attacks the player and is in sight: enemies and creeps */
+    readonly hostile: UnitSet;
+    /** The creeps in sight: hostile to everyone, no one's rival */
+    readonly creeps: UnitSet;
+    /** What is nobody's and not a resource, in sight: a shop, a neutral building. `neutral.known()` adds those seen before */
+    readonly neutral: UnitSet;
+    /** The deposits the player knows of: mines and trees in sight, and those seen before (`ofResource(kind)` for one kind) */
+    readonly resources: UnitSet;
+    /** Every player, as the snapshot has them */
+    readonly players: readonly PlayerState[];
+    /** The player a brain plays: resources, supply, tech, heroes, objectives. Mutable for the think */
+    readonly me: Me;
+    /** What happened in the tick of the picture, by kind */
+    readonly events: ViewEvents;
+    /** What unit types are for, by the game's definitions: found once, kept while they stand */
+    readonly roles: Roles;
+    /** The unit types the player has or can come to make: what the roles are narrowed to for it (`typesOf`) */
+    readonly reachable: ReadonlySet<string>;
+    /**
+     * How strong things are: a unit, a group, one force against another (`odds`), what answers what (`counterFor`). The
+     * kit's formula unless the brain was given one; what a type's numbers come to is kept between thinks
+     */
+    readonly strength: Strength;
+    private threatMap;
+    private readonly grid;
+    private readonly byIdMap;
+    private readonly indexById;
+    private readonly playerById;
+    private readonly namesMap;
+    private readonly typesByRole;
+    /** The race the view's reach was found for: a player given another race finds it anew */
+    private readonly race;
+    private basesFound;
+    private lanesFound;
+    constructor(
+    /** The picture it reads: the snapshot of the seat, plain data, the only input a brain has */
+    snapshot: Snapshot, 
+    /** The seat, for the map's facts: the ground, the regions, the mines, the camps */
+    session: GameSession, options?: ViewOptions);
+    /**
+     * Where the strength is: an influence map over the picture, the friendly and the enemy strength that reaches each
+     * cell of a coarse grid, by layer (`threat.at(point)`, `around`, `hot`). Made when first asked, once a think
+     */
+    get threat(): ThreatMap;
+    /** The tick of the picture */
+    get tick(): number;
+    /** Seconds into the game, as of the picture */
+    get time(): number;
+    /** Items lying on the ground where the player sees it */
+    get items(): readonly GroundItemState[];
+    /** What the game tells the player about itself (`GameModule.report`): a wave number, a score */
+    get report(): Record<string, unknown> | undefined;
+    /** An entity the player knows of, by id: none for one gone, or never seen */
+    byId(id: number | undefined): EntityState | undefined;
+    /** The definition of an entity's type */
+    def(entity: EntityState): UnitTypeDef;
+    /** A player, by id */
+    player(id: PlayerId): PlayerState | undefined;
+    /** What an entity's owner is to the player: `self`, `ally`, `enemy`, `neutral`. Creeps are `enemy` */
+    relation(entity: EntityState): PlayerState['relation'] | undefined;
+    /** Whether an entity is a rival's, or a creep */
+    isHostile(entity: EntityState): boolean;
+    /** Whether an entity is a creep's */
+    isCreep(entity: EntityState): boolean;
+    /** Whether an entity is the player's own or an ally's */
+    isFriendly(entity: EntityState): boolean;
+    /** The roles of an entity's type, or of a type by id */
+    roleOf(entity: EntityState | string): readonly AiRole[];
+    /** Whether an entity's type, or a type by id, has a role */
+    hasRole(entity: EntityState | string, role: AiRole): boolean;
+    /**
+     * The unit types with a role that are the player's own: those it has or can come to make (`reachable`), in the
+     * game's order, so that the first of a kind is the one meant first. A game of two races gives each player its own
+     */
+    typesOf(role: AiRole): readonly UnitTypeDef[];
+    /** Whether the player has the finished buildings something asks for (`UnitTypeDef.requires`) */
+    has(requires: readonly string[] | undefined): boolean;
+    /** The player's home: its first hall, or its first building where it has no hall. None with no buildings */
+    home(): EntityState | undefined;
+    /**
+     * The player's bases: its buildings clustered around what takes deposits (halls, what stands on a mine), each to
+     * the nearest of those within reach; and where there is nothing that takes deposits (a game with no economy), around
+     * any building, the clusters made as the buildings come. Home first
+     */
+    bases(): readonly Base[];
+    /** The deposits near a base, in sight or remembered: what it gathers from */
+    resourcesNear(base: Base | Vec2, radius?: number): UnitSet;
+    /**
+     * Where the game's money is mined, as the map shows them, under the fog too (`GameSession.mines`): what a computer
+     * player looks to for another hall. Where the session does not say, the deposits of the money it knows of
+     */
+    mines(): readonly MineInfo[];
+    /** The creep camps of the map: where they are is part of the map, which everyone knows */
+    camps(): readonly CampInfo[];
+    /**
+     * The lanes of the map (`GameSession.lanes`: its paths with a spawner of each side at their ends), as the map shows
+     * them: none where the session does not say, or the map has none. Read once a think
+     */
+    lanes(): readonly Lane[];
+    /** The regions of the map, by name, as the map was made */
+    get regions(): readonly MapRegion[];
+    /** A region of the map, by name */
+    region(name: string): MapRegion | undefined;
+    /** Whether a point is in a named region of the map. False for a region the map does not have */
+    inRegion(name: string, point: Vec2): boolean;
+    /** An entity the map or the rules named (`world.named`), where the player knows of it: "the gate", "the hero" */
+    named(name: string): EntityState | undefined;
+    /** What the game replicates to this player of an entity (`Component.replicate`), with the component's type */
+    component<T, S = T>(entity: EntityState, component: Component<T, S>): S | undefined;
+    /** Whether the player could build this here, as far as it can tell: no on ground it has not explored */
+    canPlace(unitType: string, point: Vec2): boolean;
+    /** The value of one of the game's layers of cells at a point (`Terrain.cells`, `CellLayerDef`): 0 where it is not painted */
+    cellAt(layer: string, x: number, z: number): number;
+    /** One of the game's layers of cells whole, row by row (`Terrain.cells`), to read and not to change: none where nothing is painted */
+    cells(layer: string): Readonly<Uint8Array> | undefined;
+    /** The route a unit would take, over the ground the player knows */
+    findPath(from: Vec2, to: Vec2, flying?: boolean): Vec2[] | null;
+    /** What the view found of the roles, for the debug tools: each role and its types among the player's own */
+    inspect(): Record<string, unknown>;
+}

package/dist/ai/waves.d.ts

@@ -0,0 +1,126 @@
+import { type Vec2 } from '#engine/math';
+import { type Brain } from './brain';
+import { type AiModuleDef } from './module';
+import { type AiCondition } from './rules';
+/**
+ * What a wave is made of: so many of each unit type (by id) or role (`caster`, a game's own), by name, under a condition
+ *
+ * @beta
+ */
+export interface AttackGroup {
+    /** Its name: what a wave names it by */
+    id: string;
+    /** So many of each unit type or role: `{ footman: 4, rifleman: 2 }` */
+    units: Record<string, number>;
+    /** Only while this holds: a wave of a group whose condition fails is skipped as its own would be */
+    when?: AiCondition;
+}
+/**
+ * Where a wave goes: their base nearest home, their weakest (the fewest towers and army seen there), an expansion of
+ * theirs, their army as last seen, a place, or a function of the brain
+ *
+ * @beta
+ */
+export type WaveTarget = 'nearestBase' | 'weakestBase' | 'expansion' | 'army' | Vec2 | ((ai: Brain) => Vec2 | undefined);
+/**
+ * One wave (the classic attack wave): its group, when it goes, how much of it is enough, how long it gathers, whether it
+ * goes again, together or not, and where to
+ *
+ * @beta
+ */
+export interface AttackWave {
+    /** Its group: a group's name (`WavesOptions.groups`), or the units in place (`{ footman: 4 }`) */
+    group: string | Record<string, number>;
+    /** Seconds after the wave before it (after the start, for the first) before it may go: 0 when left out */
+    after?: number;
+    /** The share of its group that is enough to go with, 0 to 1: all of it when left out */
+    minForces?: number;
+    /** Seconds it gathers at the rally before it goes, whoever is late: 15 when left out */
+    gatherFor?: number;
+    /** Whether it goes again once sent: `true` for ever, a number for so many times in all. Once when left out */
+    repeat?: boolean | number;
+    /** Only when this holds as its turn comes: a wave whose condition fails is skipped */
+    when?: AiCondition;
+    /** Whether it waits for its team's attack together (`TeamOptions.together`, C5) */
+    together?: boolean;
+    /** Where it goes: their base nearest home when left out */
+    target?: WaveTarget;
+    /** Where it gathers: a place, or a name the map or the rules gave. A little out of home towards the target when left out */
+    rally?: Vec2 | string;
+}
+/**
+ * How a brain sends its waves (`BrainDef.waves`; the seat's `AiOptions.waves` and `groups`, the data of it, go over)
+ *
+ * @beta
+ */
+export interface WavesOptions {
+    /** The groups waves are made of, by name */
+    groups?: AttackGroup[];
+    /** The waves, in order, or a function giving the wave whose turn it is (by its index), none for no more */
+    waves?: AttackWave[] | ((ai: Brain, index: number) => AttackWave | undefined);
+    /** Whether a wave's group is trained (wants of the production plan): yes when left out. No for units that are given (a lanes game) */
+    train?: boolean;
+    /** How important a wave's units are to the purse, as wants: 30 when left out (under a hall, a barracks, a hero) */
+    priority?: number;
+}
+/**
+ * What the waves module remembers between thinks, as a save keeps it
+ *
+ * @beta
+ */
+export interface WavesMemory {
+    v: 1;
+    /** The index of the wave whose turn it is: the waves sent and skipped before it */
+    index: number;
+    /** Where in the list it is (for a list), and how many times the wave there went */
+    entry: number;
+    went: number;
+    /** The tick the last wave went at (or was skipped at): what the next one's `after` counts from */
+    last: number;
+    /** The waves sent, the last ten: index, squad, size, target, tick */
+    sent: {
+        index: number;
+        squad: string;
+        size: number;
+        at: Vec2;
+        tick: number;
+    }[];
+    /** How many were skipped, their condition failing */
+    skipped: number;
+}
+/**
+ * The waves as the report shows them (`AiReport.waves`): the wave whose turn it is, its group as it stands, when it may go;
+ * the waves sent
+ *
+ * @beta
+ */
+export interface WavesReport {
+    index: number;
+    current?: {
+        units: Record<string, [free: number, wanted: number]>;
+        in: number;
+        ready: boolean;
+        status: string;
+    };
+    sent: {
+        index: number;
+        squad: string;
+        size: number;
+        at: [number, number];
+        tick: number;
+    }[];
+    skipped: number;
+}
+/**
+ * The waves module: the wave whose turn it is, each think (`ai.waves.think`): its group wanted, sent once enough of it is
+ * free and its time has come, gathering at the rally, then attacking. Idle without waves given. With how it sends waves
+ * where the brain's definition and the seat's options say nothing (`WavesOptions`)
+ *
+ * @beta
+ */
+export declare const waves: (options?: WavesOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        waves?: WavesMemory;
+    }
+}