@v12-engine/engine 0.1.0 → 0.4.0

package/dist/cellLayers.js

@@ -0,0 +1,275 @@
+import { cellsChanged, cellsSeen } from "./engineEvents.js";
+import { CellMemory, teamMemory } from "./session/memory.js";
+import { replicateEvent } from "./replication.js";
+import { inShape, shapeBounds } from "./areas.js";
+import { foliageStyleProblem } from "./foliage.js";
+//#region src/cellLayers.ts
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Why what a `data.json` says of the game's layers of cells (`GameData.cellLayers`) is not right, where it first is
+* not: nothing when it is
+*
+* @beta
+*/
+function dataCellLayersProblem(said) {
+	if (!isRecord(said)) return "cellLayers is no object by layer";
+	for (const [layer, entry] of Object.entries(said)) {
+		if (!isRecord(entry)) return `cellLayers.${layer} is no object`;
+		const other = Object.keys(entry).find((key) => key !== "values");
+		if (other) return `cellLayers.${layer}.${other} is nothing a layer says as data (values)`;
+		if (entry.values === void 0) continue;
+		if (!isRecord(entry.values)) return `cellLayers.${layer}.values is no object by value`;
+		for (const [key, value] of Object.entries(entry.values)) {
+			const what = `cellLayers.${layer}.values.${key}`;
+			if (!/^[1-9]\d{0,2}$/.test(key) || Number(key) > 255) return `${what}: a value is a number from 1 to 255`;
+			if (value === false) continue;
+			if (!isRecord(value)) return `${what} is no object, or false for none`;
+			for (const [field, held] of Object.entries(value)) if (field === "name") {
+				if (typeof held !== "string" || !held) return `${what}.name is no word`;
+			} else if (field === "color") {
+				if (!Array.isArray(held) || held.length !== 3 || !held.every((part) => typeof part === "number" && part >= 0 && part <= 1)) return `${what}.color is no colour, [r, g, b] from 0 to 1`;
+			} else if (field === "foliage") {
+				const wrong = foliageStyleProblem(held, `${what}.foliage`);
+				if (wrong) return wrong;
+			} else return `${what}.${field} is nothing a value says (name, color, foliage)`;
+		}
+	}
+}
+/**
+* A game's layers of cells with what its data says of them laid over (`DataCellLayer`): each value over the layer's of
+* the same number, field by field (its `foliage` style too), one the layer has not added (named `Style <n>` where it
+* says no name), one said `false` taken out; in the order of their numbers. A layer that lists no values has its one
+* value, 1, first. A layer the game has not is left out. The layers given are not changed
+*
+* @beta
+*/
+function layCellLayerData(layers, said) {
+	return layers.map((def) => {
+		const over = said[def.id]?.values;
+		if (!over) return def;
+		const values = new Map(cellLayerValues(def).map((each) => [each.value, each]));
+		for (const [key, entry] of Object.entries(over)) {
+			const value = Number(key);
+			if (entry === false) {
+				values.delete(value);
+				continue;
+			}
+			const under = values.get(value) ?? {
+				value,
+				name: `Style ${value}`
+			};
+			const foliage = under.foliage || entry.foliage ? {
+				...under.foliage,
+				...entry.foliage
+			} : void 0;
+			values.set(value, {
+				...under,
+				...entry,
+				value,
+				...foliage && { foliage }
+			});
+		}
+		return {
+			...def,
+			values: [...values.values()].sort((a, b) => a.value - b.value)
+		};
+	});
+}
+/**
+* Typed help for writing a layer of cells
+*
+* @public
+*/
+var defineCellLayer = (def) => def;
+/**
+* The values a layer is painted with, as the editor offers them: its own, or 1, named after the layer
+*
+* @beta
+*/
+var cellLayerValues = (def) => def.values ?? [{
+	value: 1,
+	name: def.name
+}];
+/**
+* The cells of a terrain in a shape, as indices into its layers: the cells whose middle is in it
+*
+* @beta
+*/
+function cellsIn(terrain, shape) {
+	const { width, depth } = terrain;
+	const { x0, z0, x1, z1 } = shapeBounds(shape);
+	const cells = [];
+	for (let cz = Math.max(Math.floor(z0), 0); cz < Math.min(Math.ceil(z1), depth); cz++) for (let cx = Math.max(Math.floor(x0), 0); cx < Math.min(Math.ceil(x1), width); cx++) if (inShape(shape, {
+		x: cx + .5,
+		z: cz + .5
+	})) cells.push(cz * width + cx);
+	return cells;
+}
+/** Whether a team sees a cell of the ground: its middle */
+var seesCell = (world, team, cell) => world.fog.isVisible(team, cell % world.terrain.width + .5, Math.floor(cell / world.terrain.width) + .5);
+/** What a team sees of the ground now, a byte a cell: none where it sees all of it (or the fog has nothing of it, which `seesCell` says) */
+var sightOf = (world, team) => world.fog.isRevealed(team) ? void 0 : world.fog.cells(team)?.visible;
+/**
+* Cells of a layer the rules set (`world.setCells`), each with what it was: what each team that does not see a cell
+* keeps of it as it last knew it (`TeamMemory.cells`, a `CellMemory` a layer), to be told when it comes into sight. A
+* cell set back to what the team knows is nothing to tell; one the team sees is told now. A fire changes cells every
+* tick: each team's sight is read as its grid, and nothing is made but a layer's memory the first time
+*/
+function rememberUnseenCells(world, layer, cells, was, value) {
+	const memories = world.state(teamMemory);
+	const size = world.terrain.width * world.terrain.depth;
+	for (const team of world.fog.teams) {
+		let known = memories[team]?.cells?.[layer]?.ready(size);
+		const sight = sightOf(world, team);
+		const all = !sight && world.fog.isRevealed(team);
+		for (let i = 0; i < cells.length; i++) {
+			const cell = cells[i];
+			if (all || (sight ? sight[cell] !== 0 : seesCell(world, team, cell))) {
+				known?.forget(cell);
+				continue;
+			}
+			const knew = known?.has(cell) ? known.known[cell] : was[i];
+			if (knew === value) {
+				known?.forget(cell);
+				continue;
+			}
+			if (!known) {
+				const memory = memories[team] ??= {
+					structures: {},
+					cleared: []
+				};
+				known = ((memory.cells ??= {})[layer] ??= new CellMemory()).ready(size);
+			}
+			known.remember(cell, knew);
+		}
+	}
+}
+/**
+* Of what a team sees as bits (`FogOfWar.sightBits`, rows of `words` words), the 32 cells from `first` on, in order of
+* the cells as a layer's memory holds them (`CellMemory.held`): the rows they are in, each piece taken from a word or two
+*/
+function sightWord(sight, words, width, depth, first) {
+	let z = Math.floor(first / width);
+	let x = first - z * width;
+	let word = 0;
+	for (let filled = 0; filled < 32 && z < depth; z++, x = 0) {
+		const count = Math.min(32 - filled, width - x);
+		const at = z * words + (x >>> 5);
+		const shift = x & 31;
+		let piece = sight[at] >>> shift;
+		if (shift !== 0 && shift + count > 32) piece |= sight[at + 1] << 32 - shift;
+		if (count < 32) piece &= (1 << count) - 1;
+		word |= piece << filled;
+		filled += count;
+	}
+	return word;
+}
+/**
+* The cells changed out of a team's sight that are in it now (`TeamMemory.cells`), told to the team as they are now
+* (`cellsSeen`, in order of the cells) and forgotten: after the fog is worked out again (`fogSystem`). A layer's
+* memory is gone through a word of 32 cells at a time, those it remembers none of passed over, each held against what
+* the team sees of those 32 as bits (`FogOfWar.sightBits`) where the fog has them, else cell by cell
+*/
+function tellCellsInSight(world) {
+	if (!world.states.has(teamMemory)) return;
+	const memories = world.state(teamMemory);
+	const { width, depth } = world.terrain;
+	const words = Math.ceil(width / 32);
+	for (const [key, memory] of Object.entries(memories)) {
+		if (!memory.cells) continue;
+		const team = Number(key);
+		const all = world.fog.isRevealed(team);
+		const bits = all ? void 0 : world.fog.sightBits(team);
+		const sight = all || bits ? void 0 : sightOf(world, team);
+		for (const [layer, known] of Object.entries(memory.cells)) {
+			if (known.count === 0) continue;
+			const { held } = known.ready(width * depth);
+			let seen;
+			for (let word = 0; word < held.length; word++) {
+				let found = held[word];
+				if (found === 0) continue;
+				if (!all && bits) found &= sightWord(bits, words, width, depth, word << 5);
+				while (found !== 0) {
+					const low = found & -found;
+					const cell = (word << 5) + 31 - Math.clz32(low);
+					found ^= low;
+					if (all || bits || (sight ? sight[cell] !== 0 : seesCell(world, team, cell))) (seen ??= []).push(cell);
+				}
+			}
+			if (!seen) continue;
+			const byValue = /* @__PURE__ */ new Map();
+			for (const cell of seen) {
+				known.forget(cell);
+				const value = world.terrain.cellAt(layer, cell % width + .5, Math.floor(cell / width) + .5);
+				let cells = byValue.get(value);
+				if (!cells) byValue.set(value, cells = []);
+				cells.push(cell);
+			}
+			for (const [value, cells] of byValue) world.events.emit(cellsSeen, {
+				team,
+				layer,
+				cells,
+				value
+			});
+			if (known.count === 0) delete memory.cells[layer];
+		}
+		if (Object.keys(memory.cells).length === 0) delete memory.cells;
+	}
+}
+/**
+* What a team remembers of cells the rules changed out of its sight (`TeamMemory.cells`), as a save keeps it: by
+* layer, the value it last knew by cell, a copy. `undefined` where it remembers none; a layer it remembered and has
+* forgotten all of may stay, empty, until the team's next look
+*
+* @beta
+*/
+function rememberedCells(world, team) {
+	const cells = world.states.has(teamMemory) ? world.state(teamMemory)[team]?.cells : void 0;
+	if (!cells) return void 0;
+	const size = world.terrain.width * world.terrain.depth;
+	return Object.fromEntries(Object.entries(cells).map(([layer, known]) => [layer, known.ready(size).toRecord()]));
+}
+/**
+* The world's ground as a team knows it: its layers' cells as the team last saw those changed out of its sight
+* (`TeamMemory.cells`). The ground itself where the team knows all of it, or for an observer (no team)
+*/
+function groundKnownTo(world, team) {
+	const { terrain } = world;
+	const known = team === void 0 || !world.states.has(teamMemory) ? void 0 : world.state(teamMemory)[team]?.cells;
+	if (!known) return terrain;
+	const size = terrain.width * terrain.depth;
+	const cells = { ...terrain.cells };
+	for (const [layer, memory] of Object.entries(known)) {
+		const values = cells[layer] = new Uint8Array(cells[layer] ?? size);
+		memory.ready(size).forEach((cell, was) => values[cell] = was);
+	}
+	return Object.create(terrain, { cells: { value: cells } });
+}
+/** Whether the seat's player is told of cells their team sees changed, rather than as they come into sight: an observer is told of all */
+var toldNow = (view, cell) => view.observer || seesCell(view.world, view.team, cell);
+/** A layer's cells changed (`world.setCells`): to those who see them. The others are told as they come into sight (`toldCellsSeen`) */
+var toldCells = replicateEvent(cellsChanged, "cells", ({ layer, cells, value, over }, view) => {
+	const at = cells.filter((cell) => toldNow(view, cell));
+	return at.length ? {
+		type: "cells",
+		layer,
+		at,
+		value,
+		...over !== void 0 && { over: Math.round(over * 100) / 100 }
+	} : void 0;
+});
+/**
+* Cells changed out of a team's sight came into it (`tellCellsInSight`): to the team, as they are now, said to be seen
+* so (`seen`: a screen does not show them changing now). An observer was told already
+*/
+var toldCellsSeen = replicateEvent(cellsSeen, "cells", ({ team, layer, cells, value }, view) => !view.observer && view.team === team ? {
+	type: "cells",
+	layer,
+	at: [...cells],
+	value,
+	seen: true
+} : void 0);
+//#endregion
+export { cellLayerValues, cellsIn, dataCellLayersProblem, defineCellLayer, groundKnownTo, layCellLayerData, rememberUnseenCells, rememberedCells, tellCellsInSight, toldCells, toldCellsSeen };
+
+//# sourceMappingURL=cellLayers.js.map

package/dist/cellLayers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellLayers.js","names":[],"sources":["../src/cellLayers.ts"],"sourcesContent":["import { cellsChanged, cellsSeen } from '#engine/engineEvents'\nimport { type AreaShape, inShape, shapeBounds } from './areas'\nimport type { Terrain } from './terrain'\nimport type { World } from './world'\nimport { type FoliageStyleDef, foliageStyleProblem } from './foliage'\nimport { replicateEvent, type SessionView } from './replication'\nimport { CellMemory, teamMemory } from './session/memory'\n\n/**\n * A layer of cells a game paints its maps with, for its rules to read: where the bushes are, what burns, where a\n * lane runs. A value per cell (0 to 255, 0 being none), kept with the map (`GameMap.cells`), in the world's ground\n * (`Terrain.cells`, read with `terrain.cellAt`), its saves and what each player is sent. The rules change it while\n * the game runs with `world.setCells`: the players who see a cell are told at once, the others as it comes into their\n * sight (`TeamMemory.cells`), so a change in the dark is not given away. The editor paints the layers a game lists\n * (`Rules.cellLayers`), with the values it names\n *\n * @beta\n */\nexport interface CellLayerDef {\n\t/** Its key in `Terrain.cells` and in the map's file */\n\tid: string\n\t/** What the editor calls it */\n\tname: string\n\t/** What it is for, for the editor's tooltip */\n\tdescription?: string\n\t/** The colour the editor shows it in, 0 to 1 each */\n\tcolor?: [number, number, number]\n\t/**\n\t * The values the editor paints with, named: `[{ value: 1, name: 'Bush' }]`. One value, 1, named after the layer when\n\t * left out: a layer of cells that are or are not. Of a layer of grass or bushes, its styles (`CellLayerValue.foliage`)\n\t */\n\tvalues?: CellLayerValue[]\n\t/**\n\t * How fast one on foot goes over a cell of the layer that is not 0, as a multiplier of its speed: a swamp at 0.5. 1\n\t * when left out; a cell of several such layers is slowed by each (`groundSpeedOfCell`)\n\t */\n\tspeed?: number\n}\n\n/**\n * A value a layer of cells is painted with (`CellLayerDef.values`): its number in the cells, what the editor calls it,\n * and, of a layer of grass or bushes, the style it is to the rules\n *\n * @beta\n */\nexport interface CellLayerValue {\n\t/** The value in the cells, 1 to 255 */\n\tvalue: number\n\t/** What the editor calls it */\n\tname: string\n\t/** The colour the editor shows it in, 0 to 1 each: the layer's when left out */\n\tcolor?: [number, number, number]\n\t/**\n\t * Of a layer of grass or bushes (`foliagePack`): what this style is to the rules (`FoliageStyleDef`), whether it\n\t * hides, burns, slows. Over the layer's own (`FoliageLayerOptions.style`)\n\t */\n\tfoliage?: FoliageStyleDef\n}\n\n/**\n * What a `data.json`, or a map's definitions, says of a value of a layer of cells (`DataCellLayer.values`): its name,\n * colour and style, any of them, over the game's value of the same number; one the game has not is a value of its own\n *\n * @beta\n */\nexport type DataCellLayerValue = Partial<Omit<CellLayerValue, 'value'>>\n\n/**\n * What a `data.json` (`GameData.cellLayers`, every map) or a map's definitions (`GameMap.definitions`, that map alone)\n * says of one of the game's layers of cells: its values, by their number, each over the code's (`DataCellLayerValue`),\n * or `false` to take one of the game's out. What the editor writes of a style made or changed there:\n * `{ \"grass\": { \"values\": { \"3\": { \"name\": \"Dry field\", \"foliage\": { \"flammable\": 1 } } } } }`\n *\n * @beta\n */\nexport interface DataCellLayer {\n\t/** The layer's values, by number (1 to 255): each over the game's of that number, a new one, or `false` for none */\n\tvalues?: Record<number, DataCellLayerValue | false>\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Why what a `data.json` says of the game's layers of cells (`GameData.cellLayers`) is not right, where it first is\n * not: nothing when it is\n *\n * @beta\n */\nexport function dataCellLayersProblem(said: unknown): string | undefined {\n\tif (!isRecord(said)) return 'cellLayers is no object by layer'\n\tfor (const [layer, entry] of Object.entries(said)) {\n\t\tif (!isRecord(entry)) return `cellLayers.${layer} is no object`\n\t\tconst other = Object.keys(entry).find((key) => key !== 'values')\n\t\tif (other) return `cellLayers.${layer}.${other} is nothing a layer says as data (values)`\n\t\tif (entry.values === undefined) continue\n\t\tif (!isRecord(entry.values)) return `cellLayers.${layer}.values is no object by value`\n\t\tfor (const [key, value] of Object.entries(entry.values)) {\n\t\t\tconst what = `cellLayers.${layer}.values.${key}`\n\t\t\tif (!/^[1-9]\\d{0,2}$/.test(key) || Number(key) > 255) return `${what}: a value is a number from 1 to 255`\n\t\t\tif (value === false) continue\n\t\t\tif (!isRecord(value)) return `${what} is no object, or false for none`\n\t\t\tfor (const [field, held] of Object.entries(value)) {\n\t\t\t\tif (field === 'name') {\n\t\t\t\t\tif (typeof held !== 'string' || !held) return `${what}.name is no word`\n\t\t\t\t} else if (field === 'color') {\n\t\t\t\t\tif (!Array.isArray(held) || held.length !== 3 || !held.every((part) => typeof part === 'number' && part >= 0 && part <= 1))\n\t\t\t\t\t\treturn `${what}.color is no colour, [r, g, b] from 0 to 1`\n\t\t\t\t} else if (field === 'foliage') {\n\t\t\t\t\tconst wrong = foliageStyleProblem(held, `${what}.foliage`)\n\t\t\t\t\tif (wrong) return wrong\n\t\t\t\t} else return `${what}.${field} is nothing a value says (name, color, foliage)`\n\t\t\t}\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * A game's layers of cells with what its data says of them laid over (`DataCellLayer`): each value over the layer's of\n * the same number, field by field (its `foliage` style too), one the layer has not added (named `Style <n>` where it\n * says no name), one said `false` taken out; in the order of their numbers. A layer that lists no values has its one\n * value, 1, first. A layer the game has not is left out. The layers given are not changed\n *\n * @beta\n */\nexport function layCellLayerData(layers: readonly CellLayerDef[], said: Readonly<Record<string, DataCellLayer>>): CellLayerDef[] {\n\treturn layers.map((def) => {\n\t\tconst over = said[def.id]?.values\n\t\tif (!over) return def\n\t\tconst values = new Map(cellLayerValues(def).map((each) => [each.value, each]))\n\t\tfor (const [key, entry] of Object.entries(over)) {\n\t\t\tconst value = Number(key)\n\t\t\tif (entry === false) {\n\t\t\t\tvalues.delete(value)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tconst under = values.get(value) ?? { value, name: `Style ${value}` }\n\t\t\tconst foliage = under.foliage || entry.foliage ? { ...under.foliage, ...entry.foliage } : undefined\n\t\t\tvalues.set(value, { ...under, ...entry, value, ...(foliage && { foliage }) })\n\t\t}\n\t\treturn { ...def, values: [...values.values()].sort((a, b) => a.value - b.value) }\n\t})\n}\n\n/**\n * Typed help for writing a layer of cells\n *\n * @public\n */\nexport const defineCellLayer = (def: CellLayerDef): CellLayerDef => def\n\n/**\n * The values a layer is painted with, as the editor offers them: its own, or 1, named after the layer\n *\n * @beta\n */\nexport const cellLayerValues = (def: CellLayerDef): CellLayerValue[] => def.values ?? [{ value: 1, name: def.name }]\n\n/**\n * The cells of a terrain in a shape, as indices into its layers: the cells whose middle is in it\n *\n * @beta\n */\nexport function cellsIn(terrain: Pick<Terrain, 'width' | 'depth'>, shape: AreaShape): number[] {\n\tconst { width, depth } = terrain\n\tconst { x0, z0, x1, z1 } = shapeBounds(shape)\n\tconst cells: number[] = []\n\tfor (let cz = Math.max(Math.floor(z0), 0); cz < Math.min(Math.ceil(z1), depth); cz++) {\n\t\tfor (let cx = Math.max(Math.floor(x0), 0); cx < Math.min(Math.ceil(x1), width); cx++) {\n\t\t\tif (inShape(shape, { x: cx + 0.5, z: cz + 0.5 })) cells.push(cz * width + cx)\n\t\t}\n\t}\n\treturn cells\n}\n\n/** Whether a team sees a cell of the ground: its middle */\nconst seesCell = (world: World, team: number, cell: number): boolean =>\n\tworld.fog.isVisible(team, (cell % world.terrain.width) + 0.5, Math.floor(cell / world.terrain.width) + 0.5)\n\n/** What a team sees of the ground now, a byte a cell: none where it sees all of it (or the fog has nothing of it, which `seesCell` says) */\nconst sightOf = (world: World, team: number): Uint8Array | undefined => (world.fog.isRevealed(team) ? undefined : world.fog.cells(team)?.visible)\n\n/**\n * Cells of a layer the rules set (`world.setCells`), each with what it was: what each team that does not see a cell\n * keeps of it as it last knew it (`TeamMemory.cells`, a `CellMemory` a layer), to be told when it comes into sight. A\n * cell set back to what the team knows is nothing to tell; one the team sees is told now. A fire changes cells every\n * tick: each team's sight is read as its grid, and nothing is made but a layer's memory the first time\n */\nexport function rememberUnseenCells(world: World, layer: string, cells: readonly number[], was: readonly number[], value: number): void {\n\tconst memories = world.state(teamMemory)\n\tconst size = world.terrain.width * world.terrain.depth\n\tfor (const team of world.fog.teams) {\n\t\tlet known = memories[team]?.cells?.[layer]?.ready(size)\n\t\tconst sight = sightOf(world, team)\n\t\tconst all = !sight && world.fog.isRevealed(team)\n\t\tfor (let i = 0; i < cells.length; i++) {\n\t\t\tconst cell = cells[i]\n\t\t\tif (all || (sight ? sight[cell] !== 0 : seesCell(world, team, cell))) {\n\t\t\t\tknown?.forget(cell)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tconst knew = known?.has(cell) ? known.known[cell] : was[i]\n\t\t\tif (knew === value) {\n\t\t\t\tknown?.forget(cell)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif (!known) {\n\t\t\t\tconst memory = (memories[team] ??= { structures: {}, cleared: [] })\n\t\t\t\tknown = ((memory.cells ??= {})[layer] ??= new CellMemory()).ready(size)\n\t\t\t}\n\t\t\tknown.remember(cell, knew)\n\t\t}\n\t}\n}\n\n/**\n * Of what a team sees as bits (`FogOfWar.sightBits`, rows of `words` words), the 32 cells from `first` on, in order of\n * the cells as a layer's memory holds them (`CellMemory.held`): the rows they are in, each piece taken from a word or two\n */\nfunction sightWord(sight: Uint32Array, words: number, width: number, depth: number, first: number): number {\n\tlet z = Math.floor(first / width)\n\tlet x = first - z * width\n\tlet word = 0\n\tfor (let filled = 0; filled < 32 && z < depth; z++, x = 0) {\n\t\tconst count = Math.min(32 - filled, width - x)\n\t\tconst at = z * words + (x >>> 5)\n\t\tconst shift = x & 31\n\t\tlet piece = sight[at] >>> shift\n\t\tif (shift !== 0 && shift + count > 32) piece |= sight[at + 1] << (32 - shift)\n\t\tif (count < 32) piece &= (1 << count) - 1\n\t\tword |= piece << filled\n\t\tfilled += count\n\t}\n\treturn word\n}\n\n/**\n * The cells changed out of a team's sight that are in it now (`TeamMemory.cells`), told to the team as they are now\n * (`cellsSeen`, in order of the cells) and forgotten: after the fog is worked out again (`fogSystem`). A layer's\n * memory is gone through a word of 32 cells at a time, those it remembers none of passed over, each held against what\n * the team sees of those 32 as bits (`FogOfWar.sightBits`) where the fog has them, else cell by cell\n */\nexport function tellCellsInSight(world: World): void {\n\tif (!world.states.has(teamMemory)) return\n\tconst memories = world.state(teamMemory)\n\tconst { width, depth } = world.terrain\n\tconst words = Math.ceil(width / 32)\n\tfor (const [key, memory] of Object.entries(memories)) {\n\t\tif (!memory.cells) continue\n\t\tconst team = Number(key)\n\t\tconst all = world.fog.isRevealed(team)\n\t\tconst bits = all ? undefined : world.fog.sightBits(team)\n\t\tconst sight = all || bits ? undefined : sightOf(world, team)\n\t\tfor (const [layer, known] of Object.entries(memory.cells)) {\n\t\t\tif (known.count === 0) continue\n\t\t\tconst { held } = known.ready(width * depth)\n\t\t\tlet seen: number[] | undefined\n\t\t\tfor (let word = 0; word < held.length; word++) {\n\t\t\t\tlet found = held[word]\n\t\t\t\tif (found === 0) continue\n\t\t\t\t// the cells of the word in sight, at once where the fog has them as bits\n\t\t\t\tif (!all && bits) found &= sightWord(bits, words, width, depth, word << 5)\n\t\t\t\twhile (found !== 0) {\n\t\t\t\t\tconst low = found & -found\n\t\t\t\t\tconst cell = (word << 5) + 31 - Math.clz32(low)\n\t\t\t\t\tfound ^= low\n\t\t\t\t\tif (all || bits || (sight ? sight[cell] !== 0 : seesCell(world, team, cell))) (seen ??= []).push(cell)\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (!seen) continue\n\t\t\tconst byValue = new Map<number, number[]>()\n\t\t\tfor (const cell of seen) {\n\t\t\t\tknown.forget(cell)\n\t\t\t\tconst value = world.terrain.cellAt(layer, (cell % width) + 0.5, Math.floor(cell / width) + 0.5)\n\t\t\t\tlet cells = byValue.get(value)\n\t\t\t\tif (!cells) byValue.set(value, (cells = []))\n\t\t\t\tcells.push(cell)\n\t\t\t}\n\t\t\tfor (const [value, cells] of byValue) world.events.emit(cellsSeen, { team, layer, cells, value })\n\t\t\tif (known.count === 0) delete memory.cells[layer]\n\t\t}\n\t\tif (Object.keys(memory.cells).length === 0) delete memory.cells\n\t}\n}\n\n/**\n * What a team remembers of cells the rules changed out of its sight (`TeamMemory.cells`), as a save keeps it: by\n * layer, the value it last knew by cell, a copy. `undefined` where it remembers none; a layer it remembered and has\n * forgotten all of may stay, empty, until the team's next look\n *\n * @beta\n */\nexport function rememberedCells(world: World, team: number): Record<string, Record<number, number>> | undefined {\n\tconst cells = world.states.has(teamMemory) ? world.state(teamMemory)[team]?.cells : undefined\n\tif (!cells) return undefined\n\tconst size = world.terrain.width * world.terrain.depth\n\treturn Object.fromEntries(Object.entries(cells).map(([layer, known]) => [layer, known.ready(size).toRecord()]))\n}\n\n/**\n * The world's ground as a team knows it: its layers' cells as the team last saw those changed out of its sight\n * (`TeamMemory.cells`). The ground itself where the team knows all of it, or for an observer (no team)\n */\nexport function groundKnownTo(world: World, team: number | undefined): Terrain {\n\tconst { terrain } = world\n\tconst known = team === undefined || !world.states.has(teamMemory) ? undefined : world.state(teamMemory)[team]?.cells\n\tif (!known) return terrain\n\tconst size = terrain.width * terrain.depth\n\tconst cells: Record<string, Uint8Array> = { ...terrain.cells }\n\tfor (const [layer, memory] of Object.entries(known)) {\n\t\tconst values = (cells[layer] = new Uint8Array(cells[layer] ?? size))\n\t\tmemory.ready(size).forEach((cell, was) => (values[cell] = was))\n\t}\n\treturn Object.create(terrain, { cells: { value: cells } }) as Terrain\n}\n\n/** Whether the seat's player is told of cells their team sees changed, rather than as they come into sight: an observer is told of all */\nconst toldNow = (view: SessionView, cell: number): boolean => view.observer || seesCell(view.world, view.team, cell)\n\n/** A layer's cells changed (`world.setCells`): to those who see them. The others are told as they come into sight (`toldCellsSeen`) */\nexport const toldCells = replicateEvent(cellsChanged, 'cells', ({ layer, cells, value, over }, view) => {\n\tconst at = cells.filter((cell) => toldNow(view, cell))\n\treturn at.length ? { type: 'cells', layer, at, value, ...(over !== undefined && { over: Math.round(over * 100) / 100 }) } : undefined\n})\n\n/**\n * Cells changed out of a team's sight came into it (`tellCellsInSight`): to the team, as they are now, said to be seen\n * so (`seen`: a screen does not show them changing now). An observer was told already\n */\nexport const toldCellsSeen = replicateEvent(cellsSeen, 'cells', ({ team, layer, cells, value }, view) =>\n\t!view.observer && view.team === team ? { type: 'cells', layer, at: [...cells], value, seen: true } : undefined\n)\n"],"mappings":"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"}

package/dist/cellPatches.d.ts

@@ -0,0 +1,24 @@
+import type { Terrain } from './terrain';
+/**
+ * How `patchCells` finds a patch
+ *
+ * @beta
+ */
+export interface PatchCellsOptions {
+    /**
+     * Only the cells of the same value as the first (the same style of grass): the patch of that style. Any cell that is
+     * not 0 when left out: all the grass that touches, whatever its style
+     */
+    sameValue?: boolean;
+}
+/**
+ * The patch of a layer of cells one cell is in: the cells of the layer that touch it and each other, through sides and
+ * corners, as indices (`z * width + x`) in order. The patches of a hiding layer are these (`concealmentPack`); the
+ * editor's wand picks one. None where the cell is off the ground or 0
+ *
+ *     const field = patchCells(world.terrain, 'grass', cell, { sameValue: true })
+ *     world.setCells('grass', field, 3)
+ *
+ * @beta
+ */
+export declare function patchCells(terrain: Pick<Terrain, 'width' | 'depth' | 'cells'>, layer: string, cell: number, options?: PatchCellsOptions): number[];

package/dist/cellPatches.js

@@ -0,0 +1,73 @@
+//#region src/cellPatches.ts
+/** The eight steps to the cells about one */
+var AROUND_X = [
+	-1,
+	0,
+	1,
+	-1,
+	1,
+	-1,
+	0,
+	1
+];
+var AROUND_Z = [
+	-1,
+	-1,
+	-1,
+	0,
+	0,
+	1,
+	1,
+	1
+];
+/**
+* Marks the patch a cell is in with `mark` (`of[cell] = mark`): the cells reached from it, one to the next through
+* sides and corners, that are `value` (or, with a `value` of -1, any but 0) and not marked yet in `of`. Each cell
+* reached is pushed to `out` where one is given. `stack` is scratch, left empty
+*
+* @internal
+*/
+function floodCells(width, depth, cells, value, start, of, mark, stack, out) {
+	of[start] = mark;
+	out?.push(start);
+	stack.push(start);
+	while (stack.length) {
+		const c = stack.pop();
+		const x = c % width;
+		const z = (c - x) / width;
+		for (let i = 0; i < 8; i++) {
+			const nx = x + AROUND_X[i];
+			const nz = z + AROUND_Z[i];
+			if (nx < 0 || nz < 0 || nx >= width || nz >= depth) continue;
+			const n = nz * width + nx;
+			if (of[n] !== 0) continue;
+			const held = cells[n];
+			if (value < 0 ? held === 0 : held !== value) continue;
+			of[n] = mark;
+			out?.push(n);
+			stack.push(n);
+		}
+	}
+}
+/**
+* The patch of a layer of cells one cell is in: the cells of the layer that touch it and each other, through sides and
+* corners, as indices (`z * width + x`) in order. The patches of a hiding layer are these (`concealmentPack`); the
+* editor's wand picks one. None where the cell is off the ground or 0
+*
+*     const field = patchCells(world.terrain, 'grass', cell, { sameValue: true })
+*     world.setCells('grass', field, 3)
+*
+* @beta
+*/
+function patchCells(terrain, layer, cell, options = {}) {
+	const { width, depth } = terrain;
+	const cells = terrain.cells[layer];
+	if (!cells || !Number.isInteger(cell) || cell < 0 || cell >= width * depth || cells[cell] === 0) return [];
+	const out = [];
+	floodCells(width, depth, cells, options.sameValue ? cells[cell] : -1, cell, new Int32Array(width * depth), 1, [], out);
+	return out.sort((a, b) => a - b);
+}
+//#endregion
+export { floodCells, patchCells };
+
+//# sourceMappingURL=cellPatches.js.map

package/dist/cellPatches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellPatches.js","names":[],"sources":["../src/cellPatches.ts"],"sourcesContent":["import type { Terrain } from './terrain'\n\n/*\n * Patches of a layer of cells: the cells of it that touch, sides or corners. One flood fill for all who need one: the\n * hiding places (`concealment.ts`, which labels every patch of a layer), the editor's wand and a game's own code\n * (`patchCells`, the patch of one cell).\n */\n\n/** The eight steps to the cells about one */\nconst AROUND_X = [-1, 0, 1, -1, 1, -1, 0, 1] as const\nconst AROUND_Z = [-1, -1, -1, 0, 0, 1, 1, 1] as const\n\n/**\n * Marks the patch a cell is in with `mark` (`of[cell] = mark`): the cells reached from it, one to the next through\n * sides and corners, that are `value` (or, with a `value` of -1, any but 0) and not marked yet in `of`. Each cell\n * reached is pushed to `out` where one is given. `stack` is scratch, left empty\n *\n * @internal\n */\nexport function floodCells(\n\twidth: number,\n\tdepth: number,\n\tcells: ArrayLike<number>,\n\tvalue: number,\n\tstart: number,\n\tof: Int32Array,\n\tmark: number,\n\tstack: number[],\n\tout?: number[]\n): void {\n\tof[start] = mark\n\tout?.push(start)\n\tstack.push(start)\n\twhile (stack.length) {\n\t\tconst c = stack.pop()!\n\t\tconst x = c % width\n\t\tconst z = (c - x) / width\n\t\tfor (let i = 0; i < 8; i++) {\n\t\t\tconst nx = x + AROUND_X[i]\n\t\t\tconst nz = z + AROUND_Z[i]\n\t\t\tif (nx < 0 || nz < 0 || nx >= width || nz >= depth) continue\n\t\t\tconst n = nz * width + nx\n\t\t\tif (of[n] !== 0) continue\n\t\t\tconst held = cells[n]\n\t\t\tif (value < 0 ? held === 0 : held !== value) continue\n\t\t\tof[n] = mark\n\t\t\tout?.push(n)\n\t\t\tstack.push(n)\n\t\t}\n\t}\n}\n\n/**\n * How `patchCells` finds a patch\n *\n * @beta\n */\nexport interface PatchCellsOptions {\n\t/**\n\t * Only the cells of the same value as the first (the same style of grass): the patch of that style. Any cell that is\n\t * not 0 when left out: all the grass that touches, whatever its style\n\t */\n\tsameValue?: boolean\n}\n\n/**\n * The patch of a layer of cells one cell is in: the cells of the layer that touch it and each other, through sides and\n * corners, as indices (`z * width + x`) in order. The patches of a hiding layer are these (`concealmentPack`); the\n * editor's wand picks one. None where the cell is off the ground or 0\n *\n *     const field = patchCells(world.terrain, 'grass', cell, { sameValue: true })\n *     world.setCells('grass', field, 3)\n *\n * @beta\n */\nexport function patchCells(terrain: Pick<Terrain, 'width' | 'depth' | 'cells'>, layer: string, cell: number, options: PatchCellsOptions = {}): number[] {\n\tconst { width, depth } = terrain\n\tconst cells = terrain.cells[layer]\n\tif (!cells || !Number.isInteger(cell) || cell < 0 || cell >= width * depth || cells[cell] === 0) return []\n\tconst out: number[] = []\n\tfloodCells(width, depth, cells, options.sameValue ? cells[cell] : -1, cell, new Int32Array(width * depth), 1, [], out)\n\treturn out.sort((a, b) => a - b)\n}\n"],"mappings":";;AASA,IAAM,WAAW;CAAC;CAAI;CAAG;CAAG;CAAI;CAAG;CAAI;CAAG;AAAC;AAC3C,IAAM,WAAW;CAAC;CAAI;CAAI;CAAI;CAAG;CAAG;CAAG;CAAG;AAAC;;;;;;;;AAS3C,SAAgB,WACf,OACA,OACA,OACA,OACA,OACA,IACA,MACA,OACA,KACO;CACP,GAAG,SAAS;CACZ,KAAK,KAAK,KAAK;CACf,MAAM,KAAK,KAAK;CAChB,OAAO,MAAM,QAAQ;EACpB,MAAM,IAAI,MAAM,IAAI;EACpB,MAAM,IAAI,IAAI;EACd,MAAM,KAAK,IAAI,KAAK;EACpB,KAAK,IAAI,IAAI,GAAG,IAAI,GAAG,KAAK;GAC3B,MAAM,KAAK,IAAI,SAAS;GACxB,MAAM,KAAK,IAAI,SAAS;GACxB,IAAI,KAAK,KAAK,KAAK,KAAK,MAAM,SAAS,MAAM,OAAO;GACpD,MAAM,IAAI,KAAK,QAAQ;GACvB,IAAI,GAAG,OAAO,GAAG;GACjB,MAAM,OAAO,MAAM;GACnB,IAAI,QAAQ,IAAI,SAAS,IAAI,SAAS,OAAO;GAC7C,GAAG,KAAK;GACR,KAAK,KAAK,CAAC;GACX,MAAM,KAAK,CAAC;EACb;CACD;AACD;;;;;;;;;;;AAyBA,SAAgB,WAAW,SAAqD,OAAe,MAAc,UAA6B,CAAC,GAAa;CACvJ,MAAM,EAAE,OAAO,UAAU;CACzB,MAAM,QAAQ,QAAQ,MAAM;CAC5B,IAAI,CAAC,SAAS,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,QAAQ,QAAQ,SAAS,MAAM,UAAU,GAAG,OAAO,CAAC;CACzG,MAAM,MAAgB,CAAC;CACvB,WAAW,OAAO,OAAO,OAAO,QAAQ,YAAY,MAAM,QAAQ,IAAI,MAAM,IAAI,WAAW,QAAQ,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG;CACrH,OAAO,IAAI,MAAM,GAAG,MAAM,IAAI,CAAC;AAChC"}

package/dist/cinematics.d.ts

@@ -72,7 +72,11 @@ export interface CinematicEnded {
     /** How it ended there */
     outcome: CinematicOutcome;
 }
-/** @beta */
+/**
+ * How a cinematic is played when a rule calls for it: who sees it, whether the game waits and whether it can be skipped
+ *
+ * @beta
+ */
 export interface CinematicOptions {
     /** Who sees it: a player, some, or everyone. Everyone when left out */
     to?: Audience;
@@ -154,6 +158,7 @@ export interface CinematicChoice {
     cinematic: string;
     /** The choice's name in the cinematic (`choice` when it gave none), and the answer's id */
     question: string;
+    /** The id of the answer picked */
     choice: string;
     /** Whether nobody picked and the time ran out on its default */
     timedOut: boolean;
@@ -161,14 +166,14 @@ export interface CinematicChoice {
 /** A player's pick of a choice of a cinematic, as their screen said: heard by the rules as `cinematicChoice` */
 export declare function cinematicChose(world: World, choice: CinematicChoice): void;
 /**
- * A step of a sequence that plays one of the view's cinematics: `defineSequence('td.start', [cinematic('td.intro', {
- * hold: true }), ...talk(...)])`. It does not wait for it (with `hold`, the game, and the sequence with it, waits),
+ * A step of a sequence that plays one of the view's cinematics: `defineSequence({ id: 'td.start', steps: [cinematic('td.intro', {
+ * hold: true }), ...talk(...)] })`. It does not wait for it (with `hold`, the game, and the sequence with it, waits),
  * unless told to: `wait: 'ended'` goes on once the player it was for has seen it end (or skipped it), `any` once one
  * of the players it went to has, `all` once every one of them has. Only players with a screen are waited for (not the
  * computer's); one who left a game of several never says, so a sequence for many waits for `any` where that matters.
  * With a wait it is two steps, which `defineSequence` takes as they are
  *
- * @beta
+ * @public
  */
 export declare function cinematic<D = undefined>(id: string, options?: CinematicOptions & {
     wait?: undefined;
@@ -176,7 +181,7 @@ export declare function cinematic<D = undefined>(id: string, options?: Cinematic
 /**
  * With `wait`: the cinematic played, then a wait for its end (see the other form), as two steps
  *
- * @beta
+ * @public
  */
 export declare function cinematic<D = undefined>(id: string, options: CinematicOptions & {
     wait: CinematicWait;

package/dist/cinematics.js

@@ -0,0 +1,161 @@
+import { defineComponent } from "./components.js";
+import { defineListener } from "./events.js";
+import { cinematicChoice, cinematicCue as cinematicCue$1, cinematicCued, cinematicEnded as cinematicEnded$1, enteredArea } from "./engineEvents.js";
+import { replicateEvent } from "./replication.js";
+import { plain } from "./plain.js";
+import { waitUntil } from "./sequences.js";
+//#region src/cinematics.ts
+/** The outcomes a screen may report, for the command's check */
+var CINEMATIC_OUTCOMES = [
+	"ended",
+	"skipped",
+	"stopped",
+	"replaced",
+	"ignored"
+];
+/**
+* Plays one of the view's cinematics on the screens of the players it is for, now
+*
+* @beta
+*/
+function playCinematic(world, id, options = {}) {
+	const { to = "everyone", hold = false, skippable = true, params } = options;
+	world.events.emit(cinematicCue$1, {
+		id,
+		to: audience(to),
+		hold,
+		skippable,
+		...params && { params: plain(params, `params of the cinematic "${id}"`, "Cinematic") }
+	});
+}
+/** Who a cue or a cinematic goes to, as a list: everyone's is left out */
+var audience = (to) => to === "everyone" ? void 0 : Array.isArray(to) ? to : [to];
+/**
+* Cues the cinematic playing on the screens of the players it is for (everyone when left out): one waiting for it
+* (`cut.untilCue(name)`) goes on, and the view's hooks of it (`cue:<name>`) run. Nothing happens where none plays, or
+* the one playing does not listen for it. `params` is plain data the cue carries
+*
+* @beta
+*/
+function cueCinematic(world, cue, options = {}) {
+	const { to = "everyone", params } = options;
+	world.events.emit(cinematicCued, {
+		cue,
+		to: audience(to),
+		...params && { params: plain(params, `params of the cue "${cue}"`, "Cinematic") }
+	});
+}
+/**
+* A step of a sequence that cues the cinematic playing (see `cueCinematic`): `[wait(4), cinematicCue('gateOpen')]`
+*
+* @beta
+*/
+var cinematicCue = (cue, options) => (world) => cueCinematic(world, cue, options);
+/** The sequences waiting for a cinematic to end on players' screens: in the world, so that a save keeps the count */
+var waits = defineComponent({
+	id: "core.cinematicWaits",
+	default: () => ({ list: [] })
+});
+/**
+* A player's screen says a cinematic the rules played is over (the `cinematic` command): the engine says so to the rules
+* (`cinematicEnded`), and a sequence that waits for it counts it
+*/
+function cinematicEnded(world, player, cinematic, outcome) {
+	if (world.states.has(waits)) for (const entry of world.state(waits).list) {
+		if (entry.cinematic !== cinematic || !entry.waiting.includes(player)) continue;
+		entry.waiting = entry.any ? [] : entry.waiting.filter((other) => other !== player);
+	}
+	world.events.emit(cinematicEnded$1, {
+		player,
+		cinematic,
+		outcome
+	});
+}
+/** A player's pick of a choice of a cinematic, as their screen said: heard by the rules as `cinematicChoice` */
+function cinematicChose(world, choice) {
+	world.events.emit(cinematicChoice, choice);
+}
+/**
+* The players a cinematic goes to that have a screen to say it ended: the ones of `to` (everyone's when left out) the
+* computer does not play, and not the neutral ones
+*/
+function screensOf(world, to) {
+	const computers = new Set(world.computers.list());
+	const out = [];
+	for (const player of world.players.values()) {
+		if (player.neutral || computers.has(player.id) || to && !to.includes(player.id)) continue;
+		out.push(player.id);
+	}
+	return out;
+}
+function cinematic(id, options = {}) {
+	const { wait, ...rest } = options;
+	const play = (world) => playCinematic(world, id, rest);
+	if (!wait) return play;
+	const begin = (world, _data, run) => {
+		const state = world.state(waits);
+		state.list = state.list.filter((entry) => entry.run !== run && world.sequences.running(entry.run));
+		state.list.push({
+			run,
+			cinematic: id,
+			waiting: screensOf(world, audience(rest.to ?? "everyone")),
+			any: wait === "any"
+		});
+		playCinematic(world, id, rest);
+	};
+	return [begin, waitUntil((world, _data, run) => {
+		const state = world.state(waits);
+		const entry = state.list.find((candidate) => candidate.run === run);
+		if (entry && entry.waiting.length > 0) return false;
+		state.list = state.list.filter((candidate) => candidate !== entry);
+		return true;
+	})];
+}
+/** A cinematic played, to whom it is for: everyone when it names nobody */
+var toldCinematic = replicateEvent(cinematicCue$1, "cinematic", ({ id, to, hold, skippable, params }, view) => !to || to.includes(view.player) ? {
+	type: "cinematic",
+	cinematic: id,
+	hold,
+	skippable,
+	...params && { params }
+} : void 0);
+/** A cue of the rules to a cinematic playing, to whom it is for */
+var toldCinematicCue = replicateEvent(cinematicCued, "cinematicCue", ({ cue, to, params }, view) => !to || to.includes(view.player) ? {
+	type: "cinematicCue",
+	cue,
+	...params && { params }
+} : void 0);
+/**
+* The regions whose cinematic has played (`MapRegion.cinematic`), by name: kept in the world, so that a save knows
+*
+* @internal
+*/
+var regionCinematicsPlayed = defineComponent({
+	id: "core.regionCinematics",
+	default: () => ({})
+});
+/**
+* A region of the map with a cinematic (`MapRegion.cinematic`, ED4) plays it for everyone, once, the first time a unit
+* of a player (not the neutral, nor a building) walks in, unless the game plays it its own way (`play: 'code'`)
+*
+* @beta
+*/
+var regionCinematic = defineListener({
+	id: "core.regionCinematic",
+	event: enteredArea,
+	run(world, { area, entity }) {
+		const cinematic = world.map.regions.find((each) => each.name === area)?.cinematic;
+		if (!cinematic || cinematic.play === "code" || world.player(entity.owner).neutral) return;
+		const played = world.state(regionCinematicsPlayed);
+		if (played[area]) return;
+		world.setState(regionCinematicsPlayed, {
+			...played,
+			[area]: true
+		});
+		playCinematic(world, cinematic.id);
+	}
+});
+//#endregion
+export { CINEMATIC_OUTCOMES, cinematic, cinematicChose, cinematicCue, cinematicEnded, cueCinematic, playCinematic, regionCinematic, regionCinematicsPlayed, toldCinematic, toldCinematicCue, waits };
+
+//# sourceMappingURL=cinematics.js.map