@v12-engine/engine 0.1.0 → 0.4.0

package/dist/ai/brain.js

@@ -0,0 +1,844 @@
+import { plainParts } from "../plain.js";
+import { debugChecks } from "../debug2.js";
+import { rootLogger } from "../log.js";
+import { Rng } from "../rng.js";
+import { order } from "../scheduler.js";
+import { AI_PHASES } from "./module.js";
+import { ThinkBudget } from "./budget.js";
+import { Decisions, explainGoal } from "./report.js";
+import { AiView } from "./view.js";
+import { Goals } from "./goals.js";
+import { Knowledge } from "./knowledge.js";
+import { Plans } from "./plans/plans.js";
+import { Purse } from "./plans/purse.js";
+import { resolveSettings } from "./settings.js";
+import { resolveProfile } from "./profiles.js";
+import { checkBrain, orderKey } from "./checks.js";
+import { Squads } from "./squads.js";
+//#region src/ai/brain.ts
+/** A module definition's id, where it is known before the module is made: an object's, or a `defineModule`'s */
+var idOf = (def) => typeof def === "function" ? def.id : def.id;
+/**
+* What of what its seat heard since it last thought a save keeps (`BrainMemory.heard`): the facts a brain reads (deaths,
+* damage, healing, pings, chat, the game's own events). What is for the screen is left out: a builder's hammer blow
+* comes of a timer no save keeps, and the answers to its own commands name the seat's numbering of them, which a loaded
+* game's seat starts afresh
+*/
+var HEARD = /* @__PURE__ */ new Set([
+	"death",
+	"damage",
+	"heal",
+	"ping",
+	"chat",
+	"game"
+]);
+/** How much of each new think goes into a module's averaged time. Small: the panel shows a steady number */
+var SMOOTHING = .1;
+/** A timing averaged over thinks, the new one weighed in: the first stands as it is */
+var averaged = (before, took) => before === void 0 ? took : before + (took - before) * SMOOTHING;
+/**
+* A computer player made of modules (`defineBrain`), seated at a world (`world.computers.seat`). What
+* a module is handed as it thinks (`ai`): the picture of the game (`snapshot`), the seat it plays through (`session`),
+* its options, its numbers (`rng`), its log, and `send` for its commands. A brain is a `ComputerPlayer`: `think`, and
+* `save` and `restore` for what it remembers
+*
+* @beta
+*/
+var Brain = class {
+	def;
+	session;
+	options;
+	/** Its modules, in the order they run */
+	modules;
+	/**
+	* Its own numbers, for whatever it leaves to chance (which base to scout first): seeded from the world's and the
+	* player's, kept in its memory, so that the same game plays the same way. Never `Math.random`
+	*/
+	rng;
+	/** Where it says what it does: the world's log, with the player it plays and its brain on each line */
+	log;
+	/** Whether it sits still (`world.computers.pause`). Kept in a save */
+	paused = false;
+	/**
+	* What it sees, as of its last think: the snapshot of its seat, plain data, and the only input a brain has. Taken once
+	* a think: every module of the think reads the same picture
+	*/
+	snapshot;
+	/**
+	* Its reading of the picture (`AiView`): the snapshot indexed once a think and asked as sets (`view.mine.idle()`,
+	* `view.enemies.near(home, 20)`), with what unit types are for (`view.roles`) and the map's facts. What a module
+	* reads the game through
+	*/
+	view;
+	/**
+	* What it remembers of the enemy, the map and itself, with when (`Knowledge`): their bases and army as last seen,
+	* when each place was last looked at, its own losses and income. Brought up to date as each think begins, after the
+	* view; kept in a save
+	*/
+	knowledge;
+	/**
+	* What it could do (`Goals`): its goals scored each think from their considerations, the best given what they
+	* claim of its units and money, each run while it holds its claim. Its definition's goals and the seat's; a module
+	* adds its own (`ai.goals.add`). Picked by the `goals()` module, or by one of the brain's own in its place
+	*/
+	goals;
+	/**
+	* What it has to spend this think (`Purse`): its resources less what builders on their way will pay and what is
+	* held (a goal's money claim, a want saving up), rebuilt from the picture as each think begins. The one ledger:
+	* everything that spends, spends through it. `view.me.purse` is what is free
+	*/
+	purse;
+	/**
+	* Its plans (`Plans`): the build plan (`plans.build`: wants, the steps to each through the tech tree, spots,
+	* builders, saving up), the production plan (`plans.production`: the composition, counters, supply ahead,
+	* research), the game's build order over both, and `plans.want` to add to them. Run by the `build()` and
+	* `production()` modules, or by one of the brain's own
+	*/
+	plans;
+	/**
+	* Its squads (`Squads`): named groups of its units, each with a task (attack there, defend here, gather and go), made
+	* by its goals, rules and modules out of what they hold, and watched by the `squads()` module think after think:
+	* orders sent once and watched, regroups, retreats on the odds, reinforcements. Kept in a save
+	*/
+	squads;
+	/**
+	* How it plays (`AiProfile`), resolved (`resolveProfile`): how well it plays (the engine's, the game's, the
+	* difficulty's, the personality's, the seat's `every` and `budget`) and its settings, the brain's, the game's, the
+	* difficulty's, the personality's, the map's and the seat's each over the one before (a flag's function left out)
+	*/
+	profile;
+	/** Its settings' layers, lowest first (`ResolvedProfile.layers`): what `settings` is worked out from */
+	layers;
+	/** How many times it has thought */
+	thinks = 0;
+	/**
+	* What it decided, the last fifty (`decide`): the goals picked and stopped, with the reason that weighed most, and
+	* what its modules write down. Kept in a save
+	*/
+	decisions = new Decisions();
+	/** The board of its team, shared by its team's computers: what its seat was given (`BrainContext.team`), for its team play */
+	teamBoard;
+	/** Its areas, in the order they were made (`area`) */
+	areaList = [];
+	/** What a save remembered of areas not made yet, by id: taken by each as a module first asks for it */
+	waiting = {};
+	/** What was worked out for this think, by key (`cache`): thrown away with the picture */
+	memo = /* @__PURE__ */ new Map();
+	/**
+	* How strong things are (`Strength`): a unit, a group, one force against another (`odds`), what answers what
+	* (`counterFor`). The view's: the kit's formula unless the brain or the seat was given one
+	*/
+	get strength() {
+		return this.view.strength;
+	}
+	/**
+	* Where the strength is (`ThreatMap`): the friendly and the enemy strength that reaches each cell of a coarse grid
+	* over the map, by layer. Made from the think's picture when first asked; `threat.at(undefined)` is all zeros
+	*/
+	get threat() {
+		return this.view.threat;
+	}
+	/** Commands it sent this think */
+	sent = 0;
+	/** Commands it would have sent this think past what its profile lets a think send (`commandsPerThink`): not sent */
+	held = 0;
+	/**
+	* What its play adds up to since it was seated (`AiStats`): commands sent, held and refused, seconds its fighters
+	* stood idle, orders sent again for the same thing, seconds its building waited on money. For the report and
+	* `simulate`, never for a decision; not kept in a save
+	*/
+	stats = {
+		commands: 0,
+		held: 0,
+		refused: 0,
+		idleArmySeconds: 0,
+		churn: 0,
+		blockedOnMoney: 0,
+		thinks: 0
+	};
+	/** The tick of the think before, for what is counted by the seconds between thinks */
+	lastThink;
+	/** The last order each unit was sent, with the tick: what an order sent again for the same thing is counted against (`AiStats.churn`) */
+	lastOrders = /* @__PURE__ */ new Map();
+	/** The tick each unit was last told to cast: an order told again after a cast between is not counted as churn */
+	castAt = /* @__PURE__ */ new Map();
+	/**
+	* How much of a think one tick may do (`ThinkBudget`): so many modules, so many units looked at as the modules say
+	* (`budget.spent(n)`), the think going on at the next tick from where it stopped (`budget.later()`). Counted in work,
+	* never in milliseconds, so that the game is the same on every machine. What the seat was given (`BrainContext.budget`)
+	*/
+	budget;
+	/** Milliseconds each module took, averaged over thinks, by id: while the world profiles (`BrainContext.profiling`) */
+	moduleTiming = {};
+	/** The most milliseconds each module took in one pass, by id: always, as the warning (`ThinkBudgetOptions.warnAfterMs`) is */
+	moduleLongest = {};
+	/** Milliseconds taking the picture of the game took (the seat's `snapshot()`), averaged: while the world profiles */
+	snapshotTiming;
+	/** Milliseconds reading the picture into the view took (`AiView`, the ledger with it), averaged: while the world profiles */
+	viewTiming;
+	/** Milliseconds bringing the knowledge up to date took, averaged: while the world profiles */
+	knowledgeTiming;
+	/** Ticks the last think took, all its passes: 1 unless its budget sliced it */
+	thinkTicks = 0;
+	/** Ticks of the think under way so far */
+	ticksSoFar = 0;
+	/** The modules the log has warned of taking over `warnAfterMs`, once each */
+	warned = /* @__PURE__ */ new Set();
+	/**
+	* The passes of the think under way: each module run, with the units the tick had looked at before it. What a save in
+	* the middle of the think keeps (`BrainMemory.thinking`), kept only where the budget may slice
+	*/
+	passes = [];
+	heard = [];
+	/** Who follows its play from outside (`watch`): none in a game, so nothing is paid for it there */
+	watchers = [];
+	/** The module a think under way goes on from, at the next tick: none between thinks (`budget`) */
+	slice;
+	/**
+	* What it remembered as the think under way began, for a think sliced across ticks: what a save taken before the
+	* think ends keeps, with how far it got (`BrainMemory.thinking`)
+	*/
+	began;
+	/** The words told it since the think under way began: a save taken before it ends keeps them beside what it began with */
+	toldDuring = [];
+	/** A think a save was taken in the middle of: run again to where it was, then on, at the next tick (`restore`) */
+	resume;
+	/** While the modules a loaded game had run already are run again: nothing is sent, said or watched */
+	replaying = false;
+	/** While a pass is run again: how many of the words it was told the pass had heard then, the rest told it after */
+	replayHeard;
+	profiling;
+	constructor(def, session, options, context = {}) {
+		this.def = def;
+		this.session = session;
+		this.options = options;
+		this.rng = new Rng(context.seed ?? 1);
+		this.log = (session.log ?? rootLogger).child(() => ({ fields: {
+			ai: session.playerId,
+			brain: def.id
+		} }));
+		this.snapshot = session.snapshot();
+		const race = this.snapshot.players.find((player) => player.id === session.playerId)?.race;
+		const { profile, layers, unknown } = resolveProfile(options, session.registry, def.settings, race);
+		this.profile = profile;
+		this.layers = layers;
+		if (unknown.length) this.log.warn("ai", `the computer player is seated with a ${unknown.join(" and a ")} the game does not have: the defaults stand in`);
+		this.budget = new ThinkBudget(context.budget);
+		this.profiling = context.profiling ?? (() => false);
+		this.view = new AiView(this.snapshot, session, {
+			roles: options.roles,
+			strength: options.strength ?? def.strength
+		});
+		this.knowledge = new Knowledge(def.knowledge || {}, session.terrain, def.knowledge !== false);
+		this.goals = new Goals(this, def.picking);
+		this.goals.add(...def.goals ?? []);
+		this.purse = new Purse(session.registry);
+		this.purse.begin(this.view);
+		this.plans = new Plans(this, profile.plans ?? {});
+		this.squads = new Squads(this, profile.squads?.tasks);
+		this.teamBoard = context.team;
+		for (const area of [
+			this.knowledge,
+			this.goals,
+			this.plans,
+			this.squads
+		]) this.register(area);
+		this.goals.add(...options.goals ?? []);
+		const left = new Set(def.without ?? []);
+		const kept = def.modules.filter((module) => {
+			const id = idOf(module);
+			return id === void 0 || !left.has(id);
+		});
+		for (const id of left) if (!def.modules.some((module) => idOf(module) === id)) this.log.warn("ai", `the brain "${def.id}" leaves out a module "${id}" it does not have`);
+		const made = kept.map((module) => typeof module === "function" ? module(this) : module);
+		const ids = /* @__PURE__ */ new Set();
+		for (const module of made) {
+			if (ids.has(module.id)) throw new Error(`The brain "${def.id}" has two modules called "${module.id}"`);
+			ids.add(module.id);
+		}
+		let phase = 0;
+		const phased = made.map((module, listed) => {
+			if (module.phase) phase = AI_PHASES.indexOf(module.phase);
+			return {
+				module,
+				phase,
+				listed
+			};
+		});
+		phased.sort((a, b) => a.phase - b.phase || a.listed - b.listed);
+		this.modules = order(phased.map(({ module }) => ({
+			name: module.id,
+			before: module.before,
+			after: module.after,
+			module
+		}))).map((each) => each.module);
+		if (context.checks ?? debugChecks.ai) checkBrain(this);
+	}
+	/**
+	* An area of its (`AiArea`): its economy (`ai.area(Economy)`), its scouting, a game's own (`defineArea`), made the
+	* first time it is asked for, with what a save remembered of it. What its modules share beyond what every module
+	* does (`knowledge`, `goals`, `plans`, `squads`, `purse`)
+	*/
+	area(key) {
+		const known = this.areaList.find((area) => area.id === key.id);
+		if (known) return known;
+		const made = key.make(this);
+		if (made.id !== key.id) throw new Error(`The area "${key.id}" made an area called "${made.id}"`);
+		this.register(made);
+		return made;
+	}
+	/**
+	* An area made already, by id: none where no module has asked for it. For a part of the kit that reads another's
+	* area where there is one and needs nothing of it where there is none (whether a squad's fights are the micro's)
+	*/
+	made(id) {
+		return this.areaList.find((area) => area.id === id);
+	}
+	/** Its areas, in the order they were made: what its memory and its report are made of */
+	areas() {
+		return this.areaList;
+	}
+	/** Puts an area among its own, with what a save remembered of it */
+	register(area) {
+		this.areaList.push(area);
+		if (!(area.id in this.waiting)) return;
+		const memory = this.waiting[area.id];
+		delete this.waiting[area.id];
+		if (!area.restore(memory)) this.log.info("ai", area.afresh ?? `the save remembers the computer player's ${area.id} in a shape this brain does not read: it starts afresh`);
+	}
+	/**
+	* Follows its play from outside (`BrainWatcher`): the commands it sends, its thinks as each ends, what it decides.
+	* Returns the way to stop. What `watchComputer` and `recordDecisions` of `@v12-engine/engine/testing` stand on
+	*/
+	watch(watcher) {
+		this.watchers = [...this.watchers, watcher];
+		return () => {
+			this.watchers = this.watchers.filter((each) => each !== watcher);
+		};
+	}
+	/** The player it plays */
+	get playerId() {
+		return this.session.playerId;
+	}
+	/** The game's definitions, as the seat has them */
+	get registry() {
+		return this.session.registry;
+	}
+	/** The tick of its picture of the game */
+	get tick() {
+		return this.snapshot.tick;
+	}
+	/** Seconds into the game, as of its picture of it */
+	get time() {
+		return this.snapshot.tick / this.session.tickRate;
+	}
+	/** The player it plays, as its picture shows them: resources, supply, tech (`own`). Nothing once out of the game. `view.me` is the same, never nothing */
+	get me() {
+		return this.view.player(this.session.playerId);
+	}
+	module(key) {
+		const id = typeof key === "string" ? key : key.id;
+		return this.modules.find((module) => module.id === id);
+	}
+	/**
+	* What its areas play by this think (`AiSettings`): its settings' layers worked out, a flag that is a function of the
+	* brain asked now. Each area reads its own (`ai.settings.economy`), over what its module was made with
+	*/
+	get settings() {
+		return this.cache("settings", () => resolveSettings(this.layers, this));
+	}
+	/**
+	* What was worked out once for this think, by key: a consideration asked by several goals, a set a few modules
+	* read (`ai.cache('intruders', () => ...)`). Thrown away as the next think takes its picture
+	*/
+	cache(key, compute) {
+		if (this.memo.has(key)) return this.memo.get(key);
+		const value = compute();
+		this.memo.set(key, value);
+		return value;
+	}
+	/** Whether a think is under way across ticks (`budget`): the seat asks it to think on at the next tick */
+	get busy() {
+		return this.slice !== void 0 || this.resume !== void 0;
+	}
+	/**
+	* One think, or one tick of it. A new picture of the game is taken, and the modules run over it in their order, as
+	* many a tick as the budget allows (`budget`): so many modules, so many units looked at as they say. A module's error
+	* is the seat's to catch, as a system's is
+	*/
+	think() {
+		if (this.paused) return;
+		const resume = this.resume;
+		this.resume = void 0;
+		if (this.slice === void 0) {
+			const timed = this.profiling();
+			const start = timed ? performance.now() : 0;
+			const snapshot = resume?.snapshot ?? this.session.snapshot();
+			const taken = timed ? performance.now() : 0;
+			if (timed) this.snapshotTiming = averaged(this.snapshotTiming, taken - start);
+			if (snapshot.outcome !== "playing") return;
+			this.snapshot = snapshot;
+			this.memo.clear();
+			const before = this.view;
+			this.view = new AiView(snapshot, this.session, {
+				before,
+				roles: this.options.roles,
+				strength: this.options.strength ?? this.def.strength
+			});
+			const read = timed ? performance.now() : 0;
+			if (this.def.knowledge !== false) {
+				if (resume) this.knowledge.resume(this.view);
+				else this.knowledge.update(this.view, before);
+				this.view.me.income = this.knowledge.own.incomes();
+			}
+			const remembered = timed ? performance.now() : 0;
+			if (timed && this.def.knowledge !== false) this.knowledgeTiming = averaged(this.knowledgeTiming, remembered - read);
+			this.purse.begin(this.view);
+			const holds = this.goals.all();
+			for (const id in holds) if (holds[id].money) this.purse.reserve(id, holds[id].money);
+			this.view.me.purse = this.purse.free;
+			if (!resume) {
+				this.thinks++;
+				this.count();
+			}
+			this.sent = 0;
+			this.held = 0;
+			this.slice = 0;
+			this.passes = [];
+			this.ticksSoFar = 0;
+			if (timed) this.viewTiming = averaged(this.viewTiming, read - taken + (performance.now() - remembered));
+			if (this.budget.slices) {
+				this.began = this.memory();
+				this.toldDuring = [];
+			}
+			if (resume) {
+				this.replaying = true;
+				try {
+					for (const [module, units, heard] of resume.passes) {
+						this.slice = module;
+						this.budget.begin(units);
+						this.replayHeard = heard;
+						this.pass(module);
+					}
+				} finally {
+					this.replaying = false;
+					this.replayHeard = void 0;
+				}
+			}
+		}
+		this.ticksSoFar++;
+		this.budget.begin();
+		let ran = 0;
+		let at = this.slice;
+		while (at < this.modules.length && ran < this.budget.modulesPerTick && this.budget.room) {
+			const module = this.modules[at];
+			const every = module.everyThinks ?? 1;
+			if (every !== 1 && (this.thinks - 1) % every !== (module.offset ?? 0) % every) {
+				at++;
+				continue;
+			}
+			ran++;
+			const more = this.pass(at);
+			at = this.slice;
+			if (!more) break;
+		}
+		this.slice = at;
+		if (at >= this.modules.length) {
+			this.slice = void 0;
+			this.began = void 0;
+			this.passes = [];
+			this.thinkTicks = this.ticksSoFar;
+			if (this.plans.build.savingFor !== void 0) this.stats.blockedOnMoney += this.sinceLastThink();
+			this.lastThink = this.tick;
+			for (const watcher of this.watchers) watcher.thought?.(this);
+		}
+	}
+	/**
+	* One pass of a module: run once, timed, and the think moved on past it, unless it stopped for the tick with more to
+	* do (`budget.later()`), in which case it is where the think goes on at the next tick. Gives whether the think may go
+	* on this tick
+	*/
+	pass(index) {
+		const module = this.modules[index];
+		const { budget } = this;
+		const before = budget.units;
+		if (budget.slices) this.passes.push([
+			index,
+			before,
+			this.heard.length
+		]);
+		budget.deferred = false;
+		const start = performance.now();
+		module.think(this);
+		const took = performance.now() - start;
+		if (!(took <= (this.moduleLongest[module.id] ?? 0))) this.moduleLongest[module.id] = took;
+		if (this.profiling()) this.moduleTiming[module.id] = averaged(this.moduleTiming[module.id], took);
+		if (budget.warnAfterMs !== void 0 && took > budget.warnAfterMs && !this.warned.has(module.id) && !this.replaying) {
+			this.warned.add(module.id);
+			this.log.warn("ai", `the module "${module.id}" took ${took.toFixed(1)} ms, over ${budget.warnAfterMs}: said once`, {
+				module: module.id,
+				ms: Math.round(took * 100) / 100
+			});
+		}
+		if (budget.deferred) {
+			if (budget.units > before) return false;
+			if (!this.replaying && !this.warned.has(`later:${module.id}`)) {
+				this.warned.add(`later:${module.id}`);
+				this.log.warn("ai", `the module "${module.id}" asked to go on at the next tick having looked at nothing: taken to be done, said once`, { module: module.id });
+			}
+		}
+		this.slice = index + 1;
+		return budget.room;
+	}
+	/** Seconds between the think before and this one's picture: 0 for the first think */
+	sinceLastThink() {
+		return this.lastThink === void 0 ? 0 : (this.tick - this.lastThink) / this.session.tickRate;
+	}
+	/**
+	* Counts, as a think begins, what its play adds up to (`stats`): the fighters that stood idle since the last think,
+	* the commands the game refused since, and the orders it no longer needs to remember for the churn
+	*/
+	count() {
+		const { stats, view } = this;
+		stats.thinks++;
+		const seconds = this.sinceLastThink();
+		if (seconds > 0) stats.idleArmySeconds += view.mine.fighters().idle().length * seconds;
+		for (const event of view.events.of("command")) if (event.refusal) stats.refused++;
+		const forgotten = this.tick - 5 * this.session.tickRate;
+		for (const [id, last] of this.lastOrders) if (last.tick < forgotten || !view.mine.has(id)) this.lastOrders.delete(id);
+		for (const [id, tick] of this.castAt) if (tick < forgotten || !view.mine.has(id)) this.castAt.delete(id);
+	}
+	/**
+	* Sends a command, as the player would: counted (`sent`), carried out at the next tick. Returns the command's number;
+	* -1 for one past what its profile lets a think send (`commandsPerThink`, a person's hands), which is not sent
+	*/
+	send(command) {
+		if (this.replaying) {
+			this.sent++;
+			this.churn(command);
+			return -1;
+		}
+		const cap = this.profile.commandsPerThink;
+		if (cap !== void 0 && this.sent >= cap) {
+			this.held++;
+			this.stats.held++;
+			return -1;
+		}
+		this.sent++;
+		this.stats.commands++;
+		this.churn(command);
+		for (const watcher of this.watchers) watcher.sent?.(command, this);
+		return this.session.send(command);
+	}
+	/**
+	* Counts an order sent to a unit for the same thing as its last within a few seconds (`AiStats.churn`): a unit told
+	* to attack-move there every think never arrives, it stops and starts. The squads send an order once and watch it;
+	* this is how a test or `simulate` sees that they do
+	*/
+	churn(command) {
+		const key = orderKey(command);
+		if (command.queue) return;
+		if (key === void 0) {
+			if (command.type === "cast") for (const id of command.entities) this.castAt.set(id, this.tick);
+			return;
+		}
+		const window = 5 * this.session.tickRate;
+		for (const id of command.entities) {
+			const last = this.lastOrders.get(id);
+			const cast = this.castAt.get(id);
+			if (last && last.key === key && this.tick - last.tick <= window && !(cast !== void 0 && cast >= last.tick)) this.stats.churn++;
+			this.lastOrders.set(id, {
+				key,
+				tick: this.tick
+			});
+		}
+	}
+	/**
+	* The last order it sent a unit lately (within a few seconds), as a key (`orderKey`: its kind, its target, its
+	* place to the cell) with the tick: what keeps a module from telling a unit again what it is already doing, when the
+	* unit changed hands (a squad of another goal) since. None for a unit told nothing lately
+	*/
+	sentTo(unit) {
+		const last = this.lastOrders.get(unit);
+		return last && this.tick - last.tick <= 5 * this.session.tickRate ? last : void 0;
+	}
+	/**
+	* The words the game told it and no module has taken yet (`world.computers.tell`), oldest first; those of one word
+	* where given. Reading them takes nothing: `takeTold` does, as a told rule (`when.told`) does when it fires
+	*/
+	told(word) {
+		const heard = this.replayHeard === void 0 ? this.heard : this.heard.slice(0, this.replayHeard);
+		return word === void 0 ? heard : heard.filter((told) => told.word === word);
+	}
+	/**
+	* Writes down a decision (`decisions`), with the reason that weighed most, in words: what the report's log and the
+	* debug panel show, and the world's log at its `debug` level. `kind` says what it is about (`army`, `build`)
+	*/
+	decide(line, about = {}) {
+		if (this.replaying) return;
+		const decision = {
+			tick: this.tick,
+			kind: about.kind ?? "other",
+			line,
+			...about.goal !== void 0 && { goal: about.goal }
+		};
+		this.decisions.add(decision);
+		for (const watcher of this.watchers) watcher.decided?.(decision, this);
+		if (this.log.says("debug")) this.log.debug("ai", line, {
+			player: this.playerId,
+			kind: decision.kind,
+			...about.goal !== void 0 && { goal: about.goal }
+		});
+	}
+	/**
+	* What it is thinking, as plain data (`AiReport`): its goals with their considerations, what it knows, its roles,
+	* its economy, what it was told, what it decided, and each module's section. Made when asked: nothing in a think
+	* waits for it. What `inspect` gives, and the debug panel's AI tab draws
+	*/
+	report() {
+		const { view } = this;
+		const me = view.me;
+		const sections = {};
+		const report = {
+			v: 1,
+			brain: this.def.id,
+			player: this.playerId,
+			tick: this.tick,
+			time: this.time,
+			tickRate: this.session.tickRate,
+			thinks: this.thinks,
+			...this.paused && { paused: true },
+			profile: plainParts(this.options).kept,
+			playing: plainParts(this.profile).kept,
+			...this.goals.best !== void 0 && { goal: this.goals.best },
+			goals: this.goals.report(),
+			...this.def.knowledge !== false && { knowledge: this.knowledge.inspect() },
+			roles: view.inspect().roles,
+			economy: {
+				resources: { ...me.resources },
+				income: { ...me.income ?? {} },
+				supply: [me.supplyUsed, me.supplyCap]
+			},
+			plans: this.plans.report(),
+			squads: this.squads.report(),
+			threat: threatOf(view.threat),
+			told: this.heard.map((told) => ({
+				word: told.word,
+				tick: told.tick
+			})),
+			sent: this.sent,
+			...this.held && { held: this.held },
+			...this.budget.slices && { budget: {
+				...this.budget.report(),
+				ticks: this.thinkTicks
+			} },
+			stats: { ...this.stats },
+			decisions: this.decisions.save(),
+			sections
+		};
+		for (const area of this.areaList) area.reportTo?.(report);
+		for (const module of this.modules) {
+			module.report?.(report);
+			const what = module.inspect?.();
+			if (what !== void 0) sections[module.id] = what;
+		}
+		return report;
+	}
+	/**
+	* A goal's row of the report as a sentence: what it scored and why, whether it runs and with what, or what kept it
+	* from running. Nothing for a goal the brain does not have
+	*/
+	explain(goal) {
+		const row = this.goals.report().find((each) => each.id === goal);
+		return row && explainGoal(row, (tick) => tick / this.session.tickRate, this.time);
+	}
+	/** Takes in a word from the game: a module takes it with `takeTold`. What the seat calls for `world.computers.tell` */
+	tell(word, data, tick) {
+		if (word === "resume" && this.paused) {
+			this.paused = false;
+			this.decide("resumes: told to", { kind: "word" });
+			return;
+		}
+		this.heard.push({
+			word,
+			...data !== void 0 && { data },
+			tick
+		});
+		if (this.slice !== void 0 && this.began) this.toldDuring.push({
+			word,
+			...data !== void 0 && { data },
+			tick
+		});
+	}
+	/** Takes the words of one kind out of what it was told, oldest first, as many as `count` (all when left out): they are heard no more */
+	takeTold(word, count = Infinity) {
+		const taken = [];
+		const among = this.replayHeard ?? Infinity;
+		this.heard = this.heard.filter((told, index) => {
+			if (index >= among || told.word !== word || taken.length >= count) return true;
+			taken.push(told);
+			return false;
+		});
+		if (this.replayHeard !== void 0) this.replayHeard -= taken.length;
+		return taken;
+	}
+	/**
+	* What it remembers, for a save: its numbers, each module's memory with its version, what it was told. A think under
+	* way (`budget`) is kept as it began, with how far it got and its picture (`BrainMemory.thinking`): the game loaded
+	* from the save runs it on to its end as the saved game does
+	*/
+	save() {
+		const heard = this.session.can.computer?.pendingEvents().filter((event) => HEARD.has(event.type));
+		if (this.slice !== void 0 && this.began) return {
+			...this.began,
+			told: [...this.began.told, ...this.toldDuring.map((told) => ({ ...told }))],
+			...heard?.length && { heard },
+			...this.decisions.list().length > 0 && { decisions: this.decisions.save() },
+			thinking: {
+				snapshot: this.snapshot,
+				passes: this.passes.map((pass) => [...pass])
+			}
+		};
+		return {
+			...this.memory(),
+			...heard?.length && { heard }
+		};
+	}
+	/** What its areas remember, by id: those that remember anything, and what a save had of areas not made since */
+	areaMemories() {
+		const areas = { ...this.waiting };
+		for (const area of this.areaList) if (area.remembers()) areas[area.id] = area.save();
+		return areas;
+	}
+	/** What it remembers, but what its seat heard since it last thought */
+	memory() {
+		const modules = {};
+		for (const module of this.modules) {
+			const data = module.save?.();
+			if (data !== void 0) modules[module.id] = {
+				v: module.version ?? 1,
+				data
+			};
+		}
+		return {
+			v: 2,
+			rng: this.rng.save(),
+			thinks: this.thinks,
+			...this.paused && { paused: true },
+			told: this.heard.map((told) => ({ ...told })),
+			modules,
+			areas: this.areaMemories(),
+			...this.decisions.list().length > 0 && { decisions: this.decisions.save() },
+			...this.lastOrders.size > 0 && { orders: [...this.lastOrders].map(([unit, last]) => ({
+				unit,
+				...last
+			})) }
+		};
+	}
+	/**
+	* Takes back what `save` gave. A module's memory of another version goes through its `migrate`; without one, or with
+	* nothing in the save for it, the module starts afresh, and the log says so once. Memory of a module the brain no
+	* longer has is dropped, said too
+	*/
+	restore(memory) {
+		if (!memory || typeof memory !== "object" || memory.v !== 2) {
+			this.log.warn("ai", "the save remembers the computer player in a shape this brain does not read: it starts afresh", { brain: this.def.id });
+			return;
+		}
+		this.rng.restore(memory.rng);
+		this.thinks = memory.thinks ?? 0;
+		this.resume = memory.thinking && {
+			snapshot: memory.thinking.snapshot,
+			passes: memory.thinking.passes ?? Array.from({ length: memory.thinking.slice ?? 0 }, (_, module) => [
+				module,
+				0,
+				(memory.told ?? []).length
+			])
+		};
+		this.paused = !!memory.paused;
+		this.heard = (memory.told ?? []).map((told) => ({ ...told }));
+		this.decisions.restore(memory.decisions);
+		this.lastOrders.clear();
+		for (const order of memory.orders ?? []) this.lastOrders.set(order.unit, {
+			key: order.key,
+			tick: order.tick
+		});
+		if (memory.heard?.length) this.session.can.computer?.restoreEvents(memory.heard);
+		this.waiting = { ...memory.areas };
+		for (const area of [...this.areaList]) {
+			if (!(area.id in this.waiting)) continue;
+			const kept = this.waiting[area.id];
+			delete this.waiting[area.id];
+			if (!area.restore(kept)) this.log.info("ai", area.afresh ?? `the save remembers the computer player's ${area.id} in a shape this brain does not read: it starts afresh`);
+		}
+		const read = /* @__PURE__ */ new Set();
+		for (const module of this.modules) {
+			let kept = memory.modules?.[module.id];
+			if (kept) read.add(module.id);
+			else for (const was of module.wasCalled ?? []) {
+				kept = memory.modules?.[was];
+				if (!kept) continue;
+				read.add(was);
+				this.log.info("ai", `the module "${module.id}" reads what the save kept as "${was}"`, {
+					module: module.id,
+					was
+				});
+				break;
+			}
+			if (!kept) {
+				if (module.save) this.log.info("ai", `the save has nothing for the module "${module.id}": it starts afresh`, { module: module.id });
+				continue;
+			}
+			const version = module.version ?? 1;
+			let data = kept.data;
+			if (kept.v !== version) {
+				data = module.migrate?.(kept.data, kept.v);
+				if (data === void 0) {
+					this.log.info("ai", `the module "${module.id}" saved version ${kept.v} and reads ${version}: it starts afresh`, {
+						module: module.id,
+						from: kept.v
+					});
+					continue;
+				}
+			}
+			module.restore?.(data);
+		}
+		for (const id of Object.keys(memory.modules ?? {})) if (!this.module(id) && !read.has(id)) this.log.info("ai", `the save remembers a module "${id}" this brain does not have: dropped`, { module: id });
+	}
+	/** What it is thinking, for the debug tools: its report (`report`) */
+	inspect() {
+		return this.report();
+	}
+	/** Lets its modules go of what they hold outside the brain */
+	dispose() {
+		for (const module of this.modules) module.dispose?.();
+	}
+};
+/**
+* Makes a brain from its definition for a seat: the session it plays through, the options it is seated with. What
+* a brain's seat does (`createBrainSystem`); for a seat made another way (`createComputerSystem`'s `make`)
+*
+* @beta
+*/
+function createBrain(def, session, options, context = {}) {
+	return new Brain(def, session, options, context);
+}
+/** The threat map as the report has it: its cells with something in them, on the ground, what it remembers counted */
+function threatOf(map) {
+	const round = (x) => Math.round(x * 10) / 10;
+	return {
+		cell: map.cell,
+		cols: map.cols,
+		rows: map.rows,
+		cells: map.cells({ remembered: true }).map((cell) => [
+			cell.col,
+			cell.row,
+			round(cell.friendly),
+			round(cell.enemy)
+		])
+	};
+}
+//#endregion
+export { Brain, createBrain };
+
+//# sourceMappingURL=brain.js.map