@v12-engine/engine 0.1.0 → 0.4.0

package/dist/ai/computer.d.ts

@@ -11,14 +11,17 @@ import { type AiSettings } from './settings';
 /**
  * A computer player: whatever plays a seat of a world from what it sees, through commands as a player does. The
  * engine's own is a `Brain` of modules (`defineBrain`), the melee player among them; a game gives its own in code
- * (`defineComputer`, listed in `GameModule.brains`). `think` is asked about once a second (`createComputerSystem`); `save` and `restore` keep what
+ * (`defineComputer`, listed in `Rules.brains`). `think` is asked about once a second (`createComputerSystem`); `save` and `restore` keep what
  * it remembers through a save
  *
  * @beta
  */
 export interface ComputerPlayer {
+    /** Runs one think: looks at the world and sends commands as a player does */
     think(): void;
+    /** Gives what it remembers as plain data for a save; when left out it remembers nothing */
     save?(): unknown;
+    /** Takes back what `save` gave, from a saved game */
     restore?(memory: unknown): void;
     /** What it is thinking, as plain data: what the debug tools show of the player it plays (its goal, its scores) */
     inspect?(): unknown;
@@ -64,6 +67,7 @@ export interface ComputerTiming {
  * @beta
  */
 export interface ComputerSystem<C extends ComputerPlayer = ComputerPlayer> extends System {
+    /** The computer player this system runs */
     readonly computer: C;
     /** The player it plays */
     readonly player: PlayerId;
@@ -137,7 +141,7 @@ export declare const aiTeams: import("#engine/components").Component<Record<stri
 export declare function createBrainSystem(world: World, playerId: PlayerId, brain: BrainDef, options?: AiOptions): ComputerSystem<Brain>;
 /**
  * A computer player of the game's own that is not made of modules (a `ComputerPlayer`: anything that thinks), as a brain
- * the game lists (`GameModule.brains`) and seats as it does any (`world.computers.seat(player, { brain })`): found again
+ * the game lists (`Rules.brains`) and seats as it does any (`world.computers.seat(player, { brain })`): found again
  * by its id when a save is loaded. `make` is handed the seat's session, its context and what it was seated with, the
  * map's under the seat's; it thinks as often as those say (`every`, 1 second when left out)
  *
@@ -153,13 +157,16 @@ export declare function defineComputer<C extends ComputerPlayer>(id: string, mak
  * @beta
  */
 export interface MapAi {
-    /** The brain the player is seated with, by id (`GameModule.brains`): over its race's (`GameAi.races`), under the seat's */
+    /** The brain the player is seated with, by id (`Rules.brains`): over its race's (`GameAi.races`), under the seat's */
     brain?: string;
+    /** The id of the difficulty the computer plays at, which a game's brain reads from its settings */
     difficulty?: string;
+    /** The id of the personality the computer plays with, which a game's brain reads from its settings */
     personality?: string;
+    /** Settings for the brain, over the ones its difficulty and personality give */
     settings?: AiSettings;
     /**
-     * Settings by the race the player plays (`GameModule.races`), over `settings`: for a player whose race the lobby
+     * Settings by the race the player plays (`Rules.races`), over `settings`: for a player whose race the lobby
      * chooses or draws (`random`), a build order or waves for each
      */
     races?: Record<string, AiSettings>;

package/dist/ai/computer.js

@@ -0,0 +1,251 @@
+import { defineComponent } from "../components.js";
+import { invalidateStats } from "../stats.js";
+import { listKitComponents } from "../coreComponents.js";
+import { MISSION_RULES } from "../missionRules.js";
+import { LocalSession } from "../session/local.js";
+import { evaluate } from "./rules.js";
+import { resolveSettings } from "./settings.js";
+import { resolveProfile } from "./profiles.js";
+import { Brain, createBrain } from "./brain.js";
+import { emptyTeam } from "./team.js";
+//#region src/ai/computer.ts
+/**
+* The hooks a profile's handicap (`AiProfile.handicap`) is given to the world by, for one player: what its workers bring
+* in (`beforeDeposit`), the health of what it has (`stats`), the damage it deals (`beforeDamage`), how long what it
+* makes takes (`beforeProduce`). None for a handicap of 1, or none given. Ids `core.ai.handicap.<player>` and
+* `core.ai.handicap.<what>.<player>`
+*/
+function handicapHooks(player, handicap) {
+	const hooks = [];
+	const { income, health, damage, buildTime } = handicap ?? {};
+	if (income !== void 0 && income !== 1) hooks.push({
+		id: `core.ai.handicap.${player}`,
+		hook: "beforeDeposit",
+		run: (_world, event) => {
+			if (event.player === player) event.amount = Math.round(event.amount * income);
+		}
+	});
+	if (health !== void 0 && health !== 1) hooks.push({
+		id: `core.ai.handicap.health.${player}`,
+		hook: "stats",
+		run: (_world, event) => {
+			if (event.entity.owner === player) event.add({ percent: { health: health - 1 } });
+		}
+	});
+	if (damage !== void 0 && damage !== 1) hooks.push({
+		id: `core.ai.handicap.damage.${player}`,
+		hook: "beforeDamage",
+		run: (_world, event) => {
+			if (event.source?.owner === player) event.amount *= damage;
+		}
+	});
+	if (buildTime !== void 0 && buildTime !== 1) hooks.push({
+		id: `core.ai.handicap.buildTime.${player}`,
+		hook: "beforeProduce",
+		run: (_world, event) => {
+			if (event.player === player) event.time *= buildTime;
+		}
+	});
+	return hooks;
+}
+/** How much of each new think goes into the averaged time of a seat. Small: the panel shows a steady number */
+var SMOOTHING = .1;
+/** What a computer player's own numbers start from: the world's seed and the player, mixed so that two seats of one game draw differently */
+var seedOf = (seed, player) => Math.imul((seed ^ 2654435769) >>> 0, 1664525) + player * 1013904223 >>> 0;
+/**
+* Seats a computer player at a world: made of a session of its own (it sees what that player sees, and plays through
+* commands, so it cannot cheat), asked to think about once a second. `make` is handed the session and what a brain
+* takes besides (`BrainContext`: a seed of its own, the budget, whether the world profiles). Add the result to the
+* world (`world.addSystem`), or seat through `world.computers.seat`, which remembers it for a save
+*
+* @beta
+*/
+function createComputerSystem(world, playerId, make, options = {}) {
+	const session = new LocalSession(world, playerId, {
+		observer: !!options.observer || options.profile?.vision === "all",
+		forComputer: options.snapshot === "lean"
+	});
+	const handicaps = handicapHooks(playerId, options.profile?.handicap);
+	for (const hook of handicaps) world.hooks.add(hook);
+	if (handicaps.some((hook) => hook.hook === "stats")) invalidateStats(world);
+	const team = () => {
+		const boards = world.state(aiTeams);
+		const id = String(world.players.get(playerId)?.team ?? playerId);
+		return boards[id] ??= emptyTeam();
+	};
+	const computer = make(session, {
+		seed: seedOf(world.seed, playerId),
+		budget: options.budget,
+		profiling: () => world.scheduler.profiling,
+		team,
+		checks: world.checks.ai
+	});
+	const interval = Math.max(1, Math.round((options.every ?? 1) * world.tickRate));
+	const offset = options.offset ?? playerId * 7;
+	const timing = {
+		last: 0,
+		average: 0,
+		longest: 0
+	};
+	/** Milliseconds of the think under way, across its ticks */
+	let spent = 0;
+	return {
+		name: `ai-${playerId}`,
+		computer,
+		player: playerId,
+		session,
+		update() {
+			if (computer.paused) return;
+			if ((world.tick + offset) % interval !== 0 && !computer.busy) return;
+			const start = performance.now();
+			computer.think();
+			spent += performance.now() - start;
+			if (computer.busy) return;
+			timing.last = spent;
+			timing.average = timing.average === 0 ? spent : timing.average + (spent - timing.average) * SMOOTHING;
+			if (spent > timing.longest) timing.longest = spent;
+			spent = 0;
+		},
+		timing() {
+			const brain = computer instanceof Brain ? computer : void 0;
+			if (!brain) return { ...timing };
+			const modules = Object.keys(brain.moduleTiming).length ? { ...brain.moduleTiming } : void 0;
+			const longestByModule = Object.keys(brain.moduleLongest).length ? { ...brain.moduleLongest } : void 0;
+			const { snapshotTiming: snapshot, viewTiming: view, knowledgeTiming: knowledge } = brain;
+			return {
+				...timing,
+				...brain.thinkTicks > 0 && { ticks: brain.thinkTicks },
+				...modules && { modules },
+				...longestByModule && { longestByModule },
+				...snapshot !== void 0 && { snapshot },
+				...view !== void 0 && { view },
+				...knowledge !== void 0 && { knowledge }
+			};
+		},
+		dispose() {
+			computer.dispose?.();
+			session.dispose();
+			for (const hook of handicaps) world.hooks.remove(hook.hook, hook.id);
+			if (handicaps.some((hook) => hook.hook === "stats")) invalidateStats(world);
+			options.onDispose?.();
+		},
+		save: () => {
+			const memory = computer.save?.();
+			return {
+				sent: session.lastSeq,
+				...memory !== void 0 && { memory }
+			};
+		},
+		restore: (_world, data) => {
+			const { sent, memory } = data;
+			session.lastSeq = sent;
+			if (memory !== void 0) computer.restore?.(memory);
+		}
+	};
+}
+/**
+* The boards of the teams' computers (`TeamBoard`, AI plan C5), by team: in the world, so that a save keeps the
+* requests and the plan of an attack together, and never replicated, so that no player gets it in a snapshot
+*
+* @beta
+*/
+var aiTeams = defineComponent({
+	id: "core.ai.teams",
+	default: () => ({})
+});
+listKitComponents(aiTeams);
+/**
+* Seats a brain at a world as one of its players, asked to think as its definition or the options say (`every`), with
+* the budget the options give. Add the result to the world, or go through `world.computers.seat`
+*
+* @beta
+*/
+function createBrainSystem(world, playerId, brain, options = {}) {
+	const { profile } = resolveProfile(options, world.registry, void 0, world.players.get(playerId)?.race);
+	return createComputerSystem(world, playerId, (session, context) => createBrain(brain, session, options, context), {
+		every: options.every ?? (typeof brain.every === "function" ? brain.every(options) : brain.every) ?? profile.every ?? 1,
+		budget: profile.budget,
+		profile,
+		snapshot: brain.snapshot ?? "lean"
+	});
+}
+/**
+* A computer player of the game's own that is not made of modules (a `ComputerPlayer`: anything that thinks), as a brain
+* the game lists (`Rules.brains`) and seats as it does any (`world.computers.seat(player, { brain })`): found again
+* by its id when a save is loaded. `make` is handed the seat's session, its context and what it was seated with, the
+* map's under the seat's; it thinks as often as those say (`every`, 1 second when left out)
+*
+* @beta
+*/
+function defineComputer(id, make) {
+	return {
+		id,
+		modules: [],
+		seat: (world, player, given) => {
+			const options = mapAiOptions(world, player, given);
+			return createComputerSystem(world, player, (session, context) => make(session, context, options), {
+				every: options.every,
+				budget: options.budget,
+				profile: resolveProfile(options, world.registry, void 0, world.players.get(player)?.race).profile
+			});
+		}
+	};
+}
+/**
+* The seat's options with what the map says of the player under them (`MapPlayer.data.ai`), where the map gives the player
+* to the computer: the lobby's and the scene's say goes over the map's (decision 10), its settings layered over the map's
+* (the map's for the race the player plays over the rest of the map's)
+*
+* @internal
+*/
+function mapAiOptions(world, playerId, options) {
+	const player = world.map.player(playerId);
+	const map = player?.controller === "computer" ? player.data?.ai : void 0;
+	if (!map || typeof map !== "object") return options;
+	const race = world.players.get(playerId)?.race;
+	const raced = race !== void 0 ? map.races?.[race] : void 0;
+	return {
+		...map.difficulty !== void 0 && { difficulty: map.difficulty },
+		...map.personality !== void 0 && { personality: map.personality },
+		...options,
+		...(map.settings || raced || options.settings) && { settings: resolveSettings([
+			map.settings,
+			raced,
+			options.settings
+		]) }
+	};
+}
+/** A seed of a watcher's own numbers: the world's, mixed with the player's */
+var watcherSeedOf = (seed, player) => Math.imul((seed ^ 2135587861) >>> 0, 1664525) + player * 1013904223 >>> 0;
+/** The watcher's brain: nothing of its own, the kit's reading of the picture alone */
+var WATCHER = {
+	id: MISSION_RULES,
+	modules: []
+};
+/**
+* Seats a watcher for the mission rules (`missionRules`, campaign plan MS1): a brain with no modules of its own, at a
+* player, on an observer's session (it sees the whole map; `mine` and `enemy` are that player's), which reads the
+* picture as a brain does when asked to (`think`) and answers a rule's condition (`ask`: the kit's `evaluate`). Its
+* numbers are seeded from the world's and the player's, and its memory is the rules' to save
+*
+* @internal
+*/
+function ruleWatcher(world, player) {
+	const session = new LocalSession(world, player, {
+		observer: true,
+		forComputer: true
+	});
+	const brain = createBrain(WATCHER, session, {}, { seed: watcherSeedOf(world.seed, player) });
+	return {
+		think: () => brain.think(),
+		ask: (condition) => evaluate(condition, brain),
+		tell: (word, data, tick) => brain.tell(word, data, tick),
+		takeTold: (word) => void brain.takeTold(word),
+		save: () => brain.save(),
+		restore: (memory) => brain.restore(memory)
+	};
+}
+//#endregion
+export { aiTeams, createBrainSystem, createComputerSystem, defineComputer, mapAiOptions, ruleWatcher };
+
+//# sourceMappingURL=computer.js.map

package/dist/ai/computer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computer.js","names":[],"sources":["../../src/ai/computer.ts"],"sourcesContent":["import { defineComponent } from '#engine/components'\nimport { listKitComponents } from '#engine/coreComponents'\nimport type { PlayerId } from '#engine/entity'\nimport type { System } from '#engine/registry'\nimport { LocalSession } from '#engine/session/local'\nimport { invalidateStats } from '#engine/stats'\nimport type { HookDef } from '#engine/hooks'\nimport type { World } from '#engine/world'\nimport { MISSION_RULES, type RulesWatcher } from '#engine/missionRules'\nimport { evaluate } from './rules'\nimport type { AiOptions } from './options'\nimport { Brain, type BrainContext, type BrainDef, createBrain } from './brain'\nimport type { ThinkBudgetOptions } from './budget'\nimport { emptyTeam, type TeamBoard } from './team'\nimport { type AiProfile, resolveProfile } from './profiles'\nimport { type AiSettings, resolveSettings } from './settings'\n\n/*\n * The seat of a computer player (AI plan, A1): the one place the kit touches the world. A computer player is a player:\n * it gets a session of its own at the world (`LocalSession`: what that player sees, under their fog, and nothing else)\n * and plays by sending commands through it, as a mouse does. `createComputerSystem` makes the system that asks it to\n * think once in a while, each seat at another tick, so that twelve computers do not all think at once; it also times\n * the thinks, for the report. `world.computers` is who is seated: it keeps each seat in the world (`core.computers`,\n * kept in a save, so that a loaded game has its computers back by itself), and is how the game reaches a seated brain\n * (`tell`, `pause`, `get`). A seat with no brain named gets the first brain the game lists (`Rules.brains`). It names no brain of its own: the engine's (`meleeBrain`) are\n * `@v12-engine/engine/ai`'s, and a game that does not list one carries none of them. Nothing else in `ai/` imports the\n * world (a test asserts it): a brain that had the world could see through the fog\n */\n\n/**\n * A computer player: whatever plays a seat of a world from what it sees, through commands as a player does. The\n * engine's own is a `Brain` of modules (`defineBrain`), the melee player among them; a game gives its own in code\n * (`defineComputer`, listed in `Rules.brains`). `think` is asked about once a second (`createComputerSystem`); `save` and `restore` keep what\n * it remembers through a save\n *\n * @beta\n */\nexport interface ComputerPlayer {\n\t/** Runs one think: looks at the world and sends commands as a player does */\n\tthink(): void\n\t/** Gives what it remembers as plain data for a save; when left out it remembers nothing */\n\tsave?(): unknown\n\t/** Takes back what `save` gave, from a saved game */\n\trestore?(memory: unknown): void\n\t/** What it is thinking, as plain data: what the debug tools show of the player it plays (its goal, its scores) */\n\tinspect?(): unknown\n\t/** Whether a think is under way across ticks (a brain's budget): it is asked to think on at the next tick */\n\treadonly busy?: boolean\n\t/** Whether it sits still (`world.computers.pause`). A player without the field cannot be paused */\n\tpaused?: boolean\n\t/** Takes in a word from the game (`world.computers.tell`), with the tick it is told at */\n\ttell?(word: string, data: unknown, tick: number): void\n\t/** Lets go of what it holds outside its seat, once unseated */\n\tdispose?(): void\n}\n\n/**\n * Milliseconds a computer player's thinks took: for the report and the stats panel, never for a decision\n *\n * @beta\n */\nexport interface ComputerTiming {\n\t/** The last think, all its ticks where it was sliced */\n\tlast: number\n\t/** Averaged over its thinks */\n\taverage: number\n\t/** The longest think there was */\n\tlongest: number\n\t/** Ticks the last think took: 1, unless the brain's budget sliced it over ticks */\n\tticks?: number\n\t/** By module, averaged, while the world profiles (`Scheduler.profiling`): a brain's */\n\tmodules?: Record<string, number>\n\t/** By module, the most one pass of it took, always: a brain's. What `ThinkBudgetOptions.warnAfterMs` is measured against */\n\tlongestByModule?: Record<string, number>\n\t/** Of a think, what taking the picture of the game took (the seat's `snapshot()`), averaged, while the world profiles: a brain's */\n\tsnapshot?: number\n\t/** Of a think, what reading the picture into the view took (`AiView`), averaged, while the world profiles: a brain's */\n\tview?: number\n\t/** Of a think, what bringing the brain's knowledge up to date took, averaged, while the world profiles: a brain's */\n\tknowledge?: number\n}\n\n/**\n * The system a computer player plays from: it is asked to think about once a second (`every`, in seconds), each seat\n * at another tick of it, to spread the work; it is named for its seat (`ai-<player>`), which a save keeps what it\n * remembers by\n *\n * @beta\n */\nexport interface ComputerSystem<C extends ComputerPlayer = ComputerPlayer> extends System {\n\t/** The computer player this system runs */\n\treadonly computer: C\n\t/** The player it plays */\n\treadonly player: PlayerId\n\t/** The seat it plays through */\n\treadonly session: LocalSession\n\t/** Milliseconds its thinks took: the last, an average, the longest, and by module while the world profiles */\n\ttiming(): ComputerTiming\n\t/** Lets go of its seat: the session's listeners, what the computer player holds. The world stays */\n\tdispose(): void\n}\n\n/**\n * What a save keeps of a computer's seat (`ComputerSystem.save`): the number of the last command it sent, and what the\n * computer player remembers (`ComputerPlayer.save`), when it does\n *\n * @internal\n */\nexport interface ComputerSave {\n\t/** The number of the last command the seat sent */\n\tsent: number\n\t/** What the computer player remembers (`ComputerPlayer.save`), when it keeps anything */\n\tmemory?: unknown\n}\n\n/**\n * How a seat asks its computer player to think (`createComputerSystem`)\n *\n * @beta\n */\nexport interface ComputerSeatOptions {\n\t/** Seconds between thinks: 1 when left out */\n\tevery?: number\n\t/**\n\t * How much of a think one tick may do (`ThinkBudgetOptions`: modules a tick, units looked at a tick as the modules say,\n\t * the milliseconds a module is warned over), or the modules a tick as a number: a think with more goes on at the next\n\t * tick, over the same picture. Everything in one tick when left out\n\t */\n\tbudget?: number | ThinkBudgetOptions\n\t/** The tick in each round the seat thinks at: seven times the player's id when left out, so that seats think at different moments */\n\toffset?: number\n\t/**\n\t * What the seat's picture of the game carries: `lean`, what a computer reads (the entities, the players, the items, the\n\t * deaths, damage, pings, chat and the game's own events) and none of what a screen needs (projectiles, missiles,\n\t * corpses, reveals, the effects and the rest of the events), which is cheaper to take and to hear; `full`, everything a\n\t * player's seat gets. `full` when left out here; a brain's seat is `lean` unless its definition says otherwise\n\t * (`BrainDef.snapshot`)\n\t */\n\tsnapshot?: 'lean' | 'full'\n\t/**\n\t * Whether the seat sees everything, as an observer does (`LocalSession`'s `observer`): the one way a computer sees\n\t * through the fog, for a profile with `vision: 'all'` (insane). Its own seat's sight when left out\n\t */\n\tobserver?: boolean\n\t/**\n\t * How well the seat plays (`AiProfile`): its `handicap` (what its workers bring in, the health of what it has, the\n\t * damage it deals, how long what it makes takes, made more or less through hooks that go with the seat) and `vision: 'all'` (it sees everything, as `observer`). A brain's seat and a game's\n\t * own computer (`defineComputer`) are both given the profile of their difficulty\n\t */\n\tprofile?: AiProfile\n\t/** Called as the seat is taken away (`dispose`): to undo what seating did outside the computer (a hook added) */\n\tonDispose?: () => void\n}\n\n/**\n * The hooks a profile's handicap (`AiProfile.handicap`) is given to the world by, for one player: what its workers bring\n * in (`beforeDeposit`), the health of what it has (`stats`), the damage it deals (`beforeDamage`), how long what it\n * makes takes (`beforeProduce`). None for a handicap of 1, or none given. Ids `core.ai.handicap.<player>` and\n * `core.ai.handicap.<what>.<player>`\n */\nfunction handicapHooks(player: PlayerId, handicap: AiProfile['handicap']): HookDef[] {\n\tconst hooks: HookDef[] = []\n\tconst { income, health, damage, buildTime } = handicap ?? {}\n\tif (income !== undefined && income !== 1)\n\t\thooks.push({\n\t\t\tid: `core.ai.handicap.${player}`,\n\t\t\thook: 'beforeDeposit',\n\t\t\trun: (_world, event) => {\n\t\t\t\tif (event.player === player) event.amount = Math.round(event.amount * income)\n\t\t\t}\n\t\t})\n\tif (health !== undefined && health !== 1)\n\t\thooks.push({\n\t\t\tid: `core.ai.handicap.health.${player}`,\n\t\t\thook: 'stats',\n\t\t\trun: (_world, event) => {\n\t\t\t\tif (event.entity.owner === player) event.add({ percent: { health: health - 1 } })\n\t\t\t}\n\t\t})\n\tif (damage !== undefined && damage !== 1)\n\t\thooks.push({\n\t\t\tid: `core.ai.handicap.damage.${player}`,\n\t\t\thook: 'beforeDamage',\n\t\t\trun: (_world, event) => {\n\t\t\t\tif (event.source?.owner === player) event.amount *= damage\n\t\t\t}\n\t\t})\n\tif (buildTime !== undefined && buildTime !== 1)\n\t\thooks.push({\n\t\t\tid: `core.ai.handicap.buildTime.${player}`,\n\t\t\thook: 'beforeProduce',\n\t\t\trun: (_world, event) => {\n\t\t\t\tif (event.player === player) event.time *= buildTime\n\t\t\t}\n\t\t})\n\treturn hooks\n}\n\n/** How much of each new think goes into the averaged time of a seat. Small: the panel shows a steady number */\nconst SMOOTHING = 0.1\n\n/** What a computer player's own numbers start from: the world's seed and the player, mixed so that two seats of one game draw differently */\nconst seedOf = (seed: number, player: PlayerId) => (Math.imul((seed ^ 0x9e3779b9) >>> 0, 1664525) + player * 1013904223) >>> 0\n\n/**\n * Seats a computer player at a world: made of a session of its own (it sees what that player sees, and plays through\n * commands, so it cannot cheat), asked to think about once a second. `make` is handed the session and what a brain\n * takes besides (`BrainContext`: a seed of its own, the budget, whether the world profiles). Add the result to the\n * world (`world.addSystem`), or seat through `world.computers.seat`, which remembers it for a save\n *\n * @beta\n */\nexport function createComputerSystem<C extends ComputerPlayer>(\n\tworld: World,\n\tplayerId: PlayerId,\n\tmake: (session: LocalSession, context: BrainContext) => C,\n\toptions: ComputerSeatOptions = {}\n): ComputerSystem<C> {\n\tconst session = new LocalSession(world, playerId, {\n\t\tobserver: !!options.observer || options.profile?.vision === 'all',\n\t\tforComputer: options.snapshot === 'lean'\n\t})\n\t// its handicaps, asked of the game's rules through their hooks: the profile's, not the computer's doing\n\tconst handicaps = handicapHooks(playerId, options.profile?.handicap)\n\tfor (const hook of handicaps) world.hooks.add(hook)\n\tif (handicaps.some((hook) => hook.hook === 'stats')) invalidateStats(world)\n\t// the board of the player's team, shared by its computers: read anew each time, for a load replaces the world's states\n\tconst team = () => {\n\t\tconst boards = world.state(aiTeams)\n\t\tconst id = String(world.players.get(playerId)?.team ?? playerId)\n\t\treturn (boards[id] ??= emptyTeam())\n\t}\n\tconst computer = make(session, {\n\t\tseed: seedOf(world.seed, playerId),\n\t\tbudget: options.budget,\n\t\tprofiling: () => world.scheduler.profiling,\n\t\tteam,\n\t\tchecks: world.checks.ai\n\t})\n\tconst interval = Math.max(1, Math.round((options.every ?? 1) * world.tickRate))\n\t// players think at different moments, to spread the work\n\tconst offset = options.offset ?? playerId * 7\n\tconst timing: ComputerTiming = { last: 0, average: 0, longest: 0 }\n\t/** Milliseconds of the think under way, across its ticks */\n\tlet spent = 0\n\treturn {\n\t\tname: `ai-${playerId}`,\n\t\tcomputer,\n\t\tplayer: playerId,\n\t\tsession,\n\t\tupdate() {\n\t\t\tif (computer.paused) return\n\t\t\tif ((world.tick + offset) % interval !== 0 && !computer.busy) return\n\t\t\tconst start = performance.now()\n\t\t\tcomputer.think()\n\t\t\tspent += performance.now() - start\n\t\t\tif (computer.busy) return\n\t\t\ttiming.last = spent\n\t\t\ttiming.average = timing.average === 0 ? spent : timing.average + (spent - timing.average) * SMOOTHING\n\t\t\tif (spent > timing.longest) timing.longest = spent\n\t\t\tspent = 0\n\t\t},\n\t\ttiming() {\n\t\t\tconst brain = computer instanceof Brain ? computer : undefined\n\t\t\tif (!brain) return { ...timing }\n\t\t\tconst modules = Object.keys(brain.moduleTiming).length ? { ...brain.moduleTiming } : undefined\n\t\t\tconst longestByModule = Object.keys(brain.moduleLongest).length ? { ...brain.moduleLongest } : undefined\n\t\t\tconst { snapshotTiming: snapshot, viewTiming: view, knowledgeTiming: knowledge } = brain\n\t\t\treturn {\n\t\t\t\t...timing,\n\t\t\t\t...(brain.thinkTicks > 0 && { ticks: brain.thinkTicks }),\n\t\t\t\t...(modules && { modules }),\n\t\t\t\t...(longestByModule && { longestByModule }),\n\t\t\t\t...(snapshot !== undefined && { snapshot }),\n\t\t\t\t...(view !== undefined && { view }),\n\t\t\t\t...(knowledge !== undefined && { knowledge })\n\t\t\t}\n\t\t},\n\t\tdispose() {\n\t\t\tcomputer.dispose?.()\n\t\t\tsession.dispose()\n\t\t\tfor (const hook of handicaps) world.hooks.remove(hook.hook, hook.id)\n\t\t\tif (handicaps.some((hook) => hook.hook === 'stats')) invalidateStats(world)\n\t\t\toptions.onDispose?.()\n\t\t},\n\t\t// what it remembers goes into a save, with the number of the last command its seat sent; a game loaded from it\n\t\t// adds the computer player again, and it carries on\n\t\tsave: (): ComputerSave => {\n\t\t\tconst memory = computer.save?.()\n\t\t\treturn { sent: session.lastSeq, ...(memory !== undefined && { memory }) }\n\t\t},\n\t\trestore: (_world: World, data: unknown) => {\n\t\t\tconst { sent, memory } = data as ComputerSave\n\t\t\tsession.lastSeq = sent\n\t\t\tif (memory !== undefined) computer.restore?.(memory)\n\t\t}\n\t}\n}\n\n/**\n * The boards of the teams' computers (`TeamBoard`, AI plan C5), by team: in the world, so that a save keeps the\n * requests and the plan of an attack together, and never replicated, so that no player gets it in a snapshot\n *\n * @beta\n */\nexport const aiTeams = defineComponent<Record<string, TeamBoard>>({ id: 'core.ai.teams', default: () => ({}) })\n// the engine's own, found in every world's registry where the kit is loaded\nlistKitComponents(aiTeams)\n\n/**\n * Seats a brain at a world as one of its players, asked to think as its definition or the options say (`every`), with\n * the budget the options give. Add the result to the world, or go through `world.computers.seat`\n *\n * @beta\n */\nexport function createBrainSystem(world: World, playerId: PlayerId, brain: BrainDef, options: AiOptions = {}): ComputerSystem<Brain> {\n\t// its profile (D1): how often it thinks where the seat and the brain say nothing, whether it sees everything, its handicaps\n\tconst { profile } = resolveProfile(options, world.registry, undefined, world.players.get(playerId)?.race)\n\tconst every = options.every ?? (typeof brain.every === 'function' ? brain.every(options) : brain.every) ?? profile.every ?? 1\n\treturn createComputerSystem(world, playerId, (session, context) => createBrain(brain, session, options, context), {\n\t\tevery,\n\t\t// the budget (F2): the profile's, with the seat's own over it\n\t\tbudget: profile.budget,\n\t\tprofile,\n\t\t// the picture cut to what a brain reads, unless the brain says it reads everything\n\t\tsnapshot: brain.snapshot ?? 'lean'\n\t})\n}\n\n/**\n * A computer player of the game's own that is not made of modules (a `ComputerPlayer`: anything that thinks), as a brain\n * the game lists (`Rules.brains`) and seats as it does any (`world.computers.seat(player, { brain })`): found again\n * by its id when a save is loaded. `make` is handed the seat's session, its context and what it was seated with, the\n * map's under the seat's; it thinks as often as those say (`every`, 1 second when left out)\n *\n * @beta\n */\nexport function defineComputer<C extends ComputerPlayer>(\n\tid: string,\n\tmake: (session: LocalSession, context: BrainContext, options: AiOptions) => C\n): BrainDef {\n\treturn {\n\t\tid,\n\t\tmodules: [],\n\t\tseat: (world, player, given) => {\n\t\t\tconst options = mapAiOptions(world, player, given)\n\t\t\treturn createComputerSystem(world, player, (session, context) => make(session, context, options), {\n\t\t\t\tevery: options.every,\n\t\t\t\tbudget: options.budget,\n\t\t\t\t// the difficulty's handicap and vision, as a brain's seat has them\n\t\t\t\tprofile: resolveProfile(options, world.registry, undefined, world.players.get(player)?.race).profile\n\t\t\t})\n\t\t}\n\t}\n}\n\n/**\n * What a map says of how its computer player plays (`MapPlayer.data.ai`, decision 6 of the AI plan), for a player the map\n * gives the computer (`controller: 'computer'`): a difficulty and a personality by name, and settings (`AiSettings`:\n * its flags, its build order as `plans.order`, its waves as `waves.waves`, any area's numbers). Plain data, as the map's\n * file holds it\n *\n * @beta\n */\nexport interface MapAi {\n\t/** The brain the player is seated with, by id (`Rules.brains`): over its race's (`GameAi.races`), under the seat's */\n\tbrain?: string\n\t/** The id of the difficulty the computer plays at, which a game's brain reads from its settings */\n\tdifficulty?: string\n\t/** The id of the personality the computer plays with, which a game's brain reads from its settings */\n\tpersonality?: string\n\t/** Settings for the brain, over the ones its difficulty and personality give */\n\tsettings?: AiSettings\n\t/**\n\t * Settings by the race the player plays (`Rules.races`), over `settings`: for a player whose race the lobby\n\t * chooses or draws (`random`), a build order or waves for each\n\t */\n\traces?: Record<string, AiSettings>\n}\n\n/**\n * The seat's options with what the map says of the player under them (`MapPlayer.data.ai`), where the map gives the player\n * to the computer: the lobby's and the scene's say goes over the map's (decision 10), its settings layered over the map's\n * (the map's for the race the player plays over the rest of the map's)\n *\n * @internal\n */\nexport function mapAiOptions(world: World, playerId: PlayerId, options: AiOptions): AiOptions {\n\tconst player = world.map.player(playerId)\n\tconst map = player?.controller === 'computer' ? (player.data?.ai as MapAi | undefined) : undefined\n\tif (!map || typeof map !== 'object') return options\n\tconst race = world.players.get(playerId)?.race\n\tconst raced = race !== undefined ? map.races?.[race] : undefined\n\treturn {\n\t\t...(map.difficulty !== undefined && { difficulty: map.difficulty }),\n\t\t...(map.personality !== undefined && { personality: map.personality }),\n\t\t...options,\n\t\t...((map.settings || raced || options.settings) && { settings: resolveSettings([map.settings, raced, options.settings]) })\n\t}\n}\n\n/** A seed of a watcher's own numbers: the world's, mixed with the player's */\nconst watcherSeedOf = (seed: number, player: PlayerId) => (Math.imul((seed ^ 0x7f4a7c15) >>> 0, 1664525) + player * 1013904223) >>> 0\n\n/** The watcher's brain: nothing of its own, the kit's reading of the picture alone */\nconst WATCHER: BrainDef = { id: MISSION_RULES, modules: [] }\n\n/**\n * Seats a watcher for the mission rules (`missionRules`, campaign plan MS1): a brain with no modules of its own, at a\n * player, on an observer's session (it sees the whole map; `mine` and `enemy` are that player's), which reads the\n * picture as a brain does when asked to (`think`) and answers a rule's condition (`ask`: the kit's `evaluate`). Its\n * numbers are seeded from the world's and the player's, and its memory is the rules' to save\n *\n * @internal\n */\nexport function ruleWatcher(world: World, player: PlayerId): RulesWatcher {\n\tconst session = new LocalSession(world, player, { observer: true, forComputer: true })\n\tconst brain = createBrain(WATCHER, session, {}, { seed: watcherSeedOf(world.seed, player) })\n\treturn {\n\t\tthink: () => brain.think(),\n\t\task: (condition) => evaluate(condition, brain),\n\t\ttell: (word, data, tick) => brain.tell(word, data, tick),\n\t\ttakeTold: (word) => void brain.takeTold(word),\n\t\tsave: () => brain.save(),\n\t\trestore: (memory) => brain.restore(memory as never)\n\t}\n}\n"],"mappings":"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"}

package/dist/ai/defence.d.ts

@@ -35,6 +35,7 @@ export interface DefenceOptions {
  * @beta
  */
 export interface DefenceMemory {
+    /** The version of the memory's format: 1 so far */
     v: 1;
     /** By base (the id of what it is around): where, how many raids, the one on now (since when), when last seen, the strongest */
     raids: Record<string, {
@@ -67,6 +68,7 @@ export interface Raid {
  * @beta
  */
 export interface DefenceReport {
+    /** The raids on now, each with where it is, the enemy units in it, their strength, the squad that answers it and how many defend, since when and how many so far */
     raids: {
         at: [number, number];
         intruders: number[];
@@ -76,11 +78,13 @@ export interface DefenceReport {
         since: number;
         count: number;
     }[];
+    /** The bases raided, each with where it is, how many raids it had and the tick of the last */
     bases: {
         at: [number, number];
         raids: number;
         last: number;
     }[];
+    /** The towers it wants, each with where, the type wanted and how far the want is along */
     towers: {
         at: [number, number];
         want: string;