@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/goals.d.ts

@@ -0,0 +1,360 @@
+import type { Cost } from '#engine/defs';
+import type { AiArea } from './area';
+import type { EntityState } from '#engine/session/protocol';
+import { type Brain } from './brain';
+import { type AiModuleDef } from './module';
+import type { Squad, SquadOptions } from './squads';
+import { UnitSet } from './view';
+/**
+ * A response curve: a number (how many, how strong, how long) to how much it matters, 0..1
+ *
+ * @beta
+ */
+export type Curve = (x: number) => number;
+/**
+ * The usual response curves, each a line (`consider(name, read, curve.saturate(6))`): how a raw number becomes "how
+ * much do I care". A curve gives 0..1; what gives nonsense (NaN) counts as 0
+ *
+ * @beta
+ */
+export declare const curve: {
+    /** A straight line from 0 at 0 to 1 at `max` (1 when left out: for a ratio), flat beyond: twice the units, twice the care, up to a point */
+    readonly linear: (max?: number) => Curve;
+    /** 1 − e^(−x/k): rises fast, then levels off at 1 (0.63 at `k`, 0.86 at `2k`): the sixth worker seen matters less than the first */
+    readonly saturate: (k: number) => Curve;
+    /** k / (k + x): 1 at 0, falling to a half at `k` and towards 0: the less there is of it, the better (how held their base is) */
+    readonly inverse: (k: number) => Curve;
+    /** 0 below `at`, 1 from it on: a threshold (a wave is ready at so many units), an on-off (any intruder at all: `step(1)`) */
+    readonly step: (at: number) => Curve;
+    /** 1 between `low` and `high`, 0 outside: a window (an army of between 4 and 12) */
+    readonly band: (low: number, high: number) => Curve;
+    /** A shape of the game's own: whatever the function gives, kept to 0..1 */
+    readonly custom: (fn: (x: number) => number) => Curve;
+};
+/**
+ * One question a goal asks of what it sees, and how much the answer matters: `read` gives the raw number, `curve`
+ * turns it into 0..1. The report keeps both
+ *
+ * @beta
+ */
+export interface Consideration {
+    /** What it asks, for the report: "intruders at my buildings" */
+    name: string;
+    /** The raw number, read from the brain each think: cheap, or cached for the think (`ai.cache`) */
+    read: (ai: Brain) => number;
+    /** How much the number matters, 0..1 */
+    curve: Curve;
+}
+/**
+ * A consideration: a question with a name, and the curve that says how much its answer matters (`curve.linear()`
+ * when left out: the number is a ratio already)
+ *
+ * @beta
+ */
+export declare function consider(name: string, read: (ai: Brain) => number, shape?: Curve): Consideration;
+/**
+ * What a goal is about, and so what it competes with: `army` goals claim units, `economy` goals money, `squad` and
+ * `hero` goals are about one of those (scored once each until squads (C1) and heroes (C2) score them apiece), or a
+ * game's own word
+ *
+ * @beta
+ */
+export type GoalScope = 'army' | 'economy' | 'squad' | 'hero' | (string & {});
+/**
+ * Why a goal lost its claim (`GoalDef.stop`): `beaten` by one that scored more by the margin, `urgent` by an urgent
+ * one, `done` as its own score fell to nothing, `told` by a rule or a module that took its units, `removed` from the
+ * brain
+ *
+ * @beta
+ */
+export type StopReason = 'beaten' | 'urgent' | 'done' | 'told' | 'removed';
+/**
+ * What a goal claims to run: units from the pool and money from the purse. The picker gives each goal what it asks
+ * of what is left, best goal first
+ *
+ * @beta
+ */
+export interface GoalClaims {
+    /**
+     * The units it takes, chosen from what it may have (`available`: the pool, and what goals it may take from hold):
+     * the nearest six fighters, one scout, everything. A goal that asks for units and gets none is not picked
+     */
+    units?: (ai: Brain, available: UnitSet) => Iterable<EntityState>;
+    /**
+     * The money it holds while it runs, in the game's money (`Registry.currency`) as a number, or as a cost by resource;
+     * a function for one that depends. Held against the purse (`Goals.reserved`), given back when the goal stops
+     */
+    money?: number | Cost | ((ai: Brain) => number | Cost | undefined);
+}
+/**
+ * What a picked goal was given (`GoalDef.run`): the units it holds this think (the dead and the lost dropped), the
+ * money, when it was picked, and whether this is the first think it runs
+ *
+ * @beta
+ */
+export interface Claimed {
+    /** The units it holds, as of this think's picture */
+    units: UnitSet;
+    /** The money it holds, where it asked for any */
+    money?: Cost;
+    /** The tick it was picked at */
+    began: number;
+    /** Whether this is the first think it runs: when its orders are to be sent, once */
+    first: boolean;
+    /**
+     * Makes a squad the goal owns (`ai.squads.make` with the goal as its `owner`): when the goal stops, its squads go.
+     * Called again for a name the goal has a squad of already (a run each think), it is that squad, kept as it is (its
+     * task, its `size`), the units given added to it and its options those given now
+     */
+    squad(name: string, units: Iterable<EntityState | number>, options?: SquadOptions): Squad;
+}
+/**
+ * A goal: something the computer could do, scored by its considerations, run with what it claims (`defineGoal`)
+ *
+ * @beta
+ */
+export interface GoalDef {
+    /** Unique among the brain's goals, prefixed as components are (the engine's `ai.defend`, a game's `mygame.raid`) */
+    id: string;
+    /** What it is about: `army` when left out */
+    scope?: GoalScope;
+    /** Its questions: the score is their product (a soft AND: one at 0 vetoes the goal), times the weight */
+    considerations: Consideration[];
+    /** What it is worth against the other goals at their best: 1 when left out */
+    weight?: number;
+    /** The score under which it is not picked: the picker's (`PickingOptions.min`) when left out */
+    min?: number;
+    /** What it takes to run: units, money. None: it runs on its score alone, holding nothing */
+    claims?: GoalClaims;
+    /**
+     * Seconds it keeps its claim once picked, unless another scores more than it by the margin, or an urgent one scores
+     * more at all. The picker's default when left out. Hysteresis: without it two close goals swap every think
+     */
+    commitment?: number;
+    /** How much more another goal must score to take from this one within its commitment: the picker's when left out */
+    margin?: number;
+    /** Whether it may break another goal's commitment as soon as it scores more: a raid that cannot wait */
+    urgent?: boolean | ((ai: Brain) => boolean);
+    /** Seconds after it stops before it may be picked again */
+    cooldown?: number;
+    /** What it does, each think it holds its claim: `claimed.first` on the first, where its orders are sent once and then watched */
+    run(ai: Brain, claimed: Claimed): void;
+    /** Told when it loses its claim, and why: to let go of what it was doing */
+    stop?(ai: Brain, why: StopReason, claimed: Claimed): void;
+}
+/**
+ * Defines a goal: checked, and given back as it is, for a brain's `goals`, `meleeBrain.with({ goals })`, or
+ * `ai.goals.add`
+ *
+ * @beta
+ */
+export declare function defineGoal(def: GoalDef): GoalDef;
+/**
+ * How a brain picks among its goals, where a goal does not say for itself (`BrainDef.picking`)
+ *
+ * @beta
+ */
+export interface PickingOptions {
+    /** The score under which a goal is not picked: 0.05 when left out */
+    min?: number;
+    /** How much more a goal must score than a committed one to take from it: 0.15 when left out */
+    margin?: number;
+    /** Seconds a picked goal keeps its claim: 5 when left out */
+    commitment?: number;
+}
+/**
+ * What a goal holds while it runs: its units (ids, of the player's), its money, when it was picked and until when it
+ * is committed. Plain data, kept in the brain's memory
+ *
+ * @beta
+ */
+export interface Hold {
+    /** The units it holds, by id, in the picture's order */
+    units: number[];
+    /** The money it holds (`GoalClaims.money`) */
+    money?: Cost;
+    /** The tick it was picked at */
+    since: number;
+    /** The tick its commitment ends at: for a rule's or a module's hold (`take` with `by`), the tick it lets go at */
+    until: number;
+    /** For a rule's or a module's hold: kept until let go of (`release`), whatever `until` says. A squad of one's own holds so */
+    kept?: true;
+    /** What it scored when picked */
+    score: number;
+}
+/**
+ * What the goals remember between thinks: what each holds, and until when each is on cooldown
+ *
+ * @beta
+ */
+export interface GoalsMemory {
+    /** The version of this shape */
+    v: 1;
+    /** What each goal holds, by goal id */
+    holds: Record<string, Hold>;
+    /** The tick each goal on cooldown may be picked again at, by goal id */
+    cooldowns: Record<string, number>;
+}
+/**
+ * One goal as the picker last saw it: for the debug tools, and for "why did it do that"
+ *
+ * @beta
+ */
+export interface GoalReport {
+    /** The goal */
+    id: string;
+    /** What it is about */
+    scope: GoalScope;
+    /** Its score: the considerations' product, weighed */
+    score: number;
+    /**
+     * Each question, its raw answer and how much that mattered. One after a question answered 0 is not asked (the goal
+     * is vetoed already): `asked: false`, its numbers 0
+     */
+    considerations: {
+        name: string;
+        value: number;
+        curved: number;
+        asked?: false;
+    }[];
+    /** Whether it ran this think */
+    picked: boolean;
+    /** Whether it may break a commitment now */
+    urgent: boolean;
+    /** What it holds: how many units (and which, `ids`), how strong together, the money, since when and until when (ticks) */
+    held?: {
+        units: number;
+        ids: number[];
+        strength: number;
+        money?: Cost;
+        since: number;
+        until: number;
+    };
+    /** Why it did not run, where it scored enough: `cooldown`, `nothing to claim`, or what it lost its claim to */
+    why?: string;
+}
+/**
+ * The brain's goals and their picker (`ai.goals`): what the computer could do, scored each think, the best given what
+ * they claim (`think`, once a think: run by the `goals()` module, or by a module of the brain's own in its place among
+ * the others). What each holds is read here (`held`, `holds`, `holder`, `pool`), taken by a rule or a module
+ * (`take`), and reported (`report`)
+ *
+ * @beta
+ */
+export declare class Goals implements AiArea {
+    /** The brain they are the goals of */
+    readonly ai: Brain;
+    /** Its id among the brain's areas: what its memory and its report are kept under */
+    readonly id = "goals";
+    /** What the log says where a save's memory of it is of a shape it does not read */
+    readonly afresh = "the save remembers what the computer player\u2019s goals held in a shape this brain does not read: they start afresh";
+    /** How much each goal scored this think, by id: what the debug tools showed before the report */
+    scores: Record<string, number>;
+    /** The goal that scored highest above the minimum this think: what the army is on. None when nothing is worth doing */
+    best: string | undefined;
+    private readonly entries;
+    private holds;
+    private cooldowns;
+    private added;
+    private thoughtAt;
+    private readonly min;
+    private readonly margin;
+    private readonly commitment;
+    constructor(
+    /** The brain they are the goals of */
+    ai: Brain, options?: PickingOptions);
+    /** Adds goals to pick among: a brain's own (`BrainDef.goals`), the seat's (`AiOptions.goals`), a module's */
+    add(...defs: GoalDef[]): void;
+    /** Takes a goal out: what it held goes back to the pool, and it is told `removed`. Whether there was one */
+    remove(id: string): boolean;
+    /** The goals, as added */
+    list(): GoalDef[];
+    /** A goal by id */
+    get(id: string): GoalDef | undefined;
+    /** What a goal holds, while it does */
+    held(id: string): Hold | undefined;
+    /** What every goal holds, by goal id */
+    all(): Readonly<Record<string, Hold>>;
+    /** The goal that holds a unit, by the unit's id: none for a unit in the pool */
+    holder(unit: number): string | undefined;
+    /** The player's units no goal holds, as of the think's picture: what a goal picked next may claim */
+    pool(): UnitSet;
+    /** The money the goals hold together (`GoalClaims.money`): held in the purse (`ai.purse`), which takes it off what is free */
+    reserved(): Cost;
+    /**
+     * Takes units from whatever goals hold them, for a rule (B2) or a module (the defence, C4) that wants them: a goal
+     * left with none is told why (`told` when left out). Those of them that were held, by id.
+     *
+     * With `by`, the units are then held by that rule or module itself (`by.id`, which names no goal: `rule:attack`),
+     * for `by.seconds` (30 when left out) or until `release(by.id)`: no goal may claim them meanwhile, for a rule goes
+     * before the goals (the one order of who may move a unit: goals, then rules take, then the defence; micro never
+     * retasks). Units taken again by the same id are added to what it holds, and its time starts again. `seconds:
+     * Infinity` holds them until let go of (`release`, `drop`): what a squad that is no goal's holds its units by
+     */
+    take(units: Iterable<number>, why?: StopReason, by?: {
+        id: string;
+        seconds?: number;
+    }): number[];
+    /**
+     * Adds units from the pool (what nothing holds) to what a goal, a rule or a module holds: a squad's reinforcements
+     * (`Squad.reinforce`). What another holds is passed over: `take` is for that. Those given, by id
+     */
+    give(id: string, units: Iterable<number>): number[];
+    /**
+     * Lets go of some of what a goal, a rule or a module holds: they go back to the pool. One left with none is released,
+     * told why (`done` when left out). Those let go of, by id
+     */
+    drop(id: string, units: Iterable<number>, why?: StopReason): number[];
+    /** What rules and modules hold (`take` with `by`), by their id: not goals' */
+    taken(): Record<string, Hold>;
+    /** Whether a unit is held by a rule or a module rather than by a goal (`take` with `by`): what nothing else is to give orders to */
+    ruled(unit: number): boolean;
+    /** Takes a goal's claim away, telling it why (`told` when left out): its units go back to the pool. Whether it held one */
+    release(id: string, why?: StopReason): boolean;
+    /**
+     * The think: every goal scored (its considerations read, curved, multiplied, weighed), the goals that hold a claim
+     * kept to it or beaten, the rest picked best first with what they claim, and each picked one run. Once a think: a
+     * second call in the same think does nothing
+     */
+    think(): void;
+    /**
+     * A goal's score this think: each consideration read and curved, their product, the weight, the game's say. Once a
+     * consideration answers 0 the goal is vetoed, and the ones after it are not asked: put the cheap questions first
+     */
+    private score;
+    /** Writes down a goal picked anew, for the decision log: its score, what it holds, its considerations */
+    private decided;
+    /**
+     * What a goal picked anew takes: the units it chooses from the pool and from the holds of goals ranked below it
+     * that it may take from (by the margin within their commitment, by any lead after it, and by any lead at all for an
+     * urgent goal), and the money it names. Nothing where it asked for units and chose none
+     */
+    private claim;
+    /** The money a goal names, as a cost: a number is in the game's money */
+    private moneyOf;
+    /** What a goal holds, as it is handed to it */
+    private claimedOf;
+    private heldIds;
+    /** Every goal as the picker last saw it: score, considerations, what it holds, why it did not run */
+    report(): GoalReport[];
+    /** What is held and on cooldown, for a save */
+    /** Whether it has anything to remember now: one that does not is left out of a save */
+    remembers(): boolean;
+    save(): GoalsMemory;
+    /** Takes back what `save` gave: whether it was read */
+    restore(memory: unknown): boolean;
+    /** What the debug tools show: the report, the best, and the picker's numbers */
+    inspect(): Record<string, unknown>;
+}
+/**
+ * The goals module: runs the brain's picker (`ai.goals.think`) in its place among the brain's modules, after what
+ * reads the game and before what acts on orders. With goals of its own to add to the brain's
+ *
+ * @beta
+ */
+export declare const goals: (defs?: GoalDef[]) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        goals?: GoalsMemory;
+    }
+}

package/dist/ai/index.d.ts

@@ -0,0 +1,38 @@
+export { Brain, type BrainContext, type BrainDef, type BrainExtension, type BrainMemory, type BrainWatcher, createBrain, type Told } from './brain';
+export { AI_PHASES, type AiModule, type AiModuleDef, type AiPhase, defineModule, type ModuleKey, moduleKey } from './module';
+export { defineBrain, type DefinedBrain } from './define';
+export { an, pair, plural, point, where } from './geometry';
+export { aiTeams, type ComputerPlayer, type ComputerSystem, type ComputerSeatOptions, type ComputerTiming, createBrainSystem, createComputerSystem, defineComputer, type MapAi } from './computer';
+export type { AiOptions } from './options';
+export type { BrainSeat, ComputerSeat, SeatRequest } from '../computers';
+export { ThinkBudget, type ThinkBudgetOptions } from './budget';
+export { AI_INVARIANTS, type AiCheckOptions, type AiEndLimits, type AiInvariant, type AiViolation, BrainChecks, checkBrain } from './checks';
+export { MELEE_LADDER, MeleeArmy, type MeleeArmyMemory, type MeleeArmyModule, MELEE_ARMY, type MeleeArmyOptions, meleeArmy, meleeArmyOf, meleeBrain, meleeBuild, type MeleeBuildOptions, meleeHeroes, type MeleeHeroesOptions, meleeProduction, meleeSurrender, type MeleeSurrenderOptions, type MeleeWant } from './melee';
+export { ambush, type AmbushThen, fleeWhen, guard, holdPosition, missionBrain, type MissionBrainDef, type MissionPartMemory, type MissionPartOptions, type MissionPlace, type MissionTarget, type MissionUnits, type MissionUnitsData, patrol, surrenderWhen, waveFrom } from './mission';
+export { lanesBrain, lanesBrainOf, laneAt, type LaneSide, LANES, type LanesModule, LanesPlay, type LanesPlayMemory, type LanesPlayOptions, type LaneState, lanesPlay, lanesTargets, onLane } from './lanes';
+export { DEFEND, defence, type DefenceMemory, type DefenceOptions, type DefenceReport, type Raid } from './defence';
+export { type Look, SCOUT, scouting, type ScoutingMemory, type ScoutingOptions, type ScoutingReport } from './scouting';
+export { economy, type EconomyBase, type EconomyMemory, type EconomyOptions, type EconomyReport, type WorkersPer } from './economy';
+export { type Claimed, consider, type Consideration, curve, type Curve, defineGoal, type GoalClaims, type GoalDef, type GoalReport, goals, Goals, type GoalScope, type GoalsMemory, type Hold, type PickingOptions, type StopReason } from './goals';
+export { type ArmySighting, type AttackSent, type DamageSeen, type DeathSeen, type EnemyBase, EnemyKnowledge, HeardEvents, Knowledge, type KnowledgeMemory, type KnowledgeOptions, type Loss, MapKnowledge, OwnKnowledge, type PingHeard, type StructureSeen, type TypeSeen, type UnitSeen } from './knowledge';
+export { type AiHints, type AiRole, inferRoles, type RoleEntry, Roles, type RolesFinder, type RolesPlayer, type RoleTable } from './roles';
+export { type Counter, type CounterHint, defaultStrength, type Force, type Matchup, Strength, type StrengthFormula, type StrengthInput } from './strength';
+export { type AiAction, type AiActionData, type AiCondition, type AiConditionData, type AiConditionTest, type AiRange, type AiRule, type AiWhose, evaluate, type RuleBuilder, rules, when, type WordData, words } from './rules';
+export { build, BuildPlan, type BuildPlanMemory, type BuildPlanOptions, type BuildPlanReport, type Want, type WantData, type WantReport } from './plans/build';
+export { enemyDirection, type PlacementName, placements, type PlacementStrategy, type PlacementTable, rings, type SiteRequest } from './plans/placement';
+export { type BuildOrderItem, Plans, type PlansMemory, type PlansOptions, type PlansReport } from './plans/plans';
+export { type Composition, type CompositionReport, production, ProductionPlan, type ProductionPlanMemory, type ProductionPlanOptions, type ProductionPlanReport, UPKEEP_SPARE, UPKEEP_TIER } from './plans/production';
+export { Purse, type PurseReport } from './plans/purse';
+export { techPath, type TechPath, type TechStep } from './plans/tech';
+export { type AiDecision, type AiReport, type AiStats, Decisions, type KnowledgeReport, type ThreatReport } from './report';
+export { type AbilityAiView, type HeroPlan, type HiringItem, micro, type MicroMemory, type MicroOptions, type MicroReport, type ShoppingItem, type SpellAim, type TargetPicker, type TargetRule } from './micro';
+export { Squad, type SquadData, SquadGroup, type SquadOptions, type SquadReport, squads, Squads, type SquadsMemory, type SquadsOptions } from './squads';
+export { defineTask, type TaskCommon, type TaskData, type TaskDef, type TaskDone, type TaskMemory, type TaskOrder, type TaskState } from './task';
+export { ATTACK, CAPTURE, type CaptureData, CREEP, type CreepData, DEFEND_TASK, type DefendData, type DefendMemory, ESCORT, type EscortData, type FightData, type FightMemory, GATHER, type GatherData, HARASS, HOLD, type HoldData, MOVE, type MoveData, PATROL, RETREAT, type RetreatData, type RoundData, type RoundMemory, SCOUT_TASK } from './tasks';
+export { type AiFlag, type AiFlags, type AiHandicap, type AiProfile, type AiProfileTable, DEFAULT_PROFILE, DIFFICULTIES, difficultiesOf, flagOf, type GameAi, PERSONALITIES, personalitiesOf, type ResolvedProfile, resolveProfile } from './profiles';
+export { type AiSettings, resolveSettings } from './settings';
+export { type AttackPlan, HELP, team, type TeamBoard, type TeamOptions, type TeamPlayMemory, type TeamReport, type TeamRequest } from './team';
+export { type AttackGroup, type AttackWave, type WaveTarget, waves, type WavesMemory, type WavesOptions, type WavesReport } from './waves';
+export { type Threat, type ThreatCell, ThreatMap, type ThreatQuery } from './threat';
+export { AiView, type Base, type Me, UnitSet, ViewEvents, type ViewOptions } from './view';
+export { missionRules } from './missionRules';