@v12-engine/engine 0.1.0 → 0.4.0

package/dist/ai/report.js

@@ -0,0 +1,87 @@
+//#region src/ai/report.ts
+/**
+* How many decisions the log keeps
+*
+* @internal
+*/
+var DECISIONS_KEPT = 50;
+/**
+* The last fifty things a computer player decided (`Brain.decisions`, written by `ai.decide`), oldest first: kept in a
+* save, plain data
+*
+* @beta
+*/
+var Decisions = class {
+	limit;
+	lines = [];
+	constructor(limit = 50) {
+		this.limit = limit;
+	}
+	/** Writes one down: the oldest goes once there are more than the log keeps */
+	add(decision) {
+		this.lines.push(decision);
+		if (this.lines.length > this.limit) this.lines.splice(0, this.lines.length - this.limit);
+	}
+	/** What it decided, oldest first */
+	list() {
+		return this.lines;
+	}
+	/** The last decision about a goal, or of a kind */
+	last(about) {
+		for (let i = this.lines.length - 1; i >= 0; i--) {
+			const line = this.lines[i];
+			if ((about.goal === void 0 || line.goal === about.goal) && (about.kind === void 0 || line.kind === about.kind)) return line;
+		}
+	}
+	/** For a save: a copy */
+	save() {
+		return this.lines.map((line) => ({ ...line }));
+	}
+	/** Takes back what `save` gave: what is not a decision is passed over */
+	restore(lines) {
+		this.lines = Array.isArray(lines) ? lines.filter((line) => !!line && typeof line.line === "string" && typeof line.tick === "number").slice(-this.limit) : [];
+	}
+};
+/** A number as the report writes it: two places */
+var fixed = (x) => x.toFixed(2);
+/** 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 */
+function considerationsLine(goal) {
+	return goal.considerations.filter((each) => each.asked !== false).map((each) => `${each.name} ${fixed(each.curved)}`).join(" · ");
+}
+/**
+* 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
+*/
+function weakest(goal) {
+	let least;
+	for (const each of goal.considerations) if (each.asked !== false && (!least || each.curved < least.curved)) least = each;
+	return least;
+}
+/** A raw value as a sentence writes it: a whole number as it is, the rest to two places */
+var raw = (x) => Number.isInteger(x) ? String(x) : fixed(x);
+/**
+* A goal's row of the report as a sentence (`Brain.explain`): its score, what each question answered and how much that
+* mattered, whether it runs and with what, or why not. `seconds` turns a tick into seconds of the game
+*
+* @internal
+*/
+function explainGoal(goal, seconds, now) {
+	const asked = goal.considerations.filter((each) => each.asked !== false);
+	const unasked = goal.considerations.length - asked.length;
+	const questions = asked.length ? `: ${asked.map((each) => `${each.name} is ${raw(each.value)} (${fixed(each.curved)})`).join(", ")}${unasked ? `; ${unasked} more not asked, the goal vetoed already` : ""}` : "";
+	const score = `${goal.id} scores ${fixed(goal.score)}${questions}.`;
+	if (goal.picked && goal.held) {
+		const left = Math.max(0, Math.round(seconds(goal.held.until) - now));
+		const since = Math.max(0, Math.round(now - seconds(goal.held.since)));
+		return `${score} It runs with ${goal.held.units === 1 ? "1 unit" : `${goal.held.units} units`} (strength ${Math.round(goal.held.strength)}), for ${since} s now${left ? `, committed for ${left} s more` : ""}${goal.urgent ? ", urgent" : ""}.`;
+	}
+	if (goal.picked) return `${score} It runs.`;
+	if (goal.why) return `${score} It does not run: ${goal.why}.`;
+	const limit = weakest(goal);
+	if (goal.score <= 0 && limit) return `${score} It does not run: ${limit.name} vetoes it.`;
+	return `${score} It does not run: it scores too little${limit ? `, held back most by ${limit.name}` : ""}.`;
+}
+//#endregion
+export { DECISIONS_KEPT, Decisions, considerationsLine, explainGoal, weakest };
+
+//# sourceMappingURL=report.js.map

package/dist/ai/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","names":[],"sources":["../../src/ai/report.ts"],"sourcesContent":["import type { PlayerId } from '#engine/entity'\nimport type { ComputerTiming } from './computer'\nimport type { ThinkBudgetOptions } from './budget'\nimport type { GoalReport } from './goals'\nimport type { PlansReport } from './plans/plans'\nimport type { SquadReport } from './squads'\nimport type { MicroReport } from './micro'\nimport type { DefenceReport } from './defence'\nimport type { EconomyReport } from './economy'\nimport type { ScoutingReport } from './scouting'\nimport type { TeamReport } from './team'\nimport type { AiProfile } from './profiles'\nimport type { WavesReport } from './waves'\n\n/*\n * What a computer player is thinking, written down (AI plan, E1): the answer to \"why did it do that\", read rather than\n * guessed. Two things live here:\n *\n * - **The report** (`AiReport`): plain data, put together from the brain when someone looks (`Brain.report`, what\n *   `Brain.inspect` gives, and what the debug panel's AI tab draws). The brain writes its own parts (its goals with\n *   every consideration's raw and curved value, what it knows, its roles, what it was told), and each module writes\n *   its section: a module's `report` hook fills a part of the report the kit names (squads, plans, as those items\n *   come), its `inspect` goes under its id in `sections`. Plain data, so it crosses a worker and could cross a wire:\n *   the panel draws data, it never reaches a brain.\n * - **The decision log** (`Decisions`): the last fifty things it decided, as a line of text each, with the tick: \"attack\n *   picked at 0.80: its time has come 1.00 · the wave is ready 1.00\". The goals' picker writes a line when a goal\n *   starts or stops, and a module writes its own (`ai.decide`): a wave sent, a building put up. Each line goes to the\n *   world's log too (`debug`, category `ai`) where the logger's level lets it through. The log is kept in a save, so\n *   that a save sent with a bug report says what the computer had in mind.\n *\n * Nothing in here decides anything: the report is made only when asked, and the milliseconds in it are for reading.\n */\n\n/**\n * One thing a computer player decided, as a line of text: what it did and the reason that weighed most\n *\n * @beta\n */\nexport interface AiDecision {\n\t/** The tick of the think it was decided at */\n\ttick: number\n\t/** What it is about: `goal` for the goals' picker, or the module's word (`army`, `build`, `research`, `hero`) */\n\tkind: string\n\t/** What was decided, in words: \"attack picked at 0.80 (8 units): its time has come 1.00 · the wave is ready 1.00\" */\n\tline: string\n\t/** The goal it is about, where it is about one */\n\tgoal?: string\n}\n\n/**\n * What a computer player remembers of what it saw, in short, for the report: its rivals' bases and their army as last\n * seen, with how many seconds ago, and the tech seen\n *\n * @beta\n */\nexport interface KnowledgeReport {\n\t/** The enemy bases known, each with its owner, where, how many structures, how many seconds ago it was seen and whether it is gone */\n\tbases: { owner: PlayerId; at: [number, number]; structures: number; seen: number; gone?: true }[]\n\t/** The enemy armies as last seen, each with where, how many fighters and how many seconds ago */\n\tarmy: { at: [number, number]; count: number; seen: number }[]\n\t/** The enemy tech seen: the types of their finished buildings */\n\ttech: string[]\n\t/** How many of its own things were lost */\n\tlost: number\n}\n\n/**\n * What a computer player's play adds up to since it was seated (`Brain.stats`, `AiReport.stats`): the numbers\n * `simulate` reports beside who won, and a test reads to see that the squads send an order once and watch it. Counted,\n * never decided on\n *\n * @beta\n */\nexport interface AiStats {\n\t/** Commands sent */\n\tcommands: number\n\t/** Commands held back past what a think may send (`AiProfile.commandsPerThink`) */\n\theld: number\n\t/** Commands the game refused (a unit that could not do it, a place it could not build at) */\n\trefused: number\n\t/** Seconds its fighters stood idle, summed over the fighters: ten footmen idle for a minute are six hundred */\n\tidleArmySeconds: number\n\t/** Orders sent to a unit again for the same thing within a few seconds: a unit told the same every think stops and starts */\n\tchurn: number\n\t/** Seconds its building waited on money: a want saving up */\n\tblockedOnMoney: number\n\t/** Thinks counted */\n\tthinks: number\n}\n\n/**\n * The threat map as a computer player read it last think (`ThreatMap.cells`, on the ground, the enemy structures it\n * remembers counted): what the game view's AI overlay draws as heat over the ground. The size of a cell, the grid's\n * cells across and down, and each cell with something in it as `[col, row, friendly, enemy]`\n *\n * @beta\n */\nexport interface ThreatReport {\n\t/** The side of a grid cell, in cells of the map */\n\tcell: number\n\t/** How many grid cells across */\n\tcols: number\n\t/** How many grid cells down */\n\trows: number\n\t/** Each grid cell with something in it as `[col, row, friendly, enemy]`, the strength of each side */\n\tcells: [col: number, row: number, friendly: number, enemy: number][]\n}\n\n/**\n * What a computer player is thinking, as plain data (`Brain.report`, `Brain.inspect`): what the debug panel's AI tab\n * draws, and what a test reads. Each module adds its section (`AiModule.report`, `AiModule.inspect`)\n *\n * @beta\n */\nexport interface AiReport {\n\t/** The version of this shape */\n\tv: 1\n\t/** The brain's id (`core.melee`) */\n\tbrain: string\n\t/** The player it plays */\n\tplayer: PlayerId\n\t/** The tick of its last picture of the game */\n\ttick: number\n\t/** Seconds into the game, as of its last picture */\n\ttime: number\n\t/** Ticks a second: what turns a decision's tick into the game's time */\n\ttickRate: number\n\t/** How many times it has thought */\n\tthinks: number\n\t/** Whether it sits still (`world.computers.pause`) */\n\tpaused?: true\n\t/** What it was seated with: the data of its options (`AiOptions`: the difficulty, the numbers); code left out */\n\tprofile: Record<string, unknown>\n\t/** What it plays by (`Brain.profile`): the profile resolved, layer over layer; code (a flag's function) left out */\n\tplaying?: AiProfile\n\t/** The goal that scored highest above the minimum this think: what the army is on. None when nothing is worth doing */\n\tgoal?: string\n\t/** Every goal as the picker last saw it: its score, each consideration's raw and curved value, what it holds, why not */\n\tgoals: GoalReport[]\n\t/** What it remembers of the enemy: left out by a brain that keeps no knowledge */\n\tknowledge?: KnowledgeReport\n\t/** The roles it found among the types it can make: `{ worker: ['peasant'] }` */\n\troles: Record<string, string[]>\n\t/**\n\t * What it has to spend and how it comes in: its resources, its income a minute, its supply; and its economy's say\n\t * (`EconomyReport`): each base with its workers on each resource against what it wants and what is served, the\n\t * workers that fled a raid, the workers had against wanted, where the next hall stands\n\t */\n\teconomy: { resources: Record<string, number>; income: Record<string, number>; supply: [used: number, cap: number] } & Partial<EconomyReport>\n\t/** The raids on its bases with what answers each, every base's raids so far, the towers it wants (`DefenceReport`) */\n\tdefence?: DefenceReport\n\t/** Its plan of looks with how long since each was in sight and whether it is due, its scout and where it goes (`ScoutingReport`) */\n\tscouting?: ScoutingReport\n\t/** Its team: the computers of it, the requests on its board, the plan of an attack together (`TeamReport`) */\n\tteam?: TeamReport\n\t/** Its waves: the one whose turn it is, its group as it stands and when it may go, the waves sent (`WavesReport`) */\n\twaves?: WavesReport\n\t/** Its plans: the purse (what is free, promised, held), and every want of the build plan with what it waits for */\n\tplans: PlansReport\n\t/** Its squads: whose each is, its units and their strength, where it is, its task and how it goes, its last change */\n\tsquads: SquadReport[]\n\t/** Where the strength is, as its threat map read it last think (`ThreatReport`): what the AI overlay draws as heat */\n\tthreat?: ThreatReport\n\t/** 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 */\n\tmicro?: MicroReport\n\t/** The words the game told it that no module has taken yet */\n\ttold: { word: string; tick: number }[]\n\t/** Commands it sent its last think */\n\tsent: number\n\t/** Commands it would have sent its last think past what its profile lets a think send (`commandsPerThink`) */\n\theld?: number\n\t/** 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 */\n\tbudget?: ThinkBudgetOptions & { ticks: number }\n\t/** What its play adds up to since it was seated (`AiStats`): commands, idle army seconds, churn, seconds blocked on money */\n\tstats: AiStats\n\t/**\n\t * Milliseconds its thinks take, for reading only: the last, an average, the longest, and by module while the world\n\t * profiles. Given by the seat (`inspect` of the player), which times the thinks\n\t */\n\ttiming?: ComputerTiming\n\t/** What it decided, the last fifty, oldest first */\n\tdecisions: AiDecision[]\n\t/** What each module says of itself that the report has no part for (`AiModule.inspect`), under the module's id */\n\tsections: Record<string, unknown>\n}\n\n/**\n * How many decisions the log keeps\n *\n * @internal\n */\nexport const DECISIONS_KEPT = 50\n\n/**\n * The last fifty things a computer player decided (`Brain.decisions`, written by `ai.decide`), oldest first: kept in a\n * save, plain data\n *\n * @beta\n */\nexport class Decisions {\n\tprivate lines: AiDecision[] = []\n\n\tconstructor(private readonly limit = DECISIONS_KEPT) {}\n\n\t/** Writes one down: the oldest goes once there are more than the log keeps */\n\tadd(decision: AiDecision): void {\n\t\tthis.lines.push(decision)\n\t\tif (this.lines.length > this.limit) this.lines.splice(0, this.lines.length - this.limit)\n\t}\n\n\t/** What it decided, oldest first */\n\tlist(): readonly AiDecision[] {\n\t\treturn this.lines\n\t}\n\n\t/** The last decision about a goal, or of a kind */\n\tlast(about: { goal?: string; kind?: string }): AiDecision | undefined {\n\t\tfor (let i = this.lines.length - 1; i >= 0; i--) {\n\t\t\tconst line = this.lines[i]\n\t\t\tif ((about.goal === undefined || line.goal === about.goal) && (about.kind === undefined || line.kind === about.kind)) return line\n\t\t}\n\t\treturn undefined\n\t}\n\n\t/** For a save: a copy */\n\tsave(): AiDecision[] {\n\t\treturn this.lines.map((line) => ({ ...line }))\n\t}\n\n\t/** Takes back what `save` gave: what is not a decision is passed over */\n\trestore(lines: unknown): void {\n\t\tthis.lines = Array.isArray(lines)\n\t\t\t? lines.filter((line): line is AiDecision => !!line && typeof line.line === 'string' && typeof line.tick === 'number').slice(-this.limit)\n\t\t\t: []\n\t}\n}\n\n/** A number as the report writes it: two places */\nconst fixed = (x: number) => x.toFixed(2)\n\n/** 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 */\nexport function considerationsLine(goal: Pick<GoalReport, 'considerations'>): string {\n\treturn goal.considerations\n\t\t.filter((each) => each.asked !== false)\n\t\t.map((each) => `${each.name} ${fixed(each.curved)}`)\n\t\t.join(' · ')\n}\n\n/**\n * The consideration that held a goal back most: the one with the least curved value of those asked (a score is their\n * product, so the least is what kept it low), and none for a goal with no considerations\n */\nexport function weakest(goal: GoalReport): GoalReport['considerations'][number] | undefined {\n\tlet least: GoalReport['considerations'][number] | undefined\n\tfor (const each of goal.considerations) if (each.asked !== false && (!least || each.curved < least.curved)) least = each\n\treturn least\n}\n\n/** A raw value as a sentence writes it: a whole number as it is, the rest to two places */\nconst raw = (x: number) => (Number.isInteger(x) ? String(x) : fixed(x))\n\n/**\n * A goal's row of the report as a sentence (`Brain.explain`): its score, what each question answered and how much that\n * mattered, whether it runs and with what, or why not. `seconds` turns a tick into seconds of the game\n *\n * @internal\n */\nexport function explainGoal(goal: GoalReport, seconds: (tick: number) => number, now: number): string {\n\tconst asked = goal.considerations.filter((each) => each.asked !== false)\n\tconst unasked = goal.considerations.length - asked.length\n\tconst questions = asked.length\n\t\t? `: ${asked.map((each) => `${each.name} is ${raw(each.value)} (${fixed(each.curved)})`).join(', ')}${unasked ? `; ${unasked} more not asked, the goal vetoed already` : ''}`\n\t\t: ''\n\tconst score = `${goal.id} scores ${fixed(goal.score)}${questions}.`\n\tif (goal.picked && goal.held) {\n\t\tconst left = Math.max(0, Math.round(seconds(goal.held.until) - now))\n\t\tconst since = Math.max(0, Math.round(now - seconds(goal.held.since)))\n\t\tconst units = goal.held.units === 1 ? '1 unit' : `${goal.held.units} units`\n\t\treturn `${score} It runs with ${units} (strength ${Math.round(goal.held.strength)}), for ${since} s now${left ? `, committed for ${left} s more` : ''}${goal.urgent ? ', urgent' : ''}.`\n\t}\n\tif (goal.picked) return `${score} It runs.`\n\tif (goal.why) return `${score} It does not run: ${goal.why}.`\n\tconst limit = weakest(goal)\n\tif (goal.score <= 0 && limit) return `${score} It does not run: ${limit.name} vetoes it.`\n\treturn `${score} It does not run: it scores too little${limit ? `, held back most by ${limit.name}` : ''}.`\n}\n"],"mappings":"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"}

package/dist/ai/roles.d.ts

@@ -56,8 +56,11 @@ export interface AiHints {
  * @beta
  */
 export interface RoleEntry {
+    /** The unit type's roles, such as fighter or worker */
     roles: AiRole[];
+    /** The unit type's tags, the game's own names for what it is */
     tags: string[];
+    /** A line for each role that was inferred, saying why; none for declared ones */
     why?: string[];
 }
 /**
@@ -73,6 +76,7 @@ export type RoleTable = Record<string, RoleEntry>;
  * @beta
  */
 export interface RolesPlayer {
+    /** The player's id */
     id: PlayerId;
     /** The race it plays, where the game has races */
     race?: string;

package/dist/ai/roles.js

@@ -0,0 +1,207 @@
+import { baseStats, supplyGivenOf, upgradesOf } from "../defs.js";
+import { availableToPlayer } from "../shared.js";
+//#region src/ai/roles.ts
+/** The tags the kit infers from an attack: for a brain that asks for the ranged or for what hits the air */
+var RANGED = "ranged";
+var MELEE = "melee";
+var HITS_AIR = "hitsAir";
+/** What fights: a unit with an attack that is not a worker (a worker that builds does not fight; a ghoul, which only gathers, does) */
+var fights = (def) => def.kind === "unit" && !!def.attacks?.length && !(def.harvester && def.builds?.length);
+/** Whether a building takes deposits of a resource: all of them, or that one among those it lists */
+var takes = (def, kind) => kind !== void 0 && (def.dropOff === true || Array.isArray(def.dropOff) && def.dropOff.includes(kind));
+/** What a race's types are, for the rules that look across a race: those of its race, and those of none */
+var ofRace = (def, race) => def.race === void 0 || def.race === race;
+/**
+* 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
+*/
+function inferRoles(registry) {
+	const table = {};
+	const all = registry.units.all();
+	const money = registry.currency ?? registry.resources[0]?.id;
+	const heals = (def) => (def.abilities ?? []).some((id) => registry.abilities.has(id) && registry.ability(id).effects.some((effect) => effect.type === "heal"));
+	const detects = (def) => (def.abilities ?? []).some((id) => registry.abilities.has(id) && registry.ability(id).effects.some((effect) => effect.type === "detect"));
+	const workers = all.filter((def) => def.kind === "unit" && def.harvester && def.builds?.length);
+	const trainsWorker = (def) => !!def.trains?.some((id) => workers.some((worker) => worker.id === id));
+	const hallsOf = (race) => all.filter((def) => def.kind === "building" && def.dropOff && !def.builtOn && ofRace(def, race) && trainsWorker(def));
+	const soldiers = all.filter((def) => fights(def) && !def.hero);
+	const speed = (def) => baseStats(def, registry).moveSpeed;
+	const scoutOf = (race) => {
+		let best;
+		for (const def of soldiers) if (def.race === race && (!best || speed(def) > speed(best))) best = def;
+		return best;
+	};
+	for (const def of all) {
+		const roles = [];
+		const why = [];
+		const tags = [];
+		const give = (role, reason) => {
+			roles.push(role);
+			why.push(`${role}: ${reason}`);
+		};
+		if (def.kind === "unit") {
+			if (def.harvester && def.builds?.length) give("worker", "gathers and builds");
+			if (def.harvester) give("gatherer", "gathers");
+			if (def.hero) give("hero", "a hero");
+			else if (fights(def)) give("soldier", "fights and is no hero");
+			if (fights(def) && !def.hero && def.abilities?.length && baseStats(def, registry).mana > 0) give("caster", "fights with mana and abilities");
+			if (heals(def)) give("healer", "has an ability that heals");
+			if (def.attacks?.some((attack) => attack.splash || attack.fells || attack.ground)) give("siege", "its attacks splash, fell or are aimed at the ground");
+			if (def.flying) give("air", "flies");
+			if (!def.hero && fights(def) && scoutOf(def.race) === def) give("scout", "the fastest of its soldiers");
+			if (detects(def)) give("detector", "has an ability that finds the invisible");
+		} else if (def.kind === "building") {
+			if (def.builtOn !== void 0 && def.builtOn === money && takes(def, money)) give("topper", "put up on a deposit of the money, where it is gathered");
+			else if (def.dropOff && !def.builtOn) {
+				const halls = hallsOf(def.race);
+				if (trainsWorker(def)) give("hall", "takes deposits and trains workers");
+				else if (halls.length === 0) give("hall", "takes deposits, and nothing of its race takes them and trains workers");
+			}
+			if (supplyGivenOf(def) && !def.trains?.length) give("supply", "provides supply and trains nothing");
+			if (def.trains?.some((id) => registry.units.has(id) && fights(registry.unit(id)) && !registry.unit(id).hero)) give("barracks", "trains soldiers");
+			if (def.revives || def.trains?.some((id) => registry.units.has(id) && registry.unit(id).hero)) give("altar", "trains or revives heroes");
+			if (def.researches?.length) give("workshop", "researches");
+			if (def.attacks?.length && !def.transport?.armed) give("tower", "a building that attacks by itself");
+			if (def.sells?.length || def.hires?.length) give("shop", "sells or hires");
+			if (detects(def)) give("detector", "has an ability that finds the invisible");
+		}
+		const attacks = def.attacks ?? [];
+		if (attacks.some((attack) => attack.projectileSpeed)) tags.push(RANGED);
+		if (attacks.some((attack) => !attack.projectileSpeed)) tags.push(MELEE);
+		if (attacks.some((attack) => attack.targets?.includes("air"))) tags.push(HITS_AIR);
+		table[def.id] = {
+			roles,
+			tags,
+			why
+		};
+	}
+	return table;
+}
+/**
+* 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
+*/
+var Roles = class {
+	table;
+	registry;
+	byRole = /* @__PURE__ */ new Map();
+	byTag = /* @__PURE__ */ new Map();
+	constructor(table, registry) {
+		this.table = table;
+		this.registry = registry;
+	}
+	/** The roles of a unit type: none for one that has none, or is not a unit type at all */
+	of(type) {
+		return this.table[type]?.roles ?? NONE;
+	}
+	/** Whether a unit type has a role */
+	has(type, role) {
+		return this.of(type).includes(role);
+	}
+	/** The tags of a unit type: the kit's (`ranged`, `melee`, `hitsAir`) and the game's (`UnitTypeDef.ai.tags`) */
+	tags(type) {
+		return this.table[type]?.tags ?? NONE;
+	}
+	/** Whether a unit type has a tag */
+	hasTag(type, tag) {
+		return this.tags(type).includes(tag);
+	}
+	/** The unit types with a role, in the game's order (the first of a kind is the one meant first) */
+	types(role) {
+		let found = this.byRole.get(role);
+		if (!found) this.byRole.set(role, found = this.registry.units.all().filter((def) => this.has(def.id, role)));
+		return found;
+	}
+	/** The unit types with a tag, in the game's order */
+	tagged(tag) {
+		let found = this.byTag.get(tag);
+		if (!found) this.byTag.set(tag, found = this.registry.units.all().filter((def) => this.hasTag(def.id, tag)));
+		return found;
+	}
+	/** What a game declared of a type (`UnitTypeDef.ai`): nothing where it declared nothing */
+	hints(type) {
+		return this.registry.units.has(type) ? this.registry.unit(type).ai : void 0;
+	}
+	/**
+	* 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) {
+		const entry = this.table[type];
+		if (!entry) return "no roles";
+		if (!entry.roles.length) return "none";
+		return entry.why?.length ? entry.why.join("; ") : `declared: ${entry.roles.join(", ")}`;
+	}
+	/** Every role and the types that have it, for the report (the debug tools) */
+	report() {
+		const report = {};
+		for (const [type, entry] of Object.entries(this.table)) for (const role of entry.roles) (report[role] ??= []).push(type);
+		return report;
+	}
+};
+var NONE = [];
+/**
+* Finds what the unit types of a game are for, for a player: inferred from the definitions (`inferRoles`), or by
+* the game's own finder where it gives one (`AiOptions.roles`), with what the game declares on a type
+* (`UnitTypeDef.ai.role`) over either, and the game's tags beside the inferred ones. What the view does once per
+* brain (`AiView.roles`), again only when the game's definitions change
+*
+* @internal
+*/
+function findRoles(registry, player, finder) {
+	const table = finder ? finder(registry, player) : inferRoles(registry);
+	for (const def of registry.units.all()) {
+		const hints = def.ai;
+		if (!hints) continue;
+		const entry = table[def.id] ??= {
+			roles: [],
+			tags: []
+		};
+		if (hints.role !== void 0) {
+			entry.roles = Array.isArray(hints.role) ? [...hints.role] : [hints.role];
+			delete entry.why;
+		}
+		if (hints.tags) entry.tags = [.../* @__PURE__ */ new Set([...entry.tags, ...hints.tags])];
+	}
+	return new Roles(table, registry);
+}
+/**
+* The unit types a player has or can come to make, from what it has (`owned`): what its units build, its buildings
+* train and what they turn into, followed through, of what its race and the game's `available` hook let it make.
+* Of the whole game, for a player with nothing yet. What the view narrows the roles to for the player (`AiView.typesOf`)
+*
+* @internal
+*/
+function reachableTypes(registry, player, owned) {
+	const mine = new Set(owned);
+	const may = (def) => availableToPlayer(def, {
+		race: player.race,
+		availability: player.availability
+	}, def.id);
+	const reach = /* @__PURE__ */ new Set();
+	const next = [...mine];
+	while (next.length) {
+		const id = next.pop();
+		if (reach.has(id) || !registry.units.has(id)) continue;
+		const def = registry.unit(id);
+		if (!mine.has(id) && !may(def)) continue;
+		reach.add(id);
+		for (const made of [
+			...def.builds ?? [],
+			...def.trains ?? [],
+			...upgradesOf(def)
+		]) if (!reach.has(made)) next.push(made);
+	}
+	if (reach.size) return reach;
+	for (const def of registry.units.all()) if (may(def)) reach.add(def.id);
+	return reach;
+}
+//#endregion
+export { Roles, findRoles, inferRoles, reachableTypes };
+
+//# sourceMappingURL=roles.js.map

package/dist/ai/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","names":[],"sources":["../../src/ai/roles.ts"],"sourcesContent":["import { baseStats, supplyGivenOf, type UnitTypeDef, upgradesOf } from '#engine/defs'\nimport type { PlayerId } from '#engine/entity'\nimport type { Registry } from '#engine/registry'\nimport { availableToPlayer } from '#engine/shared'\nimport type { PlacementName } from './plans/placement'\nimport type { CounterHint } from './strength'\n\n/*\n * What unit types are for, to a computer player (AI plan, A2). The kit knows nothing of any one game: it does not know what\n * a \"farm\" or a \"town hall\" is. It knows roles: the worker is what gathers and builds, the hall is where what is\n * gathered is brought and workers come from, supply is the cheapest building that provides supply and trains nothing,\n * and so on. A game declares a type's roles where it wants to (`UnitTypeDef.ai.role`), and what it does not declare is\n * inferred here from the definition, by the rules written down in `inferRoles`, each with its reason, the one place\n * those inferences live. When a role is wrong in a game, the fix is a declaration in the game, not a special case in\n * the kit. The inferences are visible in the report (`Roles.explain`), so that a wrong one is seen, not guessed at.\n *\n * Roles are of a type, not of a player: an enemy's hall is a hall. What of the roles is a player's own (the types it\n * has or can make, as its race and the game's `available` hook say) is the view's to say (`AiView.typesOf`)\n */\n\n/**\n * 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\n * several (a ghoul is a `gatherer` and a `soldier`)\n *\n * - `worker`: gathers and builds; `gatherer`: gathers (a worker is one too); `topper`: what is put up on a deposit of\n *   the money to gather it there (`builtOn`)\n * - `hall`: takes deposits and trains workers; `supply`: provides supply and trains nothing; `barracks`: trains\n *   soldiers; `altar`: trains or revives heroes; `workshop`: researches; `tower`: a building that attacks; `shop`:\n *   sells or hires\n * - `soldier`: a unit that fights and is no hero; `hero`; `caster`: fights with mana; `healer`: has an ability that\n *   heals; `siege`: attacks that splash, fell or are aimed at the ground; `air`: flies; `scout`: the fastest of the\n *   soldiers; `detector`: finds the invisible\n *\n * @beta\n */\nexport type AiRole =\n\t| 'worker'\n\t| 'gatherer'\n\t| 'topper'\n\t| 'hall'\n\t| 'supply'\n\t| 'barracks'\n\t| 'altar'\n\t| 'workshop'\n\t| 'tower'\n\t| 'shop'\n\t| 'soldier'\n\t| 'hero'\n\t| 'caster'\n\t| 'healer'\n\t| 'siege'\n\t| 'air'\n\t| 'scout'\n\t| 'detector'\n\t| (string & {})\n\n/**\n * What a game declares of a unit type for the computer player (`UnitTypeDef.ai`), where what the kit infers from the\n * definition is wrong or cannot be known: its roles, words of the game's own about it, what it answers, how much it\n * is worth hitting. A declared role is in place of the inferred ones, not beside them\n *\n * @beta\n */\nexport interface AiHints {\n\t/** What it is for (`AiRole`), one or several: in place of what the kit would infer */\n\trole?: AiRole | AiRole[]\n\t/** Words of the game's own about it (`'ranged'`, `'cavalry'`), for a brain's queries (`UnitSet.withTag`). Beside the inferred ones */\n\ttags?: string[]\n\t/**\n\t * What it is good against: tags, roles or type ids (`['air', 'siege']`), each with a weight where a word is not enough\n\t * (`{ target: 'air', weight: 1 }`). Read by the matchups (`Strength.matchup`, `odds`, `counterFor`)\n\t */\n\tcounters?: CounterHint[]\n\t/**\n\t * How strong it is at full health, in place of the kit's formula (`defaultStrength`) and of any formula the brain was\n\t * given: for a type whose numbers mislead (a unit that is all spells). Scaled by the health a unit has left\n\t */\n\tstrength?: number\n\t/** How much it is worth hitting first, in a fight: 1 when left out. Read by the micro of C2 */\n\tpriority?: number\n\t/**\n\t * Where the build plan puts it (`PlacementName`): `atEdge` for a tower, `behind` for supply, `cluster` beside its\n\t * own kind. Over the brain's table; the role's default when left out\n\t */\n\tplacement?: PlacementName\n}\n\n/**\n * The roles and tags of one unit type, with why (`why`: a line per inferred role, for the report; none for a declared\n * one)\n *\n * @beta\n */\nexport interface RoleEntry {\n\t/** The unit type's roles, such as fighter or worker */\n\troles: AiRole[]\n\t/** The unit type's tags, the game's own names for what it is */\n\ttags: string[]\n\t/** A line for each role that was inferred, saying why; none for declared ones */\n\twhy?: string[]\n}\n\n/**\n * The roles and tags of every unit type of a game, by type id: what `inferRoles` gives, and what a game's own\n * `AiOptions.roles` gives in its place\n *\n * @beta\n */\nexport type RoleTable = Record<string, RoleEntry>\n\n/**\n * The player the roles are found for, where finding them depends on who asks (`AiOptions.roles`)\n *\n * @beta\n */\nexport interface RolesPlayer {\n\t/** The player's id */\n\tid: PlayerId\n\t/** The race it plays, where the game has races */\n\trace?: string\n\t/** What the game's `available` hook decided for it, by type (`PlayerState.own.availability`) */\n\tavailability?: Record<string, boolean>\n}\n\n/**\n * A game's own way of saying what unit types are for, in place of the kit's inference (`AiOptions.roles`): every type\n * it has a role for, with its roles and tags. What is declared on a type (`UnitTypeDef.ai`) still goes over it\n *\n * @beta\n */\nexport type RolesFinder = (registry: Registry, player: RolesPlayer) => RoleTable\n\n/** The tags the kit infers from an attack: for a brain that asks for the ranged or for what hits the air */\nconst RANGED = 'ranged'\nconst MELEE = 'melee'\nconst HITS_AIR = 'hitsAir'\n\n/** What fights: a unit with an attack that is not a worker (a worker that builds does not fight; a ghoul, which only gathers, does) */\nconst fights = (def: UnitTypeDef): boolean => def.kind === 'unit' && !!def.attacks?.length && !(def.harvester && def.builds?.length)\n\n/** Whether a building takes deposits of a resource: all of them, or that one among those it lists */\nconst takes = (def: UnitTypeDef, kind: string | undefined): boolean =>\n\tkind !== undefined && (def.dropOff === true || (Array.isArray(def.dropOff) && def.dropOff.includes(kind)))\n\n/** What a race's types are, for the rules that look across a race: those of its race, and those of none */\nconst ofRace = (def: UnitTypeDef, race: string | undefined): boolean => def.race === undefined || def.race === race\n\n/**\n * Infers what every unit type of the game is for, from its definition: the rules, written down once, each with its\n * reason (`RoleEntry.why`). What a game declares (`UnitTypeDef.ai.role`) is not looked at here: `findRoles` puts it\n * over what is inferred\n *\n * @beta\n */\nexport function inferRoles(registry: Registry): RoleTable {\n\tconst table: RoleTable = {}\n\tconst all = registry.units.all()\n\tconst money = registry.currency ?? registry.resources[0]?.id\n\tconst heals = (def: UnitTypeDef) =>\n\t\t(def.abilities ?? []).some((id) => registry.abilities.has(id) && registry.ability(id).effects.some((effect) => effect.type === 'heal'))\n\tconst detects = (def: UnitTypeDef) =>\n\t\t(def.abilities ?? []).some((id) => registry.abilities.has(id) && registry.ability(id).effects.some((effect) => effect.type === 'detect'))\n\t// a worker's kind: the units that gather and build. A race has one; the rules about halls look for it\n\tconst workers = all.filter((def) => def.kind === 'unit' && def.harvester && def.builds?.length)\n\tconst trainsWorker = (def: UnitTypeDef) => !!def.trains?.some((id) => workers.some((worker) => worker.id === id))\n\t// a hall is where deposits go and workers come from. A race with no building that does both (a lanes game with a\n\t// drop-off and no workers) has its drop-offs for halls, whatever they train\n\tconst hallsOf = (race: string | undefined) =>\n\t\tall.filter((def) => def.kind === 'building' && def.dropOff && !def.builtOn && ofRace(def, race) && trainsWorker(def))\n\t// the soldiers of a race, for the scout: the fastest of them\n\tconst soldiers = all.filter((def) => fights(def) && !def.hero)\n\tconst speed = (def: UnitTypeDef) => baseStats(def, registry).moveSpeed\n\t// of its own race alone: a creep of no race is no one's scout\n\tconst scoutOf = (race: string | undefined): UnitTypeDef | undefined => {\n\t\tlet best: UnitTypeDef | undefined\n\t\tfor (const def of soldiers) if (def.race === race && (!best || speed(def) > speed(best))) best = def\n\t\treturn best\n\t}\n\n\tfor (const def of all) {\n\t\tconst roles: AiRole[] = []\n\t\tconst why: string[] = []\n\t\tconst tags: string[] = []\n\t\tconst give = (role: AiRole, reason: string) => {\n\t\t\troles.push(role)\n\t\t\twhy.push(`${role}: ${reason}`)\n\t\t}\n\t\tif (def.kind === 'unit') {\n\t\t\tif (def.harvester && def.builds?.length) give('worker', 'gathers and builds')\n\t\t\tif (def.harvester) give('gatherer', 'gathers')\n\t\t\tif (def.hero) give('hero', 'a hero')\n\t\t\telse if (fights(def)) give('soldier', 'fights and is no hero')\n\t\t\tif (fights(def) && !def.hero && def.abilities?.length && baseStats(def, registry).mana > 0) give('caster', 'fights with mana and abilities')\n\t\t\tif (heals(def)) give('healer', 'has an ability that heals')\n\t\t\tif (def.attacks?.some((attack) => attack.splash || attack.fells || attack.ground))\n\t\t\t\tgive('siege', 'its attacks splash, fell or are aimed at the ground')\n\t\t\tif (def.flying) give('air', 'flies')\n\t\t\tif (!def.hero && fights(def) && scoutOf(def.race) === def) give('scout', 'the fastest of its soldiers')\n\t\t\tif (detects(def)) give('detector', 'has an ability that finds the invisible')\n\t\t} else if (def.kind === 'building') {\n\t\t\tif (def.builtOn !== undefined && def.builtOn === money && takes(def, money))\n\t\t\t\tgive('topper', 'put up on a deposit of the money, where it is gathered')\n\t\t\telse if (def.dropOff && !def.builtOn) {\n\t\t\t\tconst halls = hallsOf(def.race)\n\t\t\t\tif (trainsWorker(def)) give('hall', 'takes deposits and trains workers')\n\t\t\t\telse if (halls.length === 0) give('hall', 'takes deposits, and nothing of its race takes them and trains workers')\n\t\t\t}\n\t\t\tif (supplyGivenOf(def) && !def.trains?.length) give('supply', 'provides supply and trains nothing')\n\t\t\tif (def.trains?.some((id) => registry.units.has(id) && fights(registry.unit(id)) && !registry.unit(id).hero))\n\t\t\t\tgive('barracks', 'trains soldiers')\n\t\t\tif (def.revives || def.trains?.some((id) => registry.units.has(id) && registry.unit(id).hero)) give('altar', 'trains or revives heroes')\n\t\t\tif (def.researches?.length) give('workshop', 'researches')\n\t\t\t// not one that shoots only with units inside it (a burrow): that is shelter, not a defence to put up\n\t\t\tif (def.attacks?.length && !def.transport?.armed) give('tower', 'a building that attacks by itself')\n\t\t\tif (def.sells?.length || def.hires?.length) give('shop', 'sells or hires')\n\t\t\tif (detects(def)) give('detector', 'has an ability that finds the invisible')\n\t\t}\n\t\t// of each of its attacks: one that shoots, one that strikes, one that hits the air\n\t\tconst attacks = def.attacks ?? []\n\t\tif (attacks.some((attack) => attack.projectileSpeed)) tags.push(RANGED)\n\t\tif (attacks.some((attack) => !attack.projectileSpeed)) tags.push(MELEE)\n\t\tif (attacks.some((attack) => attack.targets?.includes('air'))) tags.push(HITS_AIR)\n\t\ttable[def.id] = { roles, tags, why }\n\t}\n\treturn table\n}\n\n/**\n * What the unit types of a game are for (`AiView.roles`): the inferred roles (`inferRoles`, or a game's own finder\n * in its place) with what the game declares on a type over them (`UnitTypeDef.ai`), and the queries over them\n *\n * @beta\n */\nexport class Roles {\n\tprivate readonly byRole = new Map<string, UnitTypeDef[]>()\n\tprivate readonly byTag = new Map<string, UnitTypeDef[]>()\n\n\tconstructor(\n\t\t/** Every unit type's roles and tags, by id */\n\t\treadonly table: RoleTable,\n\t\tprivate readonly registry: Registry\n\t) {}\n\n\t/** The roles of a unit type: none for one that has none, or is not a unit type at all */\n\tof(type: string): readonly AiRole[] {\n\t\treturn this.table[type]?.roles ?? NONE\n\t}\n\n\t/** Whether a unit type has a role */\n\thas(type: string, role: AiRole): boolean {\n\t\treturn this.of(type).includes(role)\n\t}\n\n\t/** The tags of a unit type: the kit's (`ranged`, `melee`, `hitsAir`) and the game's (`UnitTypeDef.ai.tags`) */\n\ttags(type: string): readonly string[] {\n\t\treturn this.table[type]?.tags ?? NONE\n\t}\n\n\t/** Whether a unit type has a tag */\n\thasTag(type: string, tag: string): boolean {\n\t\treturn this.tags(type).includes(tag)\n\t}\n\n\t/** The unit types with a role, in the game's order (the first of a kind is the one meant first) */\n\ttypes(role: AiRole): readonly UnitTypeDef[] {\n\t\tlet found = this.byRole.get(role)\n\t\tif (!found) this.byRole.set(role, (found = this.registry.units.all().filter((def) => this.has(def.id, role))))\n\t\treturn found\n\t}\n\n\t/** The unit types with a tag, in the game's order */\n\ttagged(tag: string): readonly UnitTypeDef[] {\n\t\tlet found = this.byTag.get(tag)\n\t\tif (!found) this.byTag.set(tag, (found = this.registry.units.all().filter((def) => this.hasTag(def.id, tag))))\n\t\treturn found\n\t}\n\n\t/** What a game declared of a type (`UnitTypeDef.ai`): nothing where it declared nothing */\n\thints(type: string): AiHints | undefined {\n\t\treturn this.registry.units.has(type) ? this.registry.unit(type).ai : undefined\n\t}\n\n\t/**\n\t * Why a type has the roles it has, in words, for the report: `declared: worker` for what the game said, a line per\n\t * inferred role otherwise\n\t */\n\texplain(type: string): string {\n\t\tconst entry = this.table[type]\n\t\tif (!entry) return 'no roles'\n\t\tif (!entry.roles.length) return 'none'\n\t\treturn entry.why?.length ? entry.why.join('; ') : `declared: ${entry.roles.join(', ')}`\n\t}\n\n\t/** Every role and the types that have it, for the report (the debug tools) */\n\treport(): Record<string, string[]> {\n\t\tconst report: Record<string, string[]> = {}\n\t\tfor (const [type, entry] of Object.entries(this.table)) for (const role of entry.roles) (report[role] ??= []).push(type)\n\t\treturn report\n\t}\n}\n\nconst NONE: readonly never[] = []\n\n/**\n * Finds what the unit types of a game are for, for a player: inferred from the definitions (`inferRoles`), or by\n * the game's own finder where it gives one (`AiOptions.roles`), with what the game declares on a type\n * (`UnitTypeDef.ai.role`) over either, and the game's tags beside the inferred ones. What the view does once per\n * brain (`AiView.roles`), again only when the game's definitions change\n *\n * @internal\n */\nexport function findRoles(registry: Registry, player: RolesPlayer, finder?: RolesFinder): Roles {\n\tconst table = finder ? finder(registry, player) : inferRoles(registry)\n\tfor (const def of registry.units.all()) {\n\t\tconst hints = def.ai\n\t\tif (!hints) continue\n\t\tconst entry = (table[def.id] ??= { roles: [], tags: [] })\n\t\tif (hints.role !== undefined) {\n\t\t\tentry.roles = Array.isArray(hints.role) ? [...hints.role] : [hints.role]\n\t\t\tdelete entry.why\n\t\t}\n\t\tif (hints.tags) entry.tags = [...new Set([...entry.tags, ...hints.tags])]\n\t}\n\treturn new Roles(table, registry)\n}\n\n/**\n * The unit types a player has or can come to make, from what it has (`owned`): what its units build, its buildings\n * train and what they turn into, followed through, of what its race and the game's `available` hook let it make.\n * Of the whole game, for a player with nothing yet. What the view narrows the roles to for the player (`AiView.typesOf`)\n *\n * @internal\n */\nexport function reachableTypes(registry: Registry, player: RolesPlayer, owned: Iterable<string>): Set<string> {\n\tconst mine = new Set(owned)\n\tconst may = (def: UnitTypeDef) => availableToPlayer(def, { race: player.race, availability: player.availability }, def.id)\n\tconst reach = new Set<string>()\n\tconst next = [...mine]\n\twhile (next.length) {\n\t\tconst id = next.pop()!\n\t\tif (reach.has(id) || !registry.units.has(id)) continue\n\t\tconst def = registry.unit(id)\n\t\t// what it may not make (another race's) is not reached through, but what it has is its own\n\t\tif (!mine.has(id) && !may(def)) continue\n\t\treach.add(id)\n\t\tfor (const made of [...(def.builds ?? []), ...(def.trains ?? []), ...upgradesOf(def)]) if (!reach.has(made)) next.push(made)\n\t}\n\tif (reach.size) return reach\n\tfor (const def of registry.units.all()) if (may(def)) reach.add(def.id)\n\treturn reach\n}\n"],"mappings":"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"}

package/dist/ai/rules.d.ts

@@ -9,7 +9,9 @@ import type { AiRole } from './roles';
  * @beta
  */
 export interface AiRange {
+    /** The lowest it may be; no lower bound when left out */
     min?: number;
+    /** The highest it may be; no upper bound when left out */
     max?: number;
 }
 /**
@@ -20,7 +22,7 @@ export interface AiRange {
 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
+ * table in `docs/ai/scripting.md` says what each asks
  *
  * @beta
  */
@@ -125,7 +127,7 @@ export type AiConditionData =
         status: ObjectiveStatus | ObjectiveStatus[];
     };
 }
-/** A value of the game's report to this player (`GameModule.report`), by its path (`'waves.next'`): equal to, or within */
+/** A value of the game's report to this player (`Rules.report`), by its path (`'waves.next'`): equal to, or within */
  | {
     report: {
         path: string;
@@ -187,7 +189,9 @@ export declare function evaluate(condition: AiCondition, ai: Brain): boolean;
  * @beta
  */
 export interface AiActionData {
+    /** The word the brain tells itself, which the `words()` module or a rule of its own answers */
     say: string;
+    /** What goes with the word, for whoever answers it; nothing when left out */
     data?: unknown;
 }
 /**
@@ -264,7 +268,9 @@ export declare const rules: (list: AiRule[], options?: {
  * @beta
  */
 export interface WordData {
+    /** Where: a point, or the name an entity or region was given by the map or the rules */
     at?: Vec2 | string;
+    /** For how many seconds the army is the word's rather than the goals' */
     seconds?: number;
 }
 /**