@v12-engine/engine 0.1.1 → 0.4.0

package/dist/determinism.js

@@ -0,0 +1,247 @@
+import { hashText } from "./math.js";
+import { teamMemory } from "./session/memory.js";
+import { fighting } from "./entity.js";
+import { decodeSave, encodeSave, saveWorld } from "./save.js";
+import { loadWorld } from "./game.js";
+//#region src/determinism.ts
+/**
+* Whether a game comes out the same (determinism plan D1): the simulation's state as data and as a hash, and a check
+* that runs a world twice, and on from a save, and says the first tick and the first thing they differ at. What a
+* replay of commands, a save that goes on exactly and a game the same in every browser stand on
+*/
+/**
+* The simulation's state as plain data: its save, which holds all of it, but what each team's screens remember of the
+* map, which is the watchers' (`teamMemory`)
+*
+* @beta
+*/
+function worldState(world) {
+	return decided(saveWorld(world, { reseat: false }), world.registry);
+}
+/**
+* A save as what decides the game: without what each team's screens remember of the map (`teamMemory`: kept in the
+* world for who comes back, written by whoever watches it, and read by nothing that decides), and, with the rules, the
+* components nobody would have made had nobody asked for them (`unasked`)
+*/
+function decided(save, registry) {
+	const { [teamMemory.id]: _memory, ...state } = save.state;
+	const kept = (components) => registry ? unasked(registry, components) : components;
+	return {
+		...save,
+		state: kept(state),
+		players: save.players.map((player) => ({
+			...player,
+			state: kept(player.state)
+		})),
+		entities: save.entities.map((entity) => entity.components ? {
+			...entity,
+			components: kept(entity.components)
+		} : entity)
+	};
+}
+/**
+* Where two saves of a game first differ, as `checkDeterminism` looks (what decides first: the tick, the random state,
+* the players, the entities): the path to it (`entities[id 11].pos.x`) and what each holds there, or nothing when they
+* are the same. What the screens remember of the map, and the hash of the rules they were made with, are left out;
+* with the game's `registry`, so are components that hold what they are made with (a screen asking for one makes it).
+* What a replay that came apart says at its checkpoints (`runReplay`), and `v12 save diff`
+*
+* @beta
+*/
+function saveDifference(a, b, registry) {
+	const ordered = (save) => {
+		const { hash: _rules, ...state } = decided(save, registry);
+		return {
+			...Object.fromEntries(FIRST.map((key) => [key, state[key]])),
+			...state
+		};
+	};
+	return firstDifference(ordered(a), ordered(b));
+}
+/**
+* Components as they would be had nobody asked for one that was not there: one that holds what its component makes
+* when asked for (its `default`) is left out. Asking makes one, and a watcher's screen asks for what it shows (a
+* player's objectives), so a world watched and the same world unwatched differ in that alone
+*/
+function unasked(registry, components) {
+	const kept = {};
+	for (const [id, value] of Object.entries(components)) {
+		const made = registry.component(id)?.default?.();
+		if (made !== void 0 && JSON.stringify(made) === JSON.stringify(value)) continue;
+		kept[id] = value;
+	}
+	return kept;
+}
+/**
+* The simulation's state as a hash: two worlds with the same hash are, to all that is saved of them, the same. Fourteen
+* hex digits (cyrb53, of the save as JSON, but the hash of the rules, which another build of the same code writes
+* otherwise): enough to tell drift, not to stand against someone forging a state
+*
+* @beta
+*/
+var worldHash = (world) => {
+	const { hash: _rules, ...state } = worldState(world);
+	return hashText(canonical(state));
+};
+/**
+* JSON with the keys of every object in order: the same state as text however it was put together (a component a
+* watcher made early comes first in its object, and later where nobody watched)
+*/
+function canonical(value) {
+	return JSON.stringify(value, (_key, each) => {
+		if (!each || typeof each !== "object" || Array.isArray(each)) return each;
+		const sorted = {};
+		for (const key of Object.keys(each).sort()) sorted[key] = each[key];
+		return sorted;
+	});
+}
+/**
+* A quick hash of what a game that came apart differs in first: the tick, the random state, each player's resources,
+* upgrades and supply, and each entity's id, type, owner, place, facing, health, mana, whether it lives, its orders (how
+* many, and the first's kind and target), its buffs (which, and the time left) and its attack's cooldown and swing. Read
+* off the world as it is, with no save: 0.4 ms at 1000 units a side, where `worldHash` takes 66. What a
+* replay of commands keeps every few seconds and checks as it plays (`recordCommands`), and what `checkDeterminism`
+* compares every tick, for the tick a game came apart at; what it leaves out (components, areas, the fog) the whole
+* state, compared every so often, has
+*
+* @beta
+*/
+function worldFingerprint(world) {
+	const values = [world.tick, world.rng.save()];
+	for (const player of world.players.values()) {
+		values.push(player.id, player.supplyUsed, player.supplyCap);
+		for (const key of Object.keys(player.resources).sort()) values.push(player.resources[key] ?? 0);
+		for (const [upgrade, level] of player.upgrades) values.push(wordOf(upgrade), level);
+	}
+	for (const entity of world.entities.values()) {
+		values.push(entity.id, wordOf(entity.def.id), entity.owner, entity.pos.x, entity.pos.z, entity.facing, entity.health, entity.mana, entity.alive ? 1 : 0);
+		const order = entity.orders[0];
+		values.push(entity.orders.length, order ? wordOf(order.type) : 0, order?.init.target ?? 0);
+		values.push(entity.buffs.length);
+		for (const buff of entity.buffs) values.push(wordOf(buff.id), buff.remaining);
+		if (entity.get(fighting)) values.push(entity.get(fighting).cooldown, entity.get(fighting).swing);
+	}
+	return hashWords(new Uint32Array(Float64Array.from(values).buffer));
+}
+/** A short text as a number, for the fingerprint: FNV-1a of its characters */
+function wordOf(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+	return h >>> 0;
+}
+/** cyrb53 of 32-bit words: the bits of numbers, hashed as they are */
+function hashWords(words) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (const word of words) {
+		h1 = Math.imul(h1 ^ word, 2654435761);
+		h2 = Math.imul(h2 ^ word, 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");
+}
+/**
+* Where two states first differ: the path to it (`entities[id 11].pos.x`) and what each holds there. Nothing when they
+* are the same. Lists of things with an `id` are named by it, the rest by their place
+*
+* @beta
+*/
+function firstDifference(a, b, path = "") {
+	if (Object.is(a, b)) return void 0;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) return {
+		path,
+		a,
+		b
+	};
+	if (Array.isArray(a) && Array.isArray(b)) {
+		for (let i = 0; i < Math.max(a.length, b.length); i++) {
+			const each = a[i] ?? b[i];
+			const named = each && typeof each === "object" && "id" in each ? `[id ${String(each.id)}]` : `[${i}]`;
+			const found = firstDifference(a[i], b[i], `${path}${named}`);
+			if (found) return found;
+		}
+		return;
+	}
+	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const key of keys) {
+		const found = firstDifference(a[key], b[key], path ? `${path}.${key}` : key);
+		if (found) return found;
+	}
+}
+/**
+* Makes a world twice with `make` (the same seed, the same commands given in it, as a replay would) and runs them side
+* by side, comparing their fingerprints every tick and their states (and the order each player's entities are filed
+* in) every `every` ticks; with `from`, a third is saved at that tick and a fourth loaded
+* from the save, and the two run on side by side. Says, for each, the first tick and thing it differs at, or that it does not. A test of a game's
+* own systems: one that reads `Math.random`, the clock, or the order of something unordered is found here
+*
+*     const report = await checkDeterminism(() => makeMyGame(1), { ticks: 1800, from: 300, rules })
+*     expect(report).toEqual({ twice: null, fromSave: null })
+*
+* @public
+*/
+async function checkDeterminism(make, options) {
+	const { ticks, every = 30, from } = options;
+	if (from !== void 0 && !options.rules) throw new Error("checkDeterminism: a check from a save needs the game to load it with (game)");
+	const first = await make();
+	const second = await make();
+	const saved = from === void 0 ? void 0 : await make();
+	let loaded;
+	const report = {
+		twice: null,
+		...from !== void 0 && { fromSave: null }
+	};
+	try {
+		for (let tick = 1; tick <= ticks; tick++) {
+			first.step();
+			if (!report.twice) second.step();
+			if (saved && !report.fromSave) {
+				saved.step();
+				loaded?.step();
+				if (saved.tick === from) loaded = await loadWorld(decodeSave(encodeSave(saveWorld(saved))), { rules: options.rules });
+			}
+			const whole = tick % every === 0;
+			if (!report.twice && (whole || worldFingerprint(first) !== worldFingerprint(second))) report.twice = apartAt(first.tick, compared(first), compared(second));
+			if (loaded && !report.fromSave && saved.tick > from && (whole || worldFingerprint(saved) !== worldFingerprint(loaded))) report.fromSave = apartAt(saved.tick, compared(saved), compared(loaded));
+			if (report.twice && (from === void 0 || report.fromSave)) break;
+		}
+	} finally {
+		first.dispose();
+		second.dispose();
+		saved?.dispose();
+		loaded?.dispose();
+	}
+	return report;
+}
+var compared = (world) => ({
+	...worldState(world),
+	owned: Object.fromEntries([...world.players.keys()].map((player) => [player, [...world.index.ownedBy(player)].map((entity) => entity.id)]))
+});
+/**
+* What is looked at first: what is decided (the random state, the players, the entities, the order they are filed in)
+* before what follows from it (the fog, which units see), so that what is said is where it began
+*/
+var FIRST = [
+	"tick",
+	"rng",
+	"players",
+	"entities",
+	"owned",
+	"units"
+];
+var apartAt = (tick, a, b) => {
+	const ordered = (state) => ({
+		...Object.fromEntries(FIRST.map((key) => [key, state[key]])),
+		...state
+	});
+	const found = firstDifference(ordered(a), ordered(b));
+	return found ? {
+		tick,
+		...found
+	} : null;
+};
+//#endregion
+export { checkDeterminism, firstDifference, saveDifference, worldFingerprint, worldHash, worldState };
+
+//# sourceMappingURL=determinism.js.map

package/dist/determinism.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"determinism.js","names":[],"sources":["../src/determinism.ts"],"sourcesContent":["/**\n * Whether a game comes out the same (determinism plan D1): the simulation's state as data and as a hash, and a check\n * that runs a world twice, and on from a save, and says the first tick and the first thing they differ at. What a\n * replay of commands, a save that goes on exactly and a game the same in every browser stand on\n */\nimport { type Rules, loadWorld } from './game'\nimport { decodeSave, encodeSave, saveWorld, type WorldSave } from './save'\nimport type { Registry } from './registry'\nimport { teamMemory } from './session/memory'\nimport type { World } from './world'\nimport { fighting } from './entity'\nimport { hashText } from './math'\n\n/**\n * The simulation's state as plain data: its save, which holds all of it, but what each team's screens remember of the\n * map, which is the watchers' (`teamMemory`)\n *\n * @beta\n */\nexport function worldState(world: World): WorldSave {\n\treturn decided(saveWorld(world, { reseat: false }), world.registry)\n}\n\n/**\n * A save as what decides the game: without what each team's screens remember of the map (`teamMemory`: kept in the\n * world for who comes back, written by whoever watches it, and read by nothing that decides), and, with the rules, the\n * components nobody would have made had nobody asked for them (`unasked`)\n */\nfunction decided(save: WorldSave, registry?: Registry): WorldSave {\n\tconst { [teamMemory.id]: _memory, ...state } = save.state\n\tconst kept = (components: Record<string, unknown>) => (registry ? unasked(registry, components) : components)\n\treturn {\n\t\t...save,\n\t\tstate: kept(state),\n\t\tplayers: save.players.map((player) => ({ ...player, state: kept(player.state) })),\n\t\tentities: save.entities.map((entity) =>\n\t\t\tentity.components ? { ...entity, components: kept(entity.components as Record<string, unknown>) } : entity\n\t\t)\n\t}\n}\n\n/**\n * Where two saves of a game first differ, as `checkDeterminism` looks (what decides first: the tick, the random state,\n * the players, the entities): the path to it (`entities[id 11].pos.x`) and what each holds there, or nothing when they\n * are the same. What the screens remember of the map, and the hash of the rules they were made with, are left out;\n * with the game's `registry`, so are components that hold what they are made with (a screen asking for one makes it).\n * What a replay that came apart says at its checkpoints (`runReplay`), and `v12 save diff`\n *\n * @beta\n */\nexport function saveDifference(a: WorldSave, b: WorldSave, registry?: Registry): Difference | undefined {\n\tconst ordered = (save: WorldSave) => {\n\t\tconst { hash: _rules, ...state } = decided(save, registry)\n\t\treturn { ...Object.fromEntries(FIRST.map((key) => [key, (state as Partial<Compared>)[key]])), ...state }\n\t}\n\treturn firstDifference(ordered(a), ordered(b))\n}\n\n/**\n * Components as they would be had nobody asked for one that was not there: one that holds what its component makes\n * when asked for (its `default`) is left out. Asking makes one, and a watcher's screen asks for what it shows (a\n * player's objectives), so a world watched and the same world unwatched differ in that alone\n */\nfunction unasked(registry: Registry, components: Record<string, unknown>): Record<string, unknown> {\n\tconst kept: Record<string, unknown> = {}\n\tfor (const [id, value] of Object.entries(components)) {\n\t\tconst made = registry.component(id)?.default?.()\n\t\tif (made !== undefined && JSON.stringify(made) === JSON.stringify(value)) continue\n\t\tkept[id] = value\n\t}\n\treturn kept\n}\n\n/**\n * The simulation's state as a hash: two worlds with the same hash are, to all that is saved of them, the same. Fourteen\n * hex digits (cyrb53, of the save as JSON, but the hash of the rules, which another build of the same code writes\n * otherwise): enough to tell drift, not to stand against someone forging a state\n *\n * @beta\n */\nexport const worldHash = (world: World): string => {\n\t// the rules' own hash names the code they were built from, which another build of the same game writes otherwise\n\tconst { hash: _rules, ...state } = worldState(world)\n\treturn hashText(canonical(state))\n}\n\n/**\n * JSON with the keys of every object in order: the same state as text however it was put together (a component a\n * watcher made early comes first in its object, and later where nobody watched)\n */\nfunction canonical(value: unknown): string {\n\treturn JSON.stringify(value, (_key, each: unknown) => {\n\t\tif (!each || typeof each !== 'object' || Array.isArray(each)) return each\n\t\tconst sorted: Record<string, unknown> = {}\n\t\tfor (const key of Object.keys(each).sort()) sorted[key] = (each as Record<string, unknown>)[key]\n\t\treturn sorted\n\t})\n}\n\n/**\n * A quick hash of what a game that came apart differs in first: the tick, the random state, each player's resources,\n * upgrades and supply, and each entity's id, type, owner, place, facing, health, mana, whether it lives, its orders (how\n * many, and the first's kind and target), its buffs (which, and the time left) and its attack's cooldown and swing. Read\n * off the world as it is, with no save: 0.4 ms at 1000 units a side, where `worldHash` takes 66. What a\n * replay of commands keeps every few seconds and checks as it plays (`recordCommands`), and what `checkDeterminism`\n * compares every tick, for the tick a game came apart at; what it leaves out (components, areas, the fog) the whole\n * state, compared every so often, has\n *\n * @beta\n */\nexport function worldFingerprint(world: World): string {\n\tconst values: number[] = [world.tick, world.rng.save()]\n\tfor (const player of world.players.values()) {\n\t\tvalues.push(player.id, player.supplyUsed, player.supplyCap)\n\t\tfor (const key of Object.keys(player.resources).sort()) values.push(player.resources[key] ?? 0)\n\t\tfor (const [upgrade, level] of player.upgrades) values.push(wordOf(upgrade), level)\n\t}\n\tfor (const entity of world.entities.values()) {\n\t\tvalues.push(\n\t\t\tentity.id,\n\t\t\twordOf(entity.def.id),\n\t\t\tentity.owner,\n\t\t\tentity.pos.x,\n\t\t\tentity.pos.z,\n\t\t\tentity.facing,\n\t\t\tentity.health,\n\t\t\tentity.mana,\n\t\t\tentity.alive ? 1 : 0\n\t\t)\n\t\tconst order = entity.orders[0]\n\t\tvalues.push(entity.orders.length, order ? wordOf(order.type) : 0, order?.init.target ?? 0)\n\t\tvalues.push(entity.buffs.length)\n\t\tfor (const buff of entity.buffs) values.push(wordOf(buff.id), buff.remaining)\n\t\tif (entity.get(fighting)) values.push(entity.get(fighting)!.cooldown, entity.get(fighting)!.swing)\n\t}\n\treturn hashWords(new Uint32Array(Float64Array.from(values).buffer))\n}\n\n/** A short text as a number, for the fingerprint: FNV-1a of its characters */\nfunction wordOf(text: string): number {\n\tlet h = 0x811c9dc5\n\tfor (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619)\n\treturn h >>> 0\n}\n\n/** cyrb53 of 32-bit words: the bits of numbers, hashed as they are */\nfunction hashWords(words: Uint32Array): string {\n\tlet h1 = 0xdeadbeef\n\tlet h2 = 0x41c6ce57\n\tfor (const word of words) {\n\t\th1 = Math.imul(h1 ^ word, 2654435761)\n\t\th2 = Math.imul(h2 ^ word, 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 * Where two states first differ: the path to it (`entities[id 11].pos.x`) and what each holds there. Nothing when they\n * are the same. Lists of things with an `id` are named by it, the rest by their place\n *\n * @beta\n */\nexport function firstDifference(a: unknown, b: unknown, path = ''): Difference | undefined {\n\tif (Object.is(a, b)) return undefined\n\tif (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) return { path, a, b }\n\tif (Array.isArray(a) && Array.isArray(b)) {\n\t\tfor (let i = 0; i < Math.max(a.length, b.length); i++) {\n\t\t\tconst each = a[i] ?? b[i]\n\t\t\tconst named = each && typeof each === 'object' && 'id' in each ? `[id ${String((each as { id: unknown }).id)}]` : `[${i}]`\n\t\t\tconst found = firstDifference(a[i], b[i], `${path}${named}`)\n\t\t\tif (found) return found\n\t\t}\n\t\treturn undefined\n\t}\n\tconst keys = new Set([...Object.keys(a), ...Object.keys(b)])\n\tfor (const key of keys) {\n\t\tconst found = firstDifference((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key], path ? `${path}.${key}` : key)\n\t\tif (found) return found\n\t}\n\treturn undefined\n}\n\n/**\n * Where two states differ (`firstDifference`)\n *\n * @beta\n */\nexport interface Difference {\n\t/** The path to it in the state: `entities[id 11].pos.x` */\n\tpath: string\n\t/** What the first holds there */\n\ta: unknown\n\t/** What the second holds there */\n\tb: unknown\n}\n\n/**\n * Where two runs of a game came apart: the first tick they were looked at and differed, and what differed first\n *\n * @beta\n */\nexport interface Apart extends Difference {\n\t/** The tick they were looked at and differed */\n\ttick: number\n}\n\n/**\n * How a game is checked for coming out the same (`checkDeterminism`)\n *\n * @beta\n */\nexport interface DeterminismOptions {\n\t/** How many ticks each world runs */\n\tticks: number\n\t/**\n\t * How often their whole state is compared, in ticks: every 30 when left out. Their fingerprints\n\t * (`worldFingerprint`) are compared every tick, and the whole state at once where those differ, so that the tick\n\t * said is the one they came apart at\n\t */\n\tevery?: number\n\t/**\n\t * A tick to save a third world at, and load a fourth from that save (`loadWorld`, with `game`): the game saved and\n\t * the game loaded are run on side by side and compared. Not done when left out\n\t */\n\tfrom?: number\n\t/** The game the save is loaded with, for `from` */\n\trules?: Rules\n}\n\n/**\n * What the check found: for each run, where it came apart from the first, or `null` for the same to the last tick\n *\n * @beta\n */\nexport interface DeterminismReport {\n\t/** A second world made the same way and run the same */\n\ttwice: Apart | null\n\t/** A world loaded from a save taken at `from`, beside the world the save was taken of: none when `from` was not said */\n\tfromSave?: Apart | null\n}\n\n/**\n * Makes a world twice with `make` (the same seed, the same commands given in it, as a replay would) and runs them side\n * by side, comparing their fingerprints every tick and their states (and the order each player's entities are filed\n * in) every `every` ticks; with `from`, a third is saved at that tick and a fourth loaded\n * from the save, and the two run on side by side. Says, for each, the first tick and thing it differs at, or that it does not. A test of a game's\n * own systems: one that reads `Math.random`, the clock, or the order of something unordered is found here\n *\n *     const report = await checkDeterminism(() => makeMyGame(1), { ticks: 1800, from: 300, rules })\n *     expect(report).toEqual({ twice: null, fromSave: null })\n *\n * @public\n */\nexport async function checkDeterminism(make: () => World | Promise<World>, options: DeterminismOptions): Promise<DeterminismReport> {\n\tconst { ticks, every = 30, from } = options\n\tif (from !== undefined && !options.rules) throw new Error('checkDeterminism: a check from a save needs the game to load it with (game)')\n\tconst first = await make()\n\tconst second = await make()\n\t// the game that is saved at `from` and goes on, and the game loaded from that save beside it\n\tconst saved = from === undefined ? undefined : await make()\n\tlet loaded: World | undefined\n\tconst report: DeterminismReport = { twice: null, ...(from !== undefined && { fromSave: null }) }\n\ttry {\n\t\tfor (let tick = 1; tick <= ticks; tick++) {\n\t\t\tfirst.step()\n\t\t\tif (!report.twice) second.step()\n\t\t\tif (saved && !report.fromSave) {\n\t\t\t\tsaved.step()\n\t\t\t\tloaded?.step()\n\t\t\t\tif (saved.tick === from) {\n\t\t\t\t\t// as a file keeps it (`encodeSave`): what a save cannot hold is lost here as it would be there\n\t\t\t\t\tloaded = await loadWorld(decodeSave(encodeSave(saveWorld(saved))), { rules: options.rules! })\n\t\t\t\t}\n\t\t\t}\n\t\t\t// the fingerprint every tick, for the tick they came apart at; the whole state every `every`, and at once where\n\t\t\t// the fingerprints differ, for what it is\n\t\t\tconst whole = tick % every === 0\n\t\t\tif (!report.twice && (whole || worldFingerprint(first) !== worldFingerprint(second)))\n\t\t\t\treport.twice = apartAt(first.tick, compared(first), compared(second))\n\t\t\tconst going = loaded && !report.fromSave && saved!.tick > from!\n\t\t\tif (going && (whole || worldFingerprint(saved!) !== worldFingerprint(loaded!)))\n\t\t\t\treport.fromSave = apartAt(saved!.tick, compared(saved!), compared(loaded!))\n\t\t\tif (report.twice && (from === undefined || report.fromSave)) break\n\t\t}\n\t} finally {\n\t\tfirst.dispose()\n\t\tsecond.dispose()\n\t\tsaved?.dispose()\n\t\tloaded?.dispose()\n\t}\n\treturn report\n}\n\n/**\n * What is compared of a world: its state (`worldState`), and the order its index gives each player's entities in\n * (`world.index.ownedBy`), which a save does not hold and which decides what is picked first among equals (the closest\n * drop-off, a shopper, who shares the experience): a world loaded from a save has to give them in the same order\n */\ntype Compared = WorldSave & { owned: Record<number, number[]> }\n\nconst compared = (world: World): Compared => ({\n\t...worldState(world),\n\towned: Object.fromEntries([...world.players.keys()].map((player) => [player, [...world.index.ownedBy(player)].map((entity) => entity.id)]))\n})\n\n/**\n * What is looked at first: what is decided (the random state, the players, the entities, the order they are filed in)\n * before what follows from it (the fog, which units see), so that what is said is where it began\n */\nconst FIRST: (keyof Compared)[] = ['tick', 'rng', 'players', 'entities', 'owned', 'units']\n\nconst apartAt = (tick: number, a: Compared, b: Compared): Apart | null => {\n\tconst ordered = (state: Compared) => ({ ...Object.fromEntries(FIRST.map((key) => [key, state[key]])), ...state })\n\tconst found = firstDifference(ordered(a), ordered(b))\n\treturn found ? { tick, ...found } : null\n}\n"],"mappings":"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"}

package/dist/dialog.d.ts

@@ -17,6 +17,13 @@ export interface LineDef {
     text: MessageRef;
     /** How long it stays, in seconds. `LINE_SECONDS` when left out: the rules know the key of the words, not how long they are */
     seconds?: number;
+    /**
+     * The unit that says it, by its entity id or its name on the map: the screen shows its face talking (the HUD's
+     * portrait box, or the dialog box's) over the speaker's portrait. The speaker's look's portrait when left out
+     */
+    unit?: number | string;
+    /** How it is said (`angry`, `whisper`): the speaker's face plays its clip for the mood, the box has it for its styles */
+    emotion?: string;
 }
 /**
  * Whom a line is said to: a player, some, or everyone
@@ -30,12 +37,20 @@ export type Audience = PlayerId | PlayerId[] | 'everyone';
  * @beta
  */
 export interface SaidLine {
+    /** The line's number, which a client knows it by */
     id: number;
+    /** Who says it, the name shown with the line */
     speaker: string;
+    /** What is said */
     text: Message;
+    /** How long the line is shown */
     seconds: number;
     /** Who hears it. Everyone when left out */
     to?: PlayerId[];
+    /** The unit that says it, by its entity id or its name on the map (`LineDef.unit`) */
+    unit?: number | string;
+    /** How it is said (`LineDef.emotion`) */
+    emotion?: string;
 }
 /**
  * The line each player hears now, the sequence waiting on it, and the tick it is over at, for skipping. Kept in the
@@ -83,9 +98,9 @@ export declare class Dialog {
  * The steps of a conversation, for a sequence: each line is said and stays for as long as it lasts, then the next.
  * Skipping a line (the `skipLine` command) goes on to the next at once:
  *
- *     defineSequence('td.beforeTheBoss', [...talk(DEFENDER, [{ speaker: 'td.commander', text: 'bossComing' }, ...])])
+ *     defineSequence({ id: 'td.beforeTheBoss', steps: [...talk(DEFENDER, [{ speaker: 'td.commander', text: 'bossComing' }, ...])] })
  *
- * @beta
+ * @public
  */
 export declare function talk<D = undefined>(to: Audience, lines: LineDef[]): Step<D>[];
 /** A line said, to whom it is for: everyone when it names nobody */

package/dist/dialog.js

@@ -0,0 +1,108 @@
+import { defineComponent } from "./components.js";
+import { lineEnded, lineSaid } from "./engineEvents.js";
+import { replicateEvent } from "./replication.js";
+import { toMessage } from "./messages.js";
+import { wait } from "./sequences.js";
+//#region src/dialog.ts
+/**
+* How long a line stays when it does not say: long enough to read a sentence
+*
+* @internal
+*/
+var LINE_SECONDS = 4;
+/**
+* The line each player hears now, the sequence waiting on it, and the tick it is over at, for skipping. Kept in the
+* world: a save has it
+*/
+var current = defineComponent({
+	id: "core.dialog",
+	default: () => ({
+		next: 1,
+		lines: {}
+	})
+});
+/**
+* What is said in a world
+*
+* @beta
+*/
+var Dialog = class {
+	world;
+	constructor(world) {
+		this.world = world;
+	}
+	/**
+	* Says a line, now. On its own it waits for nothing: in a sequence, `talk` says lines one after the other, each
+	* for as long as it lasts. `run` is the sequence that waits on it, which skipping the line hurries along
+	*/
+	say(to, line, run) {
+		const state = this.world.state(current);
+		const text = toMessage(line.text);
+		const players = to === "everyone" ? void 0 : Array.isArray(to) ? to : [to];
+		const said = {
+			id: state.next++,
+			speaker: line.speaker,
+			text,
+			seconds: line.seconds ?? 4,
+			to: players,
+			...line.unit !== void 0 && { unit: line.unit },
+			...line.emotion !== void 0 && { emotion: line.emotion }
+		};
+		const until = Number.isFinite(said.seconds) ? this.world.tick + Math.ceil(said.seconds * this.world.tickRate) : void 0;
+		for (const player of players ?? this.listeners()) state.lines[player] = {
+			line: said.id,
+			run,
+			to: players,
+			...until !== void 0 && { until }
+		};
+		this.world.events.emit(lineSaid, said);
+		return said;
+	}
+	/**
+	* A player asks to skip the line they hear: it ends, and a conversation goes on to its next line. Only a line
+	* said to them alone can be: what others hear too goes on for them
+	*/
+	skip(player) {
+		const state = this.world.state(current);
+		const heard = state.lines[player];
+		if (!heard || heard.to?.length !== 1 || heard.to[0] !== player) return;
+		delete state.lines[player];
+		if (heard.until !== void 0 && this.world.tick >= heard.until) return;
+		this.world.events.emit(lineEnded, {
+			id: heard.line,
+			to: [player]
+		});
+		if (heard.run !== void 0) this.world.sequences.hurry(heard.run);
+	}
+	/** The players a line said to everyone is heard by: everyone who plays */
+	listeners() {
+		const players = [];
+		for (const player of this.world.players.values()) if (!player.neutral) players.push(player.id);
+		return players;
+	}
+};
+/**
+* The steps of a conversation, for a sequence: each line is said and stays for as long as it lasts, then the next.
+* Skipping a line (the `skipLine` command) goes on to the next at once:
+*
+*     defineSequence({ id: 'td.beforeTheBoss', steps: [...talk(DEFENDER, [{ speaker: 'td.commander', text: 'bossComing' }, ...])] })
+*
+* @public
+*/
+function talk(to, lines) {
+	return lines.flatMap((line) => [(world, _data, run) => void world.dialog.say(to, line, run), wait(line.seconds ?? 4)]);
+}
+/** A line said, to whom it is for: everyone when it names nobody */
+var toldLine = replicateEvent(lineSaid, "line", (line, view) => !line.to || line.to.includes(view.player) ? {
+	type: "line",
+	line: structuredClone(line)
+} : void 0);
+/** A line over, to whom it was for */
+var toldLineEnded = replicateEvent(lineEnded, "lineEnded", ({ id, to }, view) => to.includes(view.player) ? {
+	type: "lineEnded",
+	id
+} : void 0);
+//#endregion
+export { Dialog, LINE_SECONDS, current, talk, toldLine, toldLineEnded };
+
+//# sourceMappingURL=dialog.js.map

package/dist/dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog.js","names":["lineSaidEvent"],"sources":["../src/dialog.ts"],"sourcesContent":["import { lineEnded, lineSaid as lineSaidEvent } from '#engine/engineEvents'\nimport { defineComponent } from './components'\nimport type { PlayerId } from './entity'\nimport { type Message, type MessageRef, toMessage } from './messages'\nimport { type Step, wait } from './sequences'\nimport type { World } from './world'\nimport { replicateEvent } from './replication'\n\n/**\n * Something someone says: a commander between waves, a hero in a cutscene. The rules say a line is said, so that\n * every player hears it at the same moment and a save knows where a conversation was; the view shows it (a box with\n * a portrait, subtitles) and plays its voice. Who the speaker is on the screen, their name and portrait, is the\n * view's (`GameView.cinematics.speakers`)\n *\n * @beta\n */\nexport interface LineDef {\n\t/** Who says it, by an id of the game's (`'td.commander'`) */\n\tspeaker: string\n\t/** What is said, in the words of the game: a message key, with params */\n\ttext: MessageRef\n\t/** How long it stays, in seconds. `LINE_SECONDS` when left out: the rules know the key of the words, not how long they are */\n\tseconds?: number\n\t/**\n\t * The unit that says it, by its entity id or its name on the map: the screen shows its face talking (the HUD's\n\t * portrait box, or the dialog box's) over the speaker's portrait. The speaker's look's portrait when left out\n\t */\n\tunit?: number | string\n\t/** How it is said (`angry`, `whisper`): the speaker's face plays its clip for the mood, the box has it for its styles */\n\temotion?: string\n}\n\n/**\n * Whom a line is said to: a player, some, or everyone\n *\n * @beta\n */\nexport type Audience = PlayerId | PlayerId[] | 'everyone'\n\n/**\n * A line as it is said: what the engine's `lineSaid` event carries, and what goes to the screen\n *\n * @beta\n */\nexport interface SaidLine {\n\t/** The line's number, which a client knows it by */\n\tid: number\n\t/** Who says it, the name shown with the line */\n\tspeaker: string\n\t/** What is said */\n\ttext: Message\n\t/** How long the line is shown */\n\tseconds: number\n\t/** Who hears it. Everyone when left out */\n\tto?: PlayerId[]\n\t/** The unit that says it, by its entity id or its name on the map (`LineDef.unit`) */\n\tunit?: number | string\n\t/** How it is said (`LineDef.emotion`) */\n\temotion?: string\n}\n\n/**\n * How long a line stays when it does not say: long enough to read a sentence\n *\n * @internal\n */\nexport const LINE_SECONDS = 4\n\n/**\n * The line each player hears now, the sequence waiting on it, and the tick it is over at, for skipping. Kept in the\n * world: a save has it\n */\nexport const current = defineComponent<{ next: number; lines: Record<number, { line: number; run?: number; to?: PlayerId[]; until?: number }> }>({ id: 'core.dialog', default: () => ({ next: 1, lines: {} }) })\n\n/**\n * What is said in a world\n *\n * @beta\n */\nexport class Dialog {\n\tconstructor(private readonly world: World) {}\n\n\t/**\n\t * Says a line, now. On its own it waits for nothing: in a sequence, `talk` says lines one after the other, each\n\t * for as long as it lasts. `run` is the sequence that waits on it, which skipping the line hurries along\n\t */\n\tsay(to: Audience, line: LineDef, run?: number): SaidLine {\n\t\tconst state = this.world.state(current)\n\t\tconst text = toMessage(line.text)\n\t\tconst players = to === 'everyone' ? undefined : Array.isArray(to) ? to : [to]\n\t\tconst said: SaidLine = {\n\t\t\tid: state.next++,\n\t\t\tspeaker: line.speaker,\n\t\t\ttext,\n\t\t\tseconds: line.seconds ?? LINE_SECONDS,\n\t\t\tto: players,\n\t\t\t...(line.unit !== undefined && { unit: line.unit }),\n\t\t\t...(line.emotion !== undefined && { emotion: line.emotion })\n\t\t}\n\t\t// a line that waits to be moved on lasts until it is\n\t\tconst until = Number.isFinite(said.seconds) ? this.world.tick + Math.ceil(said.seconds * this.world.tickRate) : undefined\n\t\tfor (const player of players ?? this.listeners()) state.lines[player] = { line: said.id, run, to: players, ...(until !== undefined && { until }) }\n\t\tthis.world.events.emit(lineSaidEvent, said)\n\t\treturn said\n\t}\n\n\t/**\n\t * A player asks to skip the line they hear: it ends, and a conversation goes on to its next line. Only a line\n\t * said to them alone can be: what others hear too goes on for them\n\t */\n\tskip(player: PlayerId): void {\n\t\tconst state = this.world.state(current)\n\t\tconst heard = state.lines[player]\n\t\tif (!heard || heard.to?.length !== 1 || heard.to[0] !== player) return\n\t\tdelete state.lines[player]\n\t\t// a line that is over is skipped no more: the sequence that said it waits on something else by now (a minute\n\t\t// before the next wave), which skipping it once cut short\n\t\tif (heard.until !== undefined && this.world.tick >= heard.until) return\n\t\tthis.world.events.emit(lineEnded, { id: heard.line, to: [player] })\n\t\tif (heard.run !== undefined) this.world.sequences.hurry(heard.run)\n\t}\n\n\t/** The players a line said to everyone is heard by: everyone who plays */\n\tprivate listeners(): PlayerId[] {\n\t\tconst players: PlayerId[] = []\n\t\tfor (const player of this.world.players.values()) if (!player.neutral) players.push(player.id)\n\t\treturn players\n\t}\n}\n\n/**\n * The steps of a conversation, for a sequence: each line is said and stays for as long as it lasts, then the next.\n * Skipping a line (the `skipLine` command) goes on to the next at once:\n *\n *     defineSequence({ id: 'td.beforeTheBoss', steps: [...talk(DEFENDER, [{ speaker: 'td.commander', text: 'bossComing' }, ...])] })\n *\n * @public\n */\nexport function talk<D = undefined>(to: Audience, lines: LineDef[]): Step<D>[] {\n\treturn lines.flatMap((line): Step<D>[] => [(world, _data, run) => void world.dialog.say(to, line, run), wait(line.seconds ?? LINE_SECONDS)])\n}\n\n/** A line said, to whom it is for: everyone when it names nobody */\nexport const toldLine = replicateEvent(lineSaidEvent, 'line', (line, view) =>\n\t!line.to || line.to.includes(view.player) ? { type: 'line', line: structuredClone(line) } : undefined\n)\n\n/** A line over, to whom it was for */\nexport const toldLineEnded = replicateEvent(lineEnded, 'lineEnded', ({ id, to }, view) =>\n\tto.includes(view.player) ? { type: 'lineEnded', id } : undefined\n)\n"],"mappings":";;;;;;;;;;;AAkEA,IAAa,eAAe;;;;;AAM5B,IAAa,UAAU,gBAA0H;CAAE,IAAI;CAAe,gBAAgB;EAAE,MAAM;EAAG,OAAO,CAAC;CAAE;AAAG,CAAC;;;;;;AAO/M,IAAa,SAAb,MAAoB;CACU;CAA7B,YAAY,OAA+B;EAAd,KAAA,QAAA;CAAe;;;;;CAM5C,IAAI,IAAc,MAAe,KAAwB;EACxD,MAAM,QAAQ,KAAK,MAAM,MAAM,OAAO;EACtC,MAAM,OAAO,UAAU,KAAK,IAAI;EAChC,MAAM,UAAU,OAAO,aAAa,KAAA,IAAY,MAAM,QAAQ,EAAE,IAAI,KAAK,CAAC,EAAE;EAC5E,MAAM,OAAiB;GACtB,IAAI,MAAM;GACV,SAAS,KAAK;GACd;GACA,SAAS,KAAK,WAAA;GACd,IAAI;GACJ,GAAI,KAAK,SAAS,KAAA,KAAa,EAAE,MAAM,KAAK,KAAK;GACjD,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,SAAS,KAAK,QAAQ;EAC3D;EAEA,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,IAAI,KAAK,MAAM,OAAO,KAAK,KAAK,KAAK,UAAU,KAAK,MAAM,QAAQ,IAAI,KAAA;EAChH,KAAK,MAAM,UAAU,WAAW,KAAK,UAAU,GAAG,MAAM,MAAM,UAAU;GAAE,MAAM,KAAK;GAAI;GAAK,IAAI;GAAS,GAAI,UAAU,KAAA,KAAa,EAAE,MAAM;EAAG;EACjJ,KAAK,MAAM,OAAO,KAAKA,UAAe,IAAI;EAC1C,OAAO;CACR;;;;;CAMA,KAAK,QAAwB;EAC5B,MAAM,QAAQ,KAAK,MAAM,MAAM,OAAO;EACtC,MAAM,QAAQ,MAAM,MAAM;EAC1B,IAAI,CAAC,SAAS,MAAM,IAAI,WAAW,KAAK,MAAM,GAAG,OAAO,QAAQ;EAChE,OAAO,MAAM,MAAM;EAGnB,IAAI,MAAM,UAAU,KAAA,KAAa,KAAK,MAAM,QAAQ,MAAM,OAAO;EACjE,KAAK,MAAM,OAAO,KAAK,WAAW;GAAE,IAAI,MAAM;GAAM,IAAI,CAAC,MAAM;EAAE,CAAC;EAClE,IAAI,MAAM,QAAQ,KAAA,GAAW,KAAK,MAAM,UAAU,MAAM,MAAM,GAAG;CAClE;;CAGA,YAAgC;EAC/B,MAAM,UAAsB,CAAC;EAC7B,KAAK,MAAM,UAAU,KAAK,MAAM,QAAQ,OAAO,GAAG,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,OAAO,EAAE;EAC7F,OAAO;CACR;AACD;;;;;;;;;AAUA,SAAgB,KAAoB,IAAc,OAA6B;CAC9E,OAAO,MAAM,SAAS,SAAoB,EAAE,OAAO,OAAO,QAAQ,KAAK,MAAM,OAAO,IAAI,IAAI,MAAM,GAAG,GAAG,KAAK,KAAK,WAAA,CAAuB,CAAC,CAAC;AAC5I;;AAGA,IAAa,WAAW,eAAeA,UAAe,SAAS,MAAM,SACpE,CAAC,KAAK,MAAM,KAAK,GAAG,SAAS,KAAK,MAAM,IAAI;CAAE,MAAM;CAAQ,MAAM,gBAAgB,IAAI;AAAE,IAAI,KAAA,CAC7F;;AAGA,IAAa,gBAAgB,eAAe,WAAW,cAAc,EAAE,IAAI,MAAM,SAChF,GAAG,SAAS,KAAK,MAAM,IAAI;CAAE,MAAM;CAAa;AAAG,IAAI,KAAA,CACxD"}

package/dist/effectRefs.js

@@ -0,0 +1,28 @@
+import { plain } from "./plain.js";
+//#region src/effectRefs.ts
+/** Where an effect is in the definition of an ability, found by identity; a copy of it when it is not in there */
+function effectRef(registry, ability, effect) {
+	const path = registry.abilities.has(ability) ? find(registry.ability(ability), effect, []) : void 0;
+	return path ? { path } : { value: plain(effect, `effect of ${ability}`, "Save", "keep ids and plain objects in game state") };
+}
+function find(within, wanted, path) {
+	if (within === wanted) return path;
+	if (typeof within !== "object" || within === null) return void 0;
+	for (const [key, value] of Object.entries(within)) {
+		if (typeof value !== "object" || value === null) continue;
+		const found = find(value, wanted, [...path, Array.isArray(within) ? Number(key) : key]);
+		if (found) return found;
+	}
+}
+/** The effect a save kept (`effectRef`): found in the ability again, or the copy */
+function resolveEffect(registry, ability, ref) {
+	if ("value" in ref) return structuredClone(ref.value);
+	let at = registry.ability(ability);
+	for (const key of ref.path) at = at?.[key];
+	if (at === void 0) throw new Error(`Save: an effect of "${ability}" is not where it was. Was the ability changed since?`);
+	return at;
+}
+//#endregion
+export { effectRef, resolveEffect };
+
+//# sourceMappingURL=effectRefs.js.map

package/dist/effectRefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectRefs.js","names":[],"sources":["../src/effectRefs.ts"],"sourcesContent":["/**\n * An effect of an ability as a save keeps it (`EffectRef`): where it is in the definition of the ability, found again\n * as a save is loaded, or a copy of one made up on the spot. What saves of missiles, zones and dashes are made with\n */\nimport type { EffectDef } from './defs'\nimport { plain } from './plain'\nimport type { Registry } from './registry'\n\n/** An effect of an ability: where it is in the definition of the ability, or a copy for one made up on the spot */\nexport type EffectRef = { path: (string | number)[] } | { value: unknown }\n\n/** Where an effect is in the definition of an ability, found by identity; a copy of it when it is not in there */\nexport function effectRef(registry: Registry, ability: string, effect: EffectDef | EffectDef[]): EffectRef {\n\tconst path = registry.abilities.has(ability) ? find(registry.ability(ability), effect, []) : undefined\n\treturn path ? { path } : { value: plain(effect, `effect of ${ability}`, 'Save', 'keep ids and plain objects in game state') }\n}\n\nfunction find(within: unknown, wanted: unknown, path: (string | number)[]): (string | number)[] | undefined {\n\tif (within === wanted) return path\n\tif (typeof within !== 'object' || within === null) return undefined\n\tfor (const [key, value] of Object.entries(within)) {\n\t\tif (typeof value !== 'object' || value === null) continue\n\t\tconst found = find(value, wanted, [...path, Array.isArray(within) ? Number(key) : key])\n\t\tif (found) return found\n\t}\n\treturn undefined\n}\n\n/** The effect a save kept (`effectRef`): found in the ability again, or the copy */\nexport function resolveEffect(registry: Registry, ability: string, ref: EffectRef): never {\n\tif ('value' in ref) return structuredClone(ref.value) as never\n\tlet at: unknown = registry.ability(ability)\n\tfor (const key of ref.path) at = (at as Record<string | number, unknown>)?.[key]\n\tif (at === undefined) throw new Error(`Save: an effect of \"${ability}\" is not where it was. Was the ability changed since?`)\n\treturn at as never\n}\n"],"mappings":";;;AAYA,SAAgB,UAAU,UAAoB,SAAiB,QAA4C;CAC1G,MAAM,OAAO,SAAS,UAAU,IAAI,OAAO,IAAI,KAAK,SAAS,QAAQ,OAAO,GAAG,QAAQ,CAAC,CAAC,IAAI,KAAA;CAC7F,OAAO,OAAO,EAAE,KAAK,IAAI,EAAE,OAAO,MAAM,QAAQ,aAAa,WAAW,QAAQ,0CAA0C,EAAE;AAC7H;AAEA,SAAS,KAAK,QAAiB,QAAiB,MAA4D;CAC3G,IAAI,WAAW,QAAQ,OAAO;CAC9B,IAAI,OAAO,WAAW,YAAY,WAAW,MAAM,OAAO,KAAA;CAC1D,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;EAClD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM;EACjD,MAAM,QAAQ,KAAK,OAAO,QAAQ,CAAC,GAAG,MAAM,MAAM,QAAQ,MAAM,IAAI,OAAO,GAAG,IAAI,GAAG,CAAC;EACtF,IAAI,OAAO,OAAO;CACnB;AAED;;AAGA,SAAgB,cAAc,UAAoB,SAAiB,KAAuB;CACzF,IAAI,WAAW,KAAK,OAAO,gBAAgB,IAAI,KAAK;CACpD,IAAI,KAAc,SAAS,QAAQ,OAAO;CAC1C,KAAK,MAAM,OAAO,IAAI,MAAM,KAAM,KAA0C;CAC5E,IAAI,OAAO,KAAA,GAAW,MAAM,IAAI,MAAM,uBAAuB,QAAQ,sDAAsD;CAC3H,OAAO;AACR"}

package/dist/effects.d.ts

@@ -3,21 +3,24 @@ import type { Entity, PlayerId } from './entity';
 import type { Vec2 } from './math';
 import type { World } from './world';
 /**
- * An effect the rules play on the screens, as the engine's `effect` event carries it (`world.effect`)
+ * An effect the rules play on the screens, as the engine's `effect` event carries it (`world.fx`)
  *
  * @beta
  */
-export interface EffectCue {
-    /** The rules' handle on it, for `world.stopEffect` */
+export interface FxCue {
+    /** The rules' handle on it, for `world.stopFx` */
     id: number;
     /** Which of the view's effects, by name (`GameView.fx.defs`) */
     effect: string;
     /** Where: a place, at a height or on the ground */
     x?: number;
+    /** The height it is at; on the ground when left out */
     y?: number;
+    /** The north-south place, in cells */
     z?: number;
     /** Or on an entity, by its id: it follows it on the screen, at a point of its model */
     on?: number;
+    /** The point of the entity's model it follows, by name; the entity's middle when left out */
     point?: string;
     /** Its knobs, over the effect's own: plain data, as it goes to every screen */
     params?: Record<string, unknown>;
@@ -27,13 +30,19 @@ export interface EffectCue {
     to?: PlayerId[];
     /** Seen over the fog of war, by whom it is for: what is there to be noticed */
     overFog?: boolean;
+    /** The other end of one drawn between two (`FxOptions.toward`): an entity by its id */
+    toward?: number;
+    /** Or a place, east-west */
+    tx?: number;
+    /** And north-south */
+    tz?: number;
 }
 /**
- * How the rules play an effect (`world.effect`)
+ * How the rules play an effect (`world.fx`)
  *
  * @beta
  */
-export interface EffectOptions {
+export interface FxOptions {
     /** A place: on the ground (`{ x, z }`) or at a height (`{ x, y, z }`) */
     at?: Vec2 | {
         x: number;
@@ -52,6 +61,13 @@ export interface EffectOptions {
     to?: Audience;
     /** Seen over the fog of war by whom it is for, as what is there to be noticed. No when left out */
     overFog?: boolean;
+    /**
+     * The other end, for an effect drawn between two (a beam, a tether, a link of a chain: the client's `linkFx`): an
+     * entity it follows on the screen, or a place. It starts at `at` or `on`; seen by whoever sees either end
+     *
+     * @beta
+     */
+    toward?: Entity | number | Vec2;
 }
 /**
  * How many effects a world played, for their ids and their seeds: the world's, and saved with it, so that the game
@@ -60,21 +76,21 @@ export interface EffectOptions {
 export declare const played: import("./components").Component<number, number>;
 /**
  * Plays one of the view's effects on the screens of the players who see where it is (or those it is for), now. What it
- * gives back stops it (`stopEffect`). Not in the world's state but for its count: a save, and a player who joins later,
+ * gives back stops it (`stopFx`). Not in the world's state but for its count: a save, and a player who joins later,
  * know nothing of the effect itself
  *
  * @beta
  */
-export declare function playEffect(world: World, effect: string, options?: EffectOptions): number;
+export declare function playFx(world: World, effect: string, options?: FxOptions): number;
 /**
- * Stops an effect the rules played (`playEffect`), on every screen: as its own `stop` says, over `fade` seconds
+ * Stops an effect the rules played (`playFx`), on every screen: as its own `stop` says, over `fade` seconds
  *
  * @beta
  */
-export declare function stopEffect(world: World, id: number, options?: {
+export declare function stopFx(world: World, id: number, options?: {
     fade?: number;
 }): void;
 /** An effect the rules play: to whom it is for, who sees where it is (what is there to be noticed, over the fog) */
-export declare const toldEffect: import("./replication").ReplicatedEvent;
+export declare const toldFx: import("./replication").ReplicatedEvent;
 /** An effect stopped: to whom saw it start */
-export declare const toldEffectStopped: import("./replication").ReplicatedEvent;
+export declare const toldFxStopped: import("./replication").ReplicatedEvent;