@v12-engine/engine 0.1.0 → 0.4.0

package/dist/mapObjectives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapObjectives.js","names":[],"sources":["../src/mapObjectives.ts"],"sourcesContent":["import type { PlayerId } from './entity'\nimport { defineHook } from './hooks'\nimport type { GameMap } from './map'\nimport type { MapProblem } from './mapFields'\nimport type { Message } from './messages'\nimport type { ObjectiveDef, ObjectiveState } from './objectives'\nimport type { GamePack } from './packs/pack'\nimport type { World } from './world'\n\n/*\n * Objectives as data on the map (campaign plan EQ3): a list kept in the map's data (`GameMap.data.objectives`), which\n * the editor's Objectives panel writes, and which the map objectives pack reads (`mapObjectives`): those given at the\n * start are each player's as the world is made from the map, the rest are given by the rules by id\n * (`giveMapObjective`). What becomes of them, done or failed, is the rules' as for any objective (`world.objectives`)\n */\n\n/**\n * The map objectives pack's id\n *\n * @beta\n */\nexport const MAP_OBJECTIVES = 'core.mapObjectives'\n\n/**\n * The key of the map's data its objectives are kept under (`GameMap.data.objectives`)\n *\n * @beta\n */\nexport const MAP_OBJECTIVES_KEY = 'objectives'\n\n/**\n * An objective a map gives, as it keeps it: an objective (`ObjectiveDef`: its id, its words, whether the mission needs\n * it, more about it) and when it is given\n *\n * @beta\n */\nexport interface MapObjective extends ObjectiveDef {\n\t/**\n\t * When it is given: as the game starts (`start`), to every player a person plays (`mapObjectivePlayers`), or when\n\t * the rules say (`rule`: `giveMapObjective(world, id)`). Anything but `rule` is the start\n\t */\n\tat: 'start' | 'rule'\n}\n\n/** The words of an objective as a file may hold them: a key, or a key with params */\nconst isWords = (text: unknown): boolean =>\n\ttypeof text === 'string'\n\t\t? text.trim() !== ''\n\t\t: typeof text === 'object' && text !== null && typeof (text as Message).key === 'string' && (text as Message).key !== ''\n\n/**\n * The objectives a map gives (`GameMap.data.objectives`), in the order it gives them: none for a map with none. What is\n * kept there and is no objective (no id, no words) is left out, so that a file changed by hand breaks no rule that reads\n * it; the map's checks say so (`mapObjectives`)\n *\n * @beta\n */\nexport function mapObjectivesOf(map: { readonly data: Readonly<Record<string, unknown>> }): MapObjective[] {\n\tconst kept = map.data[MAP_OBJECTIVES_KEY]\n\tif (!Array.isArray(kept)) return []\n\treturn kept\n\t\t.filter(\n\t\t\t(each): each is MapObjective => typeof each === 'object' && each !== null && typeof each.id === 'string' && each.id !== '' && isWords(each.text)\n\t\t)\n\t\t.map((each) => ({\n\t\t\tid: each.id,\n\t\t\ttext: each.text,\n\t\t\t...(each.detail !== undefined && isWords(each.detail) && { detail: each.detail }),\n\t\t\t...(each.required !== undefined && { required: each.required !== false }),\n\t\t\tat: each.at === 'rule' ? 'rule' : 'start'\n\t\t}))\n}\n\n/**\n * Who is given a map's objective when the rules do not say (`giveMapObjective`): the map's players a person plays, not\n * those it says the computer plays or nobody does (`MapPlayer.controller`), in the order of their ids\n *\n * @beta\n */\nexport function mapObjectivePlayers(world: World): PlayerId[] {\n\treturn [...world.players.values()]\n\t\t.filter((player) => !player.neutral && !player.creeps)\n\t\t.filter((player) => {\n\t\t\tconst controller = world.map.player(player.id)?.controller\n\t\t\treturn controller !== 'computer' && controller !== 'nobody'\n\t\t})\n\t\t.map((player) => player.id)\n\t\t.sort((a, b) => a - b)\n}\n\n/**\n * Gives players an objective of the map's, by its id (`MapObjective`): those given by a rule (`at: 'rule'`), when the\n * rules say. To every player a person plays when `players` is left out (`mapObjectivePlayers`); a player who has it\n * already keeps theirs. Its words' params and its progress go with it, as `world.objectives.add`. Throws for an id the\n * map does not have: an id in the code that is not on the map is a mistake\n *\n * @beta\n */\nexport function giveMapObjective(\n\tworld: World,\n\tid: string,\n\toptions: { players?: readonly PlayerId[]; params?: Message['params']; progress?: { value: number; max: number } } = {}\n): ObjectiveState[] {\n\tconst def = mapObjectivesOf(world.map).find((objective) => objective.id === id)\n\tif (!def) throw new Error(`The map${world.map.name ? ` \"${world.map.name}\"` : ''} has no objective \"${id}\"`)\n\tconst { at: _at, ...objective } = def\n\tconst given: ObjectiveState[] = []\n\tfor (const player of options.players ?? mapObjectivePlayers(world)) {\n\t\tif (world.objectives.has(player, id)) continue\n\t\tgiven.push(world.objectives.add(player, objective, { params: options.params, progress: options.progress }))\n\t}\n\treturn given\n}\n\n/**\n * What is wrong with a map's objectives (`GameMap.data.objectives`): one with no id or with another's, one with no\n * words, a list that is not one. Each a click away in the Objectives panel\n *\n * @beta\n */\nexport function checkMapObjectives(map: GameMap): MapProblem[] {\n\tconst kept = map.data[MAP_OBJECTIVES_KEY]\n\tif (kept === undefined) return []\n\tif (!Array.isArray(kept)) return [{ message: 'The map’s objectives are not a list', error: true, rule: 'objectives' }]\n\tconst problems: MapProblem[] = []\n\tconst seen = new Set<string>()\n\tkept.forEach((each: Partial<MapObjective> | null, index) => {\n\t\tconst id = typeof each?.id === 'string' ? each.id : ''\n\t\tconst reveal = { panel: 'objectives', entry: id || String(index) }\n\t\tif (!id) problems.push({ message: `Objective ${index + 1} has no id`, error: true, rule: 'objective-id', reveal })\n\t\telse if (seen.has(id)) problems.push({ message: `Two objectives have the id \"${id}\"`, error: true, rule: 'objective-id', reveal })\n\t\tseen.add(id)\n\t\tif (!isWords(each?.text))\n\t\t\tproblems.push({ message: `The objective \"${id || index + 1}\" has no words`, error: true, rule: 'objective-text', reveal })\n\t})\n\treturn problems\n}\n\n/**\n * Objectives as data on the map (campaign plan EQ3): a map's objectives (`MapObjective`, kept in `GameMap.data.objectives`,\n * written by the editor's Objectives panel) given at the start to every player a person plays, as the world is made\n * from the map; those given by a rule wait for the rules (`giveMapObjective(world, id)`). Done and failed as any\n * objective is (`world.objectives.complete`, `fail`); a game that is won by them has `objectiveVictory` as its\n * `victory`. The map's checks say what is wrong with them (`checkMapObjectives`)\n *\n * @beta\n */\nexport function mapObjectives(): GamePack {\n\tconst atStart = defineHook({\n\t\thook: 'mapStart',\n\t\tid: MAP_OBJECTIVES,\n\t\trun(world) {\n\t\t\tfor (const objective of mapObjectivesOf(world.map)) if (objective.at === 'start') giveMapObjective(world, objective.id)\n\t\t}\n\t})\n\treturn { id: MAP_OBJECTIVES, hooks: [atStart], check: (map) => checkMapObjectives(map) }\n}\n"],"mappings":"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"}

package/dist/mapObjects.js

@@ -0,0 +1,80 @@
+import { clamp } from "./math.js";
+import { inventorySlots } from "./inventory.js";
+import { deposit } from "./entity.js";
+import { learn, setHeroLevel } from "./hero.js";
+import { mapObjectData } from "./mapFields.js";
+import { createItem, giveItem } from "./items.js";
+import { createOrder, giveOrder } from "./orders/queue.js";
+import { mapDrops } from "./randomGroups.js";
+//#region src/mapObjects.ts
+/**
+* Makes an entity what the map says it starts as, beyond where it stands and whose it is: hurt, at a level, with
+* items. In an order that lets each count on the one before: the level first, which the health follows from
+*/
+function startAs(world, entity, object) {
+	if (object.level !== void 0) setHeroLevel(world, entity, object.level);
+	for (const [ability, level] of Object.entries(object.abilities ?? {})) for (let i = 0; i < level; i++) if (!learn(world, entity, ability)) break;
+	for (const item of object.items ?? []) if (world.registry.items.has(item) && entity.has(inventorySlots)) giveItem(world, entity, createItem(world, item));
+	if (object.amount !== void 0 && entity.get(deposit)) entity.get(deposit).amount = Math.max(object.amount, 0);
+	if (object.health !== void 0) entity.health = Math.max(Math.round(entity.maxHealth * clamp(object.health, 0, 1)), 1);
+	if (object.mana !== void 0) entity.mana = Math.round(entity.maxMana * clamp(object.mana, 0, 1));
+}
+/**
+* Puts an object of the map in the world as the map has it: where it stands, whose, turned, as big, named, hurt, at a
+* level, with items and its drops, the game's fields on it and the game told (`mapObject`), and kept as the entity of
+* that object (`World.fromMap`). Not its orders: those are given once everything stands (`giveMapOrders`). Its
+* type as said: one drawn from a random group is drawn before
+*
+* @internal
+*/
+function spawnMapObject(world, object, map) {
+	const entity = world.spawn(object.type, object.owner, object, {
+		facing: object.facing,
+		scale: object.scale,
+		look: object.look,
+		name: object.name,
+		lifetime: object.lifetime,
+		underConstruction: object.underConstruction
+	});
+	startAs(world, entity, object);
+	if (object.drops) entity.set(mapDrops, object.drops);
+	const data = mapObjectData(world.registry, object, map);
+	for (const component of world.registry.listedComponents()) if (component.field && component.id in data) entity.set(component, structuredClone(data[component.id]));
+	if (world.hooks.has("mapObject")) world.hooks.run("mapObject", {
+		entity,
+		object,
+		data
+	});
+	world.fromMap.set(object.id, entity.id);
+	return entity;
+}
+/**
+* A unit of the map given what it does as the game begins (`MapObject.orders`): its own orders, one after the other,
+* as no player's command. What it cannot be given (a path the map has not) is left out
+*
+* @internal
+*/
+function giveMapOrders(world, entity, orders) {
+	let queue = false;
+	for (const { kind, path, point } of orders) {
+		const init = kind === "hold" ? { type: "hold" } : path ? {
+			type: kind === "patrol" ? "patrolPath" : "followPath",
+			path
+		} : point ? {
+			type: kind === "patrol" ? "patrol" : "move",
+			point: {
+				x: point.x,
+				z: point.z
+			}
+		} : void 0;
+		if (!init) continue;
+		const order = createOrder(world, init);
+		if (!world.registry.order(init.type).accepts(world, entity, init)) continue;
+		giveOrder(world, entity, order, queue);
+		queue = true;
+	}
+}
+//#endregion
+export { giveMapOrders, spawnMapObject };
+
+//# sourceMappingURL=mapObjects.js.map

package/dist/mapObjects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapObjects.js","names":[],"sources":["../src/mapObjects.ts"],"sourcesContent":["import { deposit, type Entity } from './entity'\nimport { learn, setHeroLevel } from './hero'\nimport { inventorySlots } from './inventory'\nimport { createItem, giveItem } from './items'\nimport type { GameMap, MapObject, MapObjectOrder } from './map'\nimport { mapObjectData } from './mapFields'\nimport { clamp } from './math'\nimport { createOrder, giveOrder } from './orders/queue'\nimport { mapDrops } from './randomGroups'\nimport type { World } from './world'\n\n/*\n * What stands on a map put in the world: as the world is made of the map (`createWorldFromMap`), and one at a time\n * after, as the editor's Play here puts down what was placed on the map while it plays (`debug.mapObject`, EQ10)\n */\n\n/**\n * Makes an entity what the map says it starts as, beyond where it stands and whose it is: hurt, at a level, with\n * items. In an order that lets each count on the one before: the level first, which the health follows from\n */\nfunction startAs(world: World, entity: Entity, object: MapObject): void {\n\tif (object.level !== undefined) setHeroLevel(world, entity, object.level)\n\t// a point at a time, as a player would: what the level does not allow yet is left out\n\tfor (const [ability, level] of Object.entries(object.abilities ?? {})) {\n\t\tfor (let i = 0; i < level; i++) if (!learn(world, entity, ability)) break\n\t}\n\tfor (const item of object.items ?? []) {\n\t\tif (world.registry.items.has(item) && entity.has(inventorySlots)) giveItem(world, entity, createItem(world, item))\n\t}\n\tif (object.amount !== undefined && entity.get(deposit)) entity.get(deposit)!.amount = Math.max(object.amount, 0)\n\tif (object.health !== undefined) entity.health = Math.max(Math.round(entity.maxHealth * clamp(object.health, 0, 1)), 1)\n\tif (object.mana !== undefined) entity.mana = Math.round(entity.maxMana * clamp(object.mana, 0, 1))\n}\n\n/**\n * Puts an object of the map in the world as the map has it: where it stands, whose, turned, as big, named, hurt, at a\n * level, with items and its drops, the game's fields on it and the game told (`mapObject`), and kept as the entity of\n * that object (`World.fromMap`). Not its orders: those are given once everything stands (`giveMapOrders`). Its\n * type as said: one drawn from a random group is drawn before\n *\n * @internal\n */\nexport function spawnMapObject(world: World, object: MapObject, map?: GameMap): Entity {\n\tconst entity = world.spawn(object.type, object.owner, object, {\n\t\tfacing: object.facing,\n\t\tscale: object.scale,\n\t\tlook: object.look,\n\t\tname: object.name,\n\t\tlifetime: object.lifetime,\n\t\tunderConstruction: object.underConstruction\n\t})\n\tstartAs(world, entity, object)\n\tif (object.drops) entity.set(mapDrops, object.drops)\n\tconst data = mapObjectData(world.registry, object, map)\n\t// a component with a field of the map's starts as the object says, or as the field's default\n\tfor (const component of world.registry.listedComponents()) {\n\t\tif (component.field && component.id in data) entity.set(component, structuredClone(data[component.id]))\n\t}\n\t// the game's turn: what its own fields mean is its to say\n\tif (world.hooks.has('mapObject')) world.hooks.run('mapObject', { entity, object, data })\n\tworld.fromMap.set(object.id, entity.id)\n\treturn entity\n}\n\n/**\n * A unit of the map given what it does as the game begins (`MapObject.orders`): its own orders, one after the other,\n * as no player's command. What it cannot be given (a path the map has not) is left out\n *\n * @internal\n */\nexport function giveMapOrders(world: World, entity: Entity, orders: readonly MapObjectOrder[]): void {\n\tlet queue = false\n\tfor (const { kind, path, point } of orders) {\n\t\tconst init =\n\t\t\tkind === 'hold'\n\t\t\t\t? { type: 'hold' as const }\n\t\t\t\t: path\n\t\t\t\t\t? { type: kind === 'patrol' ? ('patrolPath' as const) : ('followPath' as const), path }\n\t\t\t\t\t: point\n\t\t\t\t\t\t? { type: kind === 'patrol' ? ('patrol' as const) : ('move' as const), point: { x: point.x, z: point.z } }\n\t\t\t\t\t\t: undefined\n\t\t// a guard with nowhere to go guards where it stands: what an idle unit does\n\t\tif (!init) continue\n\t\tconst order = createOrder(world, init as never)\n\t\tif (!world.registry.order(init.type).accepts(world, entity, init as never)) continue\n\t\tgiveOrder(world, entity, order, queue)\n\t\tqueue = true\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;AAoBA,SAAS,QAAQ,OAAc,QAAgB,QAAyB;CACvE,IAAI,OAAO,UAAU,KAAA,GAAW,aAAa,OAAO,QAAQ,OAAO,KAAK;CAExE,KAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,OAAO,aAAa,CAAC,CAAC,GACnE,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,MAAM,OAAO,QAAQ,OAAO,GAAG;CAErE,KAAK,MAAM,QAAQ,OAAO,SAAS,CAAC,GACnC,IAAI,MAAM,SAAS,MAAM,IAAI,IAAI,KAAK,OAAO,IAAI,cAAc,GAAG,SAAS,OAAO,QAAQ,WAAW,OAAO,IAAI,CAAC;CAElH,IAAI,OAAO,WAAW,KAAA,KAAa,OAAO,IAAI,OAAO,GAAG,OAAO,IAAI,OAAO,CAAC,CAAE,SAAS,KAAK,IAAI,OAAO,QAAQ,CAAC;CAC/G,IAAI,OAAO,WAAW,KAAA,GAAW,OAAO,SAAS,KAAK,IAAI,KAAK,MAAM,OAAO,YAAY,MAAM,OAAO,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC;CACtH,IAAI,OAAO,SAAS,KAAA,GAAW,OAAO,OAAO,KAAK,MAAM,OAAO,UAAU,MAAM,OAAO,MAAM,GAAG,CAAC,CAAC;AAClG;;;;;;;;;AAUA,SAAgB,eAAe,OAAc,QAAmB,KAAuB;CACtF,MAAM,SAAS,MAAM,MAAM,OAAO,MAAM,OAAO,OAAO,QAAQ;EAC7D,QAAQ,OAAO;EACf,OAAO,OAAO;EACd,MAAM,OAAO;EACb,MAAM,OAAO;EACb,UAAU,OAAO;EACjB,mBAAmB,OAAO;CAC3B,CAAC;CACD,QAAQ,OAAO,QAAQ,MAAM;CAC7B,IAAI,OAAO,OAAO,OAAO,IAAI,UAAU,OAAO,KAAK;CACnD,MAAM,OAAO,cAAc,MAAM,UAAU,QAAQ,GAAG;CAEtD,KAAK,MAAM,aAAa,MAAM,SAAS,iBAAiB,GACvD,IAAI,UAAU,SAAS,UAAU,MAAM,MAAM,OAAO,IAAI,WAAW,gBAAgB,KAAK,UAAU,GAAG,CAAC;CAGvG,IAAI,MAAM,MAAM,IAAI,WAAW,GAAG,MAAM,MAAM,IAAI,aAAa;EAAE;EAAQ;EAAQ;CAAK,CAAC;CACvF,MAAM,QAAQ,IAAI,OAAO,IAAI,OAAO,EAAE;CACtC,OAAO;AACR;;;;;;;AAQA,SAAgB,cAAc,OAAc,QAAgB,QAAyC;CACpG,IAAI,QAAQ;CACZ,KAAK,MAAM,EAAE,MAAM,MAAM,WAAW,QAAQ;EAC3C,MAAM,OACL,SAAS,SACN,EAAE,MAAM,OAAgB,IACxB,OACC;GAAE,MAAM,SAAS,WAAY,eAA0B;GAAwB;EAAK,IACpF,QACC;GAAE,MAAM,SAAS,WAAY,WAAsB;GAAkB,OAAO;IAAE,GAAG,MAAM;IAAG,GAAG,MAAM;GAAE;EAAE,IACvG,KAAA;EAEN,IAAI,CAAC,MAAM;EACX,MAAM,QAAQ,YAAY,OAAO,IAAa;EAC9C,IAAI,CAAC,MAAM,SAAS,MAAM,KAAK,IAAI,CAAC,CAAC,QAAQ,OAAO,QAAQ,IAAa,GAAG;EAC5E,UAAU,OAAO,QAAQ,OAAO,KAAK;EACrC,QAAQ;CACT;AACD"}

package/dist/math.d.ts

@@ -1,17 +1,31 @@
 /**
  * A point on the ground plane. The simulation is 2D; height always comes from the terrain.
  *
- * @beta
+ * @public
  */
 export interface Vec2 {
+    /** The point's place on the ground plane's x axis */
     x: number;
+    /** The point's place on the ground plane's z axis */
     z: number;
 }
-/** @beta */
+/**
+ * Makes a point from an x and a z, both 0 when left out
+ *
+ * @beta
+ */
 export declare const vec2: (x?: number, z?: number) => Vec2;
-/** @beta */
+/**
+ * Keeps a number between `min` and `max`: returns `min` below it, `max` above it
+ *
+ * @beta
+ */
 export declare const clamp: (v: number, min: number, max: number) => number;
-/** @beta */
+/**
+ * Goes from `a` to `b` by `t` (0 gives `a`, 1 gives `b`); `t` is not limited to 0..1
+ *
+ * @beta
+ */
 export declare const lerp: (a: number, b: number, t: number) => number;
 /**
  * 0 at `from` and before, 1 at `to` and after, eased in and out between: a shader's `smoothstep`
@@ -25,11 +39,23 @@ export declare const smoothstep: (from: number, to: number, x: number) => number
  * @beta
  */
 export declare function hashInts(a: number, b: number): number;
-/** @beta */
+/**
+ * The squared distance between two points, for comparing distances without a square root
+ *
+ * @beta
+ */
 export declare const distSq: (a: Vec2, b: Vec2) => number;
-/** @beta */
+/**
+ * The distance between two points on the ground plane
+ *
+ * @beta
+ */
 export declare const dist: (a: Vec2, b: Vec2) => number;
-/** @beta */
+/**
+ * Goes from angle `a` to angle `b` by `t` the short way round, in radians
+ *
+ * @beta
+ */
 export declare const lerpAngle: (a: number, b: number, t: number) => number;
 /**
  * Axis aligned rectangle on the ground plane, described by its center and half sizes.
@@ -37,8 +63,12 @@ export declare const lerpAngle: (a: number, b: number, t: number) => number;
  * @beta
  */
 export interface Rect {
+    /** The rectangle's centre on the x axis */
     x: number;
+    /** The rectangle's centre on the z axis */
     z: number;
+    /** Half the rectangle's size along x */
     hw: number;
+    /** Half the rectangle's size along z */
     hd: number;
 }

package/dist/math.js

@@ -0,0 +1,155 @@
+import { atan2 } from "./exactMath.js";
+//#region src/math.ts
+/**
+* Twice pi, a full turn in radians
+*
+* @internal
+*/
+var TAU = Math.PI * 2;
+/**
+* Makes a point from an x and a z, both 0 when left out
+*
+* @beta
+*/
+var vec2 = (x = 0, z = 0) => ({
+	x,
+	z
+});
+/**
+* Keeps a number between `min` and `max`: returns `min` below it, `max` above it
+*
+* @beta
+*/
+var clamp = (v, min, max) => v < min ? min : v > max ? max : v;
+/**
+* Goes from `a` to `b` by `t` (0 gives `a`, 1 gives `b`); `t` is not limited to 0..1
+*
+* @beta
+*/
+var lerp = (a, b, t) => a + (b - a) * t;
+/**
+* 0 at `from` and before, 1 at `to` and after, eased in and out between: a shader's `smoothstep`
+*
+* @beta
+*/
+var smoothstep = (from, to, x) => {
+	const t = clamp((x - from) / (to - from), 0, 1);
+	return t * t * (3 - 2 * t);
+};
+/**
+* A number in 0..1 for two whole numbers, the same each time and in every engine (it is integer arithmetic)
+*
+* @beta
+*/
+function hashInts(a, b) {
+	let h = Math.imul(a ^ 2654435769, 2246822507) ^ Math.imul(b, 3266489909);
+	h ^= h >>> 16;
+	h = Math.imul(h, 2146121005);
+	h ^= h >>> 15;
+	return (h >>> 0) / 4294967295;
+}
+/**
+* cyrb53: a 53-bit hash of text, the same in every engine (it is integer arithmetic)
+*
+* @internal
+*/
+function hashText(text) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < text.length; i++) {
+		const c = text.charCodeAt(i);
+		h1 = Math.imul(h1 ^ c, 2654435761);
+		h2 = Math.imul(h2 ^ c, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, "0");
+}
+/**
+* The squared distance between two points, for comparing distances without a square root
+*
+* @beta
+*/
+var distSq = (a, b) => {
+	const dx = a.x - b.x;
+	const dz = a.z - b.z;
+	return dx * dx + dz * dz;
+};
+/**
+* The distance between two points on the ground plane
+*
+* @beta
+*/
+var dist = (a, b) => Math.sqrt(distSq(a, b));
+/**
+* Facing angle (radians) of the direction from `a` to `b`. 0 faces +z, increasing towards +x.
+*
+* @internal
+*/
+var angleTo = (a, b) => atan2(b.x - a.x, b.z - a.z);
+/**
+* Shortest signed difference between two angles, in (-PI, PI].
+*
+* @internal
+*/
+var angleDiff = (from, to) => {
+	let d = (to - from) % TAU;
+	if (d > Math.PI) d -= TAU;
+	else if (d <= -Math.PI) d += TAU;
+	return d;
+};
+/**
+* Turns the angle `from` towards `to` by at most `maxStep` radians, the short way round, and returns the new angle
+*
+* @internal
+*/
+var rotateTowards = (from, to, maxStep) => {
+	const d = angleDiff(from, to);
+	if (Math.abs(d) <= maxStep) return to;
+	return from + Math.sign(d) * maxStep;
+};
+/**
+* Goes from angle `a` to angle `b` by `t` the short way round, in radians
+*
+* @beta
+*/
+var lerpAngle = (a, b, t) => a + angleDiff(a, b) * t;
+/**
+* Distance from a point to the edge of a rectangle. 0 when the point is inside.
+*
+* @internal
+*/
+var distToRect = (p, r) => {
+	const dx = Math.max(Math.abs(p.x - r.x) - r.hw, 0);
+	const dz = Math.max(Math.abs(p.z - r.z) - r.hd, 0);
+	return Math.sqrt(dx * dx + dz * dz);
+};
+/**
+* Closest point to `p` on the border of `r` grown by `margin`. Points inside are pushed out through the nearest side.
+*
+* @internal
+*/
+var closestPointOnRect = (p, r, margin = 0) => {
+	const hw = r.hw + margin;
+	const hd = r.hd + margin;
+	const lx = p.x - r.x;
+	const lz = p.z - r.z;
+	if (Math.abs(lx) < hw && Math.abs(lz) < hd) {
+		if (hw - Math.abs(lx) < hd - Math.abs(lz)) return {
+			x: r.x + (lx < 0 ? -hw : hw),
+			z: p.z
+		};
+		return {
+			x: p.x,
+			z: r.z + (lz < 0 ? -hd : hd)
+		};
+	}
+	return {
+		x: r.x + clamp(lx, -hw, hw),
+		z: r.z + clamp(lz, -hd, hd)
+	};
+};
+//#endregion
+export { TAU, angleDiff, angleTo, clamp, closestPointOnRect, dist, distSq, distToRect, hashInts, hashText, lerp, lerpAngle, rotateTowards, smoothstep, vec2 };
+
+//# sourceMappingURL=math.js.map

package/dist/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","names":[],"sources":["../src/math.ts"],"sourcesContent":["import { atan2 } from './exactMath'\n/**\n * A point on the ground plane. The simulation is 2D; height always comes from the terrain.\n *\n * @public\n */\nexport interface Vec2 {\n\t/** The point's place on the ground plane's x axis */\n\tx: number\n\t/** The point's place on the ground plane's z axis */\n\tz: number\n}\n\n/**\n * Twice pi, a full turn in radians\n *\n * @internal\n */\nexport const TAU = Math.PI * 2\n\n/**\n * Makes a point from an x and a z, both 0 when left out\n *\n * @beta\n */\nexport const vec2 = (x = 0, z = 0): Vec2 => ({ x, z })\n\n/**\n * Keeps a number between `min` and `max`: returns `min` below it, `max` above it\n *\n * @beta\n */\nexport const clamp = (v: number, min: number, max: number) => (v < min ? min : v > max ? max : v)\n\n/**\n * Goes from `a` to `b` by `t` (0 gives `a`, 1 gives `b`); `t` is not limited to 0..1\n *\n * @beta\n */\nexport const lerp = (a: number, b: number, t: number) => a + (b - a) * t\n\n/**\n * 0 at `from` and before, 1 at `to` and after, eased in and out between: a shader's `smoothstep`\n *\n * @beta\n */\nexport const smoothstep = (from: number, to: number, x: number) => {\n\tconst t = clamp((x - from) / (to - from), 0, 1)\n\treturn t * t * (3 - 2 * t)\n}\n\n/**\n * A number in 0..1 for two whole numbers, the same each time and in every engine (it is integer arithmetic)\n *\n * @beta\n */\nexport function hashInts(a: number, b: number): number {\n\tlet h = Math.imul(a ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul(b, 0xc2b2ae35)\n\th ^= h >>> 16\n\th = Math.imul(h, 0x7feb352d)\n\th ^= h >>> 15\n\treturn (h >>> 0) / 0xffffffff\n}\n\n/**\n * cyrb53: a 53-bit hash of text, the same in every engine (it is integer arithmetic)\n *\n * @internal\n */\nexport function hashText(text: string): string {\n\tlet h1 = 0xdeadbeef\n\tlet h2 = 0x41c6ce57\n\tfor (let i = 0; i < text.length; i++) {\n\t\tconst c = text.charCodeAt(i)\n\t\th1 = Math.imul(h1 ^ c, 2654435761)\n\t\th2 = Math.imul(h2 ^ c, 1597334677)\n\t}\n\th1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909)\n\th2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909)\n\treturn (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, '0')\n}\n\n/**\n * The squared distance between two points, for comparing distances without a square root\n *\n * @beta\n */\nexport const distSq = (a: Vec2, b: Vec2) => {\n\tconst dx = a.x - b.x\n\tconst dz = a.z - b.z\n\treturn dx * dx + dz * dz\n}\n\n/**\n * The distance between two points on the ground plane\n *\n * @beta\n */\nexport const dist = (a: Vec2, b: Vec2) => Math.sqrt(distSq(a, b))\n\n/**\n * Facing angle (radians) of the direction from `a` to `b`. 0 faces +z, increasing towards +x.\n *\n * @internal\n */\nexport const angleTo = (a: Vec2, b: Vec2) => atan2(b.x - a.x, b.z - a.z)\n\n/**\n * Shortest signed difference between two angles, in (-PI, PI].\n *\n * @internal\n */\nexport const angleDiff = (from: number, to: number) => {\n\tlet d = (to - from) % TAU\n\tif (d > Math.PI) d -= TAU\n\telse if (d <= -Math.PI) d += TAU\n\treturn d\n}\n\n/**\n * Turns the angle `from` towards `to` by at most `maxStep` radians, the short way round, and returns the new angle\n *\n * @internal\n */\nexport const rotateTowards = (from: number, to: number, maxStep: number) => {\n\tconst d = angleDiff(from, to)\n\tif (Math.abs(d) <= maxStep) return to\n\treturn from + Math.sign(d) * maxStep\n}\n\n/**\n * Goes from angle `a` to angle `b` by `t` the short way round, in radians\n *\n * @beta\n */\nexport const lerpAngle = (a: number, b: number, t: number) => a + angleDiff(a, b) * t\n\n/**\n * Axis aligned rectangle on the ground plane, described by its center and half sizes.\n *\n * @beta\n */\nexport interface Rect {\n\t/** The rectangle's centre on the x axis */\n\tx: number\n\t/** The rectangle's centre on the z axis */\n\tz: number\n\t/** Half the rectangle's size along x */\n\thw: number\n\t/** Half the rectangle's size along z */\n\thd: number\n}\n\n/**\n * Distance from a point to the edge of a rectangle. 0 when the point is inside.\n *\n * @internal\n */\nexport const distToRect = (p: Vec2, r: Rect) => {\n\tconst dx = Math.max(Math.abs(p.x - r.x) - r.hw, 0)\n\tconst dz = Math.max(Math.abs(p.z - r.z) - r.hd, 0)\n\treturn Math.sqrt(dx * dx + dz * dz)\n}\n\n/**\n * Closest point to `p` on the border of `r` grown by `margin`. Points inside are pushed out through the nearest side.\n *\n * @internal\n */\nexport const closestPointOnRect = (p: Vec2, r: Rect, margin = 0): Vec2 => {\n\tconst hw = r.hw + margin\n\tconst hd = r.hd + margin\n\tconst lx = p.x - r.x\n\tconst lz = p.z - r.z\n\tif (Math.abs(lx) < hw && Math.abs(lz) < hd) {\n\t\t// inside: exit through the closest side\n\t\tif (hw - Math.abs(lx) < hd - Math.abs(lz)) return { x: r.x + (lx < 0 ? -hw : hw), z: p.z }\n\t\treturn { x: p.x, z: r.z + (lz < 0 ? -hd : hd) }\n\t}\n\treturn { x: r.x + clamp(lx, -hw, hw), z: r.z + clamp(lz, -hd, hd) }\n}\n"],"mappings":";;;;;;;AAkBA,IAAa,MAAM,KAAK,KAAK;;;;;;AAO7B,IAAa,QAAQ,IAAI,GAAG,IAAI,OAAa;CAAE;CAAG;AAAE;;;;;;AAOpD,IAAa,SAAS,GAAW,KAAa,QAAiB,IAAI,MAAM,MAAM,IAAI,MAAM,MAAM;;;;;;AAO/F,IAAa,QAAQ,GAAW,GAAW,MAAc,KAAK,IAAI,KAAK;;;;;;AAOvE,IAAa,cAAc,MAAc,IAAY,MAAc;CAClE,MAAM,IAAI,OAAO,IAAI,SAAS,KAAK,OAAO,GAAG,CAAC;CAC9C,OAAO,IAAI,KAAK,IAAI,IAAI;AACzB;;;;;;AAOA,SAAgB,SAAS,GAAW,GAAmB;CACtD,IAAI,IAAI,KAAK,KAAK,IAAI,YAAY,UAAU,IAAI,KAAK,KAAK,GAAG,UAAU;CACvE,KAAK,MAAM;CACX,IAAI,KAAK,KAAK,GAAG,UAAU;CAC3B,KAAK,MAAM;CACX,QAAQ,MAAM,KAAK;AACpB;;;;;;AAOA,SAAgB,SAAS,MAAsB;CAC9C,IAAI,KAAK;CACT,IAAI,KAAK;CACT,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACrC,MAAM,IAAI,KAAK,WAAW,CAAC;EAC3B,KAAK,KAAK,KAAK,KAAK,GAAG,UAAU;EACjC,KAAK,KAAK,KAAK,KAAK,GAAG,UAAU;CAClC;CACA,KAAK,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU,IAAI,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CACrF,KAAK,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU,IAAI,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CACrF,QAAQ,cAAc,UAAU,OAAO,OAAO,GAAA,CAAI,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,GAAG;AAChF;;;;;;AAOA,IAAa,UAAU,GAAS,MAAY;CAC3C,MAAM,KAAK,EAAE,IAAI,EAAE;CACnB,MAAM,KAAK,EAAE,IAAI,EAAE;CACnB,OAAO,KAAK,KAAK,KAAK;AACvB;;;;;;AAOA,IAAa,QAAQ,GAAS,MAAY,KAAK,KAAK,OAAO,GAAG,CAAC,CAAC;;;;;;AAOhE,IAAa,WAAW,GAAS,MAAY,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;;;;;;AAOvE,IAAa,aAAa,MAAc,OAAe;CACtD,IAAI,KAAK,KAAK,QAAQ;CACtB,IAAI,IAAI,KAAK,IAAI,KAAK;MACjB,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK;CAC7B,OAAO;AACR;;;;;;AAOA,IAAa,iBAAiB,MAAc,IAAY,YAAoB;CAC3E,MAAM,IAAI,UAAU,MAAM,EAAE;CAC5B,IAAI,KAAK,IAAI,CAAC,KAAK,SAAS,OAAO;CACnC,OAAO,OAAO,KAAK,KAAK,CAAC,IAAI;AAC9B;;;;;;AAOA,IAAa,aAAa,GAAW,GAAW,MAAc,IAAI,UAAU,GAAG,CAAC,IAAI;;;;;;AAuBpF,IAAa,cAAc,GAAS,MAAY;CAC/C,MAAM,KAAK,KAAK,IAAI,KAAK,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;CACjD,MAAM,KAAK,KAAK,IAAI,KAAK,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;CACjD,OAAO,KAAK,KAAK,KAAK,KAAK,KAAK,EAAE;AACnC;;;;;;AAOA,IAAa,sBAAsB,GAAS,GAAS,SAAS,MAAY;CACzE,MAAM,KAAK,EAAE,KAAK;CAClB,MAAM,KAAK,EAAE,KAAK;CAClB,MAAM,KAAK,EAAE,IAAI,EAAE;CACnB,MAAM,KAAK,EAAE,IAAI,EAAE;CACnB,IAAI,KAAK,IAAI,EAAE,IAAI,MAAM,KAAK,IAAI,EAAE,IAAI,IAAI;EAE3C,IAAI,KAAK,KAAK,IAAI,EAAE,IAAI,KAAK,KAAK,IAAI,EAAE,GAAG,OAAO;GAAE,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,KAAK;GAAK,GAAG,EAAE;EAAE;EACzF,OAAO;GAAE,GAAG,EAAE;GAAG,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,KAAK;EAAI;CAC/C;CACA,OAAO;EAAE,GAAG,EAAE,IAAI,MAAM,IAAI,CAAC,IAAI,EAAE;EAAG,GAAG,EAAE,IAAI,MAAM,IAAI,CAAC,IAAI,EAAE;CAAE;AACnE"}

package/dist/messages.d.ts

@@ -9,10 +9,16 @@
  * @beta
  */
 export interface Message {
+    /** The message's key, which the player's screen has words for (`EngineMessages` for the engine's, a game's own otherwise) */
     key: string;
+    /** What the words name or count, by param name; ids for what is a resource, a unit type or an upgrade */
     params?: MessageParams;
 }
-/** @beta */
+/**
+ * The values a message's params can hold: a string, a number or a list of strings
+ *
+ * @beta
+ */
 export type MessageParams = Record<string, string | number | string[]>;
 /**
  * A message, or a bare key for one without params. What hooks give as the reason something is called off
@@ -20,7 +26,11 @@ export type MessageParams = Record<string, string | number | string[]>;
  * @beta
  */
 export type MessageRef = Message | string;
-/** @beta */
+/**
+ * Turns a `MessageRef` into a `Message`: a bare key becomes `{ key }`, a message is returned as it is
+ *
+ * @beta
+ */
 export declare const toMessage: (message: MessageRef) => Message;
 /**
  * The messages the engine sends, and their params. The client has words for each of these.
@@ -41,18 +51,23 @@ export interface EngineMessages {
     requires: {
         units: string[];
     };
+    /** A building's or hero's production queue has no room for more */
     queueFull: {};
+    /** The player already has the hero being asked for */
     alreadyHaveHero: {};
+    /** The player has as many heroes as the rules allow (`RuleSettings.heroes`) */
     tooManyHeroes: {};
-    /** Out of supply, and could build more of what provides it. `pool` for one of the game's own (`GameRules.supply.pools`) */
+    /** Out of supply, and could build more of what provides it. `pool` for one of the game's own (`RuleSettings.supply.pools`) */
     supplyBlocked: {
         pool?: string;
     };
-    /** Out of supply, and at the most anyone can have (`GameRules.supply.max`, a pool's `max`) */
+    /** Out of supply, and at the most anyone can have (`RuleSettings.supply.max`, a pool's `max`) */
     supplyLimit: {
         pool?: string;
     };
+    /** The upgrade being asked for is already being researched */
     alreadyResearching: {};
+    /** Research of the upgrade finished; `upgrade` is its id */
     researchDone: {
         upgrade: string;
     };
@@ -61,6 +76,7 @@ export interface EngineMessages {
         unit: string;
         level: number;
     };
+    /** The player has lost the game */
     defeated: {};
     /** Another player gave up. `player` is their name */
     surrendered: {
@@ -68,23 +84,46 @@ export interface EngineMessages {
     };
     /** Every pause of the player's is used */
     noPausesLeft: {};
+    /** A structure cannot be placed at that spot */
     cannotBuildThere: {};
     /** The navigation has no room for another building in the way (`RecastNavigationOptions.maxObstacles`) */
     tooManyBuildings: {};
+    /** A worker could not find a way to the building site */
     cannotReachSite: {};
+    /** A unit could not find a way to where it was sent */
     cannotReach: {};
     /** A worker with something to bring back and nowhere to bring it. `resource` is its id */
     nowhereToReturn: {
         resource: string;
     };
+    /** A worker cannot gather from a resource of that id */
     cannotGather: {
         resource: string;
     };
+    /** A structure cannot be placed on a resource of that id */
     buildOnResource: {
         resource: string;
     };
+    /** The unit's inventory has no free slot */
     inventoryFull: {};
+    /** The inventory of the unit it is given to has no free slot */
     theirInventoryFull: {};
+    /**
+     * The carrier has as many of the item's group as it may (`ItemDef.group`, `groupLimit`): one pair of boots. `item`
+     * is the item's id, `group` the group's, `limit` how many it may carry
+     */
+    groupLimit: {
+        item: string;
+        group: string;
+        limit: number;
+    };
+    /** The unit it is handed to has as many of the item's group as it may (`groupLimit`'s params) */
+    theirGroupLimit: {
+        item: string;
+        group: string;
+        limit: number;
+    };
+    /** A shop is out of the item */
     outOfStock: {};
     /** Buying needs one of the player's heroes at the shop, with a free slot */
     heroAtShop: {};
@@ -94,19 +133,46 @@ export interface EngineMessages {
     alreadyHired: {
         unit: string;
     };
+    /** No shop is near enough for the buyer */
     noShopNear: {};
+    /** No purchase to undo (`undoBuy`): none within the time, the hero away from the shop, the item used */
+    nothingToUndo: {};
+    /** The thing asked for cannot be done, the engine's word where a handler gave no reason */
     cannotDoThat: {};
+    /** The ability or action is not ready yet, such as on cooldown */
     notReady: {};
+    /** An item that refills has none of its charges now (`ItemDef.refill`) */
+    noCharges: {};
+    /** The caster has too little mana */
     notEnoughMana: {};
+    /** The caster has too little health to pay what the ability costs */
     notEnoughHealth: {};
+    /** The game has no buyback for this hero (`HeroSettings.buybackCost`) */
+    noBuyback: {};
+    /** The hero was bought back a moment ago, and may be again in so many seconds */
+    buybackNotReady: {
+        seconds: number;
+    };
+    /** The caster is silenced and cannot cast */
     silenced: {};
+    /** An ability that rushes or jumps the caster, which a buff keeps from it (`BuffDef.grounded`) */
+    grounded: {};
+    /** A recast that goes to the unit the cast marked (`AbilityRecast.mark`), while none carries the mark */
+    noMark: {};
     /** An ability used on something it is not for */
     cannotTargetThat: {};
+    /** An ability used on a friend that does not target friends */
     cannotTargetFriends: {};
+    /** An ability used on its caster that does not target itself */
     cannotTargetSelf: {};
+    /** An ability used on a flying unit that does not hit the air */
     cannotTargetAir: {};
+    /** An ability used on a unit that is not flying but needs a flying target */
     mustTargetAir: {};
+    /** An ability used on a unit that is not a hero but needs a hero */
     mustTargetHero: {};
+    /** An ability used on a hero that targets anything but heroes (`targets.heroes: false`) */
+    cannotTargetHero: {};
     /** An ability used on what is immune to spells */
     targetSpellImmune: {};
     /** Pinged too often: the rest go nowhere for a moment */
@@ -123,6 +189,7 @@ export interface EngineMessages {
         resource: string;
         player: string;
     };
+    /** Resources arrived from an ally: the `amount` of the `resource` from the `player` by name */
     received: {
         amount: number;
         resource: string;

package/dist/messages.js

@@ -0,0 +1,29 @@
+import { messageSent } from "./engineEvents.js";
+import { replicateEvent } from "./replication.js";
+//#region src/messages.ts
+/**
+* Turns a `MessageRef` into a `Message`: a bare key becomes `{ key }`, a message is returned as it is
+*
+* @beta
+*/
+var toMessage = (message) => typeof message === "string" ? { key: message } : message;
+/**
+* A message of the engine's own, with its params checked
+*
+* @beta
+*/
+var engineMessage = (key, ...params) => params.length ? {
+	key,
+	params: params[0]
+} : { key };
+/** A message, to whom it is for */
+var toldMessage = replicateEvent(messageSent, "message", (message, view) => message.player === view.player ? {
+	type: "message",
+	message: message.message,
+	kind: message.kind,
+	...message.seconds !== void 0 && { seconds: message.seconds }
+} : void 0);
+//#endregion
+export { engineMessage, toMessage, toldMessage };
+
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","names":[],"sources":["../src/messages.ts"],"sourcesContent":["import { messageSent } from '#engine/engineEvents'\nimport { replicateEvent } from './replication'\n/**\n * What the simulation tells a player, like \"Not enough gold\", is a key and some params, never words. The words are\n * the business of the player's screen: the client has English for the engine's keys, and a game's view gives its own\n * (`GameView.hud.messages`) or other words for the engine's. That keeps the engine free of any one language, and lets\n * a game say \"build more farms\" where the engine only knows about supply.\n *\n * Params that name something are ids (a resource, a unit type, an upgrade), for the screen to find the name of.\n *\n * @beta\n */\nexport interface Message {\n\t/** The message's key, which the player's screen has words for (`EngineMessages` for the engine's, a game's own otherwise) */\n\tkey: string\n\t/** What the words name or count, by param name; ids for what is a resource, a unit type or an upgrade */\n\tparams?: MessageParams\n}\n\n/**\n * The values a message's params can hold: a string, a number or a list of strings\n *\n * @beta\n */\nexport type MessageParams = Record<string, string | number | string[]>\n\n/**\n * A message, or a bare key for one without params. What hooks give as the reason something is called off\n *\n * @beta\n */\nexport type MessageRef = Message | string\n\n/**\n * Turns a `MessageRef` into a `Message`: a bare key becomes `{ key }`, a message is returned as it is\n *\n * @beta\n */\nexport const toMessage = (message: MessageRef): Message => (typeof message === 'string' ? { key: message } : message)\n\n/**\n * The messages the engine sends, and their params. The client has words for each of these.\n * A game can send keys of its own as well.\n *\n * @beta\n */\nexport interface EngineMessages {\n\t/** Cannot afford something: `resource` is the id of what is short */\n\tnotEnough: { resource: string }\n\t/** A prefab asked for by a name the game has not (`debug.spawnPrefab`) */\n\tunknownPrefab: { prefab: string }\n\t/** The unit types the player still needs to build to make or research something, by id */\n\trequires: { units: string[] }\n\t/** A building's or hero's production queue has no room for more */\n\tqueueFull: {}\n\t/** The player already has the hero being asked for */\n\talreadyHaveHero: {}\n\t/** The player has as many heroes as the rules allow (`RuleSettings.heroes`) */\n\ttooManyHeroes: {}\n\t/** Out of supply, and could build more of what provides it. `pool` for one of the game's own (`RuleSettings.supply.pools`) */\n\tsupplyBlocked: { pool?: string }\n\t/** Out of supply, and at the most anyone can have (`RuleSettings.supply.max`, a pool's `max`) */\n\tsupplyLimit: { pool?: string }\n\t/** The upgrade being asked for is already being researched */\n\talreadyResearching: {}\n\t/** Research of the upgrade finished; `upgrade` is its id */\n\tresearchDone: { upgrade: string }\n\t/** `unit` is the id of the hero's type */\n\theroLevel: { unit: string; level: number }\n\t/** The player has lost the game */\n\tdefeated: {}\n\t/** Another player gave up. `player` is their name */\n\tsurrendered: { player: string }\n\t/** Every pause of the player's is used */\n\tnoPausesLeft: {}\n\t/** A structure cannot be placed at that spot */\n\tcannotBuildThere: {}\n\t/** The navigation has no room for another building in the way (`RecastNavigationOptions.maxObstacles`) */\n\ttooManyBuildings: {}\n\t/** A worker could not find a way to the building site */\n\tcannotReachSite: {}\n\t/** A unit could not find a way to where it was sent */\n\tcannotReach: {}\n\t/** A worker with something to bring back and nowhere to bring it. `resource` is its id */\n\tnowhereToReturn: { resource: string }\n\t/** A worker cannot gather from a resource of that id */\n\tcannotGather: { resource: string }\n\t/** A structure cannot be placed on a resource of that id */\n\tbuildOnResource: { resource: string }\n\t/** The unit's inventory has no free slot */\n\tinventoryFull: {}\n\t/** The inventory of the unit it is given to has no free slot */\n\ttheirInventoryFull: {}\n\t/**\n\t * The carrier has as many of the item's group as it may (`ItemDef.group`, `groupLimit`): one pair of boots. `item`\n\t * is the item's id, `group` the group's, `limit` how many it may carry\n\t */\n\tgroupLimit: { item: string; group: string; limit: number }\n\t/** The unit it is handed to has as many of the item's group as it may (`groupLimit`'s params) */\n\ttheirGroupLimit: { item: string; group: string; limit: number }\n\t/** A shop is out of the item */\n\toutOfStock: {}\n\t/** Buying needs one of the player's heroes at the shop, with a free slot */\n\theroAtShop: {}\n\t/** Hiring needs one of the player's units at the place that hires */\n\tunitAtShop: {}\n\t/** A hero is hired once: the player has it already. `unit` is its type */\n\talreadyHired: { unit: string }\n\t/** No shop is near enough for the buyer */\n\tnoShopNear: {}\n\t/** No purchase to undo (`undoBuy`): none within the time, the hero away from the shop, the item used */\n\tnothingToUndo: {}\n\t/** The thing asked for cannot be done, the engine's word where a handler gave no reason */\n\tcannotDoThat: {}\n\t/** The ability or action is not ready yet, such as on cooldown */\n\tnotReady: {}\n\t/** An item that refills has none of its charges now (`ItemDef.refill`) */\n\tnoCharges: {}\n\t/** The caster has too little mana */\n\tnotEnoughMana: {}\n\t/** The caster has too little health to pay what the ability costs */\n\tnotEnoughHealth: {}\n\t/** The game has no buyback for this hero (`HeroSettings.buybackCost`) */\n\tnoBuyback: {}\n\t/** The hero was bought back a moment ago, and may be again in so many seconds */\n\tbuybackNotReady: { seconds: number }\n\t/** The caster is silenced and cannot cast */\n\tsilenced: {}\n\t/** An ability that rushes or jumps the caster, which a buff keeps from it (`BuffDef.grounded`) */\n\tgrounded: {}\n\t/** A recast that goes to the unit the cast marked (`AbilityRecast.mark`), while none carries the mark */\n\tnoMark: {}\n\t/** An ability used on something it is not for */\n\tcannotTargetThat: {}\n\t/** An ability used on a friend that does not target friends */\n\tcannotTargetFriends: {}\n\t/** An ability used on its caster that does not target itself */\n\tcannotTargetSelf: {}\n\t/** An ability used on a flying unit that does not hit the air */\n\tcannotTargetAir: {}\n\t/** An ability used on a unit that is not flying but needs a flying target */\n\tmustTargetAir: {}\n\t/** An ability used on a unit that is not a hero but needs a hero */\n\tmustTargetHero: {}\n\t/** An ability used on a hero that targets anything but heroes (`targets.heroes: false`) */\n\tcannotTargetHero: {}\n\t/** An ability used on what is immune to spells */\n\ttargetSpellImmune: {}\n\t/** Pinged too often: the rest go nowhere for a moment */\n\ttooManyPings: {}\n\t/** Said too much too quickly: the rest goes nowhere for a moment */\n\ttooManyLines: {}\n\t/** Sent commands faster than the game takes them (a server's rate, `World.commandLimit`): the rest went nowhere */\n\ttooManyCommands: {}\n\t/** Resources given to someone who is not an ally */\n\tnotAnAlly: {}\n\t/** Resources given to an ally, and received from one (see `give`) */\n\tsent: { amount: number; resource: string; player: string }\n\t/** Resources arrived from an ally: the `amount` of the `resource` from the `player` by name */\n\treceived: { amount: number; resource: string; player: string }\n\t/** One resource traded for another at a rate (see `exchange`): `amount` of `resource` went, `received` of `for` came */\n\texchanged: { amount: number; resource: string; received: number; for: string }\n\t/** A field of a definition the game does not let be changed, or a value it does not take (`debug.redefine`) */\n\tdataRefused: { why: string }\n}\n\n/**\n * A message of the engine's own, with its params checked\n *\n * @beta\n */\nexport const engineMessage = <K extends keyof EngineMessages>(\n\tkey: K,\n\t// a message whose params may all be left out takes them or not\n\t...params: {} extends EngineMessages[K] ? [] | [EngineMessages[K]] : [EngineMessages[K]]\n): Message => (params.length ? { key, params: params[0] as MessageParams } : { key })\n\n/** A message, to whom it is for */\nexport const toldMessage = replicateEvent(messageSent, 'message', (message, view) =>\n\tmessage.player === view.player\n\t\t? { type: 'message', message: message.message, kind: message.kind, ...(message.seconds !== undefined && { seconds: message.seconds }) }\n\t\t: undefined\n)\n"],"mappings":";;;;;;;;AAsCA,IAAa,aAAa,YAAkC,OAAO,YAAY,WAAW,EAAE,KAAK,QAAQ,IAAI;;;;;;AAqI7G,IAAa,iBACZ,KAEA,GAAG,WACW,OAAO,SAAS;CAAE;CAAK,QAAQ,OAAO;AAAoB,IAAI,EAAE,IAAI;;AAGnF,IAAa,cAAc,eAAe,aAAa,YAAY,SAAS,SAC3E,QAAQ,WAAW,KAAK,SACrB;CAAE,MAAM;CAAW,SAAS,QAAQ;CAAS,MAAM,QAAQ;CAAM,GAAI,QAAQ,YAAY,KAAA,KAAa,EAAE,SAAS,QAAQ,QAAQ;AAAG,IACpI,KAAA,CACJ"}

package/dist/missionRules.d.ts

@@ -34,13 +34,18 @@ export type MissionActionData =
         reason?: MessageRef;
     };
 }
-/** A line said (`world.dialog.say`): who speaks (a speaker of the view's), what (a message key, or the words), for how long */
+/**
+ * A line said (`world.dialog.say`): who speaks (a speaker of the view's), what (a message key, or the words), for how
+ * long; the unit that says it (by its name on the map: its face talks in the portrait box) and how (`emotion`)
+ */
  | {
     say: {
         speaker: string;
         text: MessageRef;
         seconds?: number;
         to?: PlayerId[];
+        unit?: string;
+        emotion?: string;
     };
 }
 /** A cinematic of the view's played (`playCinematic`), to everyone when `to` is left out */
@@ -115,7 +120,7 @@ export type MissionActionData =
 export interface MissionRule {
     /** What the log, the checks and the editor know it by; no two the same */
     id: string;
-    /** When it fires: plain data (`docs/ai.md`, "Conditions") */
+    /** When it fires: plain data (`docs/ai/scripting.md`, "Conditions") */
     when: AiConditionData;
     /** What it does, in order */
     do: MissionActionData[];
@@ -141,8 +146,11 @@ export declare const ruleFired: import("./events").EventKey<{
  * @beta
  */
 export interface MissionRuleState {
+    /** Whether the rule's condition held at the last check */
     holds: boolean;
+    /** How many times the rule has fired */
     count: number;
+    /** The tick the rule last fired at; left out when it has not */
     fired?: number;
 }
 /**