@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/ai/squads.d.ts

@@ -0,0 +1,429 @@
+import type { OrderInit } from '#engine/registry';
+import type { AiArea } from './area';
+import { type Vec2 } from '#engine/math';
+import type { EntityState } from '#engine/session/protocol';
+import { type Brain } from './brain';
+import { type AiModuleDef } from './module';
+import { UnitSet } from './view';
+import type { TaskCommon, TaskData, TaskDef, TaskDone, TaskOrder, TaskState } from './task';
+/**
+ * How a squad behaves around its task (`SquadsOptions`, `ai.squads.make(name, units, options)`): when it regroups,
+ * reinforces, retreats. Plain data, kept in a save
+ *
+ * @beta
+ */
+export interface SquadOptions {
+    /**
+     * How far from its middle a unit may be before it counts as strayed: what a regroup brings in. Grows with the squad
+     * when left out (8, and three times the square root of its size above that: 12 for sixteen units)
+     */
+    spread?: number;
+    /** The share of its units strayed (`spread`) at which it stops to regroup, on its way and out of a fight: 0.4. `false` never */
+    regroupWhen?: number | false;
+    /** Whether it makes up what it lost since its task began from the pool (the idle fighters nothing holds): no when left out */
+    reinforce?: boolean;
+    /**
+     * Its odds in a fight (`Strength.odds`) under which it falls back home, away from home: 0.3. `false` fights on to the
+     * last (a mission's guards)
+     */
+    retreatAt?: number | false;
+    /** How near home it fights on whatever the odds: there is nowhere to fall back to. 20 when left out */
+    home?: number;
+    /**
+     * Whether the micro module (`micro()`, C2) fights for it once it is in a fight: focus fire, kiting, fleeing, siege.
+     * Yes when left out; `false` for a squad left to its units (a scout, a mission's guards on an order of the game's)
+     */
+    micro?: boolean;
+}
+/**
+ * How a brain's squads behave, where a squad says nothing for itself (`BrainDef.squads`, the seat's `AiOptions.squads`
+ * over it); and the tasks of the game's own (`defineTask`) a save of the brain may name
+ *
+ * @beta
+ */
+export interface SquadsOptions extends SquadOptions {
+    /** Tasks of the game's own: registered with the brain, so that a squad on one is carried on after a load */
+    tasks?: TaskDef[];
+}
+/**
+ * A squad as the brain remembers it: plain data, kept in a save
+ *
+ * @beta
+ */
+export interface SquadData {
+    /** Unique among the brain's squads */
+    name: string;
+    /** Who it belongs to: a goal's id, a rule's or a module's hold (`squad:<name>` for one of its own) */
+    owner: string;
+    /** Its units, by id, in the picture's order */
+    units: number[];
+    /** How it behaves: its own, over the brain's */
+    options: SquadOptions;
+    /** What it is doing. None for a squad told nothing yet */
+    task?: TaskState;
+    /** How many units its task began with, or was given since: what reinforcements make up */
+    size: number;
+    /** The tick it was made at */
+    made: number;
+    /** How many times it fell back from a fight it was losing */
+    retreats: number;
+    /** The last time its units or its task changed, and why, in words */
+    changed?: {
+        tick: number;
+        why: string;
+    };
+    /** The tick it may next call for reinforcements */
+    nextReinforce?: number;
+}
+/**
+ * What the squads remember between thinks, for a save
+ *
+ * @beta
+ */
+export interface SquadsMemory {
+    v: 1;
+    squads: SquadData[];
+}
+/**
+ * A squad as the report shows it: who it belongs to, its units and their strength, where it is, its task and how it goes
+ *
+ * @beta
+ */
+export interface SquadReport {
+    name: string;
+    owner: string;
+    units: number[];
+    strength: number;
+    /** Its middle */
+    at?: [number, number];
+    size: number;
+    task?: {
+        kind: string;
+        phase: string;
+        since: number;
+        at?: [number, number];
+        done?: TaskDone;
+    };
+    retreats: number;
+    changed?: {
+        tick: number;
+        why: string;
+    };
+}
+/**
+ * A squad of the brain (`ai.squads.make`, `named`, `all`): a handle over its data, with the task methods. A squad's
+ * units are as of the think's picture: the dead and those its owner no longer holds are dropped as the squads module
+ * looks at it
+ *
+ * @beta
+ */
+export declare class Squad {
+    /** The squads it is one of */
+    readonly squads: Squads;
+    /** What it is, as plain data: what a save keeps */
+    readonly data: SquadData;
+    constructor(
+    /** The squads it is one of */
+    squads: Squads, 
+    /** What it is, as plain data: what a save keeps */
+    data: SquadData);
+    /** Its name: unique among the brain's squads */
+    get name(): string;
+    /** Who it belongs to: the goal, rule or module that made it */
+    get owner(): string;
+    /** What it is doing: none for a squad told nothing yet */
+    get current(): TaskState | undefined;
+    /** How its task ended: none while it goes on, or while it has none */
+    get done(): TaskDone | undefined;
+    /** Whether it has nothing to do: no task, or its task is over */
+    get idle(): boolean;
+    /** Whether it is still one of the brain's squads: not once disbanded */
+    get alive(): boolean;
+    /** How it behaves: its own options over the brain's */
+    get options(): SquadOptions;
+    /** Its units, as of the think's picture: those alive and the player's */
+    units(): UnitSet;
+    /** How many units it has */
+    get length(): number;
+    /** How strong it is together (`UnitSet.strength`) */
+    strength(): number;
+    /** Its middle: none with no unit left */
+    centre(): Vec2 | undefined;
+    /**
+     * How far from its middle a unit may be before it counts as strayed (`SquadOptions.spread`): grows with the squad
+     * when not given
+     */
+    spread(): number;
+    /** Adds units: what its owner may have (see `Squads.make`), taken out of any other squad */
+    add(units: Iterable<EntityState | number>, why?: string): this;
+    /** Takes units out: they go back to the pool (its owner lets go of them) */
+    remove(units: Iterable<EntityState | number>, why?: string): this;
+    /** Disbands it: its units go back to its owner (a goal's), or to the pool (a squad of its own) */
+    disband(why?: string): void;
+    /** Writes down the last change of its units or task, for the report */
+    changed(why: string): void;
+    /**
+     * Gives it a task: one of the kit's by its word (`attack`), or of the game's (`defineTask`, by its def or its id).
+     * What it was doing is over. Its first orders go at once; the squads module watches it from then on
+     */
+    task<D extends object, M extends object>(def: TaskDef<D, M>, data: D & TaskCommon): this;
+    task(kind: string, data?: TaskData): this;
+    /** Ends its task, saying how: what a task's `think` calls once it is over */
+    finish(done: TaskDone): void;
+    /**
+     * Goes to fight at a place or a target (an entity, or its id): attack-moves there, fighting what it meets, regroups
+     * on the way, retreats on the odds. Done `cleared` once there with nothing left to fight, `lost` when the target is
+     * gone. `avoid: 'army'` goes round where their strength is on the way (the threat map and their army as last seen),
+     * when there is a way round. `via`: a place to go by on the way (a way of its own: Random Paths). `then`: the task after it
+     */
+    attack(target: Vec2 | EntityState | number, options?: {
+        avoid?: 'army' | false;
+        via?: Vec2;
+        then?: TaskOrder;
+    }): this;
+    /** Attack-moves to a place, as a group of units would on a click: the squad's attack without its regroup */
+    attackMove(at: Vec2, options?: {
+        then?: TaskOrder;
+    }): this;
+    /**
+     * Holds a place against what comes within `radius` of it (16 when left out): fights what comes, goes back once it is
+     * gone. Never over by itself: its owner says when
+     */
+    defend(at: Vec2, radius?: number): this;
+    /** Goes to a place (where it stands when left out) and holds it: stands, fighting only what comes within reach */
+    hold(at?: Vec2): this;
+    /** Walks to a place, fighting nothing on the way. Done `arrived` */
+    move(at: Vec2, options?: {
+        then?: TaskOrder;
+    }): this;
+    /** Goes with a unit of the player's or an ally's, fighting what comes near it. Done `lost` when it is gone */
+    escort(target: EntityState | number): this;
+    /**
+     * Goes for the workers at a place, round where their army is (`avoid: 'army'` unless told otherwise), the workers
+     * first once there. Done `cleared`
+     */
+    harass(at: Vec2, options?: {
+        avoid?: 'army' | false;
+        then?: TaskOrder;
+    }): this;
+    /** Goes to look at places, one after the other: each is looked at once in sight, or reached as near as the ground lets. Done `arrived` */
+    scout(points: readonly Vec2[]): this;
+    /**
+     * Gathers at a rally point before going on (`then`): until `minForces` of it (a share, 1 when left out) is there,
+     * or `seconds` have gone by. Done `arrived`, and on to `then`
+     */
+    gather(at: Vec2, options?: {
+        minForces?: number;
+        seconds?: number;
+        then?: TaskOrder;
+    }): this;
+    /** Falls back to a place (home when left out), fighting nothing on the way. Done `retreated` */
+    retreat(to?: Vec2, why?: string): this;
+    /**
+     * Walks a round of places, one after the other and back to the first, fighting what it meets on the way (an
+     * attack-move to each): a mission's guards on the road, a watch round the walls. Never over by itself: its owner
+     * says when
+     */
+    patrol(points: readonly Vec2[]): this;
+    /** Takes a camp of creeps: fights there until the camp is cleared. Done `cleared` */
+    creep(camp: Vec2): this;
+    /**
+     * Carried by transports to a place it cannot walk to, let out on the land nearest it (the `drop` task): done
+     * `landed`, then what `then` says (an attack where it landed)
+     */
+    drop(at: Vec2, transports: readonly number[], options?: {
+        then?: TaskOrder;
+    }): this;
+    /** Sends its units an order (`move`, `hold`, the game's), all or some of them: counted as the task's last */
+    order(order: OrderInit, units?: readonly number[], queue?: boolean): void;
+    /**
+     * Puts its units, all or some, in a stance, where the game has stances (`withStances`): those not in it already. A
+     * squad that holds is defensive, one sent to fight aggressive
+     */
+    setStance(id: string, units?: readonly number[]): void;
+    /**
+     * Sends its units to take a capture point of the game's (`withCapture`), by its id: they fight their way in and
+     * stand in it until it is theirs (`captured`), or it is gone (`lost`)
+     */
+    capture(id: string): this;
+    /** Sends its units, all or some, to fight at a place, or a target there: an attack-move, or an attack */
+    fight(at: Vec2, units?: readonly number[], target?: number, queue?: boolean): void;
+    /**
+     * Of some of its units, those the picture has: a unit that died since the squads were last looked at (a task given by a
+     * goal before the `squads()` module ran) is no one to order
+     */
+    private living;
+    /** Its units that stand with nothing to do: what lost its order, or never had one */
+    idleUnits(): EntityState[];
+    /** Whether its last order was sent long enough ago to send one again (`RESEND` seconds): what keeps a stuck unit from being told every think */
+    mayResend(): boolean;
+    private sent;
+}
+/**
+ * Some squads together (`ai.squads.all()`, `idle()`): read as a list, told as one (`ai.squads.all().defend(home)`:
+ * each squad is given the task)
+ *
+ * @beta
+ */
+export declare class SquadGroup implements Iterable<Squad> {
+    /** The brain they are of */
+    readonly ai: Brain;
+    /** The squads */
+    readonly squads: readonly Squad[];
+    constructor(
+    /** The brain they are of */
+    ai: Brain, 
+    /** The squads */
+    squads: readonly Squad[]);
+    [Symbol.iterator](): Iterator<Squad>;
+    /** How many squads */
+    get length(): number;
+    /** Their units together, as a set */
+    units(): UnitSet;
+    /** How strong they are together */
+    strength(): number;
+    /** Each given the same task */
+    task<D extends object, M extends object>(def: TaskDef<D, M>, data: D & TaskCommon): this;
+    task(kind: string, data?: TaskData): this;
+    attack(target: Vec2 | EntityState | number, options?: {
+        avoid?: 'army' | false;
+        then?: TaskOrder;
+    }): this;
+    defend(at: Vec2 | undefined, radius?: number): this;
+    hold(at?: Vec2): this;
+    move(at: Vec2): this;
+    retreat(to?: Vec2): this;
+    /** Each disbanded */
+    disband(why?: string): void;
+}
+/**
+ * A brain's squads (`ai.squads`): made by its goals, rules and modules, watched by the `squads()` module each think
+ * (`think`): the dead dropped, what the owner let go of let go of, each task looked at, regroups, retreats and
+ * reinforcements seen to. Kept in the brain's memory (`BrainMemory.squads`)
+ *
+ * @beta
+ */
+export declare class Squads implements AiArea {
+    /** The brain they are the squads of */
+    readonly ai: Brain;
+    /** Its id among the brain's areas: what its memory and its report are kept under */
+    readonly id = "squads";
+    /** What the log says where a save's memory of it is of a shape it does not read */
+    readonly afresh = "the save remembers the computer player\u2019s squads in a shape this brain does not read: they are let go of";
+    private list;
+    private readonly tasks;
+    private thoughtAt;
+    /** How a squad behaves where it says nothing and the brain's settings say nothing either: the `squads()` module's */
+    private moduleOptions;
+    constructor(
+    /** The brain they are the squads of */
+    ai: Brain, 
+    /** The tasks of the game's own its squads may be on (`AiSettings.squads.tasks`) */
+    tasks?: readonly TaskDef[]);
+    /** Puts the `squads()` module's options under the brain's settings */
+    configure(options: SquadOptions): void;
+    /** How a squad behaves where it says nothing: the module's options, the brain's settings over them (`ai.settings.squads`) */
+    get defaults(): SquadOptions;
+    /** Registers a task of the game's own, so that a squad on it is carried on after a load. Given by `BrainDef.squads.tasks` */
+    define(def: TaskDef): void;
+    /** A kind of task by its id: the kit's, or one registered */
+    taskDef(id: string): TaskDef | undefined;
+    /**
+     * Makes a squad of units under a name (one of that name already is disbanded first), with how it behaves where it
+     * is not the brain's way. Whose it is (`owner`): what `options.owner` names (a goal makes its own with
+     * `claimed.squad`), else its own (`squad:<name>`). A goal's squad is made of what the goal holds, and what
+     * nothing holds is given to it; a squad of a rule or a module takes its units from whatever holds them (the goal
+     * told: `stop('told')`) and holds them until it is disbanded. A unit in another squad leaves it
+     */
+    make(name: string, units: Iterable<EntityState | number>, options?: SquadOptions & {
+        owner?: string;
+    }): Squad;
+    /**
+     * Puts units in a squad: those its owner may have (held by it, or given from the pool for a goal; taken for a rule's
+     * or a module's), out of any other squad. Those put in, by id
+     */
+    enlist(squad: Squad, wanted: number[]): number[];
+    /** A squad by name: none for one there is not */
+    named(name: string): Squad | undefined;
+    /** Every squad, as made */
+    all(): SquadGroup;
+    /** The squads with nothing to do: told nothing, or their task over */
+    idle(): SquadGroup;
+    /** The squads a goal, rule or module owns */
+    of(owner: string): SquadGroup;
+    /** The squad a unit is in, by the unit or its id: none for a unit in none */
+    squadOf(unit: EntityState | number): Squad | undefined;
+    /** The player's units nothing holds (`ai.goals.pool`, buildings left out): what a squad is made of, or reinforced from */
+    pool(): UnitSet;
+    /** Disbands a squad: a squad that held its units itself lets them go back to the pool */
+    disband(squad: Squad, why?: string, letGo?: boolean): void;
+    /**
+     * Gives a squad a task: what it was doing is over, and the new one's first orders go at once. What it has now is what
+     * reinforcements make up to from then on (`SquadData.size`), but for a task it goes on to by itself (`going on`: a
+     * task's `then`, a fall back on the odds), which keeps what the task before was given. The task it is on given
+     * again changes nothing, its `size` kept: what it lost since is what reinforcements make up
+     */
+    give(squad: Squad, kind: string | TaskDef, data: TaskData, goingOn?: boolean): void;
+    /**
+     * Looks at every squad, once a think: its units (the dead, and what its owner let go of, dropped; a squad of a goal
+     * that stopped disbanded), then its task (retreat on the odds, the task's own look, regroup, reinforcements). What the
+     * `squads()` module runs; a module may call it sooner
+     */
+    think(): void;
+    /** The squads still to be looked at this think, where a pass stopped for the tick's budget, and the next of them */
+    private advancing;
+    private cursor;
+    /** Every squad's units looked at, as a think begins: the dead and what its owner let go of dropped, a squad with none left disbanded */
+    private prune;
+    /** One squad's think: retreat on the odds, the task's own look, then on to the next task, regroup, reinforcements */
+    private advance;
+    /**
+     * Whether a squad in a fight away from home is losing it (its odds under `retreatAt`), and so falls back: its task
+     * becomes `retreat`, home, and it is said why
+     */
+    private losing;
+    /**
+     * Regroups a squad that is strung out on its way: too many of its units (`regroupWhen`) further than `spread` from its
+     * middle, and no fight near. It gathers on its middle and goes on once together, or once it has waited long enough
+     */
+    private regroup;
+    /**
+     * Makes up what a squad lost since its task began from the pool: the idle fighters nothing holds, the nearest
+     * first, given to its owner and sent to join it. Never a hero: one crossing the map alone to a fight dies on the
+     * way, and heroes are sent with a squad, not after it. Not while it falls back, nor more often than every few seconds
+     */
+    private reinforce;
+    /** The place a squad's task is about: none for a task about no place */
+    whereOf(squad: Squad): Vec2 | undefined;
+    /**
+     * The way to a place round where the enemy is strong (`avoid: 'army'`): the waypoint to go by, where the straight way
+     * crosses their strength (the threat map, with what is remembered of their towers, and their army as last seen) and a
+     * way round is less hot, tried on either side and then further out, twice at most. A heuristic, not a safe route:
+     * none where the straight way is cool enough, or where there is no way round (`note` says so)
+     */
+    route(from: Vec2, to: Vec2, squad: Squad): {
+        waypoints: Vec2[];
+        note?: string;
+    };
+    /** Every squad as the report shows it */
+    report(): SquadReport[];
+    /** What the squads are, for a save: copies */
+    /** Whether it has anything to remember now: one that does not is left out of a save */
+    remembers(): boolean;
+    save(): SquadsMemory;
+    /** Takes back what `save` gave: whether it was read. A squad on a task the brain does not know is kept, and does nothing */
+    restore(memory: unknown): boolean;
+}
+/**
+ * The squads module: looks at every squad of the brain each think (`ai.squads.think`), after the goals, the rules and
+ * the words that make them: their units, their tasks, regroups, retreats, reinforcements. With how they behave where the
+ * brain's definition and the seat's options say nothing
+ *
+ * @beta
+ */
+export declare const squads: (options?: SquadsOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        squads?: SquadsMemory;
+    }
+}

package/dist/ai/strength.d.ts

@@ -0,0 +1,167 @@
+import { type Stats, type UnitTypeDef } from '#engine/defs';
+import type { Registry } from '#engine/registry';
+import type { EntityState } from '#engine/session/protocol';
+import type { AiView, UnitSet } from './view';
+/**
+ * A force to weigh: a set of entities as the view gives them (`view.enemies.fighters()`), a plain array of them, or
+ * types with counts (`{ footman: 6, gryphon: 2 }`), as the knowledge keeps an army it saw (`ArmySighting.types`,
+ * `TypeSeen`): those are taken at full health with the stats their type starts with
+ *
+ * @beta
+ */
+export type Force = UnitSet | readonly EntityState[] | Readonly<Record<string, number>>;
+/**
+ * What a strength formula is given of one unit or type: its definition, its stats as they stand (the type's, with what
+ * the snapshot shows of a seen unit's own: upgrades, items, levels, buffs), the entity where there is one (its health,
+ * its level) and the view, for the roles and the registry
+ *
+ * @beta
+ */
+export interface StrengthInput {
+    /** The unit type */
+    def: UnitTypeDef;
+    /** The stats as they stand: the type's, with a seen unit's own over them */
+    stats: Readonly<Stats>;
+    /** The unit, where one is weighed; none for a type */
+    entity?: EntityState;
+    /** 0..1: the health it has left, as a part of its most; 1 for a type */
+    health: number;
+    /** The picture it is weighed in: for the roles (`view.roles`) and the definitions (`view.registry`) */
+    view: AiView;
+}
+/**
+ * How strong a unit or a type is, as a number that adds up over a group: the kit's formula (`defaultStrength`), or a
+ * game's own in its place (`AiOptions.strength`, `BrainDef.strength`). Given the unit's definition and stats as they
+ * stand, the entity where there is one, and the health it has left as a part of its most. Must give a finite number,
+ * 0 for what does not fight
+ *
+ * @beta
+ */
+export type StrengthFormula = (input: StrengthInput) => number;
+/**
+ * What one side of a matchup is worth against the other, with how (`Strength.matchup`): the strength of each of its
+ * units against the opponent, summed
+ *
+ * @beta
+ */
+export interface Matchup {
+    /** The side's strength against the opponent: 0 where none of it can hit any of them */
+    strength: number;
+    /** The side's strength on its own, against no one in particular */
+    plain: number;
+    /** How many fought: units with health left and an attack */
+    count: number;
+}
+/**
+ * How well a type answers a force (`Strength.counterFor`): its strength against them over its plain strength. 1 is as
+ * good as it is against anyone, 0 is useless (it cannot hit them), above 1 it is the answer
+ *
+ * @beta
+ */
+export interface Counter {
+    /** The type ranked */
+    def: UnitTypeDef;
+    /** Its strength against the force over its plain strength */
+    score: number;
+}
+/**
+ * What a game declares a type good against (`UnitTypeDef.ai.counters`): a tag (`'air'`), a role (`'siege'`) or a type
+ * id, as a word, or with how much it counts (`weight`, 0.5 when left out: a unit whose whole opponent it counters is
+ * worth half again)
+ *
+ * @beta
+ */
+export type CounterHint = string | {
+    target: string;
+    weight?: number;
+};
+/**
+ * The kit's formula for how strong a unit is, under a square root so that it adds up over a group (Lanchester):
+ *
+ * `sqrt(toughness × offence) × hero`, where
+ *
+ * - `toughness` is the health it has left, more by its armour and magic resist (the middle of the two, since no
+ *   opponent is in question: 100 of armour doubles it, as the engine's `mitigation` halves what arrives),
+ * - `offence` is its damage a second (`attackDamage × attackSpeed`), up to a quarter more for reach (at 10 of range)
+ *   and a tenth for speed (at 8),
+ * - `hero` is 1 for a unit, and `1.1 + 0.1 × (level − 1)` for a hero: its spells, and more as they level.
+ *
+ * 0 for what has no attack: a building that does not shoot, a worker with no weapon. A declared strength
+ * (`UnitTypeDef.ai.strength`) is taken in its place by `Strength`, before this is asked
+ *
+ * @beta
+ */
+export declare const defaultStrength: StrengthFormula;
+/**
+ * How strong things are, to a brain (`AiView.strength`, `Brain.strength`): one unit or type (`of`), a group (`sum`,
+ * what `UnitSet.strength()` asks), one force against another (`matchup`, `odds`), and what to train against what was
+ * seen (`counterFor`). The formula is the kit's (`defaultStrength`) unless the brain was given one
+ * (`AiOptions.strength`, `BrainDef.strength`); a type's declared strength (`UnitTypeDef.ai.strength`) goes before
+ * either. What a type's numbers come to is worked out once and kept across thinks; a seen unit's own stats
+ * (`EntityState.stats`: its upgrades, items, levels, buffs) are read each time
+ *
+ * @beta
+ */
+export declare class Strength {
+    /** The game's definitions */
+    readonly registry: Registry;
+    /** The formula a unit's strength comes from: the kit's unless the brain was given one */
+    readonly formula: StrengthFormula;
+    private readonly profiles;
+    private readonly plainByType;
+    constructor(
+    /** The game's definitions */
+    registry: Registry, 
+    /** The formula a unit's strength comes from: the kit's unless the brain was given one */
+    formula?: StrengthFormula);
+    /**
+     * How strong a unit is, with the health it has left and its own stats as the snapshot shows them; or a type at full
+     * health with the stats it starts with. 0 for what does not fight. A finite number always
+     */
+    of(what: EntityState | UnitTypeDef | string): number;
+    /** A type at full health: worked out once */
+    private ofType;
+    /** The formula asked, the declared strength first; whatever comes back made finite */
+    private evaluate;
+    /** The stats of a seen unit as they stand: its type's, with its own over them (`EntityState.stats`: upgrades, items, levels, buffs) */
+    statsOf(entity: EntityState, def?: UnitTypeDef): Readonly<Stats>;
+    /** How strong a group is: the strength of each, summed */
+    sum(force: Force): number;
+    /**
+     * One force against another: the strength of each of `a`'s units against `b` (what it cannot hit counts for nothing
+     * of its damage; its damage meets their armour, theirs meets its; what it is declared to counter weighs it up),
+     * summed. `matchup(a, b).strength / matchup(b, a).strength` is how `a` compares; `odds` turns it into a chance
+     */
+    matchup(a: Force, b: Force): Matchup;
+    /**
+     * The chance that `a` beats `b` in a fight to the end, 0..1: `A² / (A² + B²)` of the two matchups (Lanchester's
+     * square law: numbers count twice, since each unit both deals and takes). 0.5 for a mirror, and when neither can hit
+     * the other. **An estimate**: it reads stats, layers, armour and declared counters, and knows nothing of spells,
+     * terrain, focus fire, who shoots first or who runs; the plan's E3 checks it against fights played out, and a game
+     * that knows better gives its own formula (`AiOptions.strength`)
+     */
+    odds(a: Force, b: Force): number;
+    /**
+     * What answers a force best among some types: each with its strength against them over its plain strength (1 is as
+     * good as against anyone, 0 cannot hit them, above 1 is the answer), the best first, equals in the order given.
+     * Against nothing, every type scores 1
+     */
+    counterFor(enemies: Force, candidates: readonly (UnitTypeDef | string)[]): Counter[];
+    /** What a game declares a type good against, as `{ target, weight }` each */
+    countersOf(type: UnitTypeDef | string): readonly {
+        target: string;
+        weight: number;
+    }[];
+    /**
+     * A profile's strength against a force over its plain strength: what its damage comes to against them (what it can
+     * hit, through their armour) and what theirs comes to against it (through its armour), each as a part of the
+     * plain, under the same square root, times what it is declared to counter. 1 against nothing
+     */
+    private edge;
+    /** Whether a declared counter's word is one of a profile's: its type, a role or a tag of it */
+    private matches;
+    /** What a type comes to for a matchup, kept */
+    private profile;
+    /** A force as groups: a profile and how many, those with health left and an attack. Units with stats of their own stand apart */
+    private groups;
+}