@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/ai/task.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A kind of task a squad is on (design review B10): its definition (`TaskDef`, `defineTask`), typed by what it is given
+ * (`TaskData`) and what it remembers (`TaskMemory`), and its state as the brain keeps it (`TaskState`). Apart from the
+ * squads (`squads.ts`), so that the kit's tasks (`tasks/`) and a game's define theirs without loading the squads
+ */
+import type { Vec2 } from '#engine/math';
+import type { Brain } from './brain';
+import type { Squad } from './squads';
+/**
+ * How a task ended (`TaskState.done`): `arrived` where it was sent, `cleared` with nothing left to fight where it went,
+ * `lost` its target (gone from sight: killed, or out of it), `retreated` home after a fight it was losing, `wiped`
+ * with none of its units left; or a game's own word
+ *
+ * @beta
+ */
+export type TaskDone = 'arrived' | 'cleared' | 'lost' | 'retreated' | 'wiped' | (string & {});
+/**
+ * A task to give next (`then`): its kind (the kit's `attack`, a game's `defineTask` id) and what it is given
+ *
+ * @beta
+ */
+export interface TaskOrder {
+    kind: string;
+    data?: TaskData;
+}
+/**
+ * What any task may be given beside its own (`TaskState.data`): the task after it (`then`), and `regroup: false` for one
+ * not stopped for its stragglers
+ *
+ * @beta
+ */
+export type TaskCommon = {
+    then?: TaskOrder;
+    regroup?: boolean;
+};
+/**
+ * What a task is given, as plain data (`TaskState.data`): each task says its own shape (`defineTask<Data>`)
+ *
+ * @beta
+ */
+export type TaskData = Record<string, unknown>;
+/**
+ * What a task remembers of its own, as plain data (`TaskState.memory`): each task says its own shape
+ * (`defineTask<Data, Memory>`)
+ *
+ * @beta
+ */
+export type TaskMemory = Record<string, unknown>;
+/**
+ * What a squad is doing, as plain data kept in the brain's memory: the kind of task, what it was given, where it is in
+ * it (`phase`: `going`, `regrouping`, `fighting`, `gathering`, `holding`, the task's own words), since when, the last
+ * order it sent, and how it ended
+ *
+ * @beta
+ */
+export interface TaskState<D extends object = TaskData, M extends object = TaskMemory> {
+    /** The kind of task: the kit's (`attack`) or a game's (`defineTask`) */
+    kind: string;
+    /** What it was given: a point (`at`), a target, a radius, what to do next (`then`). Plain data, of the task's shape */
+    data: D & TaskCommon;
+    /** The tick it began at */
+    since: number;
+    /** Where it is in it, in a word */
+    phase: string;
+    /** The tick its phase began at */
+    phaseSince: number;
+    /** The tick it last sent an order */
+    sent?: number;
+    /** How it ended: none while it goes on */
+    done?: TaskDone;
+    /** The tick it ended at */
+    doneAt?: number;
+    /** What the task remembers of its own, plain data of the task's shape: the point of a scout's round it is at */
+    memory: M;
+}
+/**
+ * A kind of task (`defineTask`): what it sends as it begins (`start`), what it looks at each think (`think`), and the
+ * place it is about (`where`, for the squads module's regroup and reinforcements and for the report). The squads
+ * module runs it with its own regroup, reinforce and retreat around it, but for what it `handles` itself
+ *
+ * @beta
+ */
+export interface TaskDef<D extends object = TaskData, M extends object = TaskMemory> {
+    /** Unique among the brain's tasks: what a save names it by. The kit's are words (`attack`); a game's prefixed (`ctf.capture`) */
+    id: string;
+    /**
+     * Sends what puts the squad on its way: called as the task is given, and again as the squad goes on after a regroup.
+     * Sets `state.phase`
+     */
+    start(ai: Brain, squad: Squad, state: TaskState<D, M>): void;
+    /** Each think, after the squads module looked at the squad: watches how it goes, sends what was lost, `squad.finish(done)` when it is over */
+    think(ai: Brain, squad: Squad, state: TaskState<D, M>): void;
+    /** Whether it is over, asked each think before `think`: how it ended, or nothing while it goes on */
+    done?(ai: Brain, squad: Squad, state: TaskState<D, M>): TaskDone | undefined | false;
+    /** The place it is about: where reinforcements are sent, what the report shows. None for a task about no place */
+    where?(ai: Brain, squad: Squad, state: TaskState<D, M>): Vec2 | undefined;
+    /** What the squads module leaves to it: a task that regroups in its own way, or retreats never */
+    handles?: readonly ('retreat' | 'regroup' | 'reinforce')[];
+    /**
+     * Whether it is a standing duty, going on as long as its squad has it (a hero walking a lane with its waves): never
+     * stuck, whatever its phase, for the `ends` invariant (`checkBrain`). No when left out
+     */
+    standing?: boolean;
+    /**
+     * Whether a squad on it is in a fight it means to win, which the micro fights for (`ai.area(Micro)`): yes when left
+     * out. No for a task that goes somewhere, looks, stands, gathers or falls back (the kit's `move`, `scout`, `hold`,
+     * `gather`, `retreat`, and the micro's own `flee`)
+     */
+    fighting?: boolean;
+}
+/**
+ * Defines a task: a kind of thing a squad can be told to do (`squad.task(def, data)`, its data typed by the task), the
+ * kit's and a game's own. List a game's in the brain's `settings.squads.tasks`, so that a squad on it goes on after a
+ * load
+ *
+ * @beta
+ */
+export declare function defineTask<D extends object = TaskData, M extends object = TaskMemory>(id: string, def: Omit<TaskDef<D, M>, 'id'>): TaskDef<D, M>;

package/dist/ai/tasks/attack.d.ts

@@ -0,0 +1,7 @@
+import { type FightData, type FightMemory } from './shared';
+/**
+ * Attacks a place or a target, by a way round where told: done `cleared` with nothing left to fight there, `lost` with its target gone
+ *
+ * @beta
+ */
+export declare const ATTACK: import("..").TaskDef<FightData, FightMemory>;

package/dist/ai/tasks/capture.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The kit's `capture` task (design review B10): takes a capture point of the game (`withCapture`): done `captured`, or `lost` where it is gone
+ */
+import { type Vec2 } from '#engine/math';
+import { type TaskMemory } from '../task';
+/**
+ * What the `capture` task is given
+ *
+ * @beta
+ */
+export type CaptureData = {
+    /** The capture point, by id (`withCapture`) */
+    point: string;
+    at?: Vec2;
+};
+/**
+ * Takes a capture point of the game (`withCapture`): done `captured`, or `lost` where it is gone
+ *
+ * @beta
+ */
+export declare const CAPTURE: import("..").TaskDef<CaptureData, TaskMemory>;

package/dist/ai/tasks/creep.d.ts

@@ -0,0 +1,16 @@
+import type { Vec2 } from '#engine/math';
+import { type FightMemory } from './shared';
+/**
+ * What the `creep` task is given: the camp
+ *
+ * @beta
+ */
+export type CreepData = {
+    at: Vec2;
+};
+/**
+ * Takes a camp of creeps: done `cleared` once the map says the camp is
+ *
+ * @beta
+ */
+export declare const CREEP: import("..").TaskDef<CreepData, FightMemory>;

package/dist/ai/tasks/defend.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The kit's `defend` task (design review B10): holds a place against what comes within its radius, one foe at a time
+ */
+import { type Vec2 } from '#engine/math';
+/**
+ * What the `defend` task is given
+ *
+ * @beta
+ */
+export type DefendData = {
+    at: Vec2;
+    /** How far round the place it fights: 16 when left out */
+    radius?: number;
+};
+/**
+ * What the `defend` task remembers
+ *
+ * @beta
+ */
+export type DefendMemory = {
+    /** The foe the whole squad is on */
+    foe?: number;
+};
+/**
+ * Holds a place against what comes within its radius, one foe at a time
+ *
+ * @beta
+ */
+export declare const DEFEND_TASK: import("..").TaskDef<DefendData, DefendMemory>;

package/dist/ai/tasks/drop.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The kit's `drop` task: a squad carried by transports to a place it cannot walk to (an island, across a river, behind
+ * the enemy's walls), let out on the land nearest it: done `landed`, its `then` after (an attack where it landed)
+ */
+import { type Vec2 } from '#engine/math';
+/**
+ * What the `drop` task is given: where it lands, and the transports that carry it (the brain's units, not of the
+ * squad: they are let go of once they have let it out)
+ *
+ * @beta
+ */
+export type DropData = {
+    at: Vec2;
+    transports: number[];
+};
+/**
+ * What the `drop` task remembers: since when it waits for its units to get in
+ *
+ * @beta
+ */
+export type DropMemory = {
+    /** When it began to wait for its units to get in, in seconds of the game */
+    waiting?: number;
+    /** When the transports were sent off, in seconds of the game */
+    sailed?: number;
+};
+/**
+ * Carries the squad to a place by its transports: each unit told to get into one (shared out as they have room), the
+ * transports sent off once all are in (or after `BOARDING_WAIT` seconds, with those that are), and told to let them out
+ * on the land nearest the place. Done `landed` once they are all out; `lost` with no transport left to carry them
+ *
+ * @beta
+ */
+export declare const DROP: import("..").TaskDef<DropData, DropMemory>;

package/dist/ai/tasks/escort.d.ts

@@ -0,0 +1,16 @@
+import { type TaskMemory } from '../task';
+/**
+ * What the `escort` task is given
+ *
+ * @beta
+ */
+export type EscortData = {
+    /** Whom it follows */
+    target: number;
+};
+/**
+ * Follows a unit and fights what comes near it: done `lost` with it gone
+ *
+ * @beta
+ */
+export declare const ESCORT: import("..").TaskDef<EscortData, TaskMemory>;

package/dist/ai/tasks/gather.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The kit's `gather` task (design review B10): gathers at a rally: done `arrived` once enough are there, or the time is up
+ */
+import { type Vec2 } from '#engine/math';
+import { type TaskMemory } from '../task';
+/**
+ * What the `gather` task is given
+ *
+ * @beta
+ */
+export type GatherData = {
+    at: Vec2;
+    /** The share of the squad there that is enough: all when left out */
+    minForces?: number;
+    /** Seconds it waits at most */
+    seconds?: number;
+};
+/**
+ * Gathers at a rally: done `arrived` once enough are there, or the time is up
+ *
+ * @beta
+ */
+export declare const GATHER: import("..").TaskDef<GatherData, TaskMemory>;

package/dist/ai/tasks/harass.d.ts

@@ -0,0 +1,7 @@
+import { type FightData, type FightMemory } from './shared';
+/**
+ * Goes for the workers at a place, one at a time, round their army where told
+ *
+ * @beta
+ */
+export declare const HARASS: import("..").TaskDef<FightData, FightMemory>;

package/dist/ai/tasks/hold.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The kit's `hold` task (design review B10): stands its ground (defensive where the game has stances), where it is or at a place
+ */
+import { type Vec2 } from '#engine/math';
+import { type TaskMemory } from '../task';
+/**
+ * What the `hold` task is given
+ *
+ * @beta
+ */
+export type HoldData = {
+    /** Where it holds: where it stands when left out */
+    at?: Vec2;
+};
+/**
+ * Stands its ground (defensive where the game has stances), where it is or at a place
+ *
+ * @beta
+ */
+export declare const HOLD: import("..").TaskDef<HoldData, TaskMemory>;

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

@@ -0,0 +1,32 @@
+/**
+ * The kit's tasks (design review B10), one file each, listed for every brain's squads (`Squads`)
+ */
+import type { TaskDef } from '../task';
+/** The kit's tasks, by their word */
+export declare const TASKS: readonly TaskDef[];
+export { ATTACK } from './attack';
+export { HARASS } from './harass';
+export { CREEP } from './creep';
+export { DEFEND_TASK } from './defend';
+export { HOLD } from './hold';
+export { MOVE } from './move';
+export { CAPTURE } from './capture';
+export { RETREAT } from './retreat';
+export { ESCORT } from './escort';
+export { SCOUT_TASK } from './scout';
+export { PATROL } from './patrol';
+export { GATHER } from './gather';
+export { DROP } from './drop';
+export type { DropData, DropMemory } from './drop';
+export { type FightData, type FightMemory } from './shared';
+export type { DefendData } from './defend';
+export type { DefendMemory } from './defend';
+export type { HoldData } from './hold';
+export type { MoveData } from './move';
+export type { CaptureData } from './capture';
+export type { EscortData } from './escort';
+export type { RoundData } from './scout';
+export type { RoundMemory } from './scout';
+export type { GatherData } from './gather';
+export type { CreepData } from './creep';
+export type { RetreatData } from './retreat';

package/dist/ai/tasks/move.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The kit's `move` task (design review B10): walks to a place: done `arrived`
+ */
+import { type Vec2 } from '#engine/math';
+import { type TaskMemory } from '../task';
+/**
+ * What the `move` task is given
+ *
+ * @beta
+ */
+export type MoveData = {
+    at: Vec2;
+};
+/**
+ * Walks to a place: done `arrived`
+ *
+ * @beta
+ */
+export declare const MOVE: import("..").TaskDef<MoveData, TaskMemory>;

package/dist/ai/tasks/patrol.d.ts

@@ -0,0 +1,8 @@
+import type { RoundData } from './scout';
+import type { RoundMemory } from './scout';
+/**
+ * Walks a round of places for ever, fighting what it meets
+ *
+ * @beta
+ */
+export declare const PATROL: import("..").TaskDef<RoundData, RoundMemory>;

package/dist/ai/tasks/retreat.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The kit's `retreat` task (design review B10): falls back to a place: done `retreated`
+ */
+import type { Vec2 } from '#engine/math';
+import { type TaskMemory } from '../task';
+/**
+ * What the `retreat` task is given: where to (home when left out), and why, for the report
+ *
+ * @beta
+ */
+export type RetreatData = {
+    at?: Vec2;
+    why?: string;
+};
+/**
+ * Falls back to a place: done `retreated`
+ *
+ * @beta
+ */
+export declare const RETREAT: import("..").TaskDef<RetreatData, TaskMemory>;

package/dist/ai/tasks/scout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The kit's `scout` task (design review B10): looks at places in turn: done `arrived` after the last
+ */
+import { type Vec2 } from '#engine/math';
+/**
+ * What the `scout` task is given
+ *
+ * @beta
+ */
+export type RoundData = {
+    points: Vec2[];
+};
+/**
+ * What the `scout` task remembers
+ *
+ * @beta
+ */
+export type RoundMemory = {
+    /** The place of the round it is on */
+    next?: number;
+    /** Times it was sent again to a place it stopped short of */
+    tries?: number;
+};
+/**
+ * Looks at places in turn: done `arrived` after the last
+ *
+ * @beta
+ */
+export declare const SCOUT_TASK: import("..").TaskDef<RoundData, RoundMemory>;

package/dist/ai/tasks/shared.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What the kit's tasks share (design review B10): where a task's data says it goes, what is fighting near a place, how a
+ * fight is gone to and watched, a way round, a walk's end
+ */
+import { type Vec2 } from '#engine/math';
+import type { Brain } from '../brain';
+import type { Squad } from '../squads';
+import type { TaskDone, TaskState } from '../task';
+import type { UnitSet } from '../view';
+/** How near the place it was sent to a squad is there */
+export declare const ARRIVE = 8;
+/** How near a place of its round a patrol is there, and a little more for each of its units (they stand round it) */
+export declare const PATROL_ARRIVE = 4;
+/** How near the place it was sent to look at a scout that stopped short is as near as the ground lets it: further is stuck */
+export declare const SCOUT_NEAR = 16;
+/**
+ * What a task that fights somewhere is given (`attack`, `harass`, `creep`): a place, or a target (an entity, as it
+ * goes), a way round their army (`avoid: 'army'`) or by a place (`via`)
+ *
+ * @beta
+ */
+export type FightData = {
+    at?: Vec2;
+    target?: number;
+    avoid?: 'army' | false;
+    via?: Vec2;
+};
+/**
+ * What a task that fights remembers: its way round, and the worker it hunts (`harass`)
+ *
+ * @beta
+ */
+export type FightMemory = {
+    routed?: boolean;
+    waypoints?: Vec2[];
+    prey?: number;
+};
+/** Where a task's data says it goes: its target where it is in sight, else its place */
+export declare function placeOf(ai: Brain, state: TaskState<FightData, FightMemory>): Vec2 | undefined;
+/** Whether a place is on the map */
+export declare function onMap(ai: Brain, at: Vec2): boolean;
+/** What is hostile and alive near a place: what a squad there fights */
+export declare function foesNear(ai: Brain, at: Vec2, radius?: number): UnitSet;
+/**
+ * Sets a task on its way to fight at its place: by the waypoints of a way round (`avoid`) where there are any, walking
+ * them, then attack-moving there; else attack-moving, or attacking its target
+ */
+export declare function goFight(ai: Brain, squad: Squad, state: TaskState<FightData, FightMemory>): void;
+/**
+ * Watches a squad on its way to fight or fighting: done once there with nothing left to fight, or once its target is
+ * gone; the units that stand idle short of it sent again
+ */
+export declare function watchFight(ai: Brain, squad: Squad, state: TaskState<FightData, FightMemory>): void;
+/**
+ * A task's target where it is in sight, to attack it by name: a building remembered out of sight (`visible: false`)
+ * cannot be told to be attacked, and is attack-moved to instead
+ */
+export declare function inSight(ai: Brain, state: TaskState<FightData, FightMemory>): number | undefined;
+/** Works out the way round for a task that avoids, as it begins: kept in its memory, said in the decision log */
+export declare function planRoute(ai: Brain, squad: Squad, state: TaskState<FightData, FightMemory>): void;
+/** The capture points of the game (`withCapture`), as the report tells the brain: none for a game without them */
+export declare function capturePointsOf(ai: Brain): {
+    id: string;
+    owner: number | null;
+    x: number;
+    z: number;
+}[];
+/**
+ * A walk's think: done (as `done` says) once its middle is near the place, or once all of it stands idle as near as the
+ * ground let it go; what stands idle short of it, while others walk on, is sent again
+ */
+export declare function arrive(done: TaskDone): (ai: Brain, squad: Squad, state: TaskState<{
+    at?: Vec2;
+}>) => void;

package/dist/ai/team.d.ts

@@ -0,0 +1,155 @@
+import type { PlayerId } from '#engine/entity';
+import { type Vec2 } from '#engine/math';
+import { type AiModuleDef } from './module';
+/**
+ * Something one computer of a team asks of the others, on the team's board: help at a place
+ *
+ * @beta
+ */
+export interface TeamRequest {
+    /** Its number on the board */
+    id: number;
+    kind: 'help' | 'attack' | 'defend' | 'rally';
+    /** Who asks: a computer of the team, or a person whose ping or plight it is */
+    from: PlayerId;
+    at: Vec2;
+    /** The enemy strength seen there as it was asked (0 for none seen: a ping on a place) */
+    strength: number;
+    /** The tick it is asked until */
+    until: number;
+    /** What it came of: a raid on a computer, a person's ping, damage seen done to an ally, a word of the game's */
+    by: 'raid' | 'ping' | 'damage' | 'word';
+    /** The computers that answered it */
+    answered: PlayerId[];
+}
+/**
+ * An attack the computers of a team agree on (`together`): where, when, who proposed it, who joined and who did not
+ *
+ * @beta
+ */
+export interface AttackPlan {
+    target: Vec2;
+    /** The tick the waves go at */
+    at: number;
+    by: PlayerId;
+    joined: PlayerId[];
+    declined: PlayerId[];
+    /** The tick it was proposed at */
+    since: number;
+}
+/**
+ * A team's board as the world keeps it (`core.ai.teams`, by team): plain data, kept in a save, never replicated
+ *
+ * @beta
+ */
+export interface TeamBoard {
+    v: 1;
+    requests: TeamRequest[];
+    plan?: AttackPlan;
+    /** What each computer of the team remembers of the enemy's bases, and when it last thought */
+    known: Record<string, {
+        tick: number;
+        bases: {
+            owner: PlayerId;
+            at: Vec2;
+            last: number;
+        }[];
+    }>;
+    /** The next request's number */
+    next: number;
+}
+/**
+ * How a brain plays with its team (`BrainDef.team`, the seat's `AiOptions.team` over it, the `team()` module's own
+ * under both). Data
+ *
+ * @beta
+ */
+export interface TeamOptions {
+    /** Whether it helps its allies, people and computers, where asked (the classic Defend Users): yes when left out */
+    defendUsers?: boolean;
+    /**
+     * Whether it does what an ally's ping asks besides help (`GameRules.talk.pings.meanings`): a squad sent to fight at
+     * an `attack` (a push), one to hold a place at a `defend` (a hold), its squads out brought home at a `rally` (a
+     * retreat). Yes when left out
+     */
+    answerPings?: boolean;
+    /** The odds of the fight (`Strength.odds`) what it sends to help is to have: one in two when left out */
+    helpOdds?: number;
+    /** Whether it asks its team for help with a raid more than it can meet: yes when left out */
+    askForHelp?: boolean;
+    /** Whether its waves wait for the team's plan and go together: no when left out */
+    together?: boolean;
+    /** Seconds ahead of the proposal the waves of a plan go: 20 when left out */
+    gatherFor?: number;
+    /** Seconds a request stands: 30 when left out */
+    requestFor?: number;
+    /** Whether it says a line to its side as it sends a wave, comes to help, falls back: no when left out */
+    say?: boolean;
+    /** Its lines, the game's words: `{ attacking, helping, retreating }`. Nothing is said for a line not given */
+    lines?: Partial<Record<'attacking' | 'helping' | 'retreating', string>>;
+}
+/**
+ * What a brain remembers of its team play between thinks (`BrainMemory.team`): up to when it heard, when it last said
+ * each line
+ *
+ * @beta
+ */
+export interface TeamPlayMemory {
+    v: 1;
+    heard: number;
+    said: Record<string, number>;
+}
+/**
+ * Team play as the report shows it (`AiReport.team`): the team, its computers, the requests on its board, the plan of
+ * an attack together, how many enemy bases the team knows
+ *
+ * @beta
+ */
+export interface TeamReport {
+    team: number;
+    computers: PlayerId[];
+    requests: {
+        id: number;
+        kind: TeamRequest['kind'];
+        from: PlayerId;
+        at: [number, number];
+        strength: number;
+        by: TeamRequest['by'];
+        answered: PlayerId[];
+        left: number;
+    }[];
+    plan?: {
+        target: [number, number];
+        in: number;
+        by: PlayerId;
+        joined: PlayerId[];
+        declined: PlayerId[];
+    };
+    enemyBases: number;
+}
+/**
+ * The id of the help goal
+ *
+ * @beta
+ */
+export declare const HELP = "help";
+/**
+ * The id of the goal that does what an ally's ping asks (`push`, `hold`): `pinged`
+ *
+ * @beta
+ */
+export declare const PINGED = "pinged";
+/**
+ * The team module: the team's board brought up to date each think (`ai.team.think`: itself and what it knows written,
+ * pings and an ally's damage heard as calls for help, its own raids asked help for, the plan of an attack together
+ * answered), and the `help` goal on the picker. With how it plays where the brain's definition and the seat's options
+ * say nothing (`TeamOptions`)
+ *
+ * @beta
+ */
+export declare const team: (options?: TeamOptions) => AiModuleDef;
+declare module './area' {
+    interface AreaMemories {
+        team?: TeamPlayMemory;
+    }
+}