@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/plans/purse.d.ts

@@ -0,0 +1,73 @@
+import type { Cost, ResourceKind } from '#engine/defs';
+import type { Registry } from '#engine/registry';
+import type { AiView } from '#engine/ai/view';
+/**
+ * What a computer player has to spend this think (`ai.purse`): its resources less what is promised and held, spent
+ * through `spend`. Rebuilt from the picture each think
+ *
+ * @beta
+ */
+export declare class Purse {
+    /** What is free to spend now, by resource: less with every `spend` and `reserve` of the think. `view.me.purse` is this */
+    free: Cost;
+    /** What builders on their way to a site will pay as they get there, by resource */
+    promised: Cost;
+    /** What was paid this think (`spend`), by resource: with `promised`, never more than the picture's resources (`ai/checks.ts`) */
+    spent: Cost;
+    /** The resource most things cost (`Registry.currency`): what `affords` keeps `spare` of */
+    readonly money: ResourceKind;
+    private holds;
+    constructor(registry: Registry);
+    /**
+     * Starts the think's ledger from the picture: the player's resources, less what its builders on their way will pay
+     * (`promised`). Every hold of the think before is dropped: whoever still wants one makes it again
+     */
+    begin(view: AiView): void;
+    /** What someone this important may spend: what is free, and what is held by anyone less important */
+    available(priority?: number): Cost;
+    /** The resource a cost is short of, out of what someone this important may spend: none when it can be paid */
+    shortOf(cost: Cost | undefined, priority?: number): ResourceKind | undefined;
+    /**
+     * Whether a cost can be paid by someone this important, with `spare` of the money left over after it (a luxury
+     * waits for gold to spare): out of what is free, and what is held by anyone less important
+     */
+    affords(cost: Cost | undefined, spare?: number, priority?: number): boolean;
+    /**
+     * Pays a cost, for a command sent this think: out of what is free first, then out of what is held by anyone less
+     * important (the least important first), whose holds are less by that much. False, and nothing paid, when it cannot be
+     */
+    spend(cost: Cost | undefined, priority?: number): boolean;
+    /**
+     * Holds a cost aside under a name (a goal's id, a want's) for the rest of the think, with how important the holder
+     * is (0 when left out): what is free is less by it, so that nothing less important spends what is saved up. Made
+     * again each think by whoever still saves; a second hold under the same name replaces the first
+     */
+    reserve(id: string, cost: Cost, priority?: number): void;
+    /** Lets a hold go: what it held is free again this think */
+    release(id: string): void;
+    /** What is held under a name */
+    reservation(id: string): Readonly<Cost> | undefined;
+    /** What is held altogether, by resource */
+    reserved(): Cost;
+    /** Every hold, by name: what and how important */
+    holdings(): Readonly<Record<string, {
+        cost: Readonly<Cost>;
+        priority: number;
+    }>>;
+    /** The ledger for the report: what is free, what is promised, what is held and by whom */
+    inspect(): PurseReport;
+}
+/**
+ * The purse as the report shows it: what is free, what builders on their way will pay, what is held and by whom, with
+ * how important each holder is
+ *
+ * @beta
+ */
+export interface PurseReport {
+    free: Cost;
+    promised: Cost;
+    held: Record<string, {
+        cost: Cost;
+        priority: number;
+    }>;
+}

package/dist/ai/plans/tech.d.ts

@@ -0,0 +1,37 @@
+import type { AiView } from '#engine/ai/view';
+/**
+ * One step towards a type: a building to build (by a worker), a building to turn another into (`morph`, from the
+ * type that turns into it), or a unit to train (at the type that trains it). `for` is what the step is on the way to
+ *
+ * @beta
+ */
+export interface TechStep {
+    type: string;
+    how: 'build' | 'morph' | 'train';
+    /** For a `morph`, the type that turns into it; for a `train`, the type that trains it; for a `build`, the type that builds it */
+    from: string;
+    for: string;
+}
+/**
+ * The steps from what the player has to being able to make a type (`techPath`): the prerequisites, the producer, in
+ * the order they can be taken; the type itself is not among them. `cycle` names the definitions that go round in a
+ * circle where they do, `impossible` the type nothing of the player's can make, and the steps are then as far as the
+ * walk got
+ *
+ * @beta
+ */
+export interface TechPath {
+    steps: TechStep[];
+    cycle?: string[];
+    impossible?: string;
+}
+/**
+ * The steps from what the player has to being able to make a type: what it requires that it lacks, each of those in
+ * turn, and the type's maker where it has none (the hall that trains the worker, the worker that builds the barracks,
+ * the hall that turns into the keep). What stands finished (`view.me.tech`, with what it counts as) or is on its way
+ * (`onItsWay`: under construction, a builder sent, a morph queued) is had already. A requirement no type has as its
+ * id is met by a type that provides it
+ *
+ * @beta
+ */
+export declare function techPath(view: AiView, target: string, onItsWay?: (type: string) => boolean): TechPath;

package/dist/ai/profiles.d.ts

@@ -0,0 +1,204 @@
+import type { Registry } from '#engine/registry';
+import type { AiConditionTest } from './rules';
+import type { ThinkBudgetOptions } from './budget';
+import type { AiOptions } from './options';
+import type { Brain } from './brain';
+import { type AiSettings } from './settings';
+/**
+ * A flag's value: as data, or worked out by the brain as it is asked (code, not kept in a save)
+ *
+ * @beta
+ */
+export type AiFlag<T> = T | ((ai: Brain) => T);
+/**
+ * The classic RTS behaviour flags, where the meaning holds, and the kit's own beside them: each a yes or no, a number where
+ * one says how much, or a function of the brain
+ *
+ * @beta
+ */
+export interface AiFlags {
+    /** Helps its allies, people and computers, where asked (the team's `help` goal) */
+    defendUsers?: AiFlag<boolean>;
+    /** Hits heroes first among those alike (the micro's targets) */
+    targetHeroes?: AiFlag<boolean>;
+    /** Mends damaged buildings when no enemy reaches them (the build plan's `repair`) */
+    repairStructures?: AiFlag<boolean>;
+    /** A hero leaves a fight under this share of its health: `true` at the share under it, `false` never (`micro.heroesFlee`) */
+    heroesFlee?: AiFlag<boolean | number>;
+    /** A unit leaves a fight under this share of its health: `true` at the share under it, `false` never (`micro.unitsFlee`) */
+    unitsFlee?: AiFlag<boolean | number>;
+    /** A squad falls back from a fight away from home under these odds: `true` at the odds under it, `false` never (`squads.retreatAt`) */
+    groupsFlee?: AiFlag<boolean | number>;
+    /** Attacks before its time when the enemy's army as last seen is weak against its own: at these odds (`true`: 0.75) */
+    noMercy?: AiFlag<boolean | number>;
+    /** A unit that fled stays out until healed */
+    ignoreInjured?: AiFlag<boolean>;
+    /** The hurt go home to heal between fights */
+    removeInjuries?: AiFlag<boolean>;
+    /** Picks up what lies about */
+    takeItems?: AiFlag<boolean>;
+    /** Its heroes buy from shops in reach */
+    buyItems?: AiFlag<boolean>;
+    /** Builds its hall again where it can, once its home falls, rather than where it first stood: yes when left out */
+    allowHomeChanges?: AiFlag<boolean>;
+    /** Siege units shoot buildings and stay behind their squad */
+    smartArtillery?: AiFlag<boolean>;
+    /** Each wave takes a way of its own to the target, by the brain's numbers: straight, or round one side or the other */
+    randomPaths?: AiFlag<boolean>;
+    /** Builds again what it lost */
+    rebuild?: AiFlag<boolean>;
+    /** Ranged units step back from melee they outrun */
+    kite?: AiFlag<boolean>;
+    /** Workers a raid is on walk to a safe base */
+    workersFlee?: AiFlag<boolean>;
+    /** Says its lines to its side (the team's `say`) */
+    say?: AiFlag<boolean>;
+    /** Sends a unit to look at the enemy (the scouting's goal) */
+    scout?: AiFlag<boolean>;
+}
+/**
+ * How a computer player plays, as plain data: the settings of its areas (`AiSettings`) and how well it plays, every field
+ * optional, layered (see the file's comment). What a difficulty, a personality and a game's defaults give
+ *
+ * @beta
+ */
+export interface AiProfile extends AiSettings {
+    /**
+     * The brain it plays with, by id (one the game lists in `GameModule.brains`): what a race's profile says
+     * (`GameAi.races`, campaign plan AR3), for a seat that names none and a map that says none. The game's first brain
+     * where nothing says
+     */
+    brain?: string;
+    /** The difficulty by name: `easy`, `normal`, `hard`, `insane`, or a game's own (`GameModule.ai.difficulties`). `normal` when left out */
+    difficulty?: string;
+    /** The personality by name: `balanced`, `rusher`, `turtle`, `expander`, `harasser`, or a game's own. `balanced` when left out */
+    personality?: string;
+    /** Seconds between thinks: its reactions */
+    every?: number;
+    /** Commands a think may send at the most, like a person's hands: no limit when left out */
+    commandsPerThink?: number;
+    /** How often it slips, 0 to 1: a think's fights left alone, a wave sent early. Drawn with the brain's own numbers */
+    mistakes?: number;
+    /** `fair`: it sees what its seat does. `all`: it sees through the fog (an observer's session), for insane only */
+    vision?: 'fair' | 'all';
+    /**
+     * 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 (4). Nothing sliced when left out: a game sets it where its numbers ask, at many computers
+     */
+    budget?: ThinkBudgetOptions;
+    /**
+     * What it is given beyond the rules, each a factor (1 is none), through the game's hooks while it is seated:
+     * `income`, what its workers bring in (1.5: half again; `beforeDeposit`); `health`, the most health of everything
+     * it has (`stats`); `damage`, the damage it deals (`beforeDamage`, before armour); `buildTime`, how long what it
+     * trains, builds and researches takes (0.8: a fifth sooner; `beforeProduce`). The classic handicap is `health`
+     */
+    handicap?: AiHandicap;
+}
+/**
+ * What a computer is given beyond the rules (`AiProfile.handicap`): each a factor, 1 (or left out) for none
+ *
+ * @beta
+ */
+export interface AiHandicap {
+    /** What its workers bring in, through the game's `beforeDeposit` hook */
+    income?: number;
+    /** The most health of everything it has, through a `stats` hook: the classic handicap */
+    health?: number;
+    /** The damage it deals, before armour, through a `beforeDamage` hook */
+    damage?: number;
+    /** How long what it trains, builds and researches takes, through a `beforeProduce` hook: under 1 is sooner */
+    buildTime?: number;
+}
+/**
+ * A difficulty's or a personality's profile, the engine's or a game's
+ *
+ * @beta
+ */
+export type AiProfileTable = Record<string, AiProfile>;
+/**
+ * The engine's defaults of how well it plays: the bottom layer. The areas' numbers are each area's own where no layer
+ * says them (`Economy`'s 8 workers)
+ *
+ * @beta
+ */
+export declare const DEFAULT_PROFILE: Readonly<AiProfile>;
+/**
+ * The engine's difficulties: how well it plays. `normal` is the areas' own numbers. `insane` sees through the fog and
+ * gets half again of what its workers bring in, as the classic insane computer does
+ *
+ * @beta
+ */
+export declare const DIFFICULTIES: Readonly<AiProfileTable>;
+/**
+ * The engine's personalities: how it likes to play. Over the difficulty, so a rusher rushes on any of them
+ *
+ * @beta
+ */
+export declare const PERSONALITIES: Readonly<AiProfileTable>;
+/**
+ * What a game says of its computer players' profiles (`GameModule.ai`): difficulties and personalities of its own, and
+ * defaults over the engine's
+ *
+ * @beta
+ */
+export interface GameAi {
+    /** Difficulties of its own, by name, beside (or over) the engine's */
+    difficulties?: AiProfileTable;
+    /** Personalities of its own, by name */
+    personalities?: AiProfileTable;
+    /** Conditions of its own, by id, for the data form (`{ is: 'mygame.bridgeDown', args }`), a map's file among them */
+    conditions?: Record<string, AiConditionTest>;
+    /** Defaults over the engine's, under the difficulty */
+    defaults?: AiProfile;
+    /**
+     * How its computers play each of its races (`GameModule.races`), by race id: a layer over `defaults` and under the
+     * difficulty, for a seat of that race (its build order, heroes, composition, flags; how often it thinks). Its
+     * `difficulty` and `personality` are the seat's where the lobby and the map say none
+     */
+    races?: AiProfileTable;
+    /** Whether a lobby offers its seats a difficulty and a personality (`seatSettingsOf`): yes when left out */
+    lobby?: boolean;
+}
+/**
+ * The difficulties a game's computers may play at, by name: the engine's, the game's over them
+ *
+ * @beta
+ */
+export declare function difficultiesOf(registry?: Pick<Registry, 'module'>): AiProfileTable;
+/**
+ * The personalities a game's computers may have, by name: the engine's, the game's over them
+ *
+ * @beta
+ */
+export declare function personalitiesOf(registry?: Pick<Registry, 'module'>): AiProfileTable;
+/**
+ * A profile resolved (`resolveProfile`): what it plays by, and its settings' layers as given, lowest first, for the brain
+ * to work out each think (a flag may be a function of it)
+ *
+ * @beta
+ */
+export interface ResolvedProfile {
+    /** The profile, its settings layered (a flag's function left out) */
+    profile: AiProfile;
+    /** Its settings' layers, lowest first: the brain's, the game's, the race's, the difficulty's, the personality's, the seat's (the map's under it) */
+    layers: readonly AiSettings[];
+    /** A difficulty or a personality the game does not have, passed over */
+    unknown: string[];
+}
+/**
+ * The profile a seat plays by (`Brain.profile`): the brain's settings (`BrainDef.settings`), the game's defaults, the
+ * race's (`GameAi.races`, for the `race` the seat plays), the difficulty, the personality, the seat's own
+ * (`AiOptions.settings`, the map's under it), each over the one before; how well it plays from the engine's defaults,
+ * the game's, the race's, the difficulty, the personality and the seat's `every` and `budget`. A name the game does not
+ * have is passed over, and `unknown` names it
+ *
+ * @beta
+ */
+export declare function resolveProfile(options: AiOptions, registry?: Pick<Registry, 'module'>, brain?: AiSettings, race?: string): ResolvedProfile;
+/**
+ * A flag's value as asked now: a function of the brain worked out, data as it is. For a flag no area has a name for
+ * (No Mercy, Random Paths, Allow Home Changes): the rest are the areas' (`ai.settings`)
+ *
+ * @beta
+ */
+export declare function flagOf<K extends keyof AiFlags>(ai: Brain, name: K): Exclude<AiFlags[K], (ai: Brain) => unknown> | undefined;

package/dist/ai/reach.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The distances and times the AI kit measures by (design review B13), each named once with why it is what it is
+ */
+export {};

package/dist/ai/report.d.ts

@@ -0,0 +1,203 @@
+import type { PlayerId } from '#engine/entity';
+import type { ComputerTiming } from './computer';
+import type { ThinkBudgetOptions } from './budget';
+import type { GoalReport } from './goals';
+import type { PlansReport } from './plans/plans';
+import type { SquadReport } from './squads';
+import type { MicroReport } from './micro';
+import type { DefenceReport } from './defence';
+import type { EconomyReport } from './economy';
+import type { ScoutingReport } from './scouting';
+import type { TeamReport } from './team';
+import type { AiProfile } from './profiles';
+import type { WavesReport } from './waves';
+/**
+ * One thing a computer player decided, as a line of text: what it did and the reason that weighed most
+ *
+ * @beta
+ */
+export interface AiDecision {
+    /** The tick of the think it was decided at */
+    tick: number;
+    /** What it is about: `goal` for the goals' picker, or the module's word (`army`, `build`, `research`, `hero`) */
+    kind: string;
+    /** What was decided, in words: "attack picked at 0.80 (8 units): its time has come 1.00 · the wave is ready 1.00" */
+    line: string;
+    /** The goal it is about, where it is about one */
+    goal?: string;
+}
+/**
+ * What a computer player remembers of what it saw, in short, for the report: its rivals' bases and their army as last
+ * seen, with how many seconds ago, and the tech seen
+ *
+ * @beta
+ */
+export interface KnowledgeReport {
+    bases: {
+        owner: PlayerId;
+        at: [number, number];
+        structures: number;
+        seen: number;
+        gone?: true;
+    }[];
+    army: {
+        at: [number, number];
+        count: number;
+        seen: number;
+    }[];
+    tech: string[];
+    lost: number;
+}
+/**
+ * What a computer player's play adds up to since it was seated (`Brain.stats`, `AiReport.stats`): the numbers
+ * `simulate` reports beside who won, and a test reads to see that the squads send an order once and watch it. Counted,
+ * never decided on
+ *
+ * @beta
+ */
+export interface AiStats {
+    /** Commands sent */
+    commands: number;
+    /** Commands held back past what a think may send (`AiProfile.commandsPerThink`) */
+    held: number;
+    /** Commands the game refused (a unit that could not do it, a place it could not build at) */
+    refused: number;
+    /** Seconds its fighters stood idle, summed over the fighters: ten footmen idle for a minute are six hundred */
+    idleArmySeconds: number;
+    /** Orders sent to a unit again for the same thing within a few seconds: a unit told the same every think stops and starts */
+    churn: number;
+    /** Seconds its building waited on money: a want saving up */
+    blockedOnMoney: number;
+    /** Thinks counted */
+    thinks: number;
+}
+/**
+ * The threat map as a computer player read it last think (`ThreatMap.cells`, on the ground, the enemy structures it
+ * remembers counted): what the game view's AI overlay draws as heat over the ground. The size of a cell, the grid's
+ * cells across and down, and each cell with something in it as `[col, row, friendly, enemy]`
+ *
+ * @beta
+ */
+export interface ThreatReport {
+    cell: number;
+    cols: number;
+    rows: number;
+    cells: [col: number, row: number, friendly: number, enemy: number][];
+}
+/**
+ * What a computer player is thinking, as plain data (`Brain.report`, `Brain.inspect`): what the debug panel's AI tab
+ * draws, and what a test reads. Each module adds its section (`AiModule.report`, `AiModule.inspect`)
+ *
+ * @beta
+ */
+export interface AiReport {
+    /** The version of this shape */
+    v: 1;
+    /** The brain's id (`core.melee`) */
+    brain: string;
+    /** The player it plays */
+    player: PlayerId;
+    /** The tick of its last picture of the game */
+    tick: number;
+    /** Seconds into the game, as of its last picture */
+    time: number;
+    /** Ticks a second: what turns a decision's tick into the game's time */
+    tickRate: number;
+    /** How many times it has thought */
+    thinks: number;
+    /** Whether it sits still (`world.computers.pause`) */
+    paused?: true;
+    /** What it was seated with: the data of its options (`AiOptions`: the difficulty, the numbers); code left out */
+    profile: Record<string, unknown>;
+    /** What it plays by (`Brain.profile`): the profile resolved, layer over layer; code (a flag's function) left out */
+    playing?: AiProfile;
+    /** The goal that scored highest above the minimum this think: what the army is on. None when nothing is worth doing */
+    goal?: string;
+    /** Every goal as the picker last saw it: its score, each consideration's raw and curved value, what it holds, why not */
+    goals: GoalReport[];
+    /** What it remembers of the enemy: left out by a brain that keeps no knowledge */
+    knowledge?: KnowledgeReport;
+    /** The roles it found among the types it can make: `{ worker: ['peasant'] }` */
+    roles: Record<string, string[]>;
+    /**
+     * What it has to spend and how it comes in: its resources, its income a minute, its supply; and its economy's say
+     * (`EconomyReport`): each base with its workers on each resource against what it wants and what is served, the
+     * workers that fled a raid, the workers had against wanted, where the next hall stands
+     */
+    economy: {
+        resources: Record<string, number>;
+        income: Record<string, number>;
+        supply: [used: number, cap: number];
+    } & Partial<EconomyReport>;
+    /** The raids on its bases with what answers each, every base's raids so far, the towers it wants (`DefenceReport`) */
+    defence?: DefenceReport;
+    /** Its plan of looks with how long since each was in sight and whether it is due, its scout and where it goes (`ScoutingReport`) */
+    scouting?: ScoutingReport;
+    /** Its team: the computers of it, the requests on its board, the plan of an attack together (`TeamReport`) */
+    team?: TeamReport;
+    /** Its waves: the one whose turn it is, its group as it stands and when it may go, the waves sent (`WavesReport`) */
+    waves?: WavesReport;
+    /** Its plans: the purse (what is free, promised, held), and every want of the build plan with what it waits for */
+    plans: PlansReport;
+    /** Its squads: whose each is, its units and their strength, where it is, its task and how it goes, its last change */
+    squads: SquadReport[];
+    /** Where the strength is, as its threat map read it last think (`ThreatReport`): what the AI overlay draws as heat */
+    threat?: ThreatReport;
+    /** Its fights: each squad in one and whom it hits, the units that fled, its heroes and what each learns next, who shops for what */
+    micro?: MicroReport;
+    /** The words the game told it that no module has taken yet */
+    told: {
+        word: string;
+        tick: number;
+    }[];
+    /** Commands it sent its last think */
+    sent: number;
+    /** Commands it would have sent its last think past what its profile lets a think send (`commandsPerThink`) */
+    held?: number;
+    /** How much of a think one tick may do, where its budget slices it (`ThinkBudget`), and the ticks its last think took. Left out where a think is one tick */
+    budget?: ThinkBudgetOptions & {
+        ticks: number;
+    };
+    /** What its play adds up to since it was seated (`AiStats`): commands, idle army seconds, churn, seconds blocked on money */
+    stats: AiStats;
+    /**
+     * Milliseconds its thinks take, for reading only: the last, an average, the longest, and by module while the world
+     * profiles. Given by the seat (`inspect` of the player), which times the thinks
+     */
+    timing?: ComputerTiming;
+    /** What it decided, the last fifty, oldest first */
+    decisions: AiDecision[];
+    /** What each module says of itself that the report has no part for (`AiModule.inspect`), under the module's id */
+    sections: Record<string, unknown>;
+}
+/**
+ * The last fifty things a computer player decided (`Brain.decisions`, written by `ai.decide`), oldest first: kept in a
+ * save, plain data
+ *
+ * @beta
+ */
+export declare class Decisions {
+    private readonly limit;
+    private lines;
+    constructor(limit?: number);
+    /** Writes one down: the oldest goes once there are more than the log keeps */
+    add(decision: AiDecision): void;
+    /** What it decided, oldest first */
+    list(): readonly AiDecision[];
+    /** The last decision about a goal, or of a kind */
+    last(about: {
+        goal?: string;
+        kind?: string;
+    }): AiDecision | undefined;
+    /** For a save: a copy */
+    save(): AiDecision[];
+    /** Takes back what `save` gave: what is not a decision is passed over */
+    restore(lines: unknown): void;
+}
+/** A goal's considerations in one line: "its time has come 1.00 · the wave is ready 0.50", what was not asked left out */
+export declare function considerationsLine(goal: Pick<GoalReport, 'considerations'>): string;
+/**
+ * The consideration that held a goal back most: the one with the least curved value of those asked (a score is their
+ * product, so the least is what kept it low), and none for a goal with no considerations
+ */
+export declare function weakest(goal: GoalReport): GoalReport['considerations'][number] | undefined;

package/dist/ai/roles.d.ts

@@ -0,0 +1,133 @@
+import { type UnitTypeDef } from '#engine/defs';
+import type { PlayerId } from '#engine/entity';
+import type { Registry } from '#engine/registry';
+import type { PlacementName } from './plans/placement';
+import type { CounterHint } from './strength';
+/**
+ * What a unit type is for, to a computer player: the engine's roles, or a word of the game's own. A type can have
+ * several (a ghoul is a `gatherer` and a `soldier`)
+ *
+ * - `worker`: gathers and builds; `gatherer`: gathers (a worker is one too); `topper`: what is put up on a deposit of
+ *   the money to gather it there (`builtOn`)
+ * - `hall`: takes deposits and trains workers; `supply`: provides supply and trains nothing; `barracks`: trains
+ *   soldiers; `altar`: trains or revives heroes; `workshop`: researches; `tower`: a building that attacks; `shop`:
+ *   sells or hires
+ * - `soldier`: a unit that fights and is no hero; `hero`; `caster`: fights with mana; `healer`: has an ability that
+ *   heals; `siege`: attacks that splash, fell or are aimed at the ground; `air`: flies; `scout`: the fastest of the
+ *   soldiers; `detector`: finds the invisible
+ *
+ * @beta
+ */
+export type AiRole = 'worker' | 'gatherer' | 'topper' | 'hall' | 'supply' | 'barracks' | 'altar' | 'workshop' | 'tower' | 'shop' | 'soldier' | 'hero' | 'caster' | 'healer' | 'siege' | 'air' | 'scout' | 'detector' | (string & {});
+/**
+ * What a game declares of a unit type for the computer player (`UnitTypeDef.ai`), where what the kit infers from the
+ * definition is wrong or cannot be known: its roles, words of the game's own about it, what it answers, how much it
+ * is worth hitting. A declared role is in place of the inferred ones, not beside them
+ *
+ * @beta
+ */
+export interface AiHints {
+    /** What it is for (`AiRole`), one or several: in place of what the kit would infer */
+    role?: AiRole | AiRole[];
+    /** Words of the game's own about it (`'ranged'`, `'cavalry'`), for a brain's queries (`UnitSet.withTag`). Beside the inferred ones */
+    tags?: string[];
+    /**
+     * What it is good against: tags, roles or type ids (`['air', 'siege']`), each with a weight where a word is not enough
+     * (`{ target: 'air', weight: 1 }`). Read by the matchups (`Strength.matchup`, `odds`, `counterFor`)
+     */
+    counters?: CounterHint[];
+    /**
+     * How strong it is at full health, in place of the kit's formula (`defaultStrength`) and of any formula the brain was
+     * given: for a type whose numbers mislead (a unit that is all spells). Scaled by the health a unit has left
+     */
+    strength?: number;
+    /** How much it is worth hitting first, in a fight: 1 when left out. Read by the micro of C2 */
+    priority?: number;
+    /**
+     * Where the build plan puts it (`PlacementName`): `atEdge` for a tower, `behind` for supply, `cluster` beside its
+     * own kind. Over the brain's table; the role's default when left out
+     */
+    placement?: PlacementName;
+}
+/**
+ * The roles and tags of one unit type, with why (`why`: a line per inferred role, for the report; none for a declared
+ * one)
+ *
+ * @beta
+ */
+export interface RoleEntry {
+    roles: AiRole[];
+    tags: string[];
+    why?: string[];
+}
+/**
+ * The roles and tags of every unit type of a game, by type id: what `inferRoles` gives, and what a game's own
+ * `AiOptions.roles` gives in its place
+ *
+ * @beta
+ */
+export type RoleTable = Record<string, RoleEntry>;
+/**
+ * The player the roles are found for, where finding them depends on who asks (`AiOptions.roles`)
+ *
+ * @beta
+ */
+export interface RolesPlayer {
+    id: PlayerId;
+    /** The race it plays, where the game has races */
+    race?: string;
+    /** What the game's `available` hook decided for it, by type (`PlayerState.own.availability`) */
+    availability?: Record<string, boolean>;
+}
+/**
+ * A game's own way of saying what unit types are for, in place of the kit's inference (`AiOptions.roles`): every type
+ * it has a role for, with its roles and tags. What is declared on a type (`UnitTypeDef.ai`) still goes over it
+ *
+ * @beta
+ */
+export type RolesFinder = (registry: Registry, player: RolesPlayer) => RoleTable;
+/**
+ * Infers what every unit type of the game is for, from its definition: the rules, written down once, each with its
+ * reason (`RoleEntry.why`). What a game declares (`UnitTypeDef.ai.role`) is not looked at here: `findRoles` puts it
+ * over what is inferred
+ *
+ * @beta
+ */
+export declare function inferRoles(registry: Registry): RoleTable;
+/**
+ * What the unit types of a game are for (`AiView.roles`): the inferred roles (`inferRoles`, or a game's own finder
+ * in its place) with what the game declares on a type over them (`UnitTypeDef.ai`), and the queries over them
+ *
+ * @beta
+ */
+export declare class Roles {
+    /** Every unit type's roles and tags, by id */
+    readonly table: RoleTable;
+    private readonly registry;
+    private readonly byRole;
+    private readonly byTag;
+    constructor(
+    /** Every unit type's roles and tags, by id */
+    table: RoleTable, registry: Registry);
+    /** The roles of a unit type: none for one that has none, or is not a unit type at all */
+    of(type: string): readonly AiRole[];
+    /** Whether a unit type has a role */
+    has(type: string, role: AiRole): boolean;
+    /** The tags of a unit type: the kit's (`ranged`, `melee`, `hitsAir`) and the game's (`UnitTypeDef.ai.tags`) */
+    tags(type: string): readonly string[];
+    /** Whether a unit type has a tag */
+    hasTag(type: string, tag: string): boolean;
+    /** The unit types with a role, in the game's order (the first of a kind is the one meant first) */
+    types(role: AiRole): readonly UnitTypeDef[];
+    /** The unit types with a tag, in the game's order */
+    tagged(tag: string): readonly UnitTypeDef[];
+    /** What a game declared of a type (`UnitTypeDef.ai`): nothing where it declared nothing */
+    hints(type: string): AiHints | undefined;
+    /**
+     * Why a type has the roles it has, in words, for the report: `declared: worker` for what the game said, a line per
+     * inferred role otherwise
+     */
+    explain(type: string): string;
+    /** Every role and the types that have it, for the report (the debug tools) */
+    report(): Record<string, string[]>;
+}