@v12-engine/engine 0.1.0 → 0.4.0

package/dist/ai/squads.js

@@ -0,0 +1,916 @@
+import { distSq } from "../math.js";
+import { heroOfState } from "../hero.js";
+import { DEFAULT_STANCE, stance, stanceCommand } from "../stances.js";
+import { defineModule } from "./module.js";
+import "./reach.js";
+import { UnitSet } from "./view.js";
+import { pair, plural, point, where } from "./geometry.js";
+import { capturePointsOf } from "./tasks/shared.js";
+import { ATTACK } from "./tasks/attack.js";
+import { HARASS } from "./tasks/harass.js";
+import { CREEP } from "./tasks/creep.js";
+import { DEFEND_TASK } from "./tasks/defend.js";
+import { HOLD } from "./tasks/hold.js";
+import { MOVE } from "./tasks/move.js";
+import { CAPTURE } from "./tasks/capture.js";
+import { RETREAT } from "./tasks/retreat.js";
+import { ESCORT } from "./tasks/escort.js";
+import { SCOUT_TASK } from "./tasks/scout.js";
+import { PATROL } from "./tasks/patrol.js";
+import { GATHER } from "./tasks/gather.js";
+import { DROP } from "./tasks/drop.js";
+import { TASKS } from "./tasks/index.js";
+//#region src/ai/squads.ts
+/** Seconds a squad waits for its stragglers at most, regrouping, before it goes on with what it has */
+var REGROUP_FOR = 10;
+/** Seconds between two calls for reinforcements */
+var REINFORCE_EVERY = 5;
+/** How far aside of the hottest place on its way a squad that avoids looks for a way round, then half as far again */
+var DETOUR = 24;
+/** Seconds a sighting of their army counts as where it is, for a squad that avoids it */
+var AVOID_SEEN = 60;
+/**
+* A squad of the brain (`ai.squads.make`, `named`, `all`): a handle over its data, with the task methods. A squad's
+* units are as of the think's picture: the dead and those its owner no longer holds are dropped as the squads module
+* looks at it
+*
+* @beta
+*/
+var Squad = class {
+	squads;
+	data;
+	constructor(squads, data) {
+		this.squads = squads;
+		this.data = data;
+	}
+	/** Its name: unique among the brain's squads */
+	get name() {
+		return this.data.name;
+	}
+	/** Who it belongs to: the goal, rule or module that made it */
+	get owner() {
+		return this.data.owner;
+	}
+	/** What it is doing: none for a squad told nothing yet */
+	get current() {
+		return this.data.task;
+	}
+	/** How its task ended: none while it goes on, or while it has none */
+	get done() {
+		return this.data.task?.done;
+	}
+	/** Whether it has nothing to do: no task, or its task is over */
+	get idle() {
+		return !this.data.task || this.data.task.done !== void 0;
+	}
+	/** Whether it is still one of the brain's squads: not once disbanded */
+	get alive() {
+		return this.squads.named(this.data.name) === this;
+	}
+	/** How it behaves: its own options over the brain's */
+	get options() {
+		return this.data.options;
+	}
+	/** Its units, as of the think's picture: those alive and the player's */
+	units() {
+		const { view } = this.squads.ai;
+		return new UnitSet(view, this.data.units.map((id) => view.byId(id)).filter((unit) => !!unit && unit.health > 0));
+	}
+	/** How many units it has */
+	get length() {
+		return this.data.units.length;
+	}
+	/** How strong it is together (`UnitSet.strength`) */
+	strength() {
+		return this.units().strength();
+	}
+	/** Its middle: none with no unit left */
+	centre() {
+		return this.units().centre();
+	}
+	/**
+	* How far from its middle a unit may be before it counts as strayed (`SquadOptions.spread`): grows with the squad
+	* when not given
+	*/
+	spread() {
+		return this.data.options.spread ?? Math.max(8, 3 * Math.sqrt(this.data.units.length));
+	}
+	/** Adds units: what its owner may have (see `Squads.make`), taken out of any other squad */
+	add(units, why = "given") {
+		const added = this.squads.enlist(this, ids(units));
+		if (added.length) {
+			this.data.size = Math.max(this.data.size, this.data.units.length);
+			this.changed(`${why}: ${plural(added.length)}`);
+		}
+		return this;
+	}
+	/** Takes units out: they go back to the pool (its owner lets go of them) */
+	remove(units, why = "taken out") {
+		const gone = new Set(ids(units));
+		const removed = this.data.units.filter((id) => gone.has(id));
+		if (!removed.length) return this;
+		this.data.units = this.data.units.filter((id) => !gone.has(id));
+		this.squads.ai.goals.drop(this.data.owner, removed);
+		this.changed(`${why}: ${plural(removed.length)}`);
+		return this;
+	}
+	/** Disbands it: its units go back to its owner (a goal's), or to the pool (a squad of its own) */
+	disband(why = "disbanded") {
+		this.squads.disband(this, why);
+	}
+	/** Writes down the last change of its units or task, for the report */
+	changed(why) {
+		this.data.changed = {
+			tick: this.squads.ai.tick,
+			why
+		};
+	}
+	task(kind, data = {}) {
+		this.squads.give(this, kind, data);
+		return this;
+	}
+	/** Ends its task, saying how: what a task's `think` calls once it is over */
+	finish(done) {
+		const state = this.data.task;
+		if (!state || state.done !== void 0) return;
+		state.done = done;
+		state.doneAt = this.squads.ai.tick;
+		state.phase = "done";
+		state.phaseSince = this.squads.ai.tick;
+	}
+	/**
+	* Goes to fight at a place or a target (an entity, or its id): attack-moves there, fighting what it meets, regroups
+	* on the way, retreats on the odds. Done `cleared` once there with nothing left to fight, `lost` when the target is
+	* gone. `avoid: 'army'` goes round where their strength is on the way (the threat map and their army as last seen),
+	* when there is a way round. `via`: a place to go by on the way (a way of its own: Random Paths). `then`: the task after it
+	*/
+	attack(target, options = {}) {
+		return this.task(ATTACK, {
+			...targetOf(this.squads.ai, target),
+			...options
+		});
+	}
+	/** Attack-moves to a place, as a group of units would on a click: the squad's attack without its regroup */
+	attackMove(at, options = {}) {
+		return this.task(ATTACK, {
+			at: point(at),
+			regroup: false,
+			...options
+		});
+	}
+	/**
+	* Holds a place against what comes within `radius` of it (16 when left out): fights what comes, goes back once it is
+	* gone. Never over by itself: its owner says when
+	*/
+	defend(at, radius = 16) {
+		return this.task(DEFEND_TASK, {
+			at: point(at),
+			radius
+		});
+	}
+	/** Goes to a place (where it stands when left out) and holds it: stands, fighting only what comes within reach */
+	hold(at) {
+		const there = at ?? this.centre();
+		return this.task(HOLD, there ? { at: point(there) } : {});
+	}
+	/** Walks to a place, fighting nothing on the way. Done `arrived` */
+	move(at, options = {}) {
+		return this.task(MOVE, {
+			at: point(at),
+			...options
+		});
+	}
+	/** Goes with a unit of the player's or an ally's, fighting what comes near it. Done `lost` when it is gone */
+	escort(target) {
+		return this.task(ESCORT, { target: typeof target === "number" ? target : target.id });
+	}
+	/**
+	* Goes for the workers at a place, round where their army is (`avoid: 'army'` unless told otherwise), the workers
+	* first once there. Done `cleared`
+	*/
+	harass(at, options = {}) {
+		return this.task(HARASS, {
+			at: point(at),
+			avoid: "army",
+			...options
+		});
+	}
+	/** Goes to look at places, one after the other: each is looked at once in sight, or reached as near as the ground lets. Done `arrived` */
+	scout(points) {
+		return this.task(SCOUT_TASK, { points: points.map(point) });
+	}
+	/**
+	* Gathers at a rally point before going on (`then`): until `minForces` of it (a share, 1 when left out) is there,
+	* or `seconds` have gone by. Done `arrived`, and on to `then`
+	*/
+	gather(at, options = {}) {
+		return this.task(GATHER, {
+			at: point(at),
+			...options
+		});
+	}
+	/** Falls back to a place (home when left out), fighting nothing on the way. Done `retreated` */
+	retreat(to, why) {
+		const home = to ?? this.squads.ai.view.home();
+		return this.task(RETREAT, {
+			...home && { at: point(home) },
+			...why && { why }
+		});
+	}
+	/**
+	* Walks a round of places, one after the other and back to the first, fighting what it meets on the way (an
+	* attack-move to each): a mission's guards on the road, a watch round the walls. Never over by itself: its owner
+	* says when
+	*/
+	patrol(points) {
+		return this.task(PATROL, { points: points.map(point) });
+	}
+	/** Takes a camp of creeps: fights there until the camp is cleared. Done `cleared` */
+	creep(camp) {
+		return this.task(CREEP, { at: point(camp) });
+	}
+	/**
+	* Carried by transports to a place it cannot walk to, let out on the land nearest it (the `drop` task): done
+	* `landed`, then what `then` says (an attack where it landed)
+	*/
+	drop(at, transports, options = {}) {
+		return this.task(DROP, {
+			at: point(at),
+			transports: [...transports],
+			...options.then && { then: options.then }
+		});
+	}
+	/** Sends its units an order (`move`, `hold`, the game's), all or some of them: counted as the task's last */
+	order(order, units = this.data.units, queue = false) {
+		units = this.living(units);
+		if (!units.length) return;
+		this.squads.ai.send({
+			type: "order",
+			entities: [...units],
+			order,
+			...queue && { queue: true }
+		});
+		this.sent();
+	}
+	/**
+	* Puts its units, all or some, in a stance, where the game has stances (`stancesPack`): those not in it already. A
+	* squad that holds is defensive, one sent to fight aggressive
+	*/
+	setStance(id, units = this.data.units) {
+		if (!this.squads.ai.registry.command("stance")) return;
+		const change = [];
+		for (const unit of this.units()) {
+			if (!units.includes(unit.id)) continue;
+			if ((unit.components?.[stance.id] ?? "aggressive") !== id) change.push(unit.id);
+		}
+		if (change.length) this.squads.ai.send(stanceCommand.make({
+			entities: change,
+			stance: id
+		}));
+	}
+	/**
+	* Sends its units to take a capture point of the game's (`capturePack`), by its id: they fight their way in and
+	* stand in it until it is theirs (`captured`), or it is gone (`lost`)
+	*/
+	capture(id) {
+		const found = capturePointsOf(this.squads.ai).find((each) => each.id === id);
+		return this.task(CAPTURE, {
+			point: id,
+			...found && { at: point({
+				x: found.x,
+				z: found.z
+			}) }
+		});
+	}
+	/** Sends its units, all or some, to fight at a place, or a target there: an attack-move, or an attack */
+	fight(at, units = this.data.units, target, queue = false) {
+		units = this.living(units);
+		if (!units.length) return;
+		this.setStance(DEFAULT_STANCE, units);
+		this.squads.ai.send({
+			type: "attack",
+			entities: [...units],
+			point: point(at),
+			...target !== void 0 && { target },
+			...queue && { queue: true }
+		});
+		this.sent();
+	}
+	/**
+	* Of some of its units, those the picture has: a unit that died since the squads were last looked at (a task given by a
+	* goal before the `squads()` module ran) is no one to order
+	*/
+	living(units) {
+		const { mine } = this.squads.ai.view;
+		return units.every((id) => mine.has(id)) ? units : units.filter((id) => mine.has(id));
+	}
+	/** Its units that stand with nothing to do: what lost its order, or never had one */
+	idleUnits() {
+		return this.units().filter((unit) => !!unit.own && !unit.own.order && !unit.own.hidden);
+	}
+	/** Whether its last order was sent long enough ago to send one again (`RESEND` seconds): what keeps a stuck unit from being told every think */
+	mayResend() {
+		const state = this.data.task;
+		const { ai } = this.squads;
+		return !state || state.sent === void 0 || ai.tick - state.sent >= 3 * ai.session.tickRate;
+	}
+	sent() {
+		if (this.data.task) this.data.task.sent = this.squads.ai.tick;
+	}
+};
+/**
+* Some squads together (`ai.squads.all()`, `idle()`): read as a list, told as one (`ai.squads.all().defend(home)`:
+* each squad is given the task)
+*
+* @beta
+*/
+var SquadGroup = class {
+	ai;
+	squads;
+	constructor(ai, squads) {
+		this.ai = ai;
+		this.squads = squads;
+	}
+	/** Iterates the squads, so that the set reads as a list */
+	[Symbol.iterator]() {
+		return this.squads[Symbol.iterator]();
+	}
+	/** How many squads */
+	get length() {
+		return this.squads.length;
+	}
+	/** Their units together, as a set */
+	units() {
+		const { view } = this.ai;
+		const all = this.squads.flatMap((squad) => squad.units().items);
+		all.sort((a, b) => view.indexOf(a) - view.indexOf(b));
+		return new UnitSet(view, all);
+	}
+	/** How strong they are together */
+	strength() {
+		return this.units().strength();
+	}
+	task(kind, data = {}) {
+		for (const squad of this.squads) squad.squads.give(squad, kind, data);
+		return this;
+	}
+	/** Tells each squad to attack a point, an entity or an entity id, as `Squad.attack` does, and returns the set */
+	attack(target, options = {}) {
+		for (const squad of this.squads) squad.attack(target, options);
+		return this;
+	}
+	/** Tells each squad to defend a place within a radius as `Squad.defend` does; does nothing without a place; returns the set */
+	defend(at, radius) {
+		if (at) for (const squad of this.squads) squad.defend(at, radius);
+		return this;
+	}
+	/** Tells each squad to hold at a place, or where it is, as `Squad.hold` does, and returns the set */
+	hold(at) {
+		for (const squad of this.squads) squad.hold(at);
+		return this;
+	}
+	/** Tells each squad to move to a point as `Squad.move` does, and returns the set */
+	move(at) {
+		for (const squad of this.squads) squad.move(at);
+		return this;
+	}
+	/** Tells each squad to retreat to a point, or home when left out, as `Squad.retreat` does, and returns the set */
+	retreat(to) {
+		for (const squad of this.squads) squad.retreat(to);
+		return this;
+	}
+	/** Each disbanded */
+	disband(why) {
+		for (const squad of [...this.squads]) squad.disband(why);
+	}
+};
+/** The ids of units given as entities or ids, each once */
+function ids(units) {
+	const result = [];
+	for (const unit of units) {
+		const id = typeof unit === "number" ? unit : unit.id;
+		if (!result.includes(id)) result.push(id);
+	}
+	return result;
+}
+/** A target as an attack's data: a place, or an entity and where it is */
+function targetOf(ai, target) {
+	if (typeof target === "number") {
+		const entity = ai.view.byId(target);
+		return {
+			target,
+			...entity && { at: point(entity) }
+		};
+	}
+	if ("id" in target && typeof target.id === "number") return {
+		target: target.id,
+		at: point(target)
+	};
+	return { at: point(target) };
+}
+/**
+* A brain's squads (`ai.squads`): made by its goals, rules and modules, watched by the `squads()` module each think
+* (`think`): the dead dropped, what the owner let go of let go of, each task looked at, regroups, retreats and
+* reinforcements seen to. Kept in the brain's memory (`BrainMemory.squads`)
+*
+* @beta
+*/
+var Squads = class {
+	ai;
+	/** Its id among the brain's areas: what its memory and its report are kept under */
+	id = "squads";
+	/** What the log says where a save's memory of it is of a shape it does not read */
+	afresh = "the save remembers the computer player’s squads in a shape this brain does not read: they are let go of";
+	list = [];
+	tasks = /* @__PURE__ */ new Map();
+	thoughtAt = -1;
+	/** How a squad behaves where it says nothing and the brain's settings say nothing either: the `squads()` module's */
+	moduleOptions = {};
+	constructor(ai, tasks = []) {
+		this.ai = ai;
+		for (const def of TASKS) this.tasks.set(def.id, def);
+		for (const def of tasks) this.define(def);
+	}
+	/** Puts the `squads()` module's options under the brain's settings */
+	configure(options) {
+		this.moduleOptions = options;
+	}
+	/** How a squad behaves where it says nothing: the module's options, the brain's settings over them (`ai.settings.squads`) */
+	get defaults() {
+		const { tasks: _tasks, ...settings } = this.ai.settings.squads ?? {};
+		return {
+			...this.moduleOptions,
+			...settings
+		};
+	}
+	/** Registers a task of the game's own, so that a squad on it is carried on after a load. Given by `BrainDef.squads.tasks` */
+	define(def) {
+		const known = this.tasks.get(def.id);
+		if (known && known !== def && TASKS.includes(known)) throw new Error(`"${def.id}" is a task of the kit's: a task of the game's needs a name of its own`);
+		this.tasks.set(def.id, def);
+	}
+	/** A kind of task by its id: the kit's, or one registered */
+	taskDef(id) {
+		return this.tasks.get(id);
+	}
+	/**
+	* Makes a squad of units under a name (one of that name already is disbanded first), with how it behaves where it
+	* is not the brain's way. Whose it is (`owner`): what `options.owner` names (a goal makes its own with
+	* `claimed.squad`), else its own (`squad:<name>`). A goal's squad is made of what the goal holds, and what
+	* nothing holds is given to it; a squad of a rule or a module takes its units from whatever holds them (the goal
+	* told: `stop('told')`) and holds them until it is disbanded. A unit in another squad leaves it
+	*/
+	make(name, units, options = {}) {
+		if (!name) throw new Error("A squad needs a name");
+		const { ai } = this;
+		const { owner: named, ...own } = options;
+		const owner = named ?? `squad:${name}`;
+		const old = this.named(name);
+		if (old) this.disband(old, "made anew", old.owner !== owner);
+		const behaves = {
+			...this.defaults,
+			...own
+		};
+		const squad = new Squad(this, {
+			name,
+			owner,
+			units: [],
+			options: behaves,
+			size: 0,
+			made: ai.tick,
+			retreats: 0
+		});
+		this.list.push(squad);
+		this.enlist(squad, ids(units));
+		squad.data.size = squad.data.units.length;
+		squad.changed(`made by ${owner === `squad:${name}` ? "itself" : owner}: ${plural(squad.data.units.length)}`);
+		return squad;
+	}
+	/**
+	* Puts units in a squad: those its owner may have (held by it, or given from the pool for a goal; taken for a rule's
+	* or a module's), out of any other squad. Those put in, by id
+	*/
+	enlist(squad, wanted) {
+		const { goals, view, session, tick } = this.ai;
+		const owner = squad.data.owner;
+		const units = wanted.filter((id) => view.mine.has(id) && !squad.data.units.includes(id));
+		if (!units.length) return [];
+		let put;
+		if (goals.get(owner)) {
+			goals.give(owner, units);
+			put = units.filter((id) => goals.holder(id) === owner);
+		} else {
+			const hold = goals.held(owner);
+			const seconds = !hold || hold.kept ? Infinity : Math.max(1, (hold.until - tick) / session.tickRate);
+			goals.take(units, "told", {
+				id: owner,
+				seconds
+			});
+			put = units.filter((id) => goals.held(owner)?.units.includes(id));
+		}
+		if (!put.length) return put;
+		for (const other of [...this.list]) {
+			if (other === squad || !other.data.units.some((id) => put.includes(id))) continue;
+			other.data.units = other.data.units.filter((id) => !put.includes(id));
+			other.changed(`${plural(put.length)} went to ${squad.name}`);
+			if (!other.data.units.length) this.disband(other, `its units went to ${squad.name}`);
+		}
+		squad.data.units = squad.data.units.filter((id) => view.mine.has(id));
+		squad.data.units.push(...put);
+		squad.data.units.sort((a, b) => view.indexOf(view.byId(a)) - view.indexOf(view.byId(b)));
+		return put;
+	}
+	/** A squad by name: none for one there is not */
+	named(name) {
+		return this.list.find((squad) => squad.data.name === name);
+	}
+	/** Every squad, as made */
+	all() {
+		return new SquadGroup(this.ai, this.list);
+	}
+	/** The squads with nothing to do: told nothing, or their task over */
+	idle() {
+		return new SquadGroup(this.ai, this.list.filter((squad) => squad.idle));
+	}
+	/** The squads a goal, rule or module owns */
+	of(owner) {
+		return new SquadGroup(this.ai, this.list.filter((squad) => squad.data.owner === owner));
+	}
+	/** The squad a unit is in, by the unit or its id: none for a unit in none */
+	squadOf(unit) {
+		const id = typeof unit === "number" ? unit : unit.id;
+		return this.list.find((squad) => squad.data.units.includes(id));
+	}
+	/** The player's units nothing holds (`ai.goals.pool`, buildings left out): what a squad is made of, or reinforced from */
+	pool() {
+		return this.ai.goals.pool().units();
+	}
+	/** Disbands a squad: a squad that held its units itself lets them go back to the pool */
+	disband(squad, why = "disbanded", letGo = true) {
+		const index = this.list.indexOf(squad);
+		if (index < 0) return;
+		this.list.splice(index, 1);
+		const { goals } = this.ai;
+		if (letGo && !goals.get(squad.data.owner) && goals.held(squad.data.owner)) {
+			const others = new Set(this.list.filter((other) => other.data.owner === squad.data.owner).flatMap((other) => other.data.units));
+			goals.drop(squad.data.owner, squad.data.units.filter((id) => !others.has(id)));
+		}
+		if (squad.data.units.length || why !== "made anew") this.ai.decide(`squad ${squad.name} disbanded: ${why}`, { kind: "squad" });
+	}
+	/**
+	* Gives a squad a task: what it was doing is over, and the new one's first orders go at once. What it has now is what
+	* reinforcements make up to from then on (`SquadData.size`), but for a task it goes on to by itself (`going on`: a
+	* task's `then`, a fall back on the odds), which keeps what the task before was given. The task it is on given
+	* again changes nothing, its `size` kept: what it lost since is what reinforcements make up
+	*/
+	give(squad, kind, data, goingOn = false) {
+		const { ai } = this;
+		const def = typeof kind === "string" ? this.tasks.get(kind) : kind;
+		if (!def) throw new Error(`The squad "${squad.name}" was given a task "${String(kind)}" the brain does not know: list it in its squads' tasks (defineTask)`);
+		if (typeof kind !== "string" && !this.tasks.has(def.id)) this.define(def);
+		const before = squad.data.task;
+		if (before && before.done === void 0 && before.kind === def.id && sameData(before.data, data)) return;
+		const state = {
+			kind: def.id,
+			data: { ...data },
+			since: ai.tick,
+			phase: "starting",
+			phaseSince: ai.tick,
+			memory: {}
+		};
+		squad.data.task = state;
+		if (!goingOn) squad.data.size = squad.data.units.length;
+		squad.changed(before && before.done === void 0 ? `${before.kind} → ${def.id}` : `on to ${def.id}`);
+		if (squad.data.units.length) def.start(ai, squad, state);
+	}
+	/**
+	* Looks at every squad, once a think: its units (the dead, and what its owner let go of, dropped; a squad of a goal
+	* that stopped disbanded), then its task (retreat on the odds, the task's own look, regroup, reinforcements). What the
+	* `squads()` module runs; a module may call it sooner
+	*/
+	think() {
+		const { ai } = this;
+		if (this.thoughtAt !== ai.tick) {
+			this.thoughtAt = ai.tick;
+			this.prune();
+			this.advancing = [...this.list];
+			this.cursor = 0;
+		} else if (!this.advancing) return;
+		const squads = this.advancing;
+		for (; this.cursor < squads.length; this.cursor++) {
+			const squad = squads[this.cursor];
+			this.advance(squad);
+			if (!ai.budget.spent(squad.data.units.length || 1) && this.cursor + 1 < squads.length) {
+				this.cursor++;
+				return ai.budget.later();
+			}
+		}
+		this.advancing = void 0;
+	}
+	/** The squads still to be looked at this think, where a pass stopped for the tick's budget, and the next of them */
+	advancing;
+	cursor = 0;
+	/** Every squad's units looked at, as a think begins: the dead and what its owner let go of dropped, a squad with none left disbanded */
+	prune() {
+		const { ai } = this;
+		const { goals, view } = ai;
+		for (const squad of [...this.list]) {
+			const hold = goals.held(squad.data.owner);
+			if (!hold) {
+				this.disband(squad, `${squad.data.owner} let go`, false);
+				continue;
+			}
+			if (!goals.get(squad.data.owner) && hold.units.some((id) => !view.mine.has(id))) hold.units = hold.units.filter((id) => view.mine.has(id));
+			const kept = squad.data.units.filter((id) => hold.units.includes(id) && view.mine.has(id) && view.byId(id).health > 0);
+			if (kept.length !== squad.data.units.length) squad.data.units = kept;
+			if (!kept.length) {
+				squad.finish("wiped");
+				this.disband(squad, "none of its units left", false);
+			}
+		}
+	}
+	/** One squad's think: retreat on the odds, the task's own look, then on to the next task, regroup, reinforcements */
+	advance(squad) {
+		const { ai } = this;
+		const state = squad.data.task;
+		const def = state && this.tasks.get(state.kind);
+		const handles = def?.handles ?? [];
+		if (state && def && state.done === void 0) {
+			if (!handles.includes("retreat") && this.losing(squad)) return;
+			const over = def.done?.(ai, squad, state);
+			if (over) squad.finish(over);
+			else def.think(ai, squad, state);
+			if (state.done === void 0 && !handles.includes("regroup") && state.data.regroup !== false) this.regroup(squad, state, def);
+			const then = state.data.then;
+			if (state.done !== void 0 && state.done !== "lost" && state.done !== "wiped" && then?.kind && this.tasks.has(then.kind)) this.give(squad, then.kind, then.data ?? {}, true);
+		}
+		if (squad.data.options.reinforce && !handles.includes("reinforce")) this.reinforce(squad);
+	}
+	/**
+	* Whether a squad in a fight away from home is losing it (its odds under `retreatAt`), and so falls back: its task
+	* becomes `retreat`, home, and it is said why
+	*/
+	losing(squad) {
+		const { ai } = this;
+		const { view } = ai;
+		const at = squad.data.options.retreatAt ?? .3;
+		if (at === false || !(at > 0)) return false;
+		const units = squad.units();
+		const middle = units.centre();
+		const home = view.home();
+		if (!middle || !home) return false;
+		const safe = squad.data.options.home ?? 20;
+		if (distSq(middle, home) < safe * safe) return false;
+		const foes = view.hostile.units().alive().near(middle, 14);
+		if (!foes.length || !foes.some((foe) => units.some((unit) => distSq(unit, foe) <= 64))) return false;
+		const odds = view.strength.odds(units.near(middle, 14), foes);
+		if (odds >= at) return false;
+		const was = squad.data.task?.kind ?? "nothing";
+		squad.data.retreats++;
+		this.give(squad, "retreat", {
+			at: point(home),
+			why: "odds"
+		}, true);
+		ai.decide(`squad ${squad.name} falls back home with ${plural(units.length)}: ${was} lost (odds ${odds.toFixed(2)} under ${at})`, { kind: "squad" });
+		return true;
+	}
+	/**
+	* Regroups a squad that is strung out on its way: too many of its units (`regroupWhen`) further than `spread` from its
+	* middle, and no fight near. It gathers on its middle and goes on once together, or once it has waited long enough
+	*/
+	regroup(squad, state, def) {
+		const { ai } = this;
+		const units = squad.units();
+		if (units.length < 3) return;
+		const middle = units.centre();
+		const spread = squad.spread();
+		if (state.phase === "regrouping") {
+			const together = units.every((unit) => distSq(unit, middle) <= spread * spread * .36);
+			if (together || ai.tick - state.phaseSince >= REGROUP_FOR * ai.session.tickRate) {
+				def.start(ai, squad, state);
+				ai.decide(`squad ${squad.name} regrouped${together ? "" : " as much as it waits for"}: on with ${state.kind}`, { kind: "squad" });
+			}
+			return;
+		}
+		if (state.phase !== "going") return;
+		const when = squad.data.options.regroupWhen ?? .4;
+		if (when === false) return;
+		const strayed = units.filter((unit) => distSq(unit, middle) > spread * spread).length;
+		if (strayed <= units.length * when) return;
+		if (ai.view.hostile.alive().near(middle, 14).length) return;
+		state.phase = "regrouping";
+		state.phaseSince = ai.tick;
+		squad.order({
+			type: "move",
+			point: point(middle)
+		});
+		ai.decide(`squad ${squad.name} regroups at ${where(middle)}: ${strayed} of ${units.length} strung out`, { kind: "squad" });
+	}
+	/**
+	* Makes up what a squad lost since its task began from the pool: the idle fighters nothing holds, the nearest
+	* first, given to its owner and sent to join it. Never a hero: one crossing the map alone to a fight dies on the
+	* way, and heroes are sent with a squad, not after it. Not while it falls back, nor more often than every few seconds
+	*/
+	reinforce(squad) {
+		const { ai } = this;
+		const { data } = squad;
+		const missing = data.size - data.units.length;
+		if (missing <= 0 || data.task?.kind === "retreat" && data.task.done === void 0) return;
+		if (data.nextReinforce !== void 0 && ai.tick < data.nextReinforce) return;
+		data.nextReinforce = ai.tick + REINFORCE_EVERY * ai.session.tickRate;
+		const join = squad.centre() ?? this.whereOf(squad) ?? ai.view.home();
+		if (!join) return;
+		const { strength } = ai.view;
+		const chosen = [...this.pool().fighters().idle()].filter((unit) => !heroOfState(unit) && unit.health >= WOUNDED * (unit.maxHealth ?? strength.statsOf(unit).health)).sort((a, b) => distSq(a, join) - distSq(b, join) || a.id - b.id).slice(0, missing).map((unit) => unit.id);
+		if (!chosen.length) return;
+		const size = data.size;
+		squad.add(chosen, "reinforced");
+		data.size = size;
+		const added = chosen.filter((id) => data.units.includes(id));
+		if (!added.length) return;
+		ai.send({
+			type: "attack",
+			entities: added,
+			point: point(join)
+		});
+		ai.decide(`squad ${squad.name} reinforced with ${plural(added.length)}`, { kind: "squad" });
+	}
+	/** The place a squad's task is about: none for a task about no place */
+	whereOf(squad) {
+		const state = squad.data.task;
+		const def = state && this.tasks.get(state.kind);
+		return state && def?.where?.(this.ai, squad, state);
+	}
+	/**
+	* The way to a place round where the enemy is strong (`avoid: 'army'`): the waypoint to go by, where the straight way
+	* crosses their strength (the threat map, with what is remembered of their towers, and their army as last seen) and a
+	* way round is less hot, tried on either side and then further out, twice at most. A heuristic, not a safe route:
+	* none where the straight way is cool enough, or where there is no way round (`note` says so)
+	*/
+	route(from, to, squad) {
+		const { ai } = this;
+		const { view } = ai;
+		const units = squad.units();
+		const flying = units.length > 0 && units.every((unit) => !!view.def(unit).flying);
+		const layer = flying ? "air" : "ground";
+		const seen = ai.def.knowledge === false ? [] : ai.knowledge.enemy.armySeen(AVOID_SEEN);
+		const danger = (at) => {
+			let enemy = view.threat.at(at, {
+				layer,
+				remembered: true
+			}).enemy;
+			for (const army of seen) if (distSq(army.at, at) < 144) enemy += army.strength;
+			return enemy;
+		};
+		const hottest = (path) => {
+			let worst = {
+				at: path[0] ?? from,
+				enemy: 0
+			};
+			for (let i = 1; i < path.length; i++) {
+				const a = path[i - 1];
+				const b = path[i];
+				const steps = Math.max(1, Math.ceil(Math.sqrt(distSq(a, b)) / 6));
+				for (let s = 1; s <= steps; s++) {
+					const at = {
+						x: a.x + (b.x - a.x) * s / steps,
+						z: a.z + (b.z - a.z) * s / steps
+					};
+					const enemy = danger(at);
+					if (enemy > worst.enemy) worst = {
+						at,
+						enemy
+					};
+				}
+			}
+			return worst;
+		};
+		const worst = hottest([from, ...view.findPath(from, to, flying) ?? [from, to]]);
+		const bearable = Math.max(1e-9, units.strength() * .5);
+		if (worst.enemy <= bearable) return { waypoints: [] };
+		const { width, depth } = view.session.terrain;
+		const dx = to.x - from.x;
+		const dz = to.z - from.z;
+		const length = Math.sqrt(dx * dx + dz * dz) || 1;
+		const aside = {
+			x: -dz / length,
+			z: dx / length
+		};
+		let best;
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const far = DETOUR * (1 + attempt / 2);
+			for (const side of [1, -1]) {
+				const at = {
+					x: Math.min(width - 1, Math.max(1, worst.at.x + aside.x * far * side)),
+					z: Math.min(depth - 1, Math.max(1, worst.at.z + aside.z * far * side))
+				};
+				const there = view.findPath(from, at, flying);
+				const on = there && view.findPath(at, to, flying);
+				if (!there || !on) continue;
+				const enemy = Math.max(hottest([from, ...there]).enemy, hottest([at, ...on]).enemy);
+				if (!best || enemy < best.enemy) best = {
+					at,
+					enemy
+				};
+			}
+			if (best && best.enemy <= bearable) return {
+				waypoints: [point(best.at)],
+				note: `round ${where(worst.at)} by ${where(best.at)}`
+			};
+		}
+		if (best && best.enemy < worst.enemy) return {
+			waypoints: [point(best.at)],
+			note: `no way round ${where(worst.at)} that is safe: by ${where(best.at)}, the least hot`
+		};
+		return {
+			waypoints: [],
+			note: `no way round ${where(worst.at)}: straight`
+		};
+	}
+	/** Every squad as the report shows it */
+	report() {
+		return this.list.map((squad) => {
+			const { data } = squad;
+			const units = squad.units();
+			const middle = units.centre();
+			const state = data.task;
+			const at = this.whereOf(squad);
+			return {
+				name: data.name,
+				owner: data.owner,
+				units: [...data.units],
+				strength: units.strength(),
+				...middle && { at: pair(middle) },
+				size: data.size,
+				...state && { task: {
+					kind: state.kind,
+					phase: state.phase,
+					since: state.since,
+					...at && { at: pair(at) },
+					...state.done !== void 0 && { done: state.done }
+				} },
+				retreats: data.retreats,
+				...data.changed && { changed: { ...data.changed } }
+			};
+		});
+	}
+	/** What the squads are, for a save: copies */
+	/** Whether it has anything to remember now: one that does not is left out of a save */
+	remembers() {
+		return this.all().length > 0;
+	}
+	/** Gives the squads' data as plain data for a save of the brain */
+	save() {
+		return {
+			v: 1,
+			squads: this.list.map((squad) => structuredClone(squad.data))
+		};
+	}
+	/** Takes back what `save` gave: whether it was read. A squad on a task the brain does not know is kept, and does nothing */
+	restore(memory) {
+		const given = memory;
+		if (!given || typeof given !== "object" || given.v !== 1 || !Array.isArray(given.squads)) return false;
+		this.list = given.squads.filter((data) => data && typeof data.name === "string" && Array.isArray(data.units)).map((data) => new Squad(this, structuredClone(data)));
+		for (const squad of this.list) {
+			const kind = squad.data.task?.kind;
+			if (kind && !this.tasks.has(kind)) this.ai.log.info("ai", `the squad "${squad.name}" is on a task "${kind}" this brain does not know: it waits`, { squad: squad.name });
+		}
+		return true;
+	}
+};
+/** The share of its health under which a unit is not sent as a reinforcement */
+var WOUNDED = .5;
+/** Whether two tasks' data say the same: plain data, field by field */
+function sameData(a, b) {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	const keys = Object.keys(a).filter((key) => a[key] !== void 0);
+	const others = Object.keys(b).filter((key) => b[key] !== void 0);
+	return keys.length === others.length && keys.every((key) => sameData(a[key], b[key]));
+}
+/**
+* The squads module: looks at every squad of the brain each think (`ai.squads.think`), after the goals, the rules and
+* the words that make them: their units, their tasks, regroups, retreats, reinforcements. With how they behave where the
+* brain's definition and the seat's options say nothing
+*
+* @beta
+*/
+var squads = (options = {}) => defineModule({
+	id: "squads",
+	make: (ai) => {
+		for (const def of options.tasks ?? []) ai.squads.define(def);
+		const { tasks: _tasks, ...defaults } = options;
+		ai.squads.configure(defaults);
+		return {
+			id: "squads",
+			phase: "act",
+			after: ["goals"],
+			think: () => ai.squads.think()
+		};
+	}
+});
+//#endregion
+export { Squad, SquadGroup, Squads, squads };
+
+//# sourceMappingURL=squads.js.map