@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/ai/rules.d.ts

@@ -0,0 +1,288 @@
+import type { Vec2 } from '#engine/math';
+import type { ObjectiveStatus } from '#engine/objectives';
+import { type Brain } from './brain';
+import { type AiModuleDef } from './module';
+import type { AiRole } from './roles';
+/**
+ * At least `min` and at most `max`, each left out for no bound: a count, an amount, a level
+ *
+ * @beta
+ */
+export interface AiRange {
+    min?: number;
+    max?: number;
+}
+/**
+ * Whose units a condition counts: the player’s own (the default), its rivals’ in sight, its allies’
+ *
+ * @beta
+ */
+export type AiWhose = 'mine' | 'enemy' | 'ally';
+/**
+ * A condition as plain data: what a map's file, a mission's JSON or the editor holds. Each form is one question; the
+ * table in `docs/ai.md` says what each asks
+ *
+ * @beta
+ */
+export type AiConditionData = 
+/** Every one of them */
+{
+    all: AiCondition[];
+}
+/** One of them at least */
+ | {
+    any: AiCondition[];
+}
+/** The other way round */
+ | {
+    not: AiCondition;
+}
+/** How much it has of a resource */
+ | {
+    resource: {
+        id: string;
+    } & AiRange;
+}
+/**
+ * How many units there are, of a type, a role or a tag, whose (`of`), near a named entity, point or region (`near`,
+ * `within`), finished only (`finished`); and for `of: 'enemy'`, those remembered out of sight too (`known`). At
+ * least one where neither `min` nor `max` is given
+ */
+ | {
+    units: {
+        type?: string;
+        role?: AiRole;
+        tag?: string;
+        of?: AiWhose;
+        near?: string | Vec2;
+        within?: number;
+        finished?: boolean;
+        known?: boolean;
+    } & AiRange;
+}
+/** Its supply: free (cap less used), used, cap */
+ | {
+    supply: {
+        free?: AiRange;
+        used?: AiRange;
+        cap?: AiRange;
+    };
+}
+/** Seconds into the game: from `after`, before `before` */
+ | {
+    time: {
+        after?: number;
+        before?: number;
+    };
+}
+/**
+ * Whether its own are being hit: damage seen to its entities within so many seconds (5 when left out), anywhere, or
+ * near a named entity, a point or a region (`near`, `within` the reach: 16)
+ */
+ | {
+    underAttack: true | {
+        seconds?: number;
+        near?: string | Vec2;
+        reach?: number;
+    };
+}
+/** Whether a rival's unit of a type or a role was seen, within so many seconds where given (ever, when left out) */
+ | {
+    seen: {
+        type?: string;
+        role?: AiRole;
+        within?: number;
+    };
+}
+/** The difficulty it plays on (its profile's: `AiOptions.difficulty`, normal when left out), one or any of a list */
+ | {
+    difficulty: string | string[];
+}
+/** Whether the game told it this word and nothing took it yet */
+ | {
+    told: string;
+}
+/** Yes so often, by the brain's own numbers (`ai.rng`): `0.3` is three times in ten. The same game says the same */
+ | {
+    chance: number;
+}
+/** Its heroes: one at least of this type (any where left out), alive where `alive` says, of a level */
+ | {
+    hero: {
+        type?: string;
+        alive?: boolean;
+        level?: AiRange;
+    };
+}
+/** The index of the wave whose turn it is (`ai.waves.index`, the waves sent and skipped before it); where it has no waves, the attacks it sent (its knowledge's `own.attacks`) */
+ | {
+    wave: AiRange;
+}
+/** One of its own objectives, by id, in this status (or any of these) */
+ | {
+    objective: {
+        id: string;
+        status: ObjectiveStatus | ObjectiveStatus[];
+    };
+}
+/** A value of the game's report to this player (`GameModule.report`), by its path (`'waves.next'`): equal to, or within */
+ | {
+    report: {
+        path: string;
+        equals?: unknown;
+    } & AiRange;
+}
+/**
+ * A value of a component the game replicates to this player (`Component.replicate`) on an entity: one the map or
+ * the rules named (`entity`), or the first of its own of a type (`type`). By path in it, where it is an object
+ */
+ | {
+    component: {
+        id: string;
+        entity?: string;
+        type?: string;
+        path?: string;
+        equals?: unknown;
+    } & AiRange;
+}
+/** How many units are in a region of the map, whose (`of`: its own when left out), of a type or a role */
+ | {
+    region: {
+        name: string;
+        of?: AiWhose;
+        type?: string;
+        role?: AiRole;
+    } & AiRange;
+}
+/** A condition of the game's own or the brain's (`GameAi.conditions`, `BrainDef.conditions`), by id, with its arguments (`{ is: 'mygame.bridge', args: { name: 'north' } }`) */
+ | {
+    is: string;
+    args?: Record<string, unknown>;
+};
+/**
+ * A condition: a question with a yes or no, as a function of the brain, or as plain data (`AiConditionData`)
+ *
+ * @beta
+ */
+export type AiCondition = ((ai: Brain) => boolean) | AiConditionData;
+/**
+ * A condition of a game's own or a brain's, for the data form (`{ is: id, args }`): a map's file names it, the game
+ * (`GameAi.conditions`) or the brain (`BrainDef.conditions`) gives the code, by an id prefixed as components are
+ * (`mygame.bridgeDown`)
+ *
+ * @beta
+ */
+export type AiConditionTest = (ai: Brain, args: Record<string, unknown>) => boolean;
+/**
+ * Whether a condition holds for the brain now: a function is asked, data is read as its form says. A form the kit
+ * does not know (a game's own not defined) is no, and the log says so once
+ *
+ * @beta
+ */
+export declare function evaluate(condition: AiCondition, ai: Brain): boolean;
+/**
+ * What a rule does, as plain data: a word the brain tells itself (`{ say: 'attack', data: { at } }`), answered by the
+ * `words()` module or a told rule of its own, the same think where they come after the rules
+ *
+ * @beta
+ */
+export interface AiActionData {
+    say: string;
+    data?: unknown;
+}
+/**
+ * What a rule does: a function of the brain and, for a told rule, what came with the word; or plain data
+ * (`AiActionData`)
+ *
+ * @beta
+ */
+export type AiAction = ((ai: Brain, data?: unknown) => void) | AiActionData;
+/**
+ * A rule of a brain (`when(condition).do(action)`): checked each think by the `rules()` module, its action done as
+ * its condition becomes true. Code: given again by the brain's definition, as goals are; what it remembers is data
+ *
+ * @beta
+ */
+export interface AiRule {
+    /** Its name: what the memory, the report and the log know it by. `rule 1`, `rule 2`… in the module's list when left out */
+    readonly id?: string;
+    /** When it fires: a condition, or a word told (`when.told`) */
+    readonly when: AiCondition | {
+        word: string;
+    };
+    /** What it does */
+    readonly action: AiAction;
+    /** Whether it fires the first time only, ever */
+    readonly once?: boolean;
+    /** Seconds: fired again while its condition holds, at most so often. Left out, it fires as it turns true */
+    readonly every?: number;
+    /** Checked before rules of less: 0 when left out */
+    readonly priority?: number;
+}
+/**
+ * A rule being written: `when(...)`, then any of `once`, `every`, `priority`, `named`, then `do`
+ *
+ * @beta
+ */
+export interface RuleBuilder {
+    /** Fires the first time only, ever */
+    once(): RuleBuilder;
+    /** Fires again while the condition holds, at most every so many seconds */
+    every(seconds: number): RuleBuilder;
+    /** Checked before rules of less */
+    priority(n: number): RuleBuilder;
+    /** Its name, for the memory, the report and the log */
+    named(id: string): RuleBuilder;
+    /** What it does: the rule */
+    do(action: AiAction): AiRule;
+}
+/**
+ * A rule: `when(condition).do(action)`, with `once()`, `every(seconds)`, `priority(n)`, `named(id)` between. The
+ * condition is a function of the brain or plain data (`AiCondition`). `when.told(word)` fires once for each time the
+ * word is told, taking it, its action given the word's data
+ *
+ * @beta
+ */
+export declare const when: ((condition: AiCondition) => RuleBuilder) & {
+    /** A rule that fires for each time the game tells the brain this word (`world.computers.tell`), and takes it */
+    told: (word: string) => RuleBuilder;
+};
+/**
+ * The rules module: checks its rules each think, in their order (by `priority`, then as given), and does each one's
+ * action as its condition turns true. Ahead of the modules that act on units, where a brain lists it: what a rule
+ * takes is then not given orders by them first. Its id is `rules` (give `id` for a second one)
+ *
+ * @beta
+ */
+export declare const rules: (list: AiRule[], options?: {
+    id?: string;
+}) => AiModuleDef;
+/**
+ * What the words a brain may be told (`words()`) come with: where (`at`, a point, or a name the map or rules gave an
+ * entity or region), and for how many seconds the army is the word's, not the goals' (`seconds`)
+ *
+ * @beta
+ */
+export interface WordData {
+    at?: Vec2 | string;
+    seconds?: number;
+}
+/**
+ * The words module: answers the words any brain may be told (`world.computers.tell(player, word, data)`), taking them:
+ *
+ * - `attack` `{ at?, seconds? }`: the army (its fighters) attacks there, fighting what it meets on the way; where no
+ *   place is given, at the nearest building of a rival's it knows of, else at the first rival's base the seat was told
+ *   (`AiOptions.enemyBases`).
+ * - `defend` `{ at?, seconds? }`: the army goes to fight there, home when left out.
+ * - `retreat` `{ seconds? }`: the army comes home, fighting nothing on the way.
+ * - `hold` `{ seconds? }`: the army stands where it is, fighting what comes in reach.
+ * - `pause`: the brain sits still until told `resume` (or `world.computers.resume`); `resume` the brain answers itself.
+ *
+ * The army goes as one squad on the kit's task of the word (`attack`, `defend`, `retreat`, `hold`, in the squad
+ * `word`), so that where the brain has the `squads()` module it regroups, focuses, kites and falls back on the odds as
+ * any squad does. The army is the word's for `seconds` (attack 60, defend 30, retreat 15, hold 30): no goal claims it
+ * meanwhile, then the squad goes and the goals have it again. Its id is `words`; put it after `rules`, so that a rule's `{ say }` is answered that think
+ *
+ * @beta
+ */
+export declare const words: () => AiModuleDef;

package/dist/ai/scouting.d.ts

@@ -0,0 +1,98 @@
+import { type Vec2 } from '#engine/math';
+import { type Brain } from './brain';
+import { type AiModuleDef } from './module';
+/**
+ * How a brain scouts (`BrainDef.scouting`, the seat's `AiOptions.scouting` over it, the `scouting()` module's own under
+ * both). Data, but for the function form of `scout`
+ *
+ * @beta
+ */
+export interface ScoutingOptions {
+    /** Seconds a place stays out of sight before it is worth a look again: 90 when left out */
+    lookEvery?: number;
+    /**
+     * Where to look: `false` nowhere (the goal is left out), a function for places of the game's own each think (in place
+     * of the kit's plan). The kit's plan when left out
+     */
+    scout?: false | ((ai: Brain) => Vec2[]);
+    /** Whether the mines they would expand to are looked at: yes when left out */
+    expansions?: boolean;
+    /** Whether where their army was last seen is looked at again: yes when left out */
+    army?: boolean;
+    /** Whether a flying unit with nothing to do goes before the fastest on foot: yes when left out */
+    flyers?: boolean;
+    /** Seconds into the game before the first look: 15 when left out */
+    from?: number;
+}
+/**
+ * What the scouting remembers between thinks, as a save keeps it
+ *
+ * @beta
+ */
+export interface ScoutingMemory {
+    v: 1;
+    /** The unit that scouts, while it lives: the same one goes on to the next round */
+    scout?: number;
+    /** Rounds sent */
+    rounds: number;
+    /** The places of the round the scout is on, while it is */
+    round?: Vec2[];
+    /**
+     * Places a scout was lost on the way to, and when: not due again for `lookEvery` seconds, as if looked at (a lost
+     * scout says as much: what guards it is there). Never the same unit sent to die at their towers over and over (AI1)
+     */
+    lost?: {
+        at: Vec2;
+        tick: number;
+    }[];
+}
+/**
+ * A place in the plan of looks: where, what kind of place it is, when it was last in sight
+ *
+ * @beta
+ */
+export interface Look {
+    at: Vec2;
+    /** Their start not seen yet, their base, a mine they would expand to, where their army was, or a place the game names */
+    kind: 'start' | 'base' | 'expansion' | 'army' | 'game';
+    /** Seconds since it was last in sight: `Infinity` for never */
+    since: number;
+    /** Whether it is worth a look now */
+    due: boolean;
+}
+/**
+ * The scouting as the report shows it (`AiReport.scouting`): the plan of looks with how old each is, the scout, where
+ * it goes
+ *
+ * @beta
+ */
+export interface ScoutingReport {
+    looks: {
+        at: [number, number];
+        kind: Look['kind'];
+        seen?: number;
+        due: boolean;
+    }[];
+    scout?: number;
+    going?: [number, number][];
+    rounds: number;
+}
+/**
+ * The id of the scouting's goal
+ *
+ * @beta
+ */
+export declare const SCOUT = "scout";
+/**
+ * The scouting module: puts the `scout` goal on the brain's picker, which sends one unit at a time to look at what is
+ * due (`ai.scouting`). With how it scouts where the brain's definition and the seat's options say nothing
+ * (`ScoutingOptions`)
+ *
+ * @beta
+ */
+export declare const scouting: (options?: ScoutingOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        scouting?: ScoutingMemory;
+    }
+}

package/dist/ai/settings.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The settings of a brain (design review B2): every number and switch its areas play by, in one schema keyed by area,
+ * each under the area's own names (`{ economy: { workers }, defence: { radius, towers }, micro: { unitsFlee } }`). Every
+ * layer speaks it, lowest first:
+ *
+ *   the brain's definition (`BrainDef.settings`)  →  the game's defaults (`GameAi.defaults`)  →  the race's
+ *   (`GameAi.races`)  →  the difficulty  →  the personality  →  the map (`MapAi.settings`, `MapAi.races`)  →  the seat
+ *   (`AiOptions.settings`)
+ *
+ * and `resolveSettings` layers them once: an area's values key by key, the higher layer's over the lower's. What a
+ * module was made with (`economy({ workers })`) is under all of them, and what no layer says is the area's own default
+ * (`Economy`'s 8 workers). An area reads what it plays by from `ai.settings` and nothing else.
+ *
+ * The classic flags (`AiFlags`) are a section of their own, for a lobby and the editor's flags list: a flag that says what
+ * an area has a name for (Kite: `micro.kite`, Units Flee: `micro.unitsFlee`) is taken into that area in the layer that
+ * says it, so that a higher layer's word goes over it either way. A flag may be a function of the brain: worked out each
+ * think, as `ai.settings` is
+ */
+import type { DefenceOptions } from './defence';
+import type { EconomyOptions } from './economy';
+import type { Brain } from './brain';
+import type { LanesPlayOptions } from './lanes';
+import type { MeleeArmyOptions } from './melee/goals';
+import type { MeleeHeroesOptions } from './melee/heroes';
+import type { MicroOptions } from './micro';
+import type { PlansOptions } from './plans/plans';
+import type { AiFlags } from './profiles';
+import type { ScoutingOptions } from './scouting';
+import type { SquadsOptions } from './squads';
+import type { TeamOptions } from './team';
+import type { WavesOptions } from './waves';
+/**
+ * What a brain's areas play by, by area, each under its own names (see the file's comment): what every layer gives, from
+ * the brain's definition to the seat. Plain data where a lobby, a map or a save holds it; a function in it is code, not
+ * kept in a save
+ *
+ * @beta
+ */
+export interface AiSettings {
+    /** The workers and the bases (`Economy`) */
+    economy?: EconomyOptions;
+    /** What it defends and how (`Defence`) */
+    defence?: DefenceOptions;
+    /** How often it looks and with whom (`Scouting`) */
+    scouting?: ScoutingOptions;
+    /** How its units fight (`Micro`) */
+    micro?: MicroOptions;
+    /** How its squads go, and the tasks they may be given (`Squads`) */
+    squads?: SquadsOptions;
+    /** How it plays with its team (`Team`) */
+    team?: TeamOptions;
+    /** The waves it was given (`Waves`) */
+    waves?: WavesOptions;
+    /** What it builds, trains and researches, and in what order (`Plans`) */
+    plans?: PlansOptions;
+    /** The melee army: when it attacks, how many go, how a wave goes (`melee.army`) */
+    army?: MeleeArmyOptions;
+    /** The melee player's heroes: how many, and from when (`melee.heroes`) */
+    heroes?: MeleeHeroesOptions;
+    /** A lanes brain's play (`lanes`) */
+    lanes?: LanesPlayOptions;
+    /** How much each goal weighs, by its id (1 when left out): the picker's (`Goals`) */
+    weights?: Record<string, number>;
+    /** The classic flags (see the file's comment) */
+    flags?: AiFlags;
+}
+/**
+ * The settings layered, lowest first (see the file's comment): each area's values key by key, a flag taken into the area
+ * it names in its own layer. A flag that is a function of the brain is asked of `ai`, and left out where none is given
+ *
+ * @beta
+ */
+export declare function resolveSettings(layers: readonly (AiSettings | undefined)[], ai?: Brain): AiSettings;