@v12-engine/engine 0.1.0 → 0.4.0

package/dist/session/worker.js

@@ -0,0 +1,499 @@
+import { checkpoint } from "../engineEvents.js";
+import { Logger, errorFields, rootLogger } from "../log.js";
+import { navigationData } from "../navigation/builds.js";
+import { saveWorld } from "../save.js";
+import { createWorldFromMap, loadWorld } from "../game.js";
+import { paceOf, savesOf } from "./can.js";
+import { RemoteSession, SessionHost, connectAs } from "./remote.js";
+import { reloadGame } from "../hotReload.js";
+import { randomSeed } from "./seed.js";
+//#region src/session/worker.ts
+/** Milliseconds between two words of where the time went */
+var TIMING_EVERY = 1e3;
+var firstOfMap = (map) => (map.players.find((player) => player.start) ?? map.players[0])?.id;
+function firstOfWorld(world) {
+	for (const player of world.players.values()) if (!player.neutral && !player.creeps) return player.id;
+	throw new Error("The world has no player to play: every one of its players is neutral");
+}
+/**
+* What a game's worker file does: `serveWorld(game, { onStart })`. It waits for the page to say what to play (a map, a
+* save, or nothing for a world made here in code), makes the world, runs it by the clock, and seats the page's player
+* at it. A new game asked for ends the one before: a restart is the same worker, its navigation built already
+*
+* @public
+*/
+function serveWorld(first, options = {}) {
+	/** The game's version now: the one it began with, or the one it took last (`reload`) */
+	let game = first;
+	const port = options.port ?? globalThis;
+	const post = (message, transfer) => port.postMessage(message, transfer);
+	/** The game running now, and what ends it */
+	let running;
+	/** Whether the systems are measured, as the page's stats ask: off until they do */
+	let profiling = false;
+	/** Each start has a number: one overtaken while its world was made is let go */
+	let starts = 0;
+	const start = async (asked) => {
+		const mine = ++starts;
+		running?.end();
+		running = void 0;
+		const log = new Logger();
+		const stopLog = log.to((entry) => post({
+			vg: "log",
+			entry
+		}));
+		let world;
+		try {
+			const seed = asked.seed ?? randomSeed();
+			world = asked.from ? await loadWorld(asked.from, {
+				rules: game,
+				log
+			}) : asked.map ? await createWorldFromMap({
+				map: asked.map,
+				rules: game,
+				seed,
+				log
+			}) : options.world ? await options.world({
+				rules: game,
+				seed,
+				args: asked.args,
+				log
+			}) : void 0;
+			if (!world) throw new Error("A game in a worker needs a map, a save to go on from, or a world made in the worker (serveWorld world)");
+			if (mine !== starts) return world.dispose();
+			world.errorPolicy ??= "end";
+			const player = asked.player ?? options.player?.(world, asked.map) ?? (asked.map && firstOfMap(asked.map)) ?? firstOfWorld(world);
+			const context = {
+				player,
+				map: asked.map,
+				args: asked.args,
+				tell: (data) => {
+					if (mine === starts) post({
+						vg: "told",
+						data
+					});
+				}
+			};
+			if (!asked.from) await options.onStart?.(world, context);
+			if (mine !== starts) return world.dispose();
+			await options.beforePlay?.(world, {
+				...context,
+				fresh: !asked.from
+			});
+			if (mine !== starts) return world.dispose();
+			if (asked.reveal) world.fog.setRevealed(world.player(player).team, true);
+			if (asked.debug) world.debugPlayers.add(player);
+			const made = world;
+			const host = new SessionHost(made, {
+				ownsWorld: true,
+				sendRate: made.tickRate,
+				dropSilentAfter: Infinity
+			});
+			let hear = () => {};
+			const transport = {
+				send: (text) => post(text),
+				onMessage: (handler) => hear = handler,
+				onClose: () => {},
+				close: () => {}
+			};
+			const stopCheckpoint = made.events.on(checkpoint, ({ label }) => {
+				setTimeout(() => {
+					if (running?.host === host) post({
+						vg: "checkpoint",
+						label,
+						save: saveWorld(made)
+					});
+				}, 0);
+			});
+			made.scheduler.profiling = profiling;
+			const timingTimer = setInterval(() => {
+				const timing = host.takeTiming();
+				post({
+					vg: "timing",
+					tick: timing.ticks ? timing.tickTime / timing.ticks : 0,
+					tickMax: timing.tickMax,
+					send: timing.sends ? timing.sendTime / timing.sends : 0,
+					systems: made.scheduler.timing()
+				});
+			}, TIMING_EVERY);
+			running = {
+				host,
+				hear: (text) => hear(text),
+				end: () => {
+					clearInterval(timingTimer);
+					stopCheckpoint();
+					stopLog();
+					host.dispose();
+				}
+			};
+			post({
+				vg: "ready",
+				player,
+				about: options.about?.(made, {
+					player,
+					map: asked.map,
+					args: asked.args
+				})
+			});
+			host.connect(player, transport, { inOrder: true });
+			host.start();
+		} catch (error) {
+			stopLog();
+			world?.dispose();
+			if (mine === starts) post({
+				vg: "refused",
+				message: error instanceof Error ? error.message : String(error),
+				stack: error instanceof Error ? error.stack : void 0
+			});
+		}
+	};
+	const heard = (message) => {
+		if (typeof message === "string") return running?.hear(message);
+		const said = message;
+		if (typeof said !== "object" || said === null) return;
+		switch (said.vg) {
+			case "start":
+				start(said);
+				return;
+			case "reload":
+				(async () => {
+					const world = running?.host.world;
+					if (!options.reload) {
+						world?.log.warn("game", `${game.id} in a worker has no reload (serveWorld reload): it keeps the version it began with`);
+						return;
+					}
+					try {
+						const next = await options.reload(Date.now());
+						if (!next) return;
+						game = next;
+						if (world && running?.host.world === world) reloadGame(world, next);
+					} catch (error) {
+						world?.log.error("game", `${game.id}'s new version could not be taken in the worker: ${error instanceof Error ? error.message : String(error)}`);
+					}
+				})();
+				return;
+			case "stop":
+				starts++;
+				running?.end();
+				running = void 0;
+				return;
+			case "speed":
+				if (running) running.host.speed = said.speed;
+				return;
+			case "advance": return running?.host.advance(said.ticks);
+			case "save":
+				try {
+					if (!running) throw new Error("There is no game to save");
+					post({
+						vg: "saved",
+						id: said.id,
+						save: saveWorld(running.host.world)
+					});
+				} catch (error) {
+					post({
+						vg: "saved",
+						id: said.id,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				}
+				return;
+			case "navigation":
+				navigationData(said.build).then((data) => post({
+					vg: "built",
+					id: said.id,
+					data
+				}), (error) => post({
+					vg: "built",
+					id: said.id,
+					error: error instanceof Error ? error.message : String(error)
+				}));
+				return;
+			case "profile":
+				profiling = said.on;
+				if (running) running.host.world.scheduler.profiling = said.on;
+				return;
+		}
+	};
+	if (port.on) port.on("message", heard);
+	else port.addEventListener?.("message", (event) => heard(event.data));
+}
+/**
+* A seat at a game run in a worker of this page (`workerSession`): a `RemoteSession` whose host is a message away,
+* with what a game played in the page has besides: its pace held and stepped (`speed`, `advance`), a save of it
+* (`save`), the checkpoint to start again from, what it says in its log, the debug tools' view, and where its time went
+*
+* @beta
+*/
+var WorkerSession = class extends RemoteSession {
+	/** What the world says (`World.log`), said again here: the page shows it with its own */
+	log;
+	/** The label and save of the last checkpoint the worker's game took, to retry from */
+	checkpoint;
+	/** What the worker's file said of the world as the game started (`ServeWorldOptions.about`): plain data, none where it says nothing */
+	about;
+	/** The debug tools' view of the world, where they are on: over the session's own words, as a server's is */
+	get debug() {
+		return this.debugView;
+	}
+	/** Its pace held and stepped, saves of it, the debug tools' view where they are on, and where its time went and in which systems */
+	can = {
+		pace: paceOf(this),
+		saves: savesOf(this),
+		inspect: this.debugView,
+		timing: {
+			timing: () => this.timing(),
+			profile: (on) => this.postToWorker({
+				vg: "profile",
+				on
+			})
+		}
+	};
+	pace = 1;
+	timed;
+	/** Milliseconds the page took to take in what the worker sent, each time, evened out: its share of a game run there */
+	received = 0;
+	postToWorker = () => {};
+	saves = /* @__PURE__ */ new Map();
+	nextSave = 0;
+	stopHearing = () => {};
+	/** Who hears what the worker's code tells (`onTold`), and what it told before anyone listened */
+	listening = /* @__PURE__ */ new Set();
+	toldBefore = [];
+	/** What `workerSession` gives it once it is made: the way to the worker, and what stops hearing it */
+	wire(post, log, stop) {
+		this.postToWorker = post;
+		this.log = log;
+		this.stopHearing = stop;
+	}
+	/** What the worker said that is not the session's own text */
+	heard(said) {
+		if (said.vg === "checkpoint") this.checkpoint = {
+			label: said.label,
+			save: said.save
+		};
+		else if (said.vg === "told") {
+			if (this.listening.size) for (const listener of this.listening) listener(said.data);
+			else this.toldBefore.push(said.data);
+		} else if (said.vg === "timing") this.timed = {
+			tick: said.tick,
+			tickMax: said.tickMax,
+			send: said.send,
+			systems: said.systems
+		};
+		else if (said.vg === "saved") {
+			const waiting = this.saves.get(said.id);
+			this.saves.delete(said.id);
+			if (said.save) waiting?.done(said.save);
+			else waiting?.failed(new Error(said.error ?? "The game could not be saved"));
+		}
+	}
+	/**
+	* Hears what the worker's code tells the page (`WorkerGameContext.tell`): plain data, in order with the ticks. What
+	* it told before anyone listened is heard by the first listener, at once. Gives back what stops hearing it
+	*/
+	onTold(listener) {
+		this.listening.add(listener);
+		for (const data of this.toldBefore.splice(0)) listener(data);
+		return () => this.listening.delete(listener);
+	}
+	/**
+	* How far behind the newest tick the screen is shown, in ticks: one, and room for how unevenly they come (a tick
+	* that took long comes late). Less than over a wire, where two are kept in hand: there is no line to stall here
+	*/
+	get delay() {
+		return this.interval + Math.min(this.jitter, this.limits.maxJitter ?? .2) * this.tickRate * 2;
+	}
+	/** The simulation speed multiplier the worker's game runs at, 0 pauses; setting it tells the worker */
+	get speed() {
+		return this.pace;
+	}
+	set speed(speed) {
+		this.pace = speed;
+		this.postToWorker({
+			vg: "speed",
+			speed
+		});
+	}
+	/** Asks the worker to step the held game by this many ticks */
+	advance(ticks = 1) {
+		this.postToWorker({
+			vg: "advance",
+			ticks
+		});
+	}
+	/**
+	* Asks the worker to take a new version of the game (hot reload): it loads the game again itself, as its file says
+	* (`serveWorld` `reload`), and puts it into its world
+	*/
+	reloadGame() {
+		this.postToWorker({ vg: "reload" });
+	}
+	/** Asks the worker for a save of its world and resolves with it; rejects if the game ends first */
+	save() {
+		return new Promise((done, failed) => {
+			const id = ++this.nextSave;
+			this.saves.set(id, {
+				done,
+				failed
+			});
+			this.postToWorker({
+				vg: "save",
+				id
+			});
+		});
+	}
+	/** Where the worker's time went (tick, send and receive milliseconds and each system's), or undefined until it has said */
+	timing() {
+		return this.timed && {
+			...this.timed,
+			receive: this.received
+		};
+	}
+	/** Ends the game in the worker. The worker is the page's: it stays, for the next game, until the page ends it */
+	dispose() {
+		this.postToWorker({ vg: "stop" });
+		this.stopHearing();
+		for (const waiting of this.saves.values()) waiting.failed(/* @__PURE__ */ new Error("The game ended"));
+		this.saves.clear();
+		super.dispose();
+	}
+};
+/** What cuts off the seat at the game a worker plays now, by the worker: a new game there ends it */
+var lines = /* @__PURE__ */ new WeakMap();
+/**
+* Plays a game in a worker, and seats this page's player at it: the worker's file calls `serveWorld` with the same
+* game. Settles once the world is made there and its welcome is in; fails with what the worker said went wrong
+*
+*     const session = await workerSession(new Worker(new URL('./game.worker.ts', import.meta.url), { type: 'module' }), { rules: game, map })
+*
+* @beta
+*/
+async function workerSession(worker, options) {
+	const { rules: game, navigation, maps, log: under, ...asked } = options;
+	let toSession = () => {};
+	let closed = () => {};
+	let session;
+	const builds = /* @__PURE__ */ new Map();
+	let nextBuild = 0;
+	/** What the worker said of its world as it was ready, before there is a session to keep it */
+	let about;
+	/** What the worker's code told before there is a session to hear it */
+	const early = [];
+	let saying;
+	const log = (under ?? rootLogger).child({ context: () => ({
+		game: saying?.game,
+		tick: saying?.tick
+	}) });
+	lines.get(worker)?.();
+	let cut = false;
+	const post = (message) => {
+		if (!cut) worker.postMessage(message);
+	};
+	let refuse = () => {};
+	const refused = new Promise((_, reject) => refuse = reject);
+	refused.catch(() => {});
+	const heard = (message) => {
+		if (typeof message === "string") {
+			const began = performance.now();
+			toSession(message);
+			if (session) session.received += (performance.now() - began - session.received) * .1;
+			return;
+		}
+		const said = message;
+		if (typeof said !== "object" || said === null) return;
+		if (said.vg === "refused") {
+			const error = new Error(said.message);
+			if (said.stack) error.stack = said.stack;
+			refuse(error);
+		} else if (said.vg === "log") {
+			saying = said.entry;
+			log.log(said.entry.level, said.entry.category, said.entry.message, said.entry.fields);
+			saying = void 0;
+		} else if (said.vg === "built") {
+			const waiting = builds.get(said.id);
+			builds.delete(said.id);
+			if (said.data) waiting?.done(said.data);
+			else waiting?.failed(new Error(said.error ?? "The navigation could not be built"));
+		} else if (said.vg === "ready") about = said.about;
+		else if (!session && said.vg === "told") early.push(said);
+		else session?.heard(said);
+	};
+	const broke = (error) => {
+		const reason = /* @__PURE__ */ new Error(`The game's worker stopped: ${error instanceof Error ? error.message : String(error?.message ?? error)}`);
+		log.error("game", reason.message, { error: errorFields(error) });
+		refuse(reason);
+		closed();
+	};
+	const onMessage = (event) => heard(event.data);
+	if (worker.on) {
+		worker.on("message", heard);
+		worker.on("error", broke);
+	} else {
+		worker.addEventListener?.("message", onMessage);
+		worker.addEventListener?.("error", broke);
+	}
+	const stop = () => {
+		if (worker.off) {
+			worker.off("message", heard);
+			worker.off("error", broke);
+		} else {
+			worker.removeEventListener?.("message", onMessage);
+			worker.removeEventListener?.("error", broke);
+		}
+	};
+	lines.set(worker, () => {
+		cut = true;
+		stop();
+	});
+	const transport = {
+		send: (text) => post(text),
+		onMessage: (handler) => toSession = handler,
+		onClose: (handler) => closed = handler,
+		close: () => {}
+	};
+	post({
+		vg: "start",
+		...asked
+	});
+	try {
+		session = await Promise.race([connectAs(transport, {
+			rules: game,
+			maps,
+			navigation: {
+				...navigation,
+				builds: { builder: (build) => new Promise((done, failed) => {
+					const id = ++nextBuild;
+					builds.set(id, {
+						done,
+						failed
+					});
+					post({
+						vg: "navigation",
+						id,
+						build: {
+							positions: build.positions.slice(),
+							indices: build.indices.slice(),
+							config: build.config,
+							...build.speeds && { speeds: {
+								...build.speeds,
+								values: build.speeds.values.slice()
+							} }
+						}
+					});
+				}) }
+			}
+		}, (...made) => new WorkerSession(...made)), refused]);
+	} catch (error) {
+		post({ vg: "stop" });
+		stop();
+		throw error;
+	}
+	session.wire(post, log, stop);
+	session.about = about;
+	for (const said of early.splice(0)) session.heard(said);
+	return session;
+}
+//#endregion
+export { WorkerSession, serveWorld, workerSession };
+
+//# sourceMappingURL=worker.js.map

package/dist/session/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","names":["checkpointEvent"],"sources":["../../src/session/worker.ts"],"sourcesContent":["import { checkpoint as checkpointEvent } from '#engine/engineEvents'\nimport { reloadGame } from '#engine/hotReload'\nimport { randomSeed } from '#engine/session/seed'\nimport { paceOf, savesOf } from './can'\nimport type { PlayerId } from '#engine/entity'\nimport { createWorldFromMap, type Rules, loadWorld } from '#engine/game'\nimport { errorFields, type LogEntry, Logger, rootLogger } from '#engine/log'\nimport type { GameMap } from '#engine/map'\nimport type { Message } from '#engine/messages'\nimport { type NavigationBuild, navigationData } from '#engine/navigation/builds'\nimport { saveWorld, type WorldSave } from '#engine/save'\nimport type { World } from '#engine/world'\nimport type { SystemTiming } from '#engine/scheduler'\nimport type { SessionCan, SessionDebug } from './protocol'\nimport { type ConnectOptions, connectAs, MAX_JITTER, RemoteSession, SessionHost, type Transport } from './remote'\n\n/*\n * The simulation off the page's thread (S54). A game played alone steps its world on the thread that draws: a tick that\n * takes long is a frame that is late. Here the world runs in a worker the page gives, and the page has a seat at it as\n * it would at a server's game: snapshots one way, commands the other, over the worker's messages. The game's code has to\n * be in the worker, and only the game's developer can put it there: the worker's file is theirs, one call\n * (`serveWorld(game, { onStart })`), made into a worker the way their bundler wants it; the library makes none. What\n * the page did by reaching into the world (holding the game for a menu, a step, a save, the checkpoint to retry from,\n * the debug tools' view, what the game says in its log) goes over the same messages.\n */\n\n/**\n * What a worker is, as far as a game goes: a page's `Worker`, or Node's `worker_threads` one\n *\n * @beta\n */\nexport interface WorldWorkerLike {\n\t/** Sends a message to the worker, with objects to transfer rather than copy */\n\tpostMessage(message: unknown, transfer?: unknown[]): void\n\t/** Listens for the worker's messages or errors, where the worker is a page's `Worker` */\n\taddEventListener?(type: 'message' | 'error', listener: (event: { data?: unknown; message?: string }) => void): void\n\t/** Stops a listener added with `addEventListener` */\n\tremoveEventListener?(type: 'message' | 'error', listener: (event: { data?: unknown; message?: string }) => void): void\n\t/** Listens for the worker's messages or errors, where the worker is Node's `worker_threads` one */\n\ton?(type: 'message' | 'error', listener: (value: unknown) => void): void\n\t/** Stops a listener added with `on` */\n\toff?(type: 'message' | 'error', listener: (value: unknown) => void): void\n}\n\n/**\n * Where a worker hears and answers: a page's worker scope, or Node's `parentPort`\n *\n * @beta\n */\nexport interface WorldPort {\n\t/** Sends a message to the page, with objects to transfer rather than copy */\n\tpostMessage(message: unknown, transfer?: unknown[]): void\n\t/** Listens for the page's messages, where the port is a worker scope */\n\taddEventListener?(type: 'message', listener: (event: { data: unknown }) => void): void\n\t/** Listens for the page's messages, where the port is Node's `parentPort` */\n\ton?(type: 'message', listener: (value: unknown) => void): void\n}\n\n/**\n * What the page says a game in a worker is made from: plain data, which is all that crosses\n *\n * @beta\n */\nexport interface WorkerGame {\n\t/** A map of the game: the world is made from it. Or a save to go on from (`from`); or neither, where the worker makes its world in code */\n\tmap?: GameMap\n\t/** A save to continue the game from, in place of a map */\n\tfrom?: WorldSave\n\t/** Who the player at the screen is: as the worker says (`ServeWorldOptions.player`), then the map's first with a start, when left out */\n\tplayer?: PlayerId\n\t/** The seed the world's random generator starts with */\n\tseed?: number\n\t/** Whether the player may use the debug tools, and sees everything from the start */\n\tdebug?: boolean\n\t/** Whether the player sees the whole map from the start */\n\treveal?: boolean\n\t/** Anything else the worker's own code is to know (`start`, `world`): plain data */\n\targs?: unknown\n}\n\n/**\n * What the worker's code that runs on a world is given (`ServeWorldOptions.onStart`, `beforePlay`): the player at the\n * screen, the map, what the page sent (`WorkerGame.args`), and a way to tell the page something\n *\n * @beta\n */\nexport interface WorkerGameContext {\n\t/** The player at the screen */\n\tplayer: PlayerId\n\t/** The map the world was made from, where it was made from one (or sent with a save) */\n\tmap?: GameMap\n\t/** What the page sent for the worker's own code (`WorkerGame.args`): plain data */\n\targs: unknown\n\t/**\n\t * Tells the page something, while this game lasts: plain data, as it crosses (a mission won and what it carries on).\n\t * The page hears it on its session (`WorkerSession.onTold`), in order with the game's ticks: what is told in a tick\n\t * is heard before the snapshot of that tick. Said for nothing once the game has ended\n\t */\n\ttell(data: unknown): void\n}\n\n/**\n * What the worker's file gives besides the game: its code that runs on the world, which cannot be sent\n *\n * @beta\n */\nexport interface ServeWorldOptions {\n\t/** A world made in code, where the page gives neither a map nor a save: generated ground, players of its own */\n\tworld?: (context: { rules: Rules; seed: number; args: unknown; log: Logger }) => World | Promise<World>\n\t/** What the game does once a new world is made, before anyone plays: as `launch`'s `start`, which a worker's game has here */\n\tonStart?: (world: World, context: WorkerGameContext) => void | Promise<void>\n\t/**\n\t * What the game does before anyone plays, a new world or one loaded from a save (`fresh`), after `onStart`: as\n\t * `prepareGame`'s `beforePlay`, which a worker's game has here. What it listens to on the world it listens to for\n\t * this game alone, as a loaded game has none of what the game before listened to\n\t */\n\tbeforePlay?: (world: World, context: WorkerGameContext & { fresh: boolean }) => void | Promise<void>\n\t/** Who the player at the screen is, where the page does not say */\n\tplayer?: (world: World, map?: GameMap) => PlayerId\n\t/**\n\t * What the page is told of the world as the game starts, which it cannot reach into: where the player's base is, who\n\t * the other side is. Plain data, as it crosses; the page reads it on its session (`WorkerSession.about`). Asked once\n\t * the world is made and started (`onStart`), for a new game and for one loaded\n\t */\n\tabout?: (world: World, context: { player: PlayerId; map?: GameMap; args: unknown }) => unknown\n\t/** Where it hears: the worker's own scope when left out (a page's worker); Node's `parentPort` in a worker thread */\n\tport?: WorldPort\n\t/**\n\t * A new version of the game, loaded again in the worker as the page asks (hot reload: the page's game took one, and\n\t * a worker has no hot reload of its own). The game's module imported anew, so that the dev server gives it as it is\n\t * now: `(version) => import(/* @vite-ignore *\\/ `./index.ts?t=${version}`).then((module) => module.myGame)` (a path\n\t * from the worker's file). Only ever asked for in the dev server. Without it, a game in the worker keeps the version it began with\n\t */\n\treload?: (version: number) => Promise<Rules | undefined> | Rules | undefined\n}\n\n/** What goes between the page and the worker besides the session's own text */\ntype ToWorker =\n\t| ({ vg: 'start' } & WorkerGame)\n\t| { vg: 'stop' }\n\t| { vg: 'reload' }\n\t| { vg: 'speed'; speed: number }\n\t| { vg: 'advance'; ticks: number }\n\t| { vg: 'save'; id: number }\n\t| { vg: 'navigation'; id: number; build: NavigationBuild }\n\t| { vg: 'profile'; on: boolean }\n\ntype FromWorker =\n\t| { vg: 'ready'; player: PlayerId; about?: unknown }\n\t| { vg: 'refused'; message: string; stack?: string }\n\t| { vg: 'saved'; id: number; save?: WorldSave; error?: string }\n\t| { vg: 'built'; id: number; data?: Uint8Array; error?: string }\n\t| { vg: 'checkpoint'; label: Message; save: WorldSave }\n\t| { vg: 'log'; entry: LogEntry }\n\t| { vg: 'timing'; tick: number; tickMax: number; send: number; systems: SystemTiming[] }\n\t| { vg: 'told'; data: unknown }\n\n/** Milliseconds between two words of where the time went */\nconst TIMING_EVERY = 1000\n\nconst firstOfMap = (map: GameMap): PlayerId | undefined => (map.players.find((player) => player.start) ?? map.players[0])?.id\n\nfunction firstOfWorld(world: World): PlayerId {\n\tfor (const player of world.players.values()) if (!player.neutral && !player.creeps) return player.id\n\tthrow new Error('The world has no player to play: every one of its players is neutral')\n}\n\n/**\n * What a game's worker file does: `serveWorld(game, { onStart })`. It waits for the page to say what to play (a map, a\n * save, or nothing for a world made here in code), makes the world, runs it by the clock, and seats the page's player\n * at it. A new game asked for ends the one before: a restart is the same worker, its navigation built already\n *\n * @public\n */\nexport function serveWorld(first: Rules, options: ServeWorldOptions = {}): void {\n\t/** The game's version now: the one it began with, or the one it took last (`reload`) */\n\tlet game = first\n\tconst port = options.port ?? (globalThis as unknown as WorldPort)\n\tconst post = (message: FromWorker | string, transfer?: unknown[]) => port.postMessage(message, transfer)\n\t/** The game running now, and what ends it */\n\tlet running: { host: SessionHost; hear: (text: string) => void; end: () => void } | undefined\n\t/** Whether the systems are measured, as the page's stats ask: off until they do */\n\tlet profiling = false\n\t/** Each start has a number: one overtaken while its world was made is let go */\n\tlet starts = 0\n\n\tconst start = async (asked: WorkerGame) => {\n\t\tconst mine = ++starts\n\t\trunning?.end()\n\t\trunning = undefined\n\t\t// what the world says goes to the page, which says it where it says its own: not twice, here too\n\t\tconst log = new Logger()\n\t\tconst stopLog = log.to((entry) => post({ vg: 'log', entry }))\n\t\tlet world: World | undefined\n\t\ttry {\n\t\t\tconst seed = asked.seed ?? randomSeed()\n\t\t\tworld = asked.from\n\t\t\t\t? await loadWorld(asked.from, { rules: game, log })\n\t\t\t\t: asked.map\n\t\t\t\t\t? await createWorldFromMap({ map: asked.map, rules: game, seed, log })\n\t\t\t\t\t: options.world\n\t\t\t\t\t\t? await options.world({ rules: game, seed, args: asked.args, log })\n\t\t\t\t\t\t: undefined\n\t\t\tif (!world) throw new Error('A game in a worker needs a map, a save to go on from, or a world made in the worker (serveWorld world)')\n\t\t\tif (mine !== starts) return world.dispose()\n\t\t\tworld.errorPolicy ??= 'end'\n\t\t\tconst player = asked.player ?? options.player?.(world, asked.map) ?? (asked.map && firstOfMap(asked.map)) ?? firstOfWorld(world)\n\t\t\t// what the game's code tells the page, while this game is the one played\n\t\t\tconst context: WorkerGameContext = {\n\t\t\t\tplayer,\n\t\t\t\tmap: asked.map,\n\t\t\t\targs: asked.args,\n\t\t\t\ttell: (data) => {\n\t\t\t\t\tif (mine === starts) post({ vg: 'told', data })\n\t\t\t\t}\n\t\t\t}\n\t\t\t// only a new game is started: one loaded goes on as it was\n\t\t\tif (!asked.from) await options.onStart?.(world, context)\n\t\t\tif (mine !== starts) return world.dispose()\n\t\t\tawait options.beforePlay?.(world, { ...context, fresh: !asked.from })\n\t\t\tif (mine !== starts) return world.dispose()\n\t\t\tif (asked.reveal) world.fog.setRevealed(world.player(player).team, true)\n\t\t\tif (asked.debug) world.debugPlayers.add(player)\n\n\t\t\tconst made = world\n\t\t\t// every tick goes to the page: there is no wire to spare, and the screen is as close to the world as it gets\n\t\t\tconst host = new SessionHost(made, { ownsWorld: true, sendRate: made.tickRate, dropSilentAfter: Infinity })\n\t\t\tlet hear: (text: string) => void = () => {}\n\t\t\tconst transport: Transport = { send: (text) => post(text), onMessage: (handler) => (hear = handler), onClose: () => {}, close: () => {} }\n\t\t\t// the checkpoint to start again from, as the world stood at the end of the tick that marked it\n\t\t\tconst stopCheckpoint = made.events.on(checkpointEvent, ({ label }) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tif (running?.host === host) post({ vg: 'checkpoint', label, save: saveWorld(made) })\n\t\t\t\t}, 0)\n\t\t\t})\n\t\t\t// measured as the page's stats ask (`profile`): the next game as the one before\n\t\t\tmade.scheduler.profiling = profiling\n\t\t\tconst timingTimer = setInterval(() => {\n\t\t\t\tconst timing = host.takeTiming()\n\t\t\t\tpost({\n\t\t\t\t\tvg: 'timing',\n\t\t\t\t\ttick: timing.ticks ? timing.tickTime / timing.ticks : 0,\n\t\t\t\t\ttickMax: timing.tickMax,\n\t\t\t\t\tsend: timing.sends ? timing.sendTime / timing.sends : 0,\n\t\t\t\t\tsystems: made.scheduler.timing()\n\t\t\t\t})\n\t\t\t}, TIMING_EVERY)\n\t\t\trunning = {\n\t\t\t\thost,\n\t\t\t\thear: (text) => hear(text),\n\t\t\t\tend: () => {\n\t\t\t\t\tclearInterval(timingTimer)\n\t\t\t\t\tstopCheckpoint()\n\t\t\t\t\tstopLog()\n\t\t\t\t\thost.dispose()\n\t\t\t\t}\n\t\t\t}\n\t\t\tpost({ vg: 'ready', player, about: options.about?.(made, { player, map: asked.map, args: asked.args }) })\n\t\t\t// a worker's messages are never lost nor reordered: each frame is the base of the next as it goes\n\t\t\thost.connect(player, transport, { inOrder: true })\n\t\t\thost.start()\n\t\t} catch (error) {\n\t\t\tstopLog()\n\t\t\tworld?.dispose()\n\t\t\tif (mine === starts)\n\t\t\t\tpost({\n\t\t\t\t\tvg: 'refused',\n\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\tstack: error instanceof Error ? error.stack : undefined\n\t\t\t\t})\n\t\t}\n\t}\n\n\tconst heard = (message: unknown) => {\n\t\t// the session's own words are text; everything else is said as an object\n\t\tif (typeof message === 'string') return running?.hear(message)\n\t\tconst said = message as ToWorker\n\t\tif (typeof said !== 'object' || said === null) return\n\t\tswitch (said.vg) {\n\t\t\tcase 'start':\n\t\t\t\treturn void start(said)\n\t\t\tcase 'reload':\n\t\t\t\treturn void (async () => {\n\t\t\t\t\tconst world = running?.host.world\n\t\t\t\t\tif (!options.reload) {\n\t\t\t\t\t\tworld?.log.warn('game', `${game.id} in a worker has no reload (serveWorld reload): it keeps the version it began with`)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst next = await options.reload(Date.now())\n\t\t\t\t\t\tif (!next) return\n\t\t\t\t\t\tgame = next\n\t\t\t\t\t\tif (world && running?.host.world === world) reloadGame(world, next)\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tworld?.log.error(\n\t\t\t\t\t\t\t'game',\n\t\t\t\t\t\t\t`${game.id}'s new version could not be taken in the worker: ${error instanceof Error ? error.message : String(error)}`\n\t\t\t\t\t\t)\n\t\t\t\t\t}\n\t\t\t\t})()\n\t\t\tcase 'stop':\n\t\t\t\tstarts++\n\t\t\t\trunning?.end()\n\t\t\t\trunning = undefined\n\t\t\t\treturn\n\t\t\tcase 'speed':\n\t\t\t\tif (running) running.host.speed = said.speed\n\t\t\t\treturn\n\t\t\tcase 'advance':\n\t\t\t\treturn running?.host.advance(said.ticks)\n\t\t\tcase 'save':\n\t\t\t\ttry {\n\t\t\t\t\tif (!running) throw new Error('There is no game to save')\n\t\t\t\t\tpost({ vg: 'saved', id: said.id, save: saveWorld(running.host.world) })\n\t\t\t\t} catch (error) {\n\t\t\t\t\tpost({ vg: 'saved', id: said.id, error: error instanceof Error ? error.message : String(error) })\n\t\t\t\t}\n\t\t\t\treturn\n\t\t\tcase 'navigation':\n\t\t\t\t// the page's own navigation (the ways it shows): built here, where the world's was, or kept from it\n\t\t\t\treturn void navigationData(said.build).then(\n\t\t\t\t\t(data) => post({ vg: 'built', id: said.id, data }),\n\t\t\t\t\t(error: unknown) => post({ vg: 'built', id: said.id, error: error instanceof Error ? error.message : String(error) })\n\t\t\t\t)\n\t\t\tcase 'profile':\n\t\t\t\tprofiling = said.on\n\t\t\t\tif (running) running.host.world.scheduler.profiling = said.on\n\t\t\t\treturn\n\t\t}\n\t}\n\tif (port.on) port.on('message', heard)\n\telse port.addEventListener?.('message', (event) => heard(event.data))\n}\n\n/**\n * A seat at a game run in a worker of this page (`workerSession`): a `RemoteSession` whose host is a message away,\n * with what a game played in the page has besides: its pace held and stepped (`speed`, `advance`), a save of it\n * (`save`), the checkpoint to start again from, what it says in its log, the debug tools' view, and where its time went\n *\n * @beta\n */\nexport class WorkerSession extends RemoteSession {\n\t/** What the world says (`World.log`), said again here: the page shows it with its own */\n\tlog!: Logger\n\t/** The label and save of the last checkpoint the worker's game took, to retry from */\n\tcheckpoint?: { label: Message; save: WorldSave }\n\t/** What the worker's file said of the world as the game started (`ServeWorldOptions.about`): plain data, none where it says nothing */\n\tabout?: unknown\n\t/** The debug tools' view of the world, where they are on: over the session's own words, as a server's is */\n\tget debug(): SessionDebug | undefined {\n\t\treturn this.debugView\n\t}\n\t/** Its pace held and stepped, saves of it, the debug tools' view where they are on, and where its time went and in which systems */\n\toverride readonly can: SessionCan = {\n\t\tpace: paceOf(this),\n\t\tsaves: savesOf(this),\n\t\tinspect: this.debugView,\n\t\ttiming: { timing: () => this.timing(), profile: (on) => this.postToWorker({ vg: 'profile', on }) }\n\t}\n\tprivate pace = 1\n\tprivate timed?: { tick: number; tickMax: number; send: number; systems: SystemTiming[] }\n\t/** Milliseconds the page took to take in what the worker sent, each time, evened out: its share of a game run there */\n\treceived = 0\n\tprivate postToWorker: (message: ToWorker) => void = () => {}\n\tprivate readonly saves = new Map<number, { done: (save: WorldSave) => void; failed: (error: Error) => void }>()\n\tprivate nextSave = 0\n\tprivate stopHearing: () => void = () => {}\n\t/** Who hears what the worker's code tells (`onTold`), and what it told before anyone listened */\n\tprivate readonly listening = new Set<(data: unknown) => void>()\n\tprivate readonly toldBefore: unknown[] = []\n\n\t/** What `workerSession` gives it once it is made: the way to the worker, and what stops hearing it */\n\twire(post: (message: ToWorker) => void, log: Logger, stop: () => void): void {\n\t\tthis.postToWorker = post\n\t\tthis.log = log\n\t\tthis.stopHearing = stop\n\t}\n\n\t/** What the worker said that is not the session's own text */\n\theard(said: FromWorker): void {\n\t\tif (said.vg === 'checkpoint') this.checkpoint = { label: said.label, save: said.save }\n\t\telse if (said.vg === 'told') {\n\t\t\tif (this.listening.size) for (const listener of this.listening) listener(said.data)\n\t\t\telse this.toldBefore.push(said.data)\n\t\t} else if (said.vg === 'timing') this.timed = { tick: said.tick, tickMax: said.tickMax, send: said.send, systems: said.systems }\n\t\telse if (said.vg === 'saved') {\n\t\t\tconst waiting = this.saves.get(said.id)\n\t\t\tthis.saves.delete(said.id)\n\t\t\tif (said.save) waiting?.done(said.save)\n\t\t\telse waiting?.failed(new Error(said.error ?? 'The game could not be saved'))\n\t\t}\n\t}\n\n\t/**\n\t * Hears what the worker's code tells the page (`WorkerGameContext.tell`): plain data, in order with the ticks. What\n\t * it told before anyone listened is heard by the first listener, at once. Gives back what stops hearing it\n\t */\n\tonTold(listener: (data: unknown) => void): () => void {\n\t\tthis.listening.add(listener)\n\t\tfor (const data of this.toldBefore.splice(0)) listener(data)\n\t\treturn () => this.listening.delete(listener)\n\t}\n\n\t/**\n\t * How far behind the newest tick the screen is shown, in ticks: one, and room for how unevenly they come (a tick\n\t * that took long comes late). Less than over a wire, where two are kept in hand: there is no line to stall here\n\t */\n\toverride get delay(): number {\n\t\treturn this.interval + Math.min(this.jitter, this.limits.maxJitter ?? MAX_JITTER) * this.tickRate * 2\n\t}\n\n\t/** The simulation speed multiplier the worker's game runs at, 0 pauses; setting it tells the worker */\n\tget speed(): number {\n\t\treturn this.pace\n\t}\n\n\tset speed(speed: number) {\n\t\tthis.pace = speed\n\t\tthis.postToWorker({ vg: 'speed', speed })\n\t}\n\n\t/** Asks the worker to step the held game by this many ticks */\n\tadvance(ticks = 1): void {\n\t\tthis.postToWorker({ vg: 'advance', ticks })\n\t}\n\n\t/**\n\t * Asks the worker to take a new version of the game (hot reload): it loads the game again itself, as its file says\n\t * (`serveWorld` `reload`), and puts it into its world\n\t */\n\treloadGame(): void {\n\t\tthis.postToWorker({ vg: 'reload' })\n\t}\n\n\t/** Asks the worker for a save of its world and resolves with it; rejects if the game ends first */\n\tsave(): Promise<WorldSave> {\n\t\treturn new Promise((done, failed) => {\n\t\t\tconst id = ++this.nextSave\n\t\t\tthis.saves.set(id, { done, failed })\n\t\t\tthis.postToWorker({ vg: 'save', id })\n\t\t})\n\t}\n\n\t/** Where the worker's time went (tick, send and receive milliseconds and each system's), or undefined until it has said */\n\ttiming(): { tick: number; tickMax: number; send: number; receive: number; systems: SystemTiming[] } | undefined {\n\t\treturn this.timed && { ...this.timed, receive: this.received }\n\t}\n\n\t/** Ends the game in the worker. The worker is the page's: it stays, for the next game, until the page ends it */\n\toverride dispose(): void {\n\t\tthis.postToWorker({ vg: 'stop' })\n\t\tthis.stopHearing()\n\t\tfor (const waiting of this.saves.values()) waiting.failed(new Error('The game ended'))\n\t\tthis.saves.clear()\n\t\tsuper.dispose()\n\t}\n}\n\n/**\n * What a seat at a worker's game is asked for: what to play (`WorkerGame`), and what `connect` takes\n *\n * @beta\n */\nexport interface WorkerSessionOptions extends WorkerGame, Pick<ConnectOptions, 'navigation' | 'maps'> {\n\t/** The game module's rules the worker's game runs, which the page needs the data of */\n\trules: Rules\n\t/** The logger what the world says is said under, in the page: the root one when left out */\n\tlog?: Logger\n}\n\n/** What cuts off the seat at the game a worker plays now, by the worker: a new game there ends it */\nconst lines = new WeakMap<object, () => void>()\n\n/**\n * Plays a game in a worker, and seats this page's player at it: the worker's file calls `serveWorld` with the same\n * game. Settles once the world is made there and its welcome is in; fails with what the worker said went wrong\n *\n *     const session = await workerSession(new Worker(new URL('./game.worker.ts', import.meta.url), { type: 'module' }), { rules: game, map })\n *\n * @beta\n */\nexport async function workerSession(worker: WorldWorkerLike, options: WorkerSessionOptions): Promise<WorkerSession> {\n\tconst { rules: game, navigation, maps, log: under, ...asked } = options\n\tlet toSession: (text: string) => void = () => {}\n\tlet closed: () => void = () => {}\n\tlet session: WorkerSession | undefined\n\tconst builds = new Map<number, { done: (data: Uint8Array) => void; failed: (error: Error) => void }>()\n\tlet nextBuild = 0\n\t/** What the worker said of its world as it was ready, before there is a session to keep it */\n\tlet about: unknown\n\t/** What the worker's code told before there is a session to hear it */\n\tconst early: FromWorker[] = []\n\t// what the world says, with the game and the tick it said it in\n\tlet saying: LogEntry | undefined\n\tconst log = (under ?? rootLogger).child({ context: () => ({ game: saying?.game, tick: saying?.tick }) })\n\t// the game before on this worker is over as this one starts (`start` ends it there): its seat neither speaks to the\n\t// worker nor hears it from now on, though its page goes on showing it a while (an app's scene before the next is in)\n\tlines.get(worker)?.()\n\tlet cut = false\n\tconst post = (message: ToWorker | string) => {\n\t\tif (!cut) worker.postMessage(message)\n\t}\n\n\tlet refuse: (error: Error) => void = () => {}\n\tconst refused = new Promise<never>((_, reject) => (refuse = reject))\n\t// nobody may be waiting on it: a game that started is not refused\n\trefused.catch(() => {})\n\n\tconst heard = (message: unknown) => {\n\t\tif (typeof message === 'string') {\n\t\t\tconst began = performance.now()\n\t\t\ttoSession(message)\n\t\t\tif (session) session.received += (performance.now() - began - session.received) * 0.1\n\t\t\treturn\n\t\t}\n\t\tconst said = message as FromWorker\n\t\tif (typeof said !== 'object' || said === null) return\n\t\tif (said.vg === 'refused') {\n\t\t\tconst error = new Error(said.message)\n\t\t\tif (said.stack) error.stack = said.stack\n\t\t\trefuse(error)\n\t\t} else if (said.vg === 'log') {\n\t\t\tsaying = said.entry\n\t\t\tlog.log(said.entry.level, said.entry.category, said.entry.message, said.entry.fields)\n\t\t\tsaying = undefined\n\t\t} else if (said.vg === 'built') {\n\t\t\tconst waiting = builds.get(said.id)\n\t\t\tbuilds.delete(said.id)\n\t\t\tif (said.data) waiting?.done(said.data)\n\t\t\telse waiting?.failed(new Error(said.error ?? 'The navigation could not be built'))\n\t\t} else if (said.vg === 'ready') about = said.about\n\t\telse if (!session && said.vg === 'told') early.push(said)\n\t\telse session?.heard(said)\n\t}\n\tconst broke = (error: unknown) => {\n\t\tconst reason = new Error(\n\t\t\t`The game's worker stopped: ${error instanceof Error ? error.message : String((error as { message?: string })?.message ?? error)}`\n\t\t)\n\t\tlog.error('game', reason.message, { error: errorFields(error) })\n\t\trefuse(reason)\n\t\tclosed()\n\t}\n\tconst onMessage = (event: { data?: unknown }) => heard(event.data)\n\tif (worker.on) {\n\t\tworker.on('message', heard)\n\t\tworker.on('error', broke)\n\t} else {\n\t\tworker.addEventListener?.('message', onMessage)\n\t\tworker.addEventListener?.('error', broke)\n\t}\n\tconst stop = () => {\n\t\tif (worker.off) {\n\t\t\tworker.off('message', heard)\n\t\t\tworker.off('error', broke)\n\t\t} else {\n\t\t\tworker.removeEventListener?.('message', onMessage)\n\t\t\tworker.removeEventListener?.('error', broke)\n\t\t}\n\t}\n\n\tlines.set(worker, () => {\n\t\tcut = true\n\t\tstop()\n\t})\n\n\tconst transport: Transport = {\n\t\tsend: (text) => post(text),\n\t\tonMessage: (handler) => (toSession = handler),\n\t\tonClose: (handler) => (closed = handler),\n\t\tclose: () => {}\n\t}\n\tpost({ vg: 'start', ...asked })\n\ttry {\n\t\tsession = await Promise.race([\n\t\t\tconnectAs(\n\t\t\t\ttransport,\n\t\t\t\t{\n\t\t\t\t\trules: game,\n\t\t\t\t\tmaps,\n\t\t\t\t\t// the page's own navigation is built in the worker, where the world's was: the page is never held for it\n\t\t\t\t\tnavigation: {\n\t\t\t\t\t\t...navigation,\n\t\t\t\t\t\tbuilds: {\n\t\t\t\t\t\t\tbuilder: (build) =>\n\t\t\t\t\t\t\t\tnew Promise<Uint8Array>((done, failed) => {\n\t\t\t\t\t\t\t\t\tconst id = ++nextBuild\n\t\t\t\t\t\t\t\t\tbuilds.set(id, { done, failed })\n\t\t\t\t\t\t\t\t\tpost({\n\t\t\t\t\t\t\t\t\t\tvg: 'navigation',\n\t\t\t\t\t\t\t\t\t\tid,\n\t\t\t\t\t\t\t\t\t\tbuild: {\n\t\t\t\t\t\t\t\t\t\t\tpositions: build.positions.slice(),\n\t\t\t\t\t\t\t\t\t\t\tindices: build.indices.slice(),\n\t\t\t\t\t\t\t\t\t\t\tconfig: build.config,\n\t\t\t\t\t\t\t\t\t\t\t...(build.speeds && { speeds: { ...build.speeds, values: build.speeds.values.slice() } })\n\t\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t(...made) => new WorkerSession(...made)\n\t\t\t),\n\t\t\trefused\n\t\t])\n\t} catch (error) {\n\t\tpost({ vg: 'stop' })\n\t\tstop()\n\t\tthrow error\n\t}\n\tsession.wire(post, log, stop)\n\tsession.about = about\n\tfor (const said of early.splice(0)) session.heard(said)\n\treturn session\n}\n"],"mappings":"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"}

package/dist/shared.d.ts

@@ -22,10 +22,21 @@ export type Relation = 'self' | 'ally' | 'enemy' | 'neutral';
  * @beta
  */
 export interface TargetFacts {
+    /** The target's entity kind, such as unit or structure */
     kind: EntityKind;
+    /** The layer the target is on (ground, air, water), which an ability's `targets` may name */
     layer: Layer;
+    /** Whether the target is a hero */
     hero: boolean;
+    /** Whether the target cannot be hurt: its type (`UnitTypeDef.invulnerable`) or a buff on it (`BuffDef.invulnerable`) */
     invulnerable: boolean;
+    /** The abilities that alone may target it (`UnitTypeDef.targetableBy`) */
+    targetableBy?: readonly string[];
+    /** A buff puts it out of everyone else's reach (`BuffDef.untargetable`): nothing but its own abilities is cast on it @beta */
+    untargetable?: boolean;
+    /** The tags of its type (`UnitTypeDef.tags`), for an ability that targets only some (`targets.tags`) @beta */
+    tags?: readonly string[];
+    /** What the target is to the caster: self, ally, enemy or neutral */
     relation: Relation;
     /** Immune to spells (see `UnitTypeDef.spellImmune`): no ability touches it but its own, and those that get through */
     spellImmune?: boolean;
@@ -54,16 +65,27 @@ export interface ReadyFacts {
     cooldown: number;
     /** Uses left, of an ability with charges (`chargesLeft`): none, and it is not ready */
     charges?: number;
+    /** The caster's mana now, to meet the ability's mana cost */
     mana: number;
-    hp: number;
-    maxHp: number;
+    /** The caster's health now, for abilities that cost health */
+    health: number;
+    /** The caster's largest health, which a health cost may not take below */
+    maxHealth: number;
     /** It comes from something carried: items ask for no mana, and silence does not stop them */
     item?: boolean;
     /** One of the spells the hero brought along rather than learned: silence does not stop those either */
     spell?: boolean;
+    /** Whether the caster is silenced, which stops its spells but not items or brought-along spells */
     silenced?: boolean;
+    /** A buff keeps it from rushing or jumping of its own (`BuffDef.grounded`), and the ability would (a `dash`, a `blink`) */
+    grounded?: boolean;
     /** The debug switch that makes abilities cost nothing */
     noManaCosts?: boolean;
+    /**
+     * Health it pays for each point of mana an ability costs, in place of the mana (`BuffDef.paysWithHealth`): none, or
+     * left out, for one that pays with mana
+     */
+    healthPerMana?: number;
     /** What the simulation's `canCast` hook decided instead, when it told the screen: a reason, or null for none */
     decided?: Message | null;
 }
@@ -89,10 +111,13 @@ export declare function abilityRefusal(ability: AbilityDef, facts: ReadyFacts):
  * @beta
  */
 export interface PlayerFacts {
+    /** What the player has of each resource, to meet a cost */
     resources: Readonly<Purse>;
+    /** Supply the player's units and queued units take up now */
     supplyUsed: number;
+    /** The most supply the player may use */
     supplyCap: number;
-    /** The game's other pools of supply, by name (`GameRules.supply.pools`): left out in a game with none */
+    /** The game's other pools of supply, by name (`RuleSettings.supply.pools`): left out in a game with none */
     supplies?: Readonly<Record<string, {
         used: number;
         cap: number;
@@ -115,7 +140,7 @@ export interface PlayerFacts {
     availability?: Record<string, boolean>;
 }
 /**
- * Whether a worker gathers a kind of resource at all (`harvester.kinds`): the game's `canHarvest` hook may refuse it a
+ * Whether a worker gathers a kind of resource at all (`harvester.ids`): the game's `canHarvest` hook may refuse it a
  * resource all the same (`canHarvest`)
  *
  * @beta
@@ -164,7 +189,8 @@ export declare function trainRefusal(registry: Registry, def: UnitTypeDef, playe
     tech?: boolean;
 }): Message | undefined;
 /**
- * What a shop pays for an item: a part of its price, and of what is left of it for what runs out
+ * What a shop pays for an item: a part of its price (the item's `sellRate`, or the game's `sellPrice`), and of what is
+ * left of it for what runs out (a stack counts each of it)
  *
  * @beta
  */