@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/melee/build.d.ts

@@ -0,0 +1,61 @@
+import { type AiModuleDef } from '#engine/ai/module';
+import type { AiRole } from '#engine/ai/roles';
+import { type AiConditionData } from '#engine/ai/rules';
+/**
+ * One rung of the melee player's ladder of wants: what to have, by role, how many, how important, money to spare,
+ * when. `counter` and `tier` are worked out each think (the file's comment); any other role is the first type of it
+ * the player can make
+ *
+ * @beta
+ */
+export interface MeleeWant {
+    /** The want's id on the build plan (`melee.barracks`): what the report shows, what `without` leaves out */
+    id: string;
+    /**
+     * A role of the kit's (`hall`, `barracks`, `altar`, `workshop`, `tower`), or one worked out: `counter` (the
+     * building its best answer to their army needs), `tier` (the next tier of its hall), `expand` (another hall by a
+     * free mine once the mine at home runs low, FJ1)
+     */
+    role: AiRole | 'counter' | 'tier' | 'expand';
+    /** How many of it to have: 1 when left out */
+    count?: number;
+    /** How important it is to the purse: a want of more goes first and may spend what is held for one of less */
+    priority: number;
+    /** Money to keep spare before it is paid for (a luxury waits until there is this much over its price) */
+    spare?: number;
+    /** Only while this holds (`AiConditionData`): `{ units: { role: 'barracks' } }` for the next tier */
+    when?: AiConditionData;
+}
+/**
+ * The melee player's ladder as it stands: a hall, a barracks, another hall once the mine at home runs low, an altar,
+ * the building its best answer needs, the next tier of its hall once a barracks stands (FJ1: before the workshop, so
+ * that what the tier opens is trained while it matters), a workshop, a second barracks with money to spare
+ *
+ * @beta
+ */
+export declare const MELEE_LADDER: readonly MeleeWant[];
+/**
+ * How the melee brain builds (`build()` of the melee brain): its ladder of wants, and how much better an answer to
+ * their army must be for its building to be put up
+ *
+ * @beta
+ */
+export interface MeleeBuildOptions {
+    /** The ladder of wants, most important first: `MELEE_LADDER` when left out */
+    ladder?: readonly MeleeWant[];
+    /** How much better a type must answer their armies than what it can train now, for the building it needs to be put up: 1.2 when left out */
+    counterMargin?: number;
+    /**
+     * The part of what it held left in the mine at home under which another hall by a free mine is wanted (the `expand`
+     * rung): 0.35 when left out. 0 for never
+     */
+    expandAt?: number;
+}
+/**
+ * The melee brain's build module: the ladder of wants set on the build plan each think, the counter and the tier
+ * worked out, the plan thought. After the heroes, before the production and the picker, as the old turn had it;
+ * `steps.construction` honoured
+ *
+ * @beta
+ */
+export declare const build: (options?: MeleeBuildOptions) => AiModuleDef;

package/dist/ai/melee/goals.d.ts

@@ -0,0 +1,299 @@
+import type { MeleeSurrenderOptions } from './surrender';
+import { type Brain } from '#engine/ai/brain';
+import { type AiModule, type AiModuleDef } from '#engine/ai/module';
+import { type GoalDef } from '#engine/ai/goals';
+import type { UnitSet } from '#engine/ai/view';
+/**
+ * How the melee player's army goes about its own waves and the goals beside them (`AiSettings.army` over the melee
+ * brain's `army(options)`). Data: a save keeps the seat's
+ *
+ * @beta
+ */
+export interface MeleeArmyOptions {
+    /** Seconds before its first wave: 150 when left out */
+    firstAttack?: number;
+    /** Seconds between two waves: 45 when left out */
+    attackEvery?: number;
+    /** Units in its first wave, each after bringing two more: 6 when left out */
+    waveSize?: number;
+    /**
+     * The odds (`Strength.odds`) of what it has ready against their army as last seen (the last minute) under which a
+     * wave whose time has come waits and trains on rather than go: 0.4 when left out; `false` never waits
+     */
+    goOdds?: number | false;
+    /**
+     * Seconds a wave waits past its time at the most, outmatched or short of its size: then it goes with what it has,
+     * half the wave at the least, where that would hold against what is remembered to reach the target. Twice
+     * `attackEvery` when left out. A wave that could never reach its size (the supply capped) still comes
+     */
+    waitAtMost?: number;
+    /** Whether a wave that razed what it went for goes on to the next of their buildings it knows, while it is strong enough: yes when left out */
+    pressOn?: boolean;
+    /**
+     * Where a wave of its own goes among their buildings it knows of: the `nearest`, or the `weakest` (the one the least
+     * of their strength is remembered to reach: an expansion before a main with towers; the nearest among those alike).
+     * `weakest` when left out
+     */
+    target?: 'nearest' | 'weakest';
+    /**
+     * Whether a wave of theirs that died at its gate is answered at once with what is ready (half a wave at the least),
+     * their base being empty of it: yes when left out. `counterAfter` is how many of their fighters must have fallen
+     * near its bases in the last twenty seconds (3 when left out)
+     */
+    counter?: boolean;
+    counterAfter?: number;
+    /** The odds against their army as last seen a wave needs to go on: 0.5 when left out */
+    pressOdds?: number;
+    /** Whether idle fighters at home join a wave that is out, making up what it lost: yes when left out */
+    reinforce?: boolean;
+    /**
+     * A strike while their army is away (FJ1): every sighting of their army within `awayFor` seconds (60) stands far
+     * from what a wave would go for (their base, out raiding or creeping or at a base of mine), and what is ready (half
+     * a wave at the least) would hold against what is remembered to reach it at these odds (`odds`, 0.6): the wave goes
+     * before its time. `false` for none
+     */
+    strike?: false | {
+        awayFor?: number;
+        odds?: number;
+    };
+    /** Units more in each wave than the one before: 2 when left out */
+    waveGrowth?: number;
+    /** The most units a wave of its own asks for: 24 when left out */
+    waveMax?: number;
+    /**
+     * Raids on their workers where their army is not (the `raid` goal): how many go (`size`, 3, the fastest), the odds
+     * against what is remembered at the base they need (`odds`, 0.6), seconds between raids (`every`, 60), seconds
+     * their army must not have been seen near the base (`armyAwayFor`, 45), how long ago their workers were seen at
+     * the most (`workersSeenFor`, 120), the odds the raiders fall back at (`retreatAt`, 0.5). `false` for no raids
+     */
+    raid?: false | {
+        size?: number;
+        odds?: number;
+        every?: number;
+        armyAwayFor?: number;
+        workersSeenFor?: number;
+        retreatAt?: number;
+    };
+    /**
+     * Harassing their main before the first wave (the `harass` goal): the party (`size`, 3: the hero and the fastest),
+     * the odds it needs at their base (`odds`, 0.6), seconds between (`every`, 90), the odds it falls back at
+     * (`retreatAt`, 0.5). `false` for none
+     */
+    harass?: false | {
+        size?: number;
+        odds?: number;
+        every?: number;
+        retreatAt?: number;
+    };
+    /**
+     * Guards at a base past home that has no tower yet (the `expand` goal): how many (`guards`, 2), and how many
+     * fighters past a wave must stand idle for any to go (`spare`, 0). `false` for none
+     */
+    expand?: false | {
+        guards?: number;
+        spare?: number;
+    };
+    /**
+     * Creeping (the `creep` goal): seconds between camps (`every`, 40), seconds into the game before the first
+     * (`from`, 30), how far from home a camp may be (`reach`, 70), the fewest in a party (`party`, 3). `false` for none
+     */
+    creep?: false | {
+        every?: number;
+        from?: number;
+        reach?: number;
+        party?: number;
+    };
+    /**
+     * When it gives up (the `melee.surrender` module, `MeleeSurrenderOptions`): once it has no hall, no worker and no
+     * army that could win the game back, for half a minute, when left out; a condition of the game's own (`when`), and
+     * how long it holds first (`after`). `false` plays to the last
+     */
+    surrender?: false | MeleeSurrenderOptions;
+}
+/**
+ * What the army module remembers between thinks, as a save keeps it (`BrainMemory.modules['melee.army']`)
+ *
+ * @beta
+ */
+export interface MeleeArmyMemory {
+    v: 1;
+    /** Units the next wave of its own asks for */
+    waveSize: number;
+    /** Seconds into the game the next wave's time comes */
+    nextAttack: number;
+    /** Seconds into the game it may go creeping again */
+    nextCreeping: number;
+    /** Waves sent */
+    attacks: number;
+    /** The tick the wave it last said it falls back with turned at: said once a retreat */
+    saidRetreat?: number;
+    /** Seconds into the game the wave began waiting past its time, short of its size or outmatched (`goOdds`): none while it is not */
+    waiting?: number;
+    /** The tick the last raid was sent at */
+    raided?: number;
+    /** The tick the last harassing party was sent at */
+    harassed?: number;
+}
+/**
+ * The army module, with the army it runs (`MeleeArmy`): what the tests and the debug tools reach (`meleeArmyOf`)
+ *
+ * @beta
+ */
+export interface MeleeArmyModule extends AiModule {
+    army: MeleeArmy;
+}
+/**
+ * What finds the melee army's module with its shape (`ai.module(MELEE_ARMY)`)
+ *
+ * @beta
+ */
+export declare const MELEE_ARMY: import("#engine/ai/module").ModuleKey<MeleeArmyModule>;
+/**
+ * The melee brain's army (`MeleeArmy`) of a brain: its waves, numbers and memory, for the tests and the debug tools.
+ * Throws for a brain without the `melee.army` module
+ *
+ * @beta
+ */
+export declare function meleeArmyOf(ai: Brain): MeleeArmy;
+/**
+ * The melee player's army: its waves of its own and the goals beside them (the file's comment), its numbers from its
+ * options (`firstAttack`, `attackEvery`, `waveSize`) and the defence's radius, its memory. Made for a brain by
+ * the `army()` module; reached as `ai.module(MELEE_ARMY)?.army` (`meleeArmyOf(ai)`)
+ *
+ * @beta
+ */
+export declare class MeleeArmy {
+    /** The brain it is the army of */
+    readonly ai: Brain;
+    /** How it goes: the module's options, the brain's settings over them (`ai.settings.army`) */
+    readonly options: MeleeArmyOptions;
+    readonly memory: MeleeArmyMemory;
+    readonly firstAttack: number;
+    readonly attackEvery: number;
+    readonly defendRadius: number;
+    constructor(
+    /** The brain it is the army of */
+    ai: Brain, 
+    /** How it goes: the module's options, the brain's settings over them (`ai.settings.army`) */
+    options: MeleeArmyOptions);
+    private get time();
+    /** Its fighters: what is gathering (a ghoul at the trees) is at work, not in the army */
+    private armyOf;
+    /** The fighters no goal holds and with nothing to do: what a wave or a party is made of. Once a think */
+    ready(): UnitSet;
+    private readyOf;
+    /** Their army as last seen within so many seconds, summed by type: a force to weigh odds against */
+    private theirs;
+    /** The odds of a force of mine against their army as last seen within so many seconds: 1 where none was seen */
+    private oddsAgainstTheirs;
+    /** The odds of a force of mine against what is remembered to reach a place (towers, their army seen near it), by the square law */
+    private oddsAt;
+    /** Whether its team asks it to join an attack together it has not answered, while its waves wait for the team's (`together`) */
+    private invited;
+    /**
+     * Whether it has no mercy (No Mercy, a flag of its profile): the enemy's army as last seen (the last minute) weak
+     * against what it has ready, at the odds the flag says (0.75 for `true`), and it goes before its time
+     */
+    private merciless;
+    /**
+     * Whether the wave is worth sending now: what is ready would not lose outright against their army as last seen
+     * (`goOdds`), or it has waited long enough (`waitAtMost`). Nothing seen of their army: worth it
+     */
+    private worthGoing;
+    /**
+     * Whether a wave of theirs just died at its gate (so many of their fighters fallen near its bases in the last twenty
+     * seconds): their base is empty of it, and what is ready goes at once
+     */
+    private counterAttack;
+    /**
+     * Whether their army is away from what a wave would go for (`strike`): at least one sighting of it within `awayFor`
+     * seconds (nothing seen says nothing of where it is), every one far from the target and from every base of mine and
+     * every building of my allies' (an army at my gate is the defence's, at an ally's the team's: not a reason to trade
+     * bases), and what is ready (half a wave at the least) would hold against what is remembered to reach the target
+     * (its towers). Once a think
+     */
+    private armyAway;
+    /** Whether the wave has waited past its time as long as it will (`waitAtMost`): it goes with what it has then */
+    private waitedEnough;
+    /**
+     * Whether the wave is ready: as many as it asks for stand idle; or half of them, once it has waited long enough and
+     * they would hold against what is remembered to reach the target (half a wave is not fed to the towers)
+     */
+    private waveReady;
+    /**
+     * Where a wave goes: of the rival's buildings it knows of (in sight or remembered, not a creep's), the nearest, or
+     * (`target: 'weakest'`) the one the least of their strength is remembered to reach (an expansion before a main with
+     * towers), the nearest among those alike; else a base it was told of
+     */
+    private targetFor;
+    /**
+     * A way of its own for a wave (Random Paths, a flag of its profile): by the brain's numbers, straight, or by a place a
+     * third of the way's length to one side or the other of its middle. None for straight, or without the flag
+     */
+    private wayOf;
+    /**
+     * How the squads it sends out behave: they fall back from a fight away from home at the odds a wave used to (the
+     * profile's `retreatOdds`, or Groups Flee), fight on to the last near home, and a wave is made up from home
+     * (`reinforce`); the seat's say goes over it
+     */
+    private get outward();
+    /** A party's options: as a wave's, but it falls back sooner and nobody comes after it */
+    private party;
+    /** Sends a wave: its squad to attack the target, the next wave set, said where it says things */
+    private launch;
+    /**
+     * The squad a goal of its sent out (`wave`, `creep`, `raid`, `harass`, `expand`), while it is on its errand: on its
+     * way, fighting, falling back, or (a wave) done with its target, to go on or to be sent home. None once its task is
+     * over, or before it was sent
+     */
+    private out;
+    /**
+     * Whether a wave that razed what it went for goes on: it may, it is still a few, it is strong enough against their
+     * army as last seen and against what is remembered to reach the next target (its towers), and it knows of more of theirs
+     */
+    private mayPressOn;
+    /** The camp its ready units and hero can take near home, when it is time to go creeping */
+    private campToTake;
+    /** Where a raid would go: the base of theirs with the most workers seen lately and no army seen near it, with how many */
+    private raidTarget;
+    /** The fastest fighters of some, no heroes among them, up to so many: a party; none where fewer than two */
+    private fastest;
+    /** The raiders of what may go: the fastest few, where a raid is on and they would not die at the base */
+    private raiders;
+    /** Their main as known: the first base of theirs with a hall, nearest home */
+    private theirMain;
+    /** The party that harasses: the hero and the fastest few, where their army was not seen at their main lately and the party would hold */
+    private harassers;
+    /** Whether a base of mine still wants guards: past home, with no finished tower among its buildings */
+    private wantsGuards;
+    /** The bases past home that want guards and have none: no fighters of mine standing by them. Once a think */
+    private unguarded;
+    /** The base the expand squad guards, where it still wants guards */
+    private guarded;
+    /** The guards for the first base wanting them: the fighters nearest it, so many, from what stands idle past a wave */
+    private guards;
+    /** The goals, for the picker: attack, creep, raid, harass, expand (each unless left out) */
+    goals(): GoalDef[];
+    private attackGoal;
+    /** The attack goal's turn: the wave out watched (its fall back, its wait for the team, its next target), or sent */
+    private attack;
+    private creepGoal;
+    private raidGoal;
+    private harassGoal;
+    private expandGoal;
+    /** Once a think, before the picker: whether the wave began waiting past its time, short of its size or outmatched */
+    think(): void;
+    /** What it remembers, for a save: a copy */
+    save(): MeleeArmyMemory;
+    /** Takes back what `save` gave */
+    restore(data: unknown): void;
+    /** What it is thinking, for the debug tools: how hard it plays, its next wave, its roles */
+    inspect(): Record<string, unknown>;
+}
+/**
+ * The melee brain's army module: the goals of the army put on the picker (attack, creep, raid, harass, expand), the
+ * wave's wait counted. Before the picker (`goals`), after the building and the production, as the old turn had it. With how the army goes where the seat says nothing (`MeleeArmyOptions`)
+ *
+ * @beta
+ */
+export declare const army: (options?: MeleeArmyOptions) => AiModuleDef;

package/dist/ai/melee/heroes.d.ts

@@ -0,0 +1,27 @@
+import { type AiModuleDef } from '#engine/ai/module';
+/**
+ * How the melee brain makes its heroes (`heroes()` of the melee brain): how many once the game is under way (the
+ * profile's `heroes`), from when, and how important their price is to the purse
+ *
+ * @beta
+ */
+export interface MeleeHeroesOptions {
+    /** Heroes it has once the game is under way (`secondFrom`): one before. 2 when left out */
+    most?: number;
+    /** Seconds into the game from which it wants every hero it may have: one before. 240 when left out */
+    secondFrom?: number;
+    /**
+     * How important a hero's price is to the purse while it is short (`Purse.reserve`): the hall, supply, the barracks,
+     * the altar, the answer to their army and another hall go before it (their wants are more important); a workshop,
+     * the next tier, a second barracks and the soldiers wait for it. 35 when left out
+     */
+    priority?: number;
+}
+/**
+ * The melee brain's heroes module: a fallen hero revived, the next trained while it wants more, their price held in the
+ * purse meanwhile. After the economy, before the building, as the old turn had it; `steps.heroes` and
+ * `steps.buildOrder` honoured
+ *
+ * @beta
+ */
+export declare const heroes: (options?: MeleeHeroesOptions) => AiModuleDef;

package/dist/ai/melee/index.d.ts

@@ -0,0 +1,14 @@
+import { type DefinedBrain } from '#engine/ai/define';
+/**
+ * The engine's melee computer player as a brain: what `world.computers.seat` seats where no brain is named and the game
+ * lists it first. It thinks as its profile says (the difficulty's `every`), unless the
+ * seat's options say how often. The file's comment lists its modules
+ *
+ * @beta
+ */
+export declare const meleeBrain: DefinedBrain;
+export { build as meleeBuild, MELEE_LADDER, type MeleeBuildOptions, type MeleeWant } from './build';
+export { army as meleeArmy, MeleeArmy, type MeleeArmyMemory, type MeleeArmyModule, type MeleeArmyOptions, meleeArmyOf, MELEE_ARMY } from './goals';
+export { heroes as meleeHeroes, type MeleeHeroesOptions } from './heroes';
+export { production as meleeProduction } from './production';
+export { surrender as meleeSurrender, type MeleeSurrenderOptions } from './surrender';

package/dist/ai/melee/production.d.ts

@@ -0,0 +1,8 @@
+import { type AiModuleDef } from '#engine/ai/module';
+/**
+ * The melee brain's production module: the production plan thought, after the building and before the picker, as the
+ * old turn had it; `steps.production` honoured
+ *
+ * @beta
+ */
+export declare const production: () => AiModuleDef;

package/dist/ai/melee/surrender.d.ts

@@ -0,0 +1,24 @@
+import { type AiModuleDef } from '#engine/ai/module';
+import { type AiCondition } from '#engine/ai/rules';
+/**
+ * When the melee player gives up (`MeleeArmyOptions.surrender`): the condition, and how long it holds first
+ *
+ * @beta
+ */
+export interface MeleeSurrenderOptions {
+    /**
+     * When it cannot come back, as a condition (data or a function of the brain). By default: no hall and no worker of
+     * its own, and its fighters (none at all, or) outmatched by their army as last seen in the last two minutes, odds
+     * under 0.2
+     */
+    when?: AiCondition;
+    /** Seconds the condition holds on end before it gives up: 30 when left out */
+    after?: number;
+}
+/**
+ * The melee brain's surrender module (`melee.surrender`): gives up once it cannot come back (see
+ * `MeleeSurrenderOptions`), the engine's `surrender` command sent once. Its options under the settings' (`army.surrender`)
+ *
+ * @beta
+ */
+export declare const surrender: (options?: MeleeSurrenderOptions) => AiModuleDef;