@v12-engine/engine 0.1.0 → 0.4.0

package/dist/formation.js

@@ -0,0 +1,297 @@
+import { cos, hypot, sin } from "./exactMath.js";
+//#region src/formation.ts
+var GAP = .35;
+/**
+* The gap between two units standing next to each other in a formation
+*
+* @beta
+*/
+var FORMATION_GAP = GAP;
+/** The places of a shape in the world, each snapped onto where a unit can stand */
+function placed(context, shape) {
+	return shape.map(({ x, z }) => context.snap(context.place(x, z)));
+}
+/**
+* Fits units to places so that their ways cross as little as can be: the places in order, the front first, each to
+* the unit nearest it, measured from where the group is to where it goes (the unit's place in the group against the
+* place's in the formation). A unit left without a place goes to the target
+*
+* @beta
+*/
+function fitToPlaces(context, places) {
+	const { units, centre, target } = context;
+	const points = /* @__PURE__ */ new Map();
+	const left = [...units].sort((a, b) => a.id - b.id);
+	for (const place of places) {
+		if (left.length === 0) break;
+		const px = place.x - target.x;
+		const pz = place.z - target.z;
+		let nearest = 0;
+		let best = Infinity;
+		for (let i = 0; i < left.length; i++) {
+			const unit = left[i];
+			const d = hypot(unit.pos.x - centre.x - px, unit.pos.z - centre.z - pz);
+			if (d < best) {
+				best = d;
+				nearest = i;
+			}
+		}
+		points.set(left[nearest].id, place);
+		left.splice(nearest, 1);
+	}
+	for (const unit of left) points.set(unit.id, target);
+	return points;
+}
+/**
+* The engine's usual formation: a tight group keeps its shape as it is, and a scattered one lines up in rows across
+* the way of travel, as many across as there are rows, the units ahead in the front rows
+*
+* @beta
+*/
+var rowsFormation = {
+	id: "rows",
+	name: "Rows",
+	points(context) {
+		const { units, target, centre, spacing, forward, right, snap } = context;
+		const points = /* @__PURE__ */ new Map();
+		let spread = 0;
+		for (const unit of units) spread = Math.max(spread, hypot(unit.pos.x - centre.x, unit.pos.z - centre.z));
+		const travel = hypot(target.x - centre.x, target.z - centre.z);
+		const compact = spacing * Math.sqrt(units.length);
+		if (spread <= compact && travel > spread && !context.turned) {
+			for (const unit of units) points.set(unit.id, snap({
+				x: target.x + unit.pos.x - centre.x,
+				z: target.z + unit.pos.z - centre.z
+			}));
+			return points;
+		}
+		const columns = Math.ceil(Math.sqrt(units.length));
+		const rows = Math.ceil(units.length / columns);
+		const ahead = (u) => (u.pos.x - centre.x) * forward.x + (u.pos.z - centre.z) * forward.z;
+		const sideways = (u) => (u.pos.x - centre.x) * right.x + (u.pos.z - centre.z) * right.z;
+		const ordered = [...units].sort((a, b) => ahead(b) - ahead(a) || a.id - b.id);
+		for (let row = 0; row < rows; row++) {
+			const members = ordered.slice(row * columns, (row + 1) * columns).sort((a, b) => sideways(a) - sideways(b) || a.id - b.id);
+			const back = (row - (rows - 1) / 2) * spacing;
+			for (let i = 0; i < members.length; i++) {
+				const side = (i - (members.length - 1) / 2) * spacing;
+				points.set(members[i].id, snap(context.place(side, -back)));
+			}
+		}
+		return points;
+	}
+};
+/** How many places a ring of a radius has room for, `spacing` apart */
+var ringRoom = (radius, spacing) => Math.max(Math.floor(2 * Math.PI * radius / spacing), 1);
+/**
+* How many places each ring of a disc gets, the middle first (one), then the rings a `spacing` apart: as few rings as
+* hold them all, and the places shared out among the rings as their room goes, so that the disc is as thick
+* everywhere, filled to the middle, rather than full outer rings round a hollow. The places left over by the share go
+* to the biggest remainders, the outer ring of two first. A few that the outer ring holds alone (up to 12) stand on it
+*/
+function ringCounts(count, spacing) {
+	const room = [1];
+	let held = 1;
+	while (held < count) {
+		const on = ringRoom(room.length * spacing, spacing);
+		room.push(on);
+		held += on;
+	}
+	if (count <= room[room.length - 1]) return room.map((_, i) => i === room.length - 1 ? count : 0);
+	const counts = room.map((on) => Math.floor(count * on / held));
+	let left = count - counts.reduce((sum, on) => sum + on, 0);
+	const order = room.map((_, i) => i).sort((a, b) => count * room[b] % held - count * room[a] % held || b - a);
+	for (const i of order) {
+		if (left === 0) break;
+		if (counts[i] < room[i]) {
+			counts[i]++;
+			left--;
+		}
+	}
+	return counts;
+}
+/** The places of a ring, evenly, the first at the front, clockwise */
+function circleRing(radius, on) {
+	const places = [];
+	for (let i = 0; i < on; i++) {
+		const angle = i / on * 2 * Math.PI;
+		places.push({
+			x: radius * sin(angle),
+			z: radius * cos(angle)
+		});
+	}
+	return places;
+}
+/**
+* A circle: a ring around the target, the first place at the front, and rings within it where one is not enough for
+* them all, a `spacing` apart, down to the middle. As few rings as hold them, and the units shared out among them as
+* their room goes: a disc as thick everywhere, every ring's places even, the outer ring first
+*
+* @beta
+*/
+var circleFormation = {
+	id: "circle",
+	name: "Circle",
+	shape(count, spacing) {
+		const counts = ringCounts(count, spacing);
+		const places = [];
+		for (let i = counts.length - 1; i >= 1; i--) places.push(...circleRing(i * spacing, counts[i]));
+		if (counts[0] > 0) places.push({
+			x: 0,
+			z: 0
+		});
+		return places;
+	}
+};
+/**
+* A square: a block of rows a `spacing` apart, as many across as deep (one row fewer where that holds them), filled to
+* the middle, the front row first. Where they do not fill the last row, the back one, those in it stand in its middle
+*
+* @beta
+*/
+var squareFormation = {
+	id: "square",
+	name: "Square",
+	shape(count, spacing) {
+		const across = Math.ceil(Math.sqrt(count));
+		const deep = Math.ceil(count / across);
+		const places = [];
+		for (let row = 0; row < deep; row++) {
+			const on = Math.min(across, count - row * across);
+			const z = ((deep - 1) / 2 - row) * spacing;
+			for (let i = 0; i < on; i++) places.push({
+				x: (i - (on - 1) / 2) * spacing,
+				z
+			});
+		}
+		return places;
+	}
+};
+/**
+* No formation: every unit to the point itself, as units sent one by one go
+*
+* @beta
+*/
+var noneFormation = {
+	id: "none",
+	name: "None",
+	shape: (count) => Array.from({ length: count }, () => ({
+		x: 0,
+		z: 0
+	}))
+};
+/**
+* The engine's formations: `rows` (the usual), `circle`, `square` and `none`
+*
+* @beta
+*/
+var coreFormations = [
+	rowsFormation,
+	circleFormation,
+	squareFormation,
+	noneFormation
+];
+/**
+* What a formation is laid out with, for a group sent to a target on a navigation
+*
+* @internal
+*/
+function formationContext(world, units, target, nav, facing) {
+	let cx = 0;
+	let cz = 0;
+	let radius = 0;
+	for (const unit of units) {
+		cx += unit.pos.x;
+		cz += unit.pos.z;
+		radius = Math.max(radius, unit.def.radius);
+	}
+	cx /= units.length;
+	cz /= units.length;
+	const travel = hypot(target.x - cx, target.z - cz);
+	const forward = facing !== void 0 ? {
+		x: sin(facing),
+		z: cos(facing)
+	} : {
+		x: travel > .001 ? (target.x - cx) / travel : 0,
+		z: travel > .001 ? (target.z - cz) / travel : 1
+	};
+	const right = {
+		x: forward.z,
+		z: -forward.x
+	};
+	return {
+		world,
+		units,
+		target,
+		nav,
+		centre: {
+			x: cx,
+			z: cz
+		},
+		forward,
+		right,
+		turned: facing !== void 0,
+		spacing: radius * 2 + GAP,
+		place: (x, z) => ({
+			x: target.x + right.x * x + forward.x * z,
+			z: target.z + right.z * x + forward.z * z
+		}),
+		snap: (p) => nav.closestPoint(p, 4) ?? target
+	};
+}
+/**
+* Individual destinations for a group ordered to the same point, in a formation (`rowsFormation` when none is
+* given), and what the `formation` hook makes of them. Units that walk and units that fly are laid out apart, each
+* on their own navigation (`world.navFor`). `facing`, where the player turned the formation by hand, is the way it
+* faces (a direction as an entity's `facing` is), over the way of travel
+*
+* @beta
+*/
+function formationPoints(world, units, target, formation = rowsFormation, facing) {
+	if (units.length === 0) return /* @__PURE__ */ new Map();
+	const context = formationContext(world, units, target, world.navFor(units[0]), facing);
+	let points;
+	if (units.length === 1) points = /* @__PURE__ */ new Map([[units[0].id, target]]);
+	else if (formation.points) points = formation.points(context);
+	else if (formation.shape) points = fitToPlaces(context, placed(context, formation.shape(units.length, context.spacing, context)));
+	else throw new Error(`The formation "${formation.id}" has neither a shape nor points`);
+	if (world.hooks.has("formation")) world.hooks.run("formation", {
+		units,
+		target,
+		formation,
+		points
+	});
+	return points;
+}
+/**
+* Where a group would stand if sent to a target in a formation (by id, `rows` when unknown), from what a player's
+* screen knows of the units: what the ghosts of a right-click dragged are drawn from (`GameSession.formationPlaces`).
+* The same shapes as `formationPoints` gives, units that walk and units that fly each on their own navigation; the
+* `formation` hook (the simulation's) and a formation that reads `FormationContext.world` take no part, and the order
+* itself lays the group out as it will
+*
+* @beta
+*/
+function formationPreview(registry, units, target, navs, id, facing) {
+	const formation = registry.formations.has(id) ? registry.formation(id) : rowsFormation;
+	const places = /* @__PURE__ */ new Map();
+	for (const flying of [false, true]) {
+		const group = units.filter((unit) => !!unit.flying === flying);
+		if (group.length === 0) continue;
+		if (group.length === 1) places.set(group[0].id, target);
+		else {
+			const context = formationContext(void 0, group.map((unit) => ({
+				id: unit.id,
+				pos: unit.pos,
+				def: { radius: unit.radius }
+			})), target, flying ? navs.air : navs.nav, facing);
+			const found = formation.points ? formation.points(context) : fitToPlaces(context, placed(context, formation.shape(group.length, context.spacing, context)));
+			for (const [unit, place] of found) places.set(unit, place);
+		}
+	}
+	return places;
+}
+//#endregion
+export { FORMATION_GAP, circleFormation, coreFormations, fitToPlaces, formationContext, formationPoints, formationPreview, noneFormation, rowsFormation, squareFormation };
+
+//# sourceMappingURL=formation.js.map

package/dist/formation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formation.js","names":[],"sources":["../src/formation.ts"],"sourcesContent":["import type { Entity, EntityId } from './entity'\nimport type { Vec2 } from './math'\nimport type { Navigation } from './navigation/navigation'\nimport type { Registry } from './registry'\nimport type { World } from './world'\nimport { cos, hypot, sin } from './exactMath'\n\nconst GAP = 0.35\n\n/**\n * What a formation lays units out with: the group, where it is sent, the way there, and the room each unit takes.\n * Points are in the world; `right` and `forward` are the formation's own axes, each a unit long, for a shape that is\n * drawn facing the way of travel: a place `right * x + forward * z` from the target\n *\n * @beta\n */\nexport interface FormationContext {\n\t/** The world the formation is laid out in */\n\treadonly world: World\n\t/** The units laid out: those that walk, or those that fly, apart */\n\treadonly units: readonly Entity[]\n\t/** Where the units are sent */\n\treadonly target: Vec2\n\t/** The navigation they go on, to find where they can stand */\n\treadonly nav: Navigation\n\t/** The middle of where the units are */\n\treadonly centre: Vec2\n\t/** The way from where they are to the target, a unit long (forward, where they face at the end) */\n\treadonly forward: Vec2\n\t/** To the right of `forward`, a unit long */\n\treadonly right: Vec2\n\t/**\n\t * Whether the player turned the formation by hand (a right-click dragged: `OrderInit.facing`): `forward` is then\n\t * the way they dragged, not the way of travel, and a formation that keeps a group's own shape lays it out anew\n\t */\n\treadonly turned: boolean\n\t/** Room a unit takes: twice the biggest radius among them, and a gap of `FORMATION_GAP` */\n\treadonly spacing: number\n\t/** A point in the world, `x` to the right of the target and `z` forward of it */\n\tplace(x: number, z: number): Vec2\n\t/** The nearest point a unit can stand on, or the target where there is none within 4 */\n\tsnap(point: Vec2): Vec2\n}\n\n/**\n * How units ordered to a point together are laid out around it (`OrderInit.formation`, `RuleSettings.movement.formation`): a\n * shape, which the engine fits the units to, or the places themselves. The engine's own are `rows`, `circle`,\n * `square` and `none` (`coreFormations`); a game adds its own (`Rules.formations`), and changes any laid out\n * with the `formation` hook\n *\n * @beta\n */\nexport interface FormationDef {\n\t/** The formation's id, which an order names it by */\n\tid: string\n\t/** What the player sees it called */\n\tname: string\n\t/**\n\t * The shape, as `count` places `spacing` apart, in the formation's own space: `x` to the right, `z` forward, the\n\t * first places at the front. Units are fitted to them so that their ways cross as little as can be\n\t * (`fitToPlaces`): those ahead to the places at the front\n\t */\n\tshape?(count: number, spacing: number, context: FormationContext): Vec2[]\n\t/**\n\t * The places themselves, by the unit's id, when the shape is not enough: one that goes by who the units are, or\n\t * where they stand. A unit given none goes to the target itself. Over `shape` where both are given\n\t */\n\tpoints?(context: FormationContext): Map<EntityId, Vec2>\n}\n\n/**\n * The gap between two units standing next to each other in a formation\n *\n * @beta\n */\nexport const FORMATION_GAP = GAP\n\n/** The places of a shape in the world, each snapped onto where a unit can stand */\nfunction placed(context: FormationContext, shape: readonly Vec2[]): Vec2[] {\n\treturn shape.map(({ x, z }) => context.snap(context.place(x, z)))\n}\n\n/**\n * Fits units to places so that their ways cross as little as can be: the places in order, the front first, each to\n * the unit nearest it, measured from where the group is to where it goes (the unit's place in the group against the\n * place's in the formation). A unit left without a place goes to the target\n *\n * @beta\n */\nexport function fitToPlaces(context: FormationContext, places: readonly Vec2[]): Map<EntityId, Vec2> {\n\tconst { units, centre, target } = context\n\tconst points = new Map<EntityId, Vec2>()\n\tconst left = [...units].sort((a, b) => a.id - b.id)\n\tfor (const place of places) {\n\t\tif (left.length === 0) break\n\t\tconst px = place.x - target.x\n\t\tconst pz = place.z - target.z\n\t\tlet nearest = 0\n\t\tlet best = Infinity\n\t\tfor (let i = 0; i < left.length; i++) {\n\t\t\tconst unit = left[i]\n\t\t\tconst d = hypot(unit.pos.x - centre.x - px, unit.pos.z - centre.z - pz)\n\t\t\tif (d < best) {\n\t\t\t\tbest = d\n\t\t\t\tnearest = i\n\t\t\t}\n\t\t}\n\t\tpoints.set(left[nearest].id, place)\n\t\tleft.splice(nearest, 1)\n\t}\n\tfor (const unit of left) points.set(unit.id, target)\n\treturn points\n}\n\n/**\n * The engine's usual formation: a tight group keeps its shape as it is, and a scattered one lines up in rows across\n * the way of travel, as many across as there are rows, the units ahead in the front rows\n *\n * @beta\n */\nexport const rowsFormation: FormationDef = {\n\tid: 'rows',\n\tname: 'Rows',\n\tpoints(context) {\n\t\tconst { units, target, centre, spacing, forward, right, snap } = context\n\t\tconst points = new Map<EntityId, Vec2>()\n\t\tlet spread = 0\n\t\tfor (const unit of units) spread = Math.max(spread, hypot(unit.pos.x - centre.x, unit.pos.z - centre.z))\n\t\tconst travel = hypot(target.x - centre.x, target.z - centre.z)\n\t\tconst compact = spacing * Math.sqrt(units.length)\n\t\tif (spread <= compact && travel > spread && !context.turned) {\n\t\t\tfor (const unit of units) points.set(unit.id, snap({ x: target.x + unit.pos.x - centre.x, z: target.z + unit.pos.z - centre.z }))\n\t\t\treturn points\n\t\t}\n\t\tconst columns = Math.ceil(Math.sqrt(units.length))\n\t\tconst rows = Math.ceil(units.length / columns)\n\t\t// front rows go to the units that are already ahead, to keep paths from crossing\n\t\tconst ahead = (u: Entity) => (u.pos.x - centre.x) * forward.x + (u.pos.z - centre.z) * forward.z\n\t\tconst sideways = (u: Entity) => (u.pos.x - centre.x) * right.x + (u.pos.z - centre.z) * right.z\n\t\tconst ordered = [...units].sort((a, b) => ahead(b) - ahead(a) || a.id - b.id)\n\t\tfor (let row = 0; row < rows; row++) {\n\t\t\tconst members = ordered.slice(row * columns, (row + 1) * columns).sort((a, b) => sideways(a) - sideways(b) || a.id - b.id)\n\t\t\tconst back = (row - (rows - 1) / 2) * spacing\n\t\t\tfor (let i = 0; i < members.length; i++) {\n\t\t\t\tconst side = (i - (members.length - 1) / 2) * spacing\n\t\t\t\tpoints.set(members[i].id, snap(context.place(side, -back)))\n\t\t\t}\n\t\t}\n\t\treturn points\n\t}\n}\n\n/** How many places a ring of a radius has room for, `spacing` apart */\nconst ringRoom = (radius: number, spacing: number) => Math.max(Math.floor((2 * Math.PI * radius) / spacing), 1)\n\n/**\n * How many places each ring of a disc gets, the middle first (one), then the rings a `spacing` apart: as few rings as\n * hold them all, and the places shared out among the rings as their room goes, so that the disc is as thick\n * everywhere, filled to the middle, rather than full outer rings round a hollow. The places left over by the share go\n * to the biggest remainders, the outer ring of two first. A few that the outer ring holds alone (up to 12) stand on it\n */\nfunction ringCounts(count: number, spacing: number): number[] {\n\tconst room = [1]\n\tlet held = 1\n\twhile (held < count) {\n\t\tconst on = ringRoom(room.length * spacing, spacing)\n\t\troom.push(on)\n\t\theld += on\n\t}\n\t// a few, that the outer ring holds alone: a ring of them, with nobody within\n\tif (count <= room[room.length - 1]) return room.map((_, i) => (i === room.length - 1 ? count : 0))\n\tconst counts = room.map((on) => Math.floor((count * on) / held))\n\tlet left = count - counts.reduce((sum, on) => sum + on, 0)\n\t// the remainders, the biggest first and the outer ring of two the same; whole numbers, so the same on any machine\n\tconst order = room.map((_, i) => i).sort((a, b) => ((count * room[b]) % held) - ((count * room[a]) % held) || b - a)\n\tfor (const i of order) {\n\t\tif (left === 0) break\n\t\tif (counts[i] < room[i]) {\n\t\t\tcounts[i]++\n\t\t\tleft--\n\t\t}\n\t}\n\treturn counts\n}\n\n/** The places of a ring, evenly, the first at the front, clockwise */\nfunction circleRing(radius: number, on: number): Vec2[] {\n\tconst places: Vec2[] = []\n\tfor (let i = 0; i < on; i++) {\n\t\tconst angle = (i / on) * 2 * Math.PI\n\t\tplaces.push({ x: radius * sin(angle), z: radius * cos(angle) })\n\t}\n\treturn places\n}\n\n/**\n * A circle: a ring around the target, the first place at the front, and rings within it where one is not enough for\n * them all, a `spacing` apart, down to the middle. As few rings as hold them, and the units shared out among them as\n * their room goes: a disc as thick everywhere, every ring's places even, the outer ring first\n *\n * @beta\n */\nexport const circleFormation: FormationDef = {\n\tid: 'circle',\n\tname: 'Circle',\n\tshape(count, spacing) {\n\t\tconst counts = ringCounts(count, spacing)\n\t\tconst places: Vec2[] = []\n\t\tfor (let i = counts.length - 1; i >= 1; i--) places.push(...circleRing(i * spacing, counts[i]))\n\t\tif (counts[0] > 0) places.push({ x: 0, z: 0 })\n\t\treturn places\n\t}\n}\n\n/**\n * A square: a block of rows a `spacing` apart, as many across as deep (one row fewer where that holds them), filled to\n * the middle, the front row first. Where they do not fill the last row, the back one, those in it stand in its middle\n *\n * @beta\n */\nexport const squareFormation: FormationDef = {\n\tid: 'square',\n\tname: 'Square',\n\tshape(count, spacing) {\n\t\tconst across = Math.ceil(Math.sqrt(count))\n\t\tconst deep = Math.ceil(count / across)\n\t\tconst places: Vec2[] = []\n\t\tfor (let row = 0; row < deep; row++) {\n\t\t\tconst on = Math.min(across, count - row * across)\n\t\t\tconst z = ((deep - 1) / 2 - row) * spacing\n\t\t\tfor (let i = 0; i < on; i++) places.push({ x: (i - (on - 1) / 2) * spacing, z })\n\t\t}\n\t\treturn places\n\t}\n}\n\n/**\n * No formation: every unit to the point itself, as units sent one by one go\n *\n * @beta\n */\nexport const noneFormation: FormationDef = {\n\tid: 'none',\n\tname: 'None',\n\tshape: (count) => Array.from({ length: count }, () => ({ x: 0, z: 0 }))\n}\n\n/**\n * The engine's formations: `rows` (the usual), `circle`, `square` and `none`\n *\n * @beta\n */\nexport const coreFormations: readonly FormationDef[] = [rowsFormation, circleFormation, squareFormation, noneFormation]\n\n/**\n * What a formation is laid out with, for a group sent to a target on a navigation\n *\n * @internal\n */\nexport function formationContext(world: World, units: readonly Entity[], target: Vec2, nav: Navigation, facing?: number): FormationContext {\n\tlet cx = 0\n\tlet cz = 0\n\tlet radius = 0\n\tfor (const unit of units) {\n\t\tcx += unit.pos.x\n\t\tcz += unit.pos.z\n\t\tradius = Math.max(radius, unit.def.radius)\n\t}\n\tcx /= units.length\n\tcz /= units.length\n\tconst travel = hypot(target.x - cx, target.z - cz)\n\t// turned by hand: the way the player dragged (a direction as `facing` is, 0 along +z), else the way of travel\n\tconst forward =\n\t\tfacing !== undefined\n\t\t\t? { x: sin(facing), z: cos(facing) }\n\t\t\t: { x: travel > 0.001 ? (target.x - cx) / travel : 0, z: travel > 0.001 ? (target.z - cz) / travel : 1 }\n\tconst right = { x: forward.z, z: -forward.x }\n\treturn {\n\t\tworld,\n\t\tunits,\n\t\ttarget,\n\t\tnav,\n\t\tcentre: { x: cx, z: cz },\n\t\tforward,\n\t\tright,\n\t\tturned: facing !== undefined,\n\t\tspacing: radius * 2 + GAP,\n\t\tplace: (x, z) => ({ x: target.x + right.x * x + forward.x * z, z: target.z + right.z * x + forward.z * z }),\n\t\tsnap: (p) => nav.closestPoint(p, 4) ?? target\n\t}\n}\n\n/**\n * Individual destinations for a group ordered to the same point, in a formation (`rowsFormation` when none is\n * given), and what the `formation` hook makes of them. Units that walk and units that fly are laid out apart, each\n * on their own navigation (`world.navFor`). `facing`, where the player turned the formation by hand, is the way it\n * faces (a direction as an entity's `facing` is), over the way of travel\n *\n * @beta\n */\nexport function formationPoints(\n\tworld: World,\n\tunits: readonly Entity[],\n\ttarget: Vec2,\n\tformation: FormationDef = rowsFormation,\n\tfacing?: number\n): Map<EntityId, Vec2> {\n\tif (units.length === 0) return new Map()\n\tconst context = formationContext(world, units, target, world.navFor(units[0]), facing)\n\tlet points: Map<EntityId, Vec2>\n\tif (units.length === 1) points = new Map([[units[0].id, target]])\n\telse if (formation.points) points = formation.points(context)\n\telse if (formation.shape) points = fitToPlaces(context, placed(context, formation.shape(units.length, context.spacing, context)))\n\telse throw new Error(`The formation \"${formation.id}\" has neither a shape nor points`)\n\tif (world.hooks.has('formation')) world.hooks.run('formation', { units, target, formation, points })\n\treturn points\n}\n\n/**\n * A unit as a preview of a formation knows it: where it stands and how big it is\n *\n * @beta\n */\nexport interface FormationUnit {\n\t/** The unit's entity id */\n\treadonly id: EntityId\n\t/** Where it stands, in cells */\n\treadonly pos: Vec2\n\t/** Its collision radius, in cells */\n\treadonly radius: number\n}\n\n/**\n * Where a group would stand if sent to a target in a formation (by id, `rows` when unknown), from what a player's\n * screen knows of the units: what the ghosts of a right-click dragged are drawn from (`GameSession.formationPlaces`).\n * The same shapes as `formationPoints` gives, units that walk and units that fly each on their own navigation; the\n * `formation` hook (the simulation's) and a formation that reads `FormationContext.world` take no part, and the order\n * itself lays the group out as it will\n *\n * @beta\n */\nexport function formationPreview(\n\tregistry: Registry,\n\tunits: readonly (FormationUnit & { readonly flying?: boolean })[],\n\ttarget: Vec2,\n\tnavs: { readonly nav: Navigation; readonly air: Navigation },\n\tid: string,\n\tfacing?: number\n): Map<EntityId, Vec2> {\n\tconst formation = registry.formations.has(id) ? registry.formation(id) : rowsFormation\n\tconst places = new Map<EntityId, Vec2>()\n\tfor (const flying of [false, true]) {\n\t\tconst group = units.filter((unit) => !!unit.flying === flying)\n\t\tif (group.length === 0) continue\n\t\tif (group.length === 1) places.set(group[0].id, target)\n\t\telse {\n\t\t\tconst stand = group.map((unit) => ({ id: unit.id, pos: unit.pos, def: { radius: unit.radius } }) as unknown as Entity)\n\t\t\tconst context = formationContext(undefined as unknown as World, stand, target, flying ? navs.air : navs.nav, facing)\n\t\t\tconst found = formation.points ? formation.points(context) : fitToPlaces(context, placed(context, formation.shape!(group.length, context.spacing, context)))\n\t\t\tfor (const [unit, place] of found) places.set(unit, place)\n\t\t}\n\t}\n\treturn places\n}\n"],"mappings":"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"}

package/dist/forms.d.ts

@@ -0,0 +1,58 @@
+import type { FormCooldowns, MorphBack } from './defs';
+import type { Entity } from './entity';
+import type { System } from './registry';
+import type { World } from './world';
+/**
+ * How a hero takes a form (`takeForm`): what it learns there and at what levels, what of its own it keeps, for how
+ * long, what turns it back. `learns`, `levels` and `keeps` are read as a `HeroForm`'s; with `learns` left out, what the
+ * hero's type says of the form (`HeroDef.forms`) is taken, or else what the form's own type learns
+ *
+ * @beta
+ */
+export interface FormOptions {
+    /** What it learns in the form, by id (`HeroForm.learns`) */
+    learns?: string[];
+    /**
+     * The level each of `learns` starts at, by id (`HeroForm.levels`): one of its own whose level it has, or a number
+     * (another hero's, taken over). A list is by place in `learns`, numbers alone
+     */
+    levels?: Record<string, string | number> | number[];
+    /** Its own abilities the form leaves in place, by id (`HeroForm.keeps`): an ultimate, a passive */
+    keeps?: string[];
+    /** What becomes of the cooldowns going in and out (`HeroForm.cooldowns`): the time away runs the put away down when left out */
+    cooldowns?: FormCooldowns;
+    /** Seconds it lasts: until something else turns it back when left out */
+    duration?: number;
+    /** What turns it back: its time and its death when left out */
+    back?: MorphBack[];
+    /** The ability that made it, kept in the form: cast again there, it turns it back where `back` has `ability` */
+    by?: string;
+}
+/**
+ * Turns a hero into one of its forms where it stands (`into`, a unit type that is a hero's: its stats, growth and look
+ * are the form's), as the `morph` effect does. Kept: its id, owner and place, its level and experience, its items, its
+ * buffs, the share of its health and mana, and what it was told (it goes on as the form). It learns the form's
+ * abilities (`FormOptions.learns`) at the levels the form says (`levels`: one of its own's, or a number; by slot in
+ * `HeroForm`'s shorter shape, Q is Q); those of its own it keeps (`keeps`, the ability that made the form, the spells it
+ * brought, any of its own the form learns) are the same, cooldown and all; the rest are put away until it turns back
+ * (`leaveForm`), their cooldowns as `cooldowns` says (running down by the time away when left out). A hero in a form already turns back first
+ *
+ * @beta
+ */
+export declare function takeForm(world: World, entity: Entity, into: string, options?: FormOptions): void;
+/**
+ * Turns a hero in a form back into what it was (`takeForm`): its type, its own abilities as they were (their cooldowns
+ * as `HeroForm.cooldowns` says, run down while it was away when left out, what it shares with the form as the form left it), the share of its health and mana kept
+ * and what it was told going on. `why` is told with the `morphedBack` event: one of `MorphBack`, or a game's own word
+ * (`'kill'`: a possessed hero that kills). False for one in no form
+ *
+ * @beta
+ */
+export declare function leaveForm(world: World, entity: Entity, why?: MorphBack | (string & {})): boolean;
+/**
+ * Turns back what is in a form whose time is up (`Form.until`): the living, in the order of their ids. A fallen hero
+ * in a form that does not end with its death turns back once it is brought back, if its time is up by then
+ *
+ * @beta
+ */
+export declare const formSystem: System;

package/dist/forms.js

@@ -0,0 +1,146 @@
+import { morphedBack } from "./engineEvents.js";
+import { form, learnsOf } from "./formState.js";
+import { morph } from "./tech.js";
+//#region src/forms.ts
+/**
+* A hero's forms (E2E-PLAN LB2, LB6): a hero turned into another unit type where it stands, for a while or until
+* turned back (Nidalee's cougar, a druid's bear), the form's abilities learned at the levels it says, what of its own it
+* keeps left in place and the rest put away
+*/
+var fresh = (world, id, level) => ({
+	id,
+	level,
+	cooldown: 0,
+	autocast: level > 0 && (world.registry.ability(id).autocast ?? false)
+});
+/**
+* Turns a hero into one of its forms where it stands (`into`, a unit type that is a hero's: its stats, growth and look
+* are the form's), as the `morph` effect does. Kept: its id, owner and place, its level and experience, its items, its
+* buffs, the share of its health and mana, and what it was told (it goes on as the form). It learns the form's
+* abilities (`FormOptions.learns`) at the levels the form says (`levels`: one of its own's, or a number; by slot in
+* `HeroForm`'s shorter shape, Q is Q); those of its own it keeps (`keeps`, the ability that made the form, the spells it
+* brought, any of its own the form learns) are the same, cooldown and all; the rest are put away until it turns back
+* (`leaveForm`), their cooldowns as `cooldowns` says (running down by the time away when left out). A hero in a form already turns back first
+*
+* @beta
+*/
+function takeForm(world, entity, into, options = {}) {
+	if (entity.get(form)) leaveForm(world, entity);
+	const from = entity.def.id;
+	const target = world.registry.unit(into);
+	const own = entity.abilities;
+	const ownLearns = learnsOf(entity);
+	const said = options.learns !== void 0 ? options : entity.def.hero?.forms?.[into] ?? {};
+	const learns = said.learns ?? target.hero?.learns ?? [];
+	const { levels, keeps = [], cooldowns } = said;
+	const bySlot = levels === void 0 && said.keeps === void 0;
+	const had = new Map(own.map((state) => [state.id, state]));
+	const abilities = [];
+	const linked = {};
+	const take = (state) => {
+		if (!abilities.includes(state)) abilities.push(state);
+	};
+	const levelOf = (id, place) => {
+		const by = bySlot ? ownLearns[place] : Array.isArray(levels) ? levels[place] ?? 0 : levels?.[id] ?? 0;
+		if (typeof by === "number") return by;
+		if (by === void 0 || by === id || !had.has(by)) return 0;
+		linked[id] = by;
+		return had.get(by).level;
+	};
+	for (const id of target.abilities ?? []) take(had.get(id) ?? fresh(world, id, 1));
+	learns.forEach((id, place) => take(had.get(id) ?? fresh(world, id, levelOf(id, place))));
+	const kept = [
+		...keeps,
+		...options.by !== void 0 ? [options.by] : [],
+		...entity.def.hero?.spells ?? []
+	].filter((id) => had.has(id));
+	for (const id of kept) take(had.get(id));
+	for (const id of target.hero?.spells ?? []) take(had.get(id) ?? fresh(world, id, 1));
+	if (cooldowns === "shared") for (const [id, by] of Object.entries(linked)) {
+		const state = abilities.find((each) => each.id === id);
+		if (state && !had.has(id)) state.cooldown = had.get(by).cooldown;
+	}
+	const back = options.back ?? ["time", "death"];
+	entity.set(form, {
+		from,
+		...options.by !== void 0 && { by: options.by },
+		at: world.time,
+		...options.duration !== void 0 && back.includes("time") && { until: world.time + options.duration },
+		back: [...back],
+		learns: [...learns, ...ownLearns.filter((id) => kept.includes(id) && !learns.includes(id))],
+		...Object.keys(linked).length > 0 && { linked },
+		...cooldowns !== void 0 && { cooldowns },
+		kept: own.filter((state) => !abilities.includes(state)),
+		own: own.map((state) => state.id)
+	});
+	morph(world, entity, into, {
+		keepOrders: true,
+		share: true,
+		abilities
+	});
+}
+/**
+* Turns a hero in a form back into what it was (`takeForm`): its type, its own abilities as they were (their cooldowns
+* as `HeroForm.cooldowns` says, run down while it was away when left out, what it shares with the form as the form left it), the share of its health and mana kept
+* and what it was told going on. `why` is told with the `morphedBack` event: one of `MorphBack`, or a game's own word
+* (`'kill'`: a possessed hero that kills). False for one in no form
+*
+* @beta
+*/
+function leaveForm(world, entity, why) {
+	const state = entity.get(form);
+	if (!state) return false;
+	const away = world.time - state.at;
+	const now = new Map(entity.abilities.map((ability) => [ability.id, ability]));
+	const kept = new Map(state.kept.map((ability) => [ability.id, ability]));
+	const abilities = [];
+	for (const id of state.own) {
+		const ability = now.get(id) ?? kept.get(id);
+		if (!ability) continue;
+		if (!now.has(id)) {
+			const shared = state.cooldowns === "shared" ? Object.entries(state.linked ?? {}).find(([, by]) => by === id)?.[0] : void 0;
+			const there = shared === void 0 ? void 0 : now.get(shared);
+			if (state.cooldowns === "reset") ability.cooldown = 0;
+			else if (there) ability.cooldown = there.cooldown;
+			else if (state.cooldowns !== "keep") ability.cooldown = Math.max(ability.cooldown - away, 0);
+		}
+		abilities.push(ability);
+	}
+	const was = entity.def.id;
+	entity.remove(form);
+	morph(world, entity, state.from, {
+		keepOrders: why !== "death",
+		share: true,
+		abilities
+	});
+	world.events.emit(morphedBack, {
+		entity,
+		form: was,
+		why
+	});
+	return true;
+}
+/**
+* Turns back what is in a form whose time is up (`Form.until`): the living, in the order of their ids. A fallen hero
+* in a form that does not end with its death turns back once it is brought back, if its time is up by then
+*
+* @beta
+*/
+var formSystem = {
+	name: "forms",
+	phase: "cleanup",
+	update(world) {
+		let due;
+		for (const entity of world.index.with(form)) {
+			const until = entity.get(form).until;
+			if (until !== void 0 && world.time >= until && entity.alive) (due ??= []).push(entity);
+		}
+		if (!due) return;
+		due.sort((a, b) => a.id - b.id);
+		for (const entity of due) leaveForm(world, entity, "time");
+	}
+};
+//#endregion
+export { formSystem, leaveForm, takeForm };
+
+//# sourceMappingURL=forms.js.map

package/dist/forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.js","names":[],"sources":["../src/forms.ts"],"sourcesContent":["/**\n * A hero's forms (E2E-PLAN LB2, LB6): a hero turned into another unit type where it stands, for a while or until\n * turned back (Nidalee's cougar, a druid's bear), the form's abilities learned at the levels it says, what of its own it\n * keeps left in place and the rest put away\n */\nimport { morphedBack } from '#engine/engineEvents'\nimport type { FormCooldowns, MorphBack } from './defs'\nimport type { AbilityState, Entity } from './entity'\nimport { form, learnsOf } from './formState'\nimport type { System } from './registry'\nimport { morph } from './tech'\nimport type { World } from './world'\n\n/**\n * How a hero takes a form (`takeForm`): what it learns there and at what levels, what of its own it keeps, for how\n * long, what turns it back. `learns`, `levels` and `keeps` are read as a `HeroForm`'s; with `learns` left out, what the\n * hero's type says of the form (`HeroDef.forms`) is taken, or else what the form's own type learns\n *\n * @beta\n */\nexport interface FormOptions {\n\t/** What it learns in the form, by id (`HeroForm.learns`) */\n\tlearns?: string[]\n\t/**\n\t * The level each of `learns` starts at, by id (`HeroForm.levels`): one of its own whose level it has, or a number\n\t * (another hero's, taken over). A list is by place in `learns`, numbers alone\n\t */\n\tlevels?: Record<string, string | number> | number[]\n\t/** Its own abilities the form leaves in place, by id (`HeroForm.keeps`): an ultimate, a passive */\n\tkeeps?: string[]\n\t/** What becomes of the cooldowns going in and out (`HeroForm.cooldowns`): the time away runs the put away down when left out */\n\tcooldowns?: FormCooldowns\n\t/** Seconds it lasts: until something else turns it back when left out */\n\tduration?: number\n\t/** What turns it back: its time and its death when left out */\n\tback?: MorphBack[]\n\t/** The ability that made it, kept in the form: cast again there, it turns it back where `back` has `ability` */\n\tby?: string\n}\n\nconst fresh = (world: World, id: string, level: number): AbilityState => ({\n\tid,\n\tlevel,\n\tcooldown: 0,\n\tautocast: level > 0 && (world.registry.ability(id).autocast ?? false)\n})\n\n/**\n * Turns a hero into one of its forms where it stands (`into`, a unit type that is a hero's: its stats, growth and look\n * are the form's), as the `morph` effect does. Kept: its id, owner and place, its level and experience, its items, its\n * buffs, the share of its health and mana, and what it was told (it goes on as the form). It learns the form's\n * abilities (`FormOptions.learns`) at the levels the form says (`levels`: one of its own's, or a number; by slot in\n * `HeroForm`'s shorter shape, Q is Q); those of its own it keeps (`keeps`, the ability that made the form, the spells it\n * brought, any of its own the form learns) are the same, cooldown and all; the rest are put away until it turns back\n * (`leaveForm`), their cooldowns as `cooldowns` says (running down by the time away when left out). A hero in a form already turns back first\n *\n * @beta\n */\nexport function takeForm(world: World, entity: Entity, into: string, options: FormOptions = {}): void {\n\tif (entity.get(form)) leaveForm(world, entity)\n\tconst from = entity.def.id\n\tconst target = world.registry.unit(into)\n\tconst own = entity.abilities\n\tconst ownLearns = learnsOf(entity)\n\t// what the options say, or else what the hero's type says of the form: not a mix of the two\n\tconst said = options.learns !== undefined ? options : (entity.def.hero?.forms?.[into] ?? {})\n\tconst learns = said.learns ?? target.hero?.learns ?? []\n\tconst { levels, keeps = [], cooldowns } = said\n\t// the shorter shape: a list alone, by slot\n\tconst bySlot = levels === undefined && said.keeps === undefined\n\tconst had = new Map(own.map((state) => [state.id, state]))\n\tconst abilities: AbilityState[] = []\n\tconst linked: Record<string, string> = {}\n\tconst take = (state: AbilityState) => {\n\t\tif (!abilities.includes(state)) abilities.push(state)\n\t}\n\tconst levelOf = (id: string, place: number): number => {\n\t\tconst by = bySlot ? ownLearns[place] : Array.isArray(levels) ? (levels[place] ?? 0) : (levels?.[id] ?? 0)\n\t\tif (typeof by === 'number') return by\n\t\tif (by === undefined || by === id || !had.has(by)) return 0\n\t\tlinked[id] = by\n\t\treturn had.get(by)!.level\n\t}\n\tfor (const id of target.abilities ?? []) take(had.get(id) ?? fresh(world, id, 1))\n\tlearns.forEach((id, place) => take(had.get(id) ?? fresh(world, id, levelOf(id, place))))\n\t// what of its own it keeps besides: what the form says, the ability that made it, the spells it brought along\n\tconst kept = [...keeps, ...(options.by !== undefined ? [options.by] : []), ...(entity.def.hero?.spells ?? [])].filter((id) => had.has(id))\n\tfor (const id of kept) take(had.get(id)!)\n\t// and the form's own spells\n\tfor (const id of target.hero?.spells ?? []) take(had.get(id) ?? fresh(world, id, 1))\n\t// 'shared': what it takes the place of is one cooldown with it, from now on\n\tif (cooldowns === 'shared')\n\t\tfor (const [id, by] of Object.entries(linked)) {\n\t\t\tconst state = abilities.find((each) => each.id === id)\n\t\t\tif (state && !had.has(id)) state.cooldown = had.get(by)!.cooldown\n\t\t}\n\tconst back = options.back ?? ['time', 'death']\n\tentity.set(form, {\n\t\tfrom,\n\t\t...(options.by !== undefined && { by: options.by }),\n\t\tat: world.time,\n\t\t...(options.duration !== undefined && back.includes('time') && { until: world.time + options.duration }),\n\t\tback: [...back],\n\t\t// the card shows what it learns there, then what it keeps of what it learns as itself, in its own order\n\t\tlearns: [...learns, ...ownLearns.filter((id) => kept.includes(id) && !learns.includes(id))],\n\t\t...(Object.keys(linked).length > 0 && { linked }),\n\t\t...(cooldowns !== undefined && { cooldowns }),\n\t\tkept: own.filter((state) => !abilities.includes(state)),\n\t\town: own.map((state) => state.id)\n\t})\n\tmorph(world, entity, into, { keepOrders: true, share: true, abilities })\n}\n\n/**\n * Turns a hero in a form back into what it was (`takeForm`): its type, its own abilities as they were (their cooldowns\n * as `HeroForm.cooldowns` says, run down while it was away when left out, what it shares with the form as the form left it), the share of its health and mana kept\n * and what it was told going on. `why` is told with the `morphedBack` event: one of `MorphBack`, or a game's own word\n * (`'kill'`: a possessed hero that kills). False for one in no form\n *\n * @beta\n */\nexport function leaveForm(world: World, entity: Entity, why?: MorphBack | (string & {})): boolean {\n\tconst state = entity.get(form)\n\tif (!state) return false\n\tconst away = world.time - state.at\n\tconst now = new Map(entity.abilities.map((ability) => [ability.id, ability]))\n\tconst kept = new Map(state.kept.map((ability) => [ability.id, ability]))\n\tconst abilities: AbilityState[] = []\n\tfor (const id of state.own) {\n\t\tconst ability = now.get(id) ?? kept.get(id)\n\t\tif (!ability) continue\n\t\tif (!now.has(id)) {\n\t\t\t// put away: as left ('keep'), ready ('reset'), the form's one it shares with ('shared'), or run down by the time away\n\t\t\tconst shared = state.cooldowns === 'shared' ? Object.entries(state.linked ?? {}).find(([, by]) => by === id)?.[0] : undefined\n\t\t\tconst there = shared === undefined ? undefined : now.get(shared)\n\t\t\tif (state.cooldowns === 'reset') ability.cooldown = 0\n\t\t\telse if (there) ability.cooldown = there.cooldown\n\t\t\telse if (state.cooldowns !== 'keep') ability.cooldown = Math.max(ability.cooldown - away, 0)\n\t\t}\n\t\tabilities.push(ability)\n\t}\n\tconst was = entity.def.id\n\tentity.remove(form)\n\tmorph(world, entity, state.from, { keepOrders: why !== 'death', share: true, abilities })\n\tworld.events.emit(morphedBack, { entity, form: was, why })\n\treturn true\n}\n\n/**\n * Turns back what is in a form whose time is up (`Form.until`): the living, in the order of their ids. A fallen hero\n * in a form that does not end with its death turns back once it is brought back, if its time is up by then\n *\n * @beta\n */\nexport const formSystem: System = {\n\tname: 'forms',\n\tphase: 'cleanup',\n\tupdate(world: World) {\n\t\tlet due: Entity[] | undefined\n\t\tfor (const entity of world.index.with(form)) {\n\t\t\tconst until = entity.get(form)!.until\n\t\t\tif (until !== undefined && world.time >= until && entity.alive) (due ??= []).push(entity)\n\t\t}\n\t\tif (!due) return\n\t\tdue.sort((a, b) => a.id - b.id)\n\t\tfor (const entity of due) leaveForm(world, entity, 'time')\n\t}\n}\n"],"mappings":"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"}

package/dist/friendlyFire.d.ts

@@ -8,7 +8,7 @@ import type { World } from './world';
  */
 export declare const FRIENDLY_FIRE = "core.friendlyFire";
 /**
- * What the friendly fire pack is made with (`withFriendlyFire`)
+ * What the friendly fire pack is made with (`friendlyFirePack`)
  *
  * @beta
  */
@@ -23,4 +23,4 @@ export interface FriendlyFireOptions {
  *
  * @beta
  */
-export declare function withFriendlyFire(options?: FriendlyFireOptions): GamePack;
+export declare function friendlyFirePack(options?: FriendlyFireOptions): GamePack;

package/dist/friendlyFire.js

@@ -0,0 +1,37 @@
+import { defineHook } from "./hooks.js";
+import { attackReaches } from "./systems/combat.js";
+//#region src/friendlyFire.ts
+/**
+* The friendly fire pack's id
+*
+* @beta
+*/
+var FRIENDLY_FIRE = "core.friendlyFire";
+/**
+* Friendly fire, as in classic RTS games: a unit told to attack (the attack command, never a right click) one of its own or
+* an ally's attacks it. Never of its own accord: units do not pick their own side to attack, nor fight back at it.
+* Nothing of a neutral player's (a rock, a critter) is made a target by it
+*
+* @beta
+*/
+function friendlyFirePack(options = {}) {
+	const attacks = options.attacks ?? (() => true);
+	return {
+		id: FRIENDLY_FIRE,
+		options,
+		hooks: [defineHook({
+			hook: "canAttack",
+			id: "friendlyFire",
+			run(world, event) {
+				const { attacker, target } = event;
+				if (!event.cancelled || !event.ordered || world.player(target.owner).neutral) return;
+				if (world.areEnemies(attacker.owner, target.owner)) return;
+				if (attackReaches(world, attacker, target) && attacks(world, attacker, target)) event.cancelled = false;
+			}
+		})]
+	};
+}
+//#endregion
+export { FRIENDLY_FIRE, friendlyFirePack };
+
+//# sourceMappingURL=friendlyFire.js.map

package/dist/friendlyFire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"friendlyFire.js","names":[],"sources":["../src/friendlyFire.ts"],"sourcesContent":["import type { Entity } from './entity'\nimport { defineHook } from './hooks'\nimport type { GamePack } from './packs/pack'\nimport { attackReaches } from './systems/combat'\nimport type { World } from './world'\n\n/*\n * Friendly fire, an opt-in pack: as in classic RTS games, a unit told to attack one of its own side's does\n */\n\n/**\n * The friendly fire pack's id\n *\n * @beta\n */\nexport const FRIENDLY_FIRE = 'core.friendlyFire'\n\n/**\n * What the friendly fire pack is made with (`friendlyFirePack`)\n *\n * @beta\n */\nexport interface FriendlyFireOptions {\n\t/** What of its own side's, and its allies', a unit may be told to attack: anything its attack reaches when left out */\n\tattacks?: (world: World, attacker: Entity, target: Entity) => boolean\n}\n\n/**\n * Friendly fire, as in classic RTS games: a unit told to attack (the attack command, never a right click) one of its own or\n * an ally's attacks it. Never of its own accord: units do not pick their own side to attack, nor fight back at it.\n * Nothing of a neutral player's (a rock, a critter) is made a target by it\n *\n * @beta\n */\nexport function friendlyFirePack(options: FriendlyFireOptions = {}): GamePack {\n\tconst attacks = options.attacks ?? (() => true)\n\tconst friendly = defineHook({\n\t\thook: 'canAttack',\n\t\tid: 'friendlyFire',\n\t\trun(world, event) {\n\t\t\tconst { attacker, target } = event\n\t\t\tif (!event.cancelled || !event.ordered || world.player(target.owner).neutral) return\n\t\t\tif (world.areEnemies(attacker.owner, target.owner)) return\n\t\t\tif (attackReaches(world, attacker, target) && attacks(world, attacker, target)) event.cancelled = false\n\t\t}\n\t})\n\treturn { id: FRIENDLY_FIRE, options, hooks: [friendly] }\n}\n"],"mappings":";;;;;;;;AAeA,IAAa,gBAAgB;;;;;;;;AAmB7B,SAAgB,iBAAiB,UAA+B,CAAC,GAAa;CAC7E,MAAM,UAAU,QAAQ,kBAAkB;CAW1C,OAAO;EAAE,IAAI;EAAe;EAAS,OAAO,CAV3B,WAAW;GAC3B,MAAM;GACN,IAAI;GACJ,IAAI,OAAO,OAAO;IACjB,MAAM,EAAE,UAAU,WAAW;IAC7B,IAAI,CAAC,MAAM,aAAa,CAAC,MAAM,WAAW,MAAM,OAAO,OAAO,KAAK,CAAC,CAAC,SAAS;IAC9E,IAAI,MAAM,WAAW,SAAS,OAAO,OAAO,KAAK,GAAG;IACpD,IAAI,cAAc,OAAO,UAAU,MAAM,KAAK,QAAQ,OAAO,UAAU,MAAM,GAAG,MAAM,YAAY;GACnG;EACD,CAC6C,CAAQ;CAAE;AACxD"}