@v12-engine/engine 0.1.1 → 0.4.0

package/dist/packs/director/index.d.ts

@@ -1,5 +1,9 @@
 import type { GamePack } from '#engine/packs/pack';
-/** @beta */
+/**
+ * The id of the director pack, the namespace of its commands and components
+ *
+ * @beta
+ */
 export declare const DIRECTOR = "director";
 /**
  * The cinematic playing on each player's screen, by its id, as their screen said (`cinematicPlaying`): whose
@@ -21,7 +25,11 @@ export declare const directorInvulnerable: import("#engine/components").Componen
  * @beta
  */
 export declare const DIRECTOR_ACTIONS: readonly ['spawn', 'remove', 'kill', 'teleport', 'scale', 'invulnerable', 'owner', 'order', 'facing'];
-/** @beta */
+/**
+ * One of the `DIRECTOR_ACTIONS`: what a director's command does
+ *
+ * @beta
+ */
 export type DirectorAction = (typeof DIRECTOR_ACTIONS)[number];
 /**
  * The orders a director's command gives (`order`): to a spot, or at a unit
@@ -40,7 +48,7 @@ export declare const cinematicPlayingCommand: import("#engine/commands").Defined
     playing: import("#engine/fields").Check<boolean>;
 }>;
 /**
- * What a game's director takes (`withDirector(options)`)
+ * What a game's director takes (`directorPack(options)`)
  *
  * @beta
  */
@@ -74,8 +82,8 @@ export declare const directorCommand: import("#engine/commands").DefinedCommand<
 }>;
 /**
  * The director's pack (see the top of this file): its commands, what it keeps, and what keeps a unit it made
- * invulnerable so. `packs: [withDirector()]`, or `withDirector({ cinematics: ['intro'] })` for those alone
+ * invulnerable so. `packs: [directorPack()]`, or `directorPack({ cinematics: ['intro'] })` for those alone
  *
  * @beta
  */
-export declare function withDirector(options?: DirectorOptions): GamePack;
+export declare function directorPack(options?: DirectorOptions): GamePack;

package/dist/packs/director/index.js

@@ -0,0 +1,204 @@
+import { defineComponent } from "../../components.js";
+import { commandRejected } from "../../engineEvents.js";
+import { defineHook } from "../../hooks.js";
+import { bool, id, number, oneOf, optional, point, string } from "../../fields.js";
+import { createOrder, giveOrder, interrupt } from "../../orders/queue.js";
+import { defineCommand } from "../../commands.js";
+//#region src/packs/director/index.ts
+/**
+* The id of the director pack, the namespace of its commands and components
+*
+* @beta
+*/
+var DIRECTOR = "director";
+/**
+* The cinematic playing on each player's screen, by its id, as their screen said (`cinematicPlaying`): whose
+* director's commands are taken
+*
+* @beta
+*/
+var directing = defineComponent({
+	id: "director.playing",
+	default: () => ({})
+});
+/**
+* The units a cinematic made invulnerable (`director` with `invulnerable`): nothing hurts or kills them until it says
+* otherwise
+*
+* @beta
+*/
+var directorInvulnerable = defineComponent({ id: "director.invulnerable" });
+/**
+* What a director's command does (`DirectorCommand.action`)
+*
+* @beta
+*/
+var DIRECTOR_ACTIONS = [
+	"spawn",
+	"remove",
+	"kill",
+	"teleport",
+	"scale",
+	"invulnerable",
+	"owner",
+	"order",
+	"facing"
+];
+/**
+* The orders a director's command gives (`order`): to a spot, or at a unit
+*
+* @beta
+*/
+var DIRECTOR_ORDERS = [
+	"move",
+	"attack",
+	"attackMove",
+	"patrol",
+	"stop",
+	"hold"
+];
+/**
+* A player's screen says a cinematic began on it (`playing: true`, its id) or ended: while one plays there, the
+* director's commands it sends are taken
+*
+* @beta
+*/
+var cinematicPlayingCommand = defineCommand("cinematicPlaying", {
+	cinematic: string,
+	playing: bool
+}, (world, player, command) => {
+	const known = directorOptions(world).cinematics;
+	if (command.playing && known && !known.includes(command.cinematic) && !world.debugPlayers.has(player)) return refuse(world, player, `"${command.cinematic}" is no cinematic the director plays in (directorPack's cinematics)`);
+	const now = { ...world.state(directing) };
+	if (command.playing) now[player] = command.cinematic;
+	else if (now[player] === command.cinematic) delete now[player];
+	world.setState(directing, now);
+});
+/** The options the game's director pack was made with */
+var directorOptions = (world) => world.registry.module?.packs?.find((pack) => pack.id === "director")?.options ?? {};
+/** Turned away, and counted as what the player's own client never sends */
+var refuse = (world, player, reason) => world.events.emit(commandRejected, {
+	player,
+	type: "director",
+	kind: "notDirecting",
+	reason
+});
+/**
+* A cinematic's say over the game (see the top of this file): `action` with what it takes. `unit` is the one it is
+* done to (any player's); `spawn` puts one of `unitType` down for `owner` at `at`, turned to `facing`, named `name` for
+* what comes after it in the cinematic (`world.named`)
+*
+* @beta
+*/
+var directorCommand = defineCommand("director", {
+	cinematic: string,
+	action: oneOf(...DIRECTOR_ACTIONS),
+	unit: optional(id),
+	unitType: optional(string),
+	owner: optional(id),
+	at: optional(point),
+	facing: optional(number),
+	scale: optional(number),
+	on: optional(bool),
+	name: optional(string),
+	order: optional(oneOf(...DIRECTOR_ORDERS)),
+	target: optional(id)
+}, (world, player, command) => {
+	const playing = world.state(directing)[player];
+	if (playing !== command.cinematic) {
+		refuse(world, player, playing ? `the cinematic playing is "${playing}", not "${command.cinematic}"` : "no cinematic plays on their screen");
+		return;
+	}
+	const { action } = command;
+	if (action === "spawn") {
+		if (!command.unitType || !world.registry.units.has(command.unitType)) return refuse(world, player, `there is no unit type "${command.unitType}"`);
+		const owner = command.owner ?? player;
+		if (!world.players.has(owner)) return refuse(world, player, `there is no player ${owner}`);
+		if (!command.at) return refuse(world, player, "a unit put down needs where (at)");
+		world.spawn(command.unitType, owner, command.at, {
+			...command.facing !== void 0 && { facing: command.facing },
+			...command.name && { name: command.name }
+		});
+		return;
+	}
+	const entity = command.unit === void 0 ? void 0 : world.get(command.unit);
+	if (!entity?.alive) return refuse(world, player, `there is no unit ${command.unit}`);
+	act(world, entity, command);
+});
+/** What a director's command does to a unit there is */
+function act(world, entity, command) {
+	switch (command.action) {
+		case "remove":
+			world.kill(entity, void 0, false, "removed");
+			break;
+		case "kill":
+			world.kill(entity);
+			break;
+		case "teleport":
+			if (command.at) world.place(entity, command.at);
+			break;
+		case "scale":
+			if (command.scale !== void 0 && command.scale > 0) entity.scale = command.scale;
+			break;
+		case "invulnerable":
+			if (command.on === false) entity.remove(directorInvulnerable);
+			else entity.set(directorInvulnerable, true);
+			break;
+		case "owner":
+			if (command.owner !== void 0 && world.players.has(command.owner)) world.setOwner(entity, command.owner);
+			break;
+		case "facing":
+			if (command.facing !== void 0) entity.facing = command.facing;
+			break;
+		case "order": {
+			const kind = command.order ?? "move";
+			const target = command.target === void 0 ? void 0 : world.get(command.target);
+			if (kind === "stop") {
+				interrupt(world, entity);
+				break;
+			}
+			const init = kind === "hold" ? { type: kind } : kind === "attack" && target ? {
+				type: "attack",
+				target: target.id
+			} : command.at ? {
+				type: kind === "attack" ? "attackMove" : kind,
+				point: command.at
+			} : void 0;
+			if (init) giveOrder(world, entity, createOrder(world, init));
+			break;
+		}
+	}
+}
+/** Nothing hurts or kills a unit a cinematic made invulnerable */
+var invulnerableHooks = [defineHook({
+	hook: "beforeDamage",
+	id: "director",
+	run(_world, damage) {
+		if (damage.target.has(directorInvulnerable)) damage.cancelled = true;
+	}
+}), defineHook({
+	hook: "beforeDeath",
+	id: "director",
+	run(_world, death) {
+		if (death.entity.has(directorInvulnerable) && death.reason !== "removed") death.cancelled = true;
+	}
+})];
+/**
+* The director's pack (see the top of this file): its commands, what it keeps, and what keeps a unit it made
+* invulnerable so. `packs: [directorPack()]`, or `directorPack({ cinematics: ['intro'] })` for those alone
+*
+* @beta
+*/
+function directorPack(options = {}) {
+	return {
+		id: DIRECTOR,
+		options,
+		commands: [cinematicPlayingCommand, directorCommand],
+		components: [directing, directorInvulnerable],
+		hooks: invulnerableHooks
+	};
+}
+//#endregion
+export { DIRECTOR, DIRECTOR_ACTIONS, DIRECTOR_ORDERS, cinematicPlayingCommand, directing, directorCommand, directorInvulnerable, directorPack };
+
+//# sourceMappingURL=index.js.map

package/dist/packs/director/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/packs/director/index.ts"],"sourcesContent":["import { defineComponent } from '#engine/components'\nimport { type CommandDef, defineCommand } from '#engine/commands'\nimport { commandRejected } from '#engine/engineEvents'\nimport type { Entity, PlayerId } from '#engine/entity'\nimport { bool, id, number, oneOf, optional, point, string } from '#engine/fields'\nimport { defineHook, type HookDef } from '#engine/hooks'\nimport { createOrder, giveOrder, interrupt } from '#engine/orders/queue'\nimport type { GamePack } from '#engine/packs/pack'\nimport type { World } from '#engine/world'\n\n/*\n * The director (campaign plan CI1): a cinematic that changes the game itself, for any player's units, as a film's\n * director does. A cinematic plays on a player's screen, and the rules change only by commands, so that every machine\n * and a replay have the same game: the screen says a cinematic began and ended (`cinematicPlaying`), and while one\n * plays on it, its `director` commands are taken: a unit put down, taken away, killed, put elsewhere, sized, made\n * invulnerable, given to another player, ordered, turned. Outside a cinematic they are turned away and counted\n * (`commandRejected`, `notDirecting`), as a server counts what a player's own client never sends. A game takes them\n * where it says so (`packs: [directorPack()]`)\n */\n\n/**\n * The id of the director pack, the namespace of its commands and components\n *\n * @beta\n */\nexport const DIRECTOR = 'director'\n\n/**\n * The cinematic playing on each player's screen, by its id, as their screen said (`cinematicPlaying`): whose\n * director's commands are taken\n *\n * @beta\n */\nexport const directing = defineComponent<Record<number, string>>({ id: 'director.playing', default: () => ({}) })\n\n/**\n * The units a cinematic made invulnerable (`director` with `invulnerable`): nothing hurts or kills them until it says\n * otherwise\n *\n * @beta\n */\nexport const directorInvulnerable = defineComponent<true>({ id: 'director.invulnerable' })\n\n/**\n * What a director's command does (`DirectorCommand.action`)\n *\n * @beta\n */\nexport const DIRECTOR_ACTIONS = ['spawn', 'remove', 'kill', 'teleport', 'scale', 'invulnerable', 'owner', 'order', 'facing'] as const\n\n/**\n * One of the `DIRECTOR_ACTIONS`: what a director's command does\n *\n * @beta\n */\nexport type DirectorAction = (typeof DIRECTOR_ACTIONS)[number]\n\n/**\n * The orders a director's command gives (`order`): to a spot, or at a unit\n *\n * @beta\n */\nexport const DIRECTOR_ORDERS = ['move', 'attack', 'attackMove', 'patrol', 'stop', 'hold'] as const\n\n/**\n * A player's screen says a cinematic began on it (`playing: true`, its id) or ended: while one plays there, the\n * director's commands it sends are taken\n *\n * @beta\n */\nexport const cinematicPlayingCommand = defineCommand('cinematicPlaying', { cinematic: string, playing: bool }, (world, player, command) => {\n\t// a cinematic the game says its director plays in, where it says; a debug seat's screen (the editor's preview, Play\n\t// here with cheats) may say any, as it may cheat: the one being made is not in the game's list yet\n\tconst known = directorOptions(world).cinematics\n\tif (command.playing && known && !known.includes(command.cinematic) && !world.debugPlayers.has(player))\n\t\treturn refuse(world, player, `\"${command.cinematic}\" is no cinematic the director plays in (directorPack's cinematics)`)\n\tconst now = { ...world.state(directing) }\n\tif (command.playing) now[player] = command.cinematic\n\telse if (now[player] === command.cinematic) delete now[player]\n\tworld.setState(directing, now)\n})\n\n/**\n * What a game's director takes (`directorPack(options)`)\n *\n * @beta\n */\nexport interface DirectorOptions {\n\t/**\n\t * The cinematics it plays in, by id: a screen that says another began is turned away (and counted), so that on a\n\t * server a player's own client cannot direct a game with a cinematic made up. Any when left out\n\t */\n\tcinematics?: readonly string[]\n}\n\n/** The options the game's director pack was made with */\nconst directorOptions = (world: World): DirectorOptions =>\n\t(world.registry.module?.packs?.find((pack) => pack.id === DIRECTOR)?.options as DirectorOptions | undefined) ?? {}\n\n/** Turned away, and counted as what the player's own client never sends */\nconst refuse = (world: World, player: PlayerId, reason: string) =>\n\tworld.events.emit(commandRejected, { player, type: 'director', kind: 'notDirecting', reason })\n\n/**\n * A cinematic's say over the game (see the top of this file): `action` with what it takes. `unit` is the one it is\n * done to (any player's); `spawn` puts one of `unitType` down for `owner` at `at`, turned to `facing`, named `name` for\n * what comes after it in the cinematic (`world.named`)\n *\n * @beta\n */\nexport const directorCommand = defineCommand(\n\t'director',\n\t{\n\t\tcinematic: string,\n\t\taction: oneOf(...DIRECTOR_ACTIONS),\n\t\tunit: optional(id),\n\t\tunitType: optional(string),\n\t\towner: optional(id),\n\t\tat: optional(point),\n\t\tfacing: optional(number),\n\t\tscale: optional(number),\n\t\ton: optional(bool),\n\t\tname: optional(string),\n\t\torder: optional(oneOf(...DIRECTOR_ORDERS)),\n\t\ttarget: optional(id)\n\t},\n\t(world, player, command) => {\n\t\tconst playing = world.state(directing)[player]\n\t\tif (playing !== command.cinematic) {\n\t\t\trefuse(world, player, playing ? `the cinematic playing is \"${playing}\", not \"${command.cinematic}\"` : 'no cinematic plays on their screen')\n\t\t\treturn\n\t\t}\n\t\tconst { action } = command\n\t\tif (action === 'spawn') {\n\t\t\tif (!command.unitType || !world.registry.units.has(command.unitType))\n\t\t\t\treturn refuse(world, player, `there is no unit type \"${command.unitType}\"`)\n\t\t\tconst owner = command.owner ?? player\n\t\t\tif (!world.players.has(owner)) return refuse(world, player, `there is no player ${owner}`)\n\t\t\tif (!command.at) return refuse(world, player, 'a unit put down needs where (at)')\n\t\t\tworld.spawn(command.unitType, owner, command.at, {\n\t\t\t\t...(command.facing !== undefined && { facing: command.facing }),\n\t\t\t\t...(command.name && { name: command.name })\n\t\t\t})\n\t\t\treturn\n\t\t}\n\t\tconst entity = command.unit === undefined ? undefined : world.get(command.unit)\n\t\tif (!entity?.alive) return refuse(world, player, `there is no unit ${command.unit}`)\n\t\tact(world, entity, command)\n\t}\n)\n\n/** What a director's command does to a unit there is */\nfunction act(world: World, entity: Entity, command: Parameters<typeof directorCommand.execute>[2]): void {\n\tswitch (command.action) {\n\t\tcase 'remove':\n\t\t\tworld.kill(entity, undefined, false, 'removed')\n\t\t\tbreak\n\t\tcase 'kill':\n\t\t\tworld.kill(entity)\n\t\t\tbreak\n\t\tcase 'teleport':\n\t\t\tif (command.at) world.place(entity, command.at)\n\t\t\tbreak\n\t\tcase 'scale':\n\t\t\tif (command.scale !== undefined && command.scale > 0) entity.scale = command.scale\n\t\t\tbreak\n\t\tcase 'invulnerable':\n\t\t\tif (command.on === false) entity.remove(directorInvulnerable)\n\t\t\telse entity.set(directorInvulnerable, true)\n\t\t\tbreak\n\t\tcase 'owner':\n\t\t\tif (command.owner !== undefined && world.players.has(command.owner)) world.setOwner(entity, command.owner)\n\t\t\tbreak\n\t\tcase 'facing':\n\t\t\tif (command.facing !== undefined) entity.facing = command.facing\n\t\t\tbreak\n\t\tcase 'order': {\n\t\t\tconst kind = command.order ?? 'move'\n\t\t\tconst target = command.target === undefined ? undefined : world.get(command.target)\n\t\t\t// stop is a command, not an order type: the unit is interrupted, as stopCommand does\n\t\t\tif (kind === 'stop') {\n\t\t\t\tinterrupt(world, entity)\n\t\t\t\tbreak\n\t\t\t}\n\t\t\tconst init =\n\t\t\t\tkind === 'hold'\n\t\t\t\t\t? { type: kind }\n\t\t\t\t\t: kind === 'attack' && target\n\t\t\t\t\t\t? { type: 'attack', target: target.id }\n\t\t\t\t\t\t: command.at\n\t\t\t\t\t\t\t? { type: kind === 'attack' ? 'attackMove' : kind, point: command.at }\n\t\t\t\t\t\t\t: undefined\n\t\t\tif (init) giveOrder(world, entity, createOrder(world, init as never))\n\t\t\tbreak\n\t\t}\n\t}\n}\n\n/** Nothing hurts or kills a unit a cinematic made invulnerable */\nconst invulnerableHooks: HookDef[] = [\n\tdefineHook({\n\t\thook: 'beforeDamage',\n\t\tid: 'director',\n\t\trun(_world, damage) {\n\t\t\tif (damage.target.has(directorInvulnerable)) damage.cancelled = true\n\t\t}\n\t}),\n\tdefineHook({\n\t\thook: 'beforeDeath',\n\t\tid: 'director',\n\t\trun(_world, death) {\n\t\t\tif (death.entity.has(directorInvulnerable) && death.reason !== 'removed') death.cancelled = true\n\t\t}\n\t})\n]\n\n/**\n * The director's pack (see the top of this file): its commands, what it keeps, and what keeps a unit it made\n * invulnerable so. `packs: [directorPack()]`, or `directorPack({ cinematics: ['intro'] })` for those alone\n *\n * @beta\n */\nexport function directorPack(options: DirectorOptions = {}): GamePack {\n\treturn {\n\t\tid: DIRECTOR,\n\t\toptions,\n\t\tcommands: [cinematicPlayingCommand, directorCommand] as unknown as CommandDef[],\n\t\tcomponents: [directing, directorInvulnerable],\n\t\thooks: invulnerableHooks\n\t}\n}\n"],"mappings":"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"}

package/dist/packs/heroes/campaign.d.ts

@@ -26,6 +26,7 @@ export interface MissionResult {
  * @beta
  */
 export interface CampaignProgress<D extends object = Record<string, unknown>> {
+    /** The version of the progress file's format, so what was kept is read again when the format changes */
     format: number;
     /** The campaign it is of, by id */
     campaign: string;
@@ -62,7 +63,7 @@ export declare function readCampaignProgress(data: unknown): CampaignProgress;
 export declare function missionWon<D extends object = Record<string, unknown>>(progress: CampaignProgress<D>, mission: string, seconds: number, heroes: HeroRecord[], next?: string, data?: Partial<D>): CampaignProgress<D>;
 /**
  * A unit as plain data, to take from one mission into the next (`carryUnits`, `placeUnits`): what it is, the name the
- * rules knew it by, how much of its health it has (a share, 0 to 1), its veterancy (`withVeterancy`) and its items
+ * rules knew it by, how much of its health it has (a share, 0 to 1), its veterancy (`veterancyPack`) and its items
  * slot by slot. Not where it is: the next mission says where they come in. Heroes are carried as heroes (`carryOut`)
  *
  * @beta
@@ -74,7 +75,7 @@ export interface UnitRecord {
     name?: string;
     /** Its health, a share of the most it has: 1 for whole */
     health: number;
-    /** Its experience and rank, where it has earned some (`withVeterancy`) */
+    /** Its experience and rank, where it has earned some (`veterancyPack`) */
     veterancy?: VeterancyState;
     /** Its inventory slot by slot, where it has one: null for an empty slot */
     items?: (HeroItem | null)[];

package/dist/packs/heroes/campaign.js

@@ -0,0 +1,241 @@
+import { cos, sin } from "../../exactMath.js";
+import { slotsOf } from "../../inventory.js";
+import { refreshVitals } from "../../stats.js";
+import { inventoryChanged } from "../../engineEvents.js";
+import { heroOf, heroesOf } from "../../hero.js";
+import { createItem } from "../../items.js";
+import { veterancy } from "../../veterancy.js";
+import { applyHeroRecord, heroFromRecord, heroRecord, readHeroRecord } from "./carry.js";
+//#region src/packs/heroes/campaign.ts
+/**
+* The format campaign progress is written in now
+*
+* @internal
+*/
+var CAMPAIGN_FORMAT = 1;
+/**
+* A campaign as it is before anything is played: at its first mission, with nothing carried
+*
+* @beta
+*/
+function newCampaignProgress(campaign, first) {
+	return {
+		format: 1,
+		campaign,
+		at: first,
+		done: {},
+		heroes: [],
+		data: {}
+	};
+}
+/**
+* Progress as it was kept, checked and brought up to date. Throws on what is wrong
+*
+* @beta
+*/
+function readCampaignProgress(data) {
+	const kept = data;
+	if (typeof kept !== "object" || kept === null) throw new Error("A campaign's progress is an object");
+	if (typeof kept.format !== "number" || kept.format > 1) throw new Error(`Campaign progress of format ${kept.format}, which this engine does not know`);
+	if (typeof kept.campaign !== "string" || typeof kept.at !== "string") throw new Error("A campaign's progress says which campaign it is and where it is at");
+	const done = {};
+	for (const [mission, result] of Object.entries(kept.done ?? {})) {
+		const { seconds, best, finished } = result ?? {};
+		if (typeof seconds !== "number" || !Number.isFinite(seconds)) throw new Error(`How long ${mission} took is a number`);
+		done[mission] = {
+			seconds,
+			best: typeof best === "number" ? best : seconds,
+			finished: typeof finished === "number" ? finished : 0
+		};
+	}
+	return {
+		format: 1,
+		campaign: kept.campaign,
+		at: kept.at,
+		...typeof kept.difficulty === "string" && { difficulty: kept.difficulty },
+		done,
+		heroes: (kept.heroes ?? []).map(readHeroRecord),
+		data: typeof kept.data === "object" && kept.data !== null ? kept.data : {}
+	};
+}
+/**
+* A mission won: how long it took, the best time kept, the heroes it ends with to carry on, the campaign at the
+* mission after it (`next`), or still at this one when it was the last, and what it carries of the game's own
+* (`data`: its keys over the ones kept, the rest kept as they were). A new progress: the one given is left as it was
+*
+* @beta
+*/
+function missionWon(progress, mission, seconds, heroes, next, data) {
+	const before = progress.done[mission];
+	return {
+		...progress,
+		at: next ?? progress.at,
+		done: {
+			...progress.done,
+			[mission]: {
+				seconds,
+				best: before ? Math.min(before.best, seconds) : seconds,
+				finished: Date.now()
+			}
+		},
+		heroes: structuredClone(heroes),
+		data: data ? {
+			...progress.data,
+			...structuredClone(data)
+		} : progress.data
+	};
+}
+/**
+* A player's units as records to carry on (`UnitRecord`): those alive, not structures, not heroes (`carryOut` carries
+* those), and of them what `filter` keeps (the footmen, the three nearest the gate). In the order of their ids
+*
+* @beta
+*/
+function carryUnits(world, player, filter = () => true) {
+	return [...world.index.ownedBy(player)].filter((unit) => unit.alive && unit.isUnit && !heroOf(unit) && filter(unit)).sort((a, b) => a.id - b.id).map((unit) => {
+		const name = world.nameOf(unit);
+		const rank = unit.get(veterancy);
+		const slots = slotsOf(unit);
+		return {
+			type: unit.def.id,
+			...name !== void 0 && { name },
+			health: unit.maxHealth > 0 ? Math.min(Math.max(unit.health / unit.maxHealth, 0), 1) : 1,
+			...rank && { veterancy: { ...rank } },
+			...slots && { items: slots.map((slot) => slot ? {
+				item: slot.item,
+				charges: slot.charges,
+				...slot.data && { data: structuredClone(slot.data) }
+			} : null) }
+		};
+	});
+}
+/**
+* Brings carried units into a mission for a player, round a point (`spread` apart, in rings: 1.5 when left out), each
+* with its name, its share of health, its veterancy and its items. What the game no longer has, a type or an item, is
+* left out. The units made, in the order of the records
+*
+* @beta
+*/
+function placeUnits(world, player, records, at, spread = 1.5) {
+	const made = [];
+	records.filter((record) => world.registry.units.has(record.type)).forEach((record, i) => {
+		const point = ringPoint(at, i, spread);
+		const unit = world.spawn(record.type, player, point, record.name !== void 0 ? { name: record.name } : {});
+		if (record.veterancy) {
+			unit.set(veterancy, { ...record.veterancy });
+			refreshVitals(world, unit);
+		}
+		const slots = slotsOf(unit);
+		if (slots && record.items) {
+			slots.fill(null);
+			record.items.forEach((carried, slot) => {
+				if (!carried || slot >= slots.length || !world.registry.items.has(carried.item)) return;
+				const instance = createItem(world, carried.item, carried.charges);
+				if (carried.data) instance.data = structuredClone(carried.data);
+				slots[slot] = instance;
+			});
+			world.events.emit(inventoryChanged, { entity: unit });
+		}
+		unit.health = Math.max(1, Math.round(unit.maxHealth * Math.min(Math.max(record.health, 0), 1)));
+		made.push(unit);
+	});
+	return made;
+}
+/** The `index`-th place round a point: the point first, then rings of six, twelve, … `spread` apart */
+function ringPoint(at, index, spread) {
+	if (index === 0) return {
+		x: at.x,
+		z: at.z
+	};
+	let ring = 1;
+	let first = 1;
+	while (index >= first + ring * 6) {
+		first += ring * 6;
+		ring++;
+	}
+	const angle = (index - first) / (ring * 6) * Math.PI * 2;
+	return {
+		x: at.x + sin(angle) * ring * spread,
+		z: at.z + cos(angle) * ring * spread
+	};
+}
+/**
+* What a player has researched, to carry on (`giveResearch`): each upgrade's level, by its id
+*
+* @beta
+*/
+function carryResearch(world, player) {
+	return Object.fromEntries([...world.player(player).upgrades].filter(([, level]) => level > 0));
+}
+/**
+* Gives a player research carried in (`carryResearch`): each upgrade up to its level, never down, no further than it
+* goes, and what it does besides stats (`UpgradeDef.apply`) to the units the player has, as research finishing does.
+* What the game no longer has is left out
+*
+* @beta
+*/
+function giveResearch(world, player, research) {
+	const who = world.player(player);
+	for (const [upgrade, carried] of Object.entries(research)) {
+		if (!world.registry.upgrades.has(upgrade)) continue;
+		const def = world.registry.upgrade(upgrade);
+		const to = Math.min(Math.max(Math.floor(carried), 0), def.maxLevel ?? 1);
+		for (let level = (who.upgrades.get(upgrade) ?? 0) + 1; level <= to; level++) {
+			who.setUpgrade(upgrade, level);
+			if (def.apply) {
+				for (const entity of [...world.index.ownedBy(player)]) if (entity.alive) def.apply(world, entity, level);
+			}
+		}
+		who.researching.delete(upgrade);
+	}
+}
+/**
+* What a player has of each resource, to carry on (`giveResources`): a copy, all of it, or of the kinds named
+*
+* @beta
+*/
+function carryResources(world, player, kinds) {
+	const resources = world.player(player).resources;
+	return Object.fromEntries(Object.entries(resources).filter(([kind]) => !kinds || kinds.includes(kind)));
+}
+/**
+* Gives a player resources carried in (`carryResources`), on top of what the mission starts it with. What the game no
+* longer has is left out
+*
+* @beta
+*/
+function giveResources(world, player, resources) {
+	const purse = world.player(player).resources;
+	const known = new Set(world.registry.resources.map((resource) => resource.id));
+	for (const [kind, amount] of Object.entries(resources)) if (known.has(kind) && Number.isFinite(amount)) purse[kind] = (purse[kind] ?? 0) + amount;
+}
+/**
+* The heroes of a player as records to carry on (see `heroRecord`): fallen ones too, as a campaign brings them back
+*
+* @beta
+*/
+function carryOut(world, player) {
+	return heroesOf(world, player).map((hero) => heroRecord(world, hero));
+}
+/**
+* Brings carried heroes into a mission for a player. Each takes the place of the hero the map has for it: the one of
+* that player under the same name, else one of that player of the same type; a hero the map has none for is made at
+* `at`. The heroes, in the order of the records
+*
+* @beta
+*/
+function carryIn(world, heroes, player, at) {
+	const taken = /* @__PURE__ */ new Set();
+	return heroes.map((record) => {
+		const named = record.name !== void 0 ? world.named(record.name) : void 0;
+		const placed = named && named.owner === player && heroOf(named) && !taken.has(named) ? named : heroesOf(world, player).find((hero) => hero.def.id === record.type && !taken.has(hero));
+		const hero = placed ?? heroFromRecord(world, record, player, at);
+		if (placed) applyHeroRecord(world, placed, record);
+		taken.add(hero);
+		return hero;
+	});
+}
+//#endregion
+export { CAMPAIGN_FORMAT, carryIn, carryOut, carryResearch, carryResources, carryUnits, giveResearch, giveResources, missionWon, newCampaignProgress, placeUnits, readCampaignProgress };
+
+//# sourceMappingURL=campaign.js.map

package/dist/packs/heroes/campaign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign.js","names":[],"sources":["../../../src/packs/heroes/campaign.ts"],"sourcesContent":["import { applyHeroRecord, heroFromRecord, type HeroItem, type HeroRecord, heroRecord, readHeroRecord } from './carry'\nimport { inventoryChanged } from '#engine/engineEvents'\nimport type { Entity, PlayerId } from '#engine/entity'\nimport { heroOf, heroesOf } from '#engine/hero'\nimport { slotsOf } from '#engine/inventory'\nimport { createItem } from '#engine/items'\nimport { cos, sin } from '#engine/exactMath'\nimport type { Vec2 } from '#engine/math'\nimport type { Purse } from '#engine/player'\nimport { refreshVitals } from '#engine/stats'\nimport { veterancy, type VeterancyState } from '#engine/veterancy'\nimport type { World } from '#engine/world'\n\n/**\n * How a mission of a campaign went, the last time it was won\n *\n * @beta\n */\nexport interface MissionResult {\n\t/** How long it took, in seconds of the game */\n\tseconds: number\n\t/** The shortest it ever took */\n\tbest: number\n\t/** When it was won, in milliseconds since 1970 */\n\tfinished: number\n}\n\n/**\n * How far a campaign has got, as plain data to keep between games: the mission it is at, the missions won and how\n * long each took, the heroes carried out of the last one won, and the game's own state of it (`data`, of the type\n * `D` the campaign says: choices made, gold saved up, the units that go on; what each mission won carries, merged in).\n * It says which format it is in, so that what was kept is read again when the format changes\n *\n * @beta\n */\nexport interface CampaignProgress<D extends object = Record<string, unknown>> {\n\t/** The version of the progress file's format, so what was kept is read again when the format changes */\n\tformat: number\n\t/** The campaign it is of, by id */\n\tcampaign: string\n\t/** The mission to play next */\n\tat: string\n\t/** The difficulty chosen for it (`CampaignDef.difficulties`), by name: its missions' computers play on it */\n\tdifficulty?: string\n\t/** Missions won, by id */\n\tdone: Record<string, MissionResult>\n\t/** The heroes carried into the next mission */\n\theroes: HeroRecord[]\n\t/** The game's own, plain data: what the missions won carried (`MissionDef.carry`), each mission's keys over the ones before */\n\tdata: Partial<D>\n}\n\n/**\n * The format campaign progress is written in now\n *\n * @internal\n */\nexport const CAMPAIGN_FORMAT = 1\n\n/**\n * A campaign as it is before anything is played: at its first mission, with nothing carried\n *\n * @beta\n */\nexport function newCampaignProgress<D extends object = Record<string, unknown>>(campaign: string, first: string): CampaignProgress<D> {\n\treturn { format: CAMPAIGN_FORMAT, campaign, at: first, done: {}, heroes: [], data: {} }\n}\n\n/**\n * Progress as it was kept, checked and brought up to date. Throws on what is wrong\n *\n * @beta\n */\nexport function readCampaignProgress(data: unknown): CampaignProgress {\n\tconst kept = data as Partial<CampaignProgress> | null\n\tif (typeof kept !== 'object' || kept === null) throw new Error(\"A campaign's progress is an object\")\n\tif (typeof kept.format !== 'number' || kept.format > CAMPAIGN_FORMAT)\n\t\tthrow new Error(`Campaign progress of format ${kept.format}, which this engine does not know`)\n\tif (typeof kept.campaign !== 'string' || typeof kept.at !== 'string')\n\t\tthrow new Error(\"A campaign's progress says which campaign it is and where it is at\")\n\tconst done: Record<string, MissionResult> = {}\n\tfor (const [mission, result] of Object.entries(kept.done ?? {})) {\n\t\tconst { seconds, best, finished } = (result ?? {}) as Partial<MissionResult>\n\t\tif (typeof seconds !== 'number' || !Number.isFinite(seconds)) throw new Error(`How long ${mission} took is a number`)\n\t\tdone[mission] = { seconds, best: typeof best === 'number' ? best : seconds, finished: typeof finished === 'number' ? finished : 0 }\n\t}\n\treturn {\n\t\tformat: CAMPAIGN_FORMAT,\n\t\tcampaign: kept.campaign,\n\t\tat: kept.at,\n\t\t...(typeof kept.difficulty === 'string' && { difficulty: kept.difficulty }),\n\t\tdone,\n\t\theroes: (kept.heroes ?? []).map(readHeroRecord),\n\t\tdata: typeof kept.data === 'object' && kept.data !== null ? kept.data : {}\n\t}\n}\n\n/**\n * A mission won: how long it took, the best time kept, the heroes it ends with to carry on, the campaign at the\n * mission after it (`next`), or still at this one when it was the last, and what it carries of the game's own\n * (`data`: its keys over the ones kept, the rest kept as they were). A new progress: the one given is left as it was\n *\n * @beta\n */\nexport function missionWon<D extends object = Record<string, unknown>>(\n\tprogress: CampaignProgress<D>,\n\tmission: string,\n\tseconds: number,\n\theroes: HeroRecord[],\n\tnext?: string,\n\tdata?: Partial<D>\n): CampaignProgress<D> {\n\tconst before = progress.done[mission]\n\treturn {\n\t\t...progress,\n\t\tat: next ?? progress.at,\n\t\tdone: { ...progress.done, [mission]: { seconds, best: before ? Math.min(before.best, seconds) : seconds, finished: Date.now() } },\n\t\theroes: structuredClone(heroes),\n\t\tdata: data ? { ...progress.data, ...structuredClone(data) } : progress.data\n\t}\n}\n\n/**\n * A unit as plain data, to take from one mission into the next (`carryUnits`, `placeUnits`): what it is, the name the\n * rules knew it by, how much of its health it has (a share, 0 to 1), its veterancy (`veterancyPack`) and its items\n * slot by slot. Not where it is: the next mission says where they come in. Heroes are carried as heroes (`carryOut`)\n *\n * @beta\n */\nexport interface UnitRecord {\n\t/** Its unit type */\n\ttype: string\n\t/** The name it was known by in the rules (`world.named`), when it had one */\n\tname?: string\n\t/** Its health, a share of the most it has: 1 for whole */\n\thealth: number\n\t/** Its experience and rank, where it has earned some (`veterancyPack`) */\n\tveterancy?: VeterancyState\n\t/** Its inventory slot by slot, where it has one: null for an empty slot */\n\titems?: (HeroItem | null)[]\n}\n\n/**\n * A player's units as records to carry on (`UnitRecord`): those alive, not structures, not heroes (`carryOut` carries\n * those), and of them what `filter` keeps (the footmen, the three nearest the gate). In the order of their ids\n *\n * @beta\n */\nexport function carryUnits(world: World, player: PlayerId, filter: (unit: Entity) => boolean = () => true): UnitRecord[] {\n\tconst units = [...world.index.ownedBy(player)]\n\t\t.filter((unit) => unit.alive && unit.isUnit && !heroOf(unit) && filter(unit))\n\t\t.sort((a, b) => a.id - b.id)\n\treturn units.map((unit) => {\n\t\tconst name = world.nameOf(unit)\n\t\tconst rank = unit.get(veterancy)\n\t\tconst slots = slotsOf(unit)\n\t\treturn {\n\t\t\ttype: unit.def.id,\n\t\t\t...(name !== undefined && { name }),\n\t\t\thealth: unit.maxHealth > 0 ? Math.min(Math.max(unit.health / unit.maxHealth, 0), 1) : 1,\n\t\t\t...(rank && { veterancy: { ...rank } }),\n\t\t\t...(slots && {\n\t\t\t\titems: slots.map((slot) => (slot ? { item: slot.item, charges: slot.charges, ...(slot.data && { data: structuredClone(slot.data) }) } : null))\n\t\t\t})\n\t\t}\n\t})\n}\n\n/**\n * Brings carried units into a mission for a player, round a point (`spread` apart, in rings: 1.5 when left out), each\n * with its name, its share of health, its veterancy and its items. What the game no longer has, a type or an item, is\n * left out. The units made, in the order of the records\n *\n * @beta\n */\nexport function placeUnits(world: World, player: PlayerId, records: readonly UnitRecord[], at: Vec2, spread = 1.5): Entity[] {\n\tconst made: Entity[] = []\n\tconst kept = records.filter((record) => world.registry.units.has(record.type))\n\tkept.forEach((record, i) => {\n\t\tconst point = ringPoint(at, i, spread)\n\t\tconst unit = world.spawn(record.type, player, point, record.name !== undefined ? { name: record.name } : {})\n\t\tif (record.veterancy) {\n\t\t\tunit.set(veterancy, { ...record.veterancy })\n\t\t\trefreshVitals(world, unit)\n\t\t}\n\t\tconst slots = slotsOf(unit)\n\t\tif (slots && record.items) {\n\t\t\tslots.fill(null)\n\t\t\trecord.items.forEach((carried, slot) => {\n\t\t\t\tif (!carried || slot >= slots.length || !world.registry.items.has(carried.item)) return\n\t\t\t\tconst instance = createItem(world, carried.item, carried.charges)\n\t\t\t\tif (carried.data) instance.data = structuredClone(carried.data)\n\t\t\t\tslots[slot] = instance\n\t\t\t})\n\t\t\tworld.events.emit(inventoryChanged, { entity: unit })\n\t\t}\n\t\tunit.health = Math.max(1, Math.round(unit.maxHealth * Math.min(Math.max(record.health, 0), 1)))\n\t\tmade.push(unit)\n\t})\n\treturn made\n}\n\n/** The `index`-th place round a point: the point first, then rings of six, twelve, … `spread` apart */\nfunction ringPoint(at: Vec2, index: number, spread: number): Vec2 {\n\tif (index === 0) return { x: at.x, z: at.z }\n\tlet ring = 1\n\tlet first = 1\n\twhile (index >= first + ring * 6) {\n\t\tfirst += ring * 6\n\t\tring++\n\t}\n\tconst angle = ((index - first) / (ring * 6)) * Math.PI * 2\n\treturn { x: at.x + sin(angle) * ring * spread, z: at.z + cos(angle) * ring * spread }\n}\n\n/**\n * What a player has researched, to carry on (`giveResearch`): each upgrade's level, by its id\n *\n * @beta\n */\nexport function carryResearch(world: World, player: PlayerId): Record<string, number> {\n\treturn Object.fromEntries([...world.player(player).upgrades].filter(([, level]) => level > 0))\n}\n\n/**\n * Gives a player research carried in (`carryResearch`): each upgrade up to its level, never down, no further than it\n * goes, and what it does besides stats (`UpgradeDef.apply`) to the units the player has, as research finishing does.\n * What the game no longer has is left out\n *\n * @beta\n */\nexport function giveResearch(world: World, player: PlayerId, research: Readonly<Record<string, number>>): void {\n\tconst who = world.player(player)\n\tfor (const [upgrade, carried] of Object.entries(research)) {\n\t\tif (!world.registry.upgrades.has(upgrade)) continue\n\t\tconst def = world.registry.upgrade(upgrade)\n\t\tconst to = Math.min(Math.max(Math.floor(carried), 0), def.maxLevel ?? 1)\n\t\tfor (let level = (who.upgrades.get(upgrade) ?? 0) + 1; level <= to; level++) {\n\t\t\twho.setUpgrade(upgrade, level)\n\t\t\tif (def.apply) for (const entity of [...world.index.ownedBy(player)]) if (entity.alive) def.apply(world, entity, level)\n\t\t}\n\t\twho.researching.delete(upgrade)\n\t}\n}\n\n/**\n * What a player has of each resource, to carry on (`giveResources`): a copy, all of it, or of the kinds named\n *\n * @beta\n */\nexport function carryResources(world: World, player: PlayerId, kinds?: readonly string[]): Purse {\n\tconst resources = world.player(player).resources\n\treturn Object.fromEntries(Object.entries(resources).filter(([kind]) => !kinds || kinds.includes(kind)))\n}\n\n/**\n * Gives a player resources carried in (`carryResources`), on top of what the mission starts it with. What the game no\n * longer has is left out\n *\n * @beta\n */\nexport function giveResources(world: World, player: PlayerId, resources: Readonly<Purse>): void {\n\tconst purse = world.player(player).resources\n\tconst known = new Set(world.registry.resources.map((resource) => resource.id))\n\tfor (const [kind, amount] of Object.entries(resources)) if (known.has(kind) && Number.isFinite(amount)) purse[kind] = (purse[kind] ?? 0) + amount\n}\n\n/**\n * The heroes of a player as records to carry on (see `heroRecord`): fallen ones too, as a campaign brings them back\n *\n * @beta\n */\nexport function carryOut(world: World, player: PlayerId): HeroRecord[] {\n\treturn heroesOf(world, player).map((hero) => heroRecord(world, hero))\n}\n\n/**\n * Brings carried heroes into a mission for a player. Each takes the place of the hero the map has for it: the one of\n * that player under the same name, else one of that player of the same type; a hero the map has none for is made at\n * `at`. The heroes, in the order of the records\n *\n * @beta\n */\nexport function carryIn(world: World, heroes: readonly HeroRecord[], player: PlayerId, at: Vec2): Entity[] {\n\tconst taken = new Set<Entity>()\n\treturn heroes.map((record) => {\n\t\tconst named = record.name !== undefined ? world.named(record.name) : undefined\n\t\tconst placed =\n\t\t\tnamed && named.owner === player && heroOf(named) && !taken.has(named)\n\t\t\t\t? named\n\t\t\t\t: heroesOf(world, player).find((hero) => hero.def.id === record.type && !taken.has(hero))\n\t\tconst hero = placed ?? heroFromRecord(world, record, player, at)\n\t\tif (placed) applyHeroRecord(world, placed, record)\n\t\ttaken.add(hero)\n\t\treturn hero\n\t})\n}\n"],"mappings":"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"}

package/dist/packs/heroes/carry.d.ts

@@ -7,8 +7,11 @@ import type { SpawnOptions, World } from '#engine/world';
  * @beta
  */
 export interface HeroItem {
+    /** The id of the item type carried */
     item: string;
+    /** Uses left of the item */
     charges: number;
+    /** The game's own state of the item, carried over as plain data */
     data?: Record<string, unknown>;
 }
 /**
@@ -23,8 +26,11 @@ export interface HeroRecord {
     type: string;
     /** The name it was known by in the rules (`world.named`), when it had one */
     name?: string;
+    /** The hero's level */
     level: number;
+    /** The hero's experience points */
     xp: number;
+    /** Skill points the hero has earned and not yet spent */
     points: number;
     /** Learned abilities and their level. Ones not learned are left out */
     abilities: Record<string, number>;