@v12-engine/engine 0.1.0 → 0.4.0

package/dist/player.d.ts

@@ -1,11 +1,17 @@
 import { type Component, StateStore } from './components';
 import type { Registry } from './registry';
-import type { Cost, ResourceKind } from './defs';
+import type { Cost, ResourceId } from './defs';
 import type { PlayerId } from './entity';
 import type { World } from './world';
-/** @beta */
+/**
+ * What a `Player` is made from: its id, name, team, colour, starting resources and role
+ *
+ * @beta
+ */
 export interface PlayerInit {
+    /** The player's id, by which units, commands and the world's lists name them */
     id: PlayerId;
+    /** The name shown for the player on scores, in the lobby and in messages */
     name: string;
     /** Players on the same team are allies and share vision */
     team: number;
@@ -18,27 +24,38 @@ export interface PlayerInit {
     /** The player the creeps belong to: hostile to everyone, and not someone who can win or lose */
     creeps?: boolean;
     /**
-     * The race they play (`GameModule.races`), or `random` for one drawn as the game starts. The game's first when left
+     * The race they play (`Rules.races`), or `random` for one drawn as the game starts. The game's first when left
      * out, in a game with races; none for the neutral players and the creeps
      */
     race?: string;
 }
-/** @beta */
+/**
+ * A player of a world: team, colour, race, resources, supply, researched upgrades and the state of modules, kept by `world.player(id)`
+ *
+ * @beta
+ */
 export declare class Player {
+    /** The player's id, as `PlayerInit.id` */
     readonly id: PlayerId;
+    /** The name shown for the player, as `PlayerInit.name` */
     readonly name: string;
     /** Changed by `world.setTeam`, which the fog and everyone's sight follow */
     team: number;
+    /** The player's colour as RGB, each 0..1, used to tint their units */
     readonly color: [number, number, number];
+    /** Whether this is a neutral player (owner of gold mines and the like); nobody is hostile towards it */
     readonly neutral: boolean;
+    /** Whether this is the creeps' player: hostile to everyone, and not someone who can win or lose */
     readonly creeps: boolean;
     /** The race they play (`raceOf`): changed by `setRace` only. None in a game without races */
     race: string | undefined;
     /** What the player has of each resource, by resource id */
     readonly resources: Purse;
+    /** Supply the player's units and queued units take up now; counted against `supplyCap` */
     supplyUsed: number;
+    /** The most supply the player may use, from their buildings that provide it */
     supplyCap: number;
-    /** The game's other pools of supply, by name (`GameRules.supply.pools`): what is used and the cap of each */
+    /** The game's other pools of supply, by name (`RuleSettings.supply.pools`): what is used and the cap of each */
     supplies: Record<string, {
         used: number;
         cap: number;
@@ -59,7 +76,9 @@ export declare class Player {
     get upgrades(): ReadonlyMap<string, number>;
     /** State of a game module or a mod for this player: made from the component's default when first asked for */
     state<T>(key: Component<T, unknown>): T;
+    /** Sets this player's state for a component, replacing what `state` gives for it */
     setState<T>(key: Component<T, unknown>, value: T): void;
+    /** Records that an upgrade is researched at this level and bumps `upgradesVersion` */
     setUpgrade(upgrade: string, level: number): void;
 }
 /**
@@ -67,14 +86,18 @@ export declare class Player {
  *
  * @beta
  */
-export type Purse = Record<ResourceKind, number>;
+export type Purse = Record<ResourceId, number>;
 /**
  * The resource a purse is short of for a cost, or undefined when it can afford it
  *
  * @beta
  */
-export declare function shortOf(purse: Readonly<Purse>, cost: Cost | undefined): ResourceKind | undefined;
-/** @beta */
+export declare function shortOf(purse: Readonly<Purse>, cost: Cost | undefined): ResourceId | undefined;
+/**
+ * Takes a cost out of a purse, per resource; a purse may go below zero, so check `shortOf` first
+ *
+ * @beta
+ */
 export declare function pay(purse: Purse, cost: Cost | undefined): void;
 /**
  * Gives back what something cost, or a part of it
@@ -85,9 +108,9 @@ export declare function refund(purse: Purse, cost: Cost | undefined, part?: numb
 /**
  * Adds an amount of a resource
  *
- * @beta
+ * @public
  */
-export declare function earn(purse: Purse, kind: ResourceKind, amount: number): void;
+export declare function earn(purse: Purse, kind: ResourceId, amount: number): void;
 /**
  * What a player pays for, as `resourcesSpent` says it: a unit, an upgrade, a structure, a morph, a revive (production),
  * an item, a hire, a repair, a trade at a market (`exchange`), or a game's own word

package/dist/player.js

@@ -0,0 +1,159 @@
+import { StateStore } from "./components.js";
+import { resourcesSpent } from "./engineEvents.js";
+//#region src/player.ts
+/**
+* A player of a world: team, colour, race, resources, supply, researched upgrades and the state of modules, kept by `world.player(id)`
+*
+* @beta
+*/
+var Player = class {
+	/** The player's id, as `PlayerInit.id` */
+	id;
+	/** The name shown for the player, as `PlayerInit.name` */
+	name;
+	/** Changed by `world.setTeam`, which the fog and everyone's sight follow */
+	team;
+	/** The player's colour as RGB, each 0..1, used to tint their units */
+	color;
+	/** Whether this is a neutral player (owner of gold mines and the like); nobody is hostile towards it */
+	neutral;
+	/** Whether this is the creeps' player: hostile to everyone, and not someone who can win or lose */
+	creeps;
+	/** The race they play (`raceOf`): changed by `setRace` only. None in a game without races */
+	race;
+	/** What the player has of each resource, by resource id */
+	resources;
+	/** Supply the player's units and queued units take up now; counted against `supplyCap` */
+	supplyUsed = 0;
+	/** The most supply the player may use, from their buildings that provide it */
+	supplyCap = 0;
+	/** The game's other pools of supply, by name (`RuleSettings.supply.pools`): what is used and the cap of each */
+	supplies = {};
+	/** Has had a building, and with that something to lose */
+	established = false;
+	/** Out of the game */
+	defeated = false;
+	finished = /* @__PURE__ */ new Map();
+	/** Bumped whenever a research finishes. Whatever is worked out from `upgrades` (like the stats of units) can check this to tell whether it still holds */
+	upgradesVersion = 0;
+	/** Upgrades in some production queue right now */
+	researching = /* @__PURE__ */ new Set();
+	/** State of game modules and mods for this player, see `state` */
+	states = new StateStore();
+	constructor(init) {
+		this.id = init.id;
+		this.name = init.name;
+		this.team = init.team;
+		this.color = init.color;
+		this.neutral = init.neutral ?? false;
+		this.creeps = init.creeps ?? false;
+		this.race = init.race;
+		this.resources = { ...init.resources };
+	}
+	/** Finished research: upgrade id to level. Changed through `setUpgrade` only, which keeps `upgradesVersion` honest */
+	get upgrades() {
+		return this.finished;
+	}
+	/** State of a game module or a mod for this player: made from the component's default when first asked for */
+	state(key) {
+		return this.states.get(key);
+	}
+	/** Sets this player's state for a component, replacing what `state` gives for it */
+	setState(key, value) {
+		this.states.set(key, value);
+	}
+	/** Records that an upgrade is researched at this level and bumps `upgradesVersion` */
+	setUpgrade(upgrade, level) {
+		this.finished.set(upgrade, level);
+		this.upgradesVersion++;
+	}
+};
+/**
+* The resource a purse is short of for a cost, or undefined when it can afford it
+*
+* @beta
+*/
+function shortOf(purse, cost) {
+	if (!cost) return void 0;
+	for (const kind in cost) if ((purse[kind] ?? 0) < cost[kind]) return kind;
+}
+/**
+* Takes a cost out of a purse, per resource; a purse may go below zero, so check `shortOf` first
+*
+* @beta
+*/
+function pay(purse, cost) {
+	for (const kind in cost) purse[kind] = (purse[kind] ?? 0) - cost[kind];
+}
+/**
+* Gives back what something cost, or a part of it
+*
+* @beta
+*/
+function refund(purse, cost, part = 1) {
+	for (const kind in cost) purse[kind] = (purse[kind] ?? 0) + Math.floor(cost[kind] * part);
+}
+/**
+* Adds an amount of a resource
+*
+* @public
+*/
+function earn(purse, kind, amount) {
+	purse[kind] = (purse[kind] ?? 0) + amount;
+}
+/**
+* Has a player pay a cost, and says so (`resourcesSpent`, what the score counts as spent): `on` what, and its id. For a
+* game's own purchases too, so that they count as the engine's do. The purse is not checked: `shortOf` first
+*
+* @beta
+*/
+function spend(world, player, cost, on, id) {
+	if (!cost) return;
+	pay(world.player(player).resources, cost);
+	for (const kind in cost) {
+		if (cost[kind] === 0) continue;
+		world.events.emit(resourcesSpent, {
+			player,
+			cost,
+			on,
+			id,
+			refund: false
+		});
+		return;
+	}
+}
+/**
+* Gives a player back what something cost, or a part of it (`refund`), and says so (`resourcesSpent` with `refund`):
+* what the score takes off what was spent
+*
+* @beta
+*/
+function giveBack(world, player, cost, part, on, id) {
+	if (!cost) return;
+	const back = {};
+	let any = false;
+	for (const kind in cost) {
+		back[kind] = Math.floor(cost[kind] * part);
+		if (back[kind] !== 0) any = true;
+	}
+	refund(world.player(player).resources, back);
+	if (any) world.events.emit(resourcesSpent, {
+		player,
+		cost: back,
+		on,
+		id,
+		refund: true
+	});
+}
+/**
+* What a cost asks of the game's money, see `Registry.currency`. Shops deal in that alone
+*
+* @beta
+*/
+function currencyOf(registry, cost) {
+	return registry.currency ? cost?.[registry.currency] ?? 0 : 0;
+}
+//#endregion
+export { Player, currencyOf, earn, giveBack, pay, refund, shortOf, spend };
+
+//# sourceMappingURL=player.js.map

package/dist/player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.js","names":["resourcesSpentEvent"],"sources":["../src/player.ts"],"sourcesContent":["import { resourcesSpent as resourcesSpentEvent } from '#engine/engineEvents'\nimport { type Component, StateStore } from './components'\nimport type { Registry } from './registry'\nimport type { Cost, ResourceId } from './defs'\nimport type { PlayerId } from './entity'\nimport type { World } from './world'\n\n/**\n * What a `Player` is made from: its id, name, team, colour, starting resources and role\n *\n * @beta\n */\nexport interface PlayerInit {\n\t/** The player's id, by which units, commands and the world's lists name them */\n\tid: PlayerId\n\t/** The name shown for the player on scores, in the lobby and in messages */\n\tname: string\n\t/** Players on the same team are allies and share vision */\n\tteam: number\n\t/** RGB, 0..1 */\n\tcolor: [number, number, number]\n\t/** What the player starts with, by resource id */\n\tresources?: Purse\n\t/** Neutral players own things like gold mines. Nobody is hostile towards them */\n\tneutral?: boolean\n\t/** The player the creeps belong to: hostile to everyone, and not someone who can win or lose */\n\tcreeps?: boolean\n\t/**\n\t * The race they play (`Rules.races`), or `random` for one drawn as the game starts. The game's first when left\n\t * out, in a game with races; none for the neutral players and the creeps\n\t */\n\trace?: string\n}\n\n/**\n * A player of a world: team, colour, race, resources, supply, researched upgrades and the state of modules, kept by `world.player(id)`\n *\n * @beta\n */\nexport class Player {\n\t/** The player's id, as `PlayerInit.id` */\n\treadonly id: PlayerId\n\t/** The name shown for the player, as `PlayerInit.name` */\n\treadonly name: string\n\t/** Changed by `world.setTeam`, which the fog and everyone's sight follow */\n\tteam: number\n\t/** The player's colour as RGB, each 0..1, used to tint their units */\n\treadonly color: [number, number, number]\n\t/** Whether this is a neutral player (owner of gold mines and the like); nobody is hostile towards it */\n\treadonly neutral: boolean\n\t/** Whether this is the creeps' player: hostile to everyone, and not someone who can win or lose */\n\treadonly creeps: boolean\n\t/** The race they play (`raceOf`): changed by `setRace` only. None in a game without races */\n\trace: string | undefined\n\t/** What the player has of each resource, by resource id */\n\treadonly resources: Purse\n\t/** Supply the player's units and queued units take up now; counted against `supplyCap` */\n\tsupplyUsed = 0\n\t/** The most supply the player may use, from their buildings that provide it */\n\tsupplyCap = 0\n\t/** The game's other pools of supply, by name (`RuleSettings.supply.pools`): what is used and the cap of each */\n\tsupplies: Record<string, { used: number; cap: number }> = {}\n\t/** Has had a building, and with that something to lose */\n\testablished = false\n\t/** Out of the game */\n\tdefeated = false\n\tprivate readonly finished = new Map<string, number>()\n\t/** Bumped whenever a research finishes. Whatever is worked out from `upgrades` (like the stats of units) can check this to tell whether it still holds */\n\tupgradesVersion = 0\n\t/** Upgrades in some production queue right now */\n\treadonly researching = new Set<string>()\n\t/** State of game modules and mods for this player, see `state` */\n\treadonly states = new StateStore()\n\n\tconstructor(init: PlayerInit) {\n\t\tthis.id = init.id\n\t\tthis.name = init.name\n\t\tthis.team = init.team\n\t\tthis.color = init.color\n\t\tthis.neutral = init.neutral ?? false\n\t\tthis.creeps = init.creeps ?? false\n\t\tthis.race = init.race\n\t\tthis.resources = { ...init.resources }\n\t}\n\n\t/** Finished research: upgrade id to level. Changed through `setUpgrade` only, which keeps `upgradesVersion` honest */\n\tget upgrades(): ReadonlyMap<string, number> {\n\t\treturn this.finished\n\t}\n\n\t/** State of a game module or a mod for this player: made from the component's default when first asked for */\n\tstate<T>(key: Component<T, unknown>): T {\n\t\treturn this.states.get(key)\n\t}\n\n\t/** Sets this player's state for a component, replacing what `state` gives for it */\n\tsetState<T>(key: Component<T, unknown>, value: T): void {\n\t\tthis.states.set(key, value)\n\t}\n\n\t/** Records that an upgrade is researched at this level and bumps `upgradesVersion` */\n\tsetUpgrade(upgrade: string, level: number): void {\n\t\tthis.finished.set(upgrade, level)\n\t\tthis.upgradesVersion++\n\t}\n}\n\n/**\n * Amounts of resources, by resource id: what a player has. A resource left out is none of it\n *\n * @beta\n */\nexport type Purse = Record<ResourceId, number>\n\n/**\n * The resource a purse is short of for a cost, or undefined when it can afford it\n *\n * @beta\n */\nexport function shortOf(purse: Readonly<Purse>, cost: Cost | undefined): ResourceId | undefined {\n\tif (!cost) return undefined\n\tfor (const kind in cost) if ((purse[kind] ?? 0) < cost[kind]) return kind\n\treturn undefined\n}\n\n/**\n * Takes a cost out of a purse, per resource; a purse may go below zero, so check `shortOf` first\n *\n * @beta\n */\nexport function pay(purse: Purse, cost: Cost | undefined): void {\n\tfor (const kind in cost) purse[kind] = (purse[kind] ?? 0) - cost[kind]\n}\n\n/**\n * Gives back what something cost, or a part of it\n *\n * @beta\n */\nexport function refund(purse: Purse, cost: Cost | undefined, part = 1): void {\n\tfor (const kind in cost) purse[kind] = (purse[kind] ?? 0) + Math.floor(cost[kind] * part)\n}\n\n/**\n * Adds an amount of a resource\n *\n * @public\n */\nexport function earn(purse: Purse, kind: ResourceId, amount: number): void {\n\tpurse[kind] = (purse[kind] ?? 0) + amount\n}\n\n/**\n * What a player pays for, as `resourcesSpent` says it: a unit, an upgrade, a structure, a morph, a revive (production),\n * an item, a hire, a repair, a trade at a market (`exchange`), or a game's own word\n *\n * @beta\n */\nexport type SpentOn = 'unit' | 'upgrade' | 'structure' | 'morph' | 'revive' | 'item' | 'hire' | 'repair' | 'trade' | (string & {})\n\n/**\n * Has a player pay a cost, and says so (`resourcesSpent`, what the score counts as spent): `on` what, and its id. For a\n * game's own purchases too, so that they count as the engine's do. The purse is not checked: `shortOf` first\n *\n * @beta\n */\nexport function spend(world: World, player: PlayerId, cost: Cost | undefined, on: SpentOn, id?: string): void {\n\tif (!cost) return\n\tpay(world.player(player).resources, cost)\n\tfor (const kind in cost) {\n\t\tif (cost[kind] === 0) continue\n\t\tworld.events.emit(resourcesSpentEvent, { player, cost, on, id, refund: false })\n\t\treturn\n\t}\n}\n\n/**\n * Gives a player back what something cost, or a part of it (`refund`), and says so (`resourcesSpent` with `refund`):\n * what the score takes off what was spent\n *\n * @beta\n */\nexport function giveBack(world: World, player: PlayerId, cost: Cost | undefined, part: number, on: SpentOn, id?: string): void {\n\tif (!cost) return\n\tconst back: Cost = {}\n\tlet any = false\n\tfor (const kind in cost) {\n\t\tback[kind] = Math.floor(cost[kind] * part)\n\t\tif (back[kind] !== 0) any = true\n\t}\n\trefund(world.player(player).resources, back)\n\tif (any) world.events.emit(resourcesSpentEvent, { player, cost: back, on, id, refund: true })\n}\n\n/**\n * What a cost asks of the game's money, see `Registry.currency`. Shops deal in that alone\n *\n * @beta\n */\nexport function currencyOf(registry: Registry, cost: Cost | undefined): number {\n\treturn registry.currency ? (cost?.[registry.currency] ?? 0) : 0\n}\n"],"mappings":";;;;;;;;AAuCA,IAAa,SAAb,MAAoB;;CAEnB;;CAEA;;CAEA;;CAEA;;CAEA;;CAEA;;CAEA;;CAEA;;CAEA,aAAa;;CAEb,YAAY;;CAEZ,WAA0D,CAAC;;CAE3D,cAAc;;CAEd,WAAW;CACX,2BAA4B,IAAI,IAAoB;;CAEpD,kBAAkB;;CAElB,8BAAuB,IAAI,IAAY;;CAEvC,SAAkB,IAAI,WAAW;CAEjC,YAAY,MAAkB;EAC7B,KAAK,KAAK,KAAK;EACf,KAAK,OAAO,KAAK;EACjB,KAAK,OAAO,KAAK;EACjB,KAAK,QAAQ,KAAK;EAClB,KAAK,UAAU,KAAK,WAAW;EAC/B,KAAK,SAAS,KAAK,UAAU;EAC7B,KAAK,OAAO,KAAK;EACjB,KAAK,YAAY,EAAE,GAAG,KAAK,UAAU;CACtC;;CAGA,IAAI,WAAwC;EAC3C,OAAO,KAAK;CACb;;CAGA,MAAS,KAA+B;EACvC,OAAO,KAAK,OAAO,IAAI,GAAG;CAC3B;;CAGA,SAAY,KAA4B,OAAgB;EACvD,KAAK,OAAO,IAAI,KAAK,KAAK;CAC3B;;CAGA,WAAW,SAAiB,OAAqB;EAChD,KAAK,SAAS,IAAI,SAAS,KAAK;EAChC,KAAK;CACN;AACD;;;;;;AAcA,SAAgB,QAAQ,OAAwB,MAAgD;CAC/F,IAAI,CAAC,MAAM,OAAO,KAAA;CAClB,KAAK,MAAM,QAAQ,MAAM,KAAK,MAAM,SAAS,KAAK,KAAK,OAAO,OAAO;AAEtE;;;;;;AAOA,SAAgB,IAAI,OAAc,MAA8B;CAC/D,KAAK,MAAM,QAAQ,MAAM,MAAM,SAAS,MAAM,SAAS,KAAK,KAAK;AAClE;;;;;;AAOA,SAAgB,OAAO,OAAc,MAAwB,OAAO,GAAS;CAC5E,KAAK,MAAM,QAAQ,MAAM,MAAM,SAAS,MAAM,SAAS,KAAK,KAAK,MAAM,KAAK,QAAQ,IAAI;AACzF;;;;;;AAOA,SAAgB,KAAK,OAAc,MAAkB,QAAsB;CAC1E,MAAM,SAAS,MAAM,SAAS,KAAK;AACpC;;;;;;;AAgBA,SAAgB,MAAM,OAAc,QAAkB,MAAwB,IAAa,IAAmB;CAC7G,IAAI,CAAC,MAAM;CACX,IAAI,MAAM,OAAO,MAAM,CAAC,CAAC,WAAW,IAAI;CACxC,KAAK,MAAM,QAAQ,MAAM;EACxB,IAAI,KAAK,UAAU,GAAG;EACtB,MAAM,OAAO,KAAKA,gBAAqB;GAAE;GAAQ;GAAM;GAAI;GAAI,QAAQ;EAAM,CAAC;EAC9E;CACD;AACD;;;;;;;AAQA,SAAgB,SAAS,OAAc,QAAkB,MAAwB,MAAc,IAAa,IAAmB;CAC9H,IAAI,CAAC,MAAM;CACX,MAAM,OAAa,CAAC;CACpB,IAAI,MAAM;CACV,KAAK,MAAM,QAAQ,MAAM;EACxB,KAAK,QAAQ,KAAK,MAAM,KAAK,QAAQ,IAAI;EACzC,IAAI,KAAK,UAAU,GAAG,MAAM;CAC7B;CACA,OAAO,MAAM,OAAO,MAAM,CAAC,CAAC,WAAW,IAAI;CAC3C,IAAI,KAAK,MAAM,OAAO,KAAKA,gBAAqB;EAAE;EAAQ,MAAM;EAAM;EAAI;EAAI,QAAQ;CAAK,CAAC;AAC7F;;;;;;AAOA,SAAgB,WAAW,UAAoB,MAAgC;CAC9E,OAAO,SAAS,WAAY,OAAO,SAAS,aAAa,IAAK;AAC/D"}

package/dist/portals.d.ts

@@ -63,4 +63,4 @@ export declare function townPortal(world: World, caster: Entity, near: Vec2, rad
  *
  * @beta
  */
-export declare function withPortals(): GamePack;
+export declare function portalsPack(): GamePack;

package/dist/portals.js

@@ -0,0 +1,194 @@
+import { distSq } from "./math.js";
+import { at } from "./defs.js";
+import { defineComponent } from "./components.js";
+import { defineEngineEvent } from "./events.js";
+import { distanceToEdge, moving } from "./entity.js";
+import { defineHook } from "./hooks.js";
+import { halt, moveToEntity } from "./systems/movement.js";
+import { valueOf } from "./abilities/amounts.js";
+import { defineEffect } from "./abilities/effects.js";
+import { createOrder, giveOrder } from "./orders/queue.js";
+import { homeOf } from "./home.js";
+//#region src/portals.ts
+/**
+* The portals pack's id
+*
+* @beta
+*/
+var PORTALS = "core.portals";
+/**
+* Where a waygate leads: a point of the map by its name (as the editor's field keeps it), or a place. A waygate without
+* it, or with `null`, is shut
+*
+* @beta
+*/
+var waygate = defineComponent({
+	id: "core.waygate",
+	field: {
+		name: "Leads to",
+		hint: "The point of the map a unit that walks in comes out at",
+		kind: "point",
+		for: (def) => !!def.waygate
+	}
+});
+/**
+* A unit went through a waygate, or a town portal: told to everyone who sees either end, for a sound and a flash
+*
+* @beta
+*/
+var portalUsed = defineEngineEvent({
+	id: "core.portalUsed",
+	replicate: "everyone"
+});
+/** How near a waygate's edge a unit is in it */
+var REACH = .6;
+/**
+* Where a waygate leads, or nothing for one that is shut or leads to a point the map does not have
+*
+* @beta
+*/
+function waygateTarget(world, gate) {
+	const to = gate.get(waygate);
+	if (!to || !gate.alive) return void 0;
+	if (typeof to !== "string") return to;
+	return world.map.points.some((point) => point.name === to) ? world.map.point(to) : void 0;
+}
+/**
+* Says where a waygate leads (a point of the map by its name, or a place), or shuts it (`null`): what the editor's
+* "Leads to" field says of a placed one, in code. Any building can be made a waygate so
+*
+* @beta
+*/
+function setWaygate(gate, to) {
+	gate.set(waygate, typeof to === "object" && to ? {
+		x: to.x,
+		z: to.z
+	} : to);
+}
+/**
+* Puts a unit somewhere at once, on the nearest ground it can stand on: what a waygate and a town portal do, for a game's
+* own rules. Told to everyone (`portalUsed`)
+*
+* @beta
+*/
+function portal(world, entity, to, gate) {
+	const from = {
+		x: entity.pos.x,
+		z: entity.pos.z
+	};
+	const spot = (entity.flying ? world.air : world.nav).closestPoint(to, 6) ?? to;
+	halt(world, entity);
+	world.place(entity, spot);
+	entity.prevPos.x = spot.x;
+	entity.prevPos.z = spot.z;
+	world.events.emit(portalUsed, {
+		entity: entity.id,
+		from,
+		to: {
+			x: spot.x,
+			z: spot.z
+		},
+		gate: gate?.id
+	});
+}
+/** Going through a waygate: walking into it, then out where it leads. Failed when it is shut, or there is no way to it */
+var enterOrder = {
+	type: "enterWaygate",
+	accepts(world, entity, init) {
+		const gate = world.get(init.target);
+		return !!entity.get(moving) && !!gate && !!waygateTarget(world, gate);
+	},
+	update(world, entity, order) {
+		const gate = world.get(order.init.target);
+		const to = gate && waygateTarget(world, gate);
+		if (!gate || !to) return "failed";
+		if (distanceToEdge(entity.pos, gate) - entity.def.radius <= REACH) {
+			portal(world, entity, to, gate);
+			return "done";
+		}
+		const m = entity.get(moving);
+		if (m.status === "moving") return "running";
+		if (m.status === "failed" && order.state.tried === world.tick - 1) return "failed";
+		order.state.tried = world.tick;
+		moveToEntity(world, entity, gate, REACH * .5);
+		return "running";
+	}
+};
+/** Offsets around a spot, nearest first: where those a town portal brings stand */
+var AROUND = (() => {
+	const all = [];
+	for (let dz = -3; dz <= 3; dz++) for (let dx = -3; dx <= 3; dx++) all.push({
+		x: dx * 1.2,
+		z: dz * 1.2
+	});
+	return all.sort((a, b) => a.x * a.x + a.z * a.z - (b.x * b.x + b.z * b.z));
+})();
+/**
+* Takes a unit and as many as `count` of its owner's units within `radius` of it, nearest first, to its side's home
+* nearest `near` (`homeOf`), spread around it: what the `townPortal` effect does, in code. Gives back who went, none
+* when the side has no home
+*
+* @beta
+*/
+function townPortal(world, caster, near, radius = 7, count = 12) {
+	const home = homeOf(world, caster.owner, near);
+	if (!home) return [];
+	const going = [caster, ...world.spatial.query(caster.pos.x, caster.pos.z, radius).filter((entity) => entity !== caster && entity.alive && !entity.hidden && entity.owner === caster.owner && !!entity.get(moving) && distanceToEdge(caster.pos, entity) <= radius).map((entity) => ({
+		entity,
+		d: distSq(entity.pos, caster.pos)
+	})).sort((a, b) => a.d - b.d || a.entity.id - b.entity.id).slice(0, Math.max(0, count)).map(({ entity }) => entity)];
+	going.forEach((entity, i) => {
+		const offset = AROUND[i % AROUND.length];
+		portal(world, entity, {
+			x: home.x + offset.x,
+			z: home.z + offset.z
+		});
+	});
+	return going;
+}
+var townPortalEffect = defineEffect({
+	type: "townPortal",
+	run: (context, effect) => {
+		const { world, caster, point, level } = context;
+		townPortal(world, caster, point, valueOf(context, effect.radius, void 0, 7), Math.round(at(effect.count, level, 12)));
+	},
+	fields: ["count"]
+});
+/**
+* Portals, as in classic RTS games: waygates (`UnitTypeDef.waygate`), which a unit told to (a right-click, as any building is
+* walked up to) walks into and comes out of where the gate leads (the "Leads to" field of a placed one, a point of the
+* map; `setWaygate` in code), and the `townPortal` effect (`EffectTypes.townPortal`), which takes the caster and its
+* units around it to its side's home nearest where it was aimed (`homeOf`: the map's `home.<team>` point, or the
+* nearest of its buildings). `portal` and `townPortal` do them in code
+*
+* @beta
+*/
+function portalsPack() {
+	const intoGate = defineHook({
+		hook: "beforeOrder",
+		id: "portals",
+		run(world, event) {
+			const { order, entity } = event;
+			if (order.type !== "move" || order.init.target === void 0) return;
+			const gate = world.get(order.init.target);
+			if (!gate?.def.waygate || !waygateTarget(world, gate) || !entity.get(moving)) return;
+			event.rejected = true;
+			giveOrder(world, entity, createOrder(world, {
+				type: "enterWaygate",
+				target: gate.id
+			}, order.groupId), event.queued);
+		}
+	});
+	return {
+		id: PORTALS,
+		orders: [enterOrder],
+		components: [waygate],
+		events: [portalUsed],
+		effects: [townPortalEffect],
+		hooks: [intoGate]
+	};
+}
+//#endregion
+export { PORTALS, portal, portalUsed, portalsPack, setWaygate, townPortal, waygate, waygateTarget };
+
+//# sourceMappingURL=portals.js.map

package/dist/portals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portals.js","names":[],"sources":["../src/portals.ts"],"sourcesContent":["import { defineEffect } from './abilities/effects'\nimport { at } from './defs'\nimport { valueOf } from './abilities/amounts'\nimport { defineComponent } from './components'\nimport { defineEngineEvent } from './events'\nimport { distanceToEdge, type Entity, moving } from './entity'\nimport { homeOf } from './home'\nimport { defineHook } from './hooks'\nimport { distSq, type Vec2 } from './math'\nimport { createOrder, giveOrder } from './orders/queue'\nimport type { GamePack } from './packs/pack'\nimport type { OrderBehavior, OrderParams } from './registry'\nimport { halt, moveToEntity } from './systems/movement'\nimport type { World } from './world'\n\n/*\n * Portals, an opt-in pack (review RV95): waygates, buildings a unit walks into to be elsewhere at once (`waygate`), and\n * the town portal, which takes a hero and its army to their side's home (`townPortal`)\n */\n\n/**\n * The portals pack's id\n *\n * @beta\n */\nexport const PORTALS = 'core.portals'\n\n/**\n * Where a waygate leads: a point of the map by its name (as the editor's field keeps it), or a place. A waygate without\n * it, or with `null`, is shut\n *\n * @beta\n */\nexport const waygate = defineComponent<string | Vec2 | null>({ id: 'core.waygate', field: { name: 'Leads to', hint: 'The point of the map a unit that walks in comes out at', kind: 'point', for: (def) => !!def.waygate } })\n\n/**\n * A unit went through a waygate, or a town portal: told to everyone who sees either end, for a sound and a flash\n *\n * @beta\n */\nexport const portalUsed = defineEngineEvent<{ entity: number; from: Vec2; to: Vec2; gate?: number }>({ id: 'core.portalUsed', replicate: 'everyone' })\n\n/** How near a waygate's edge a unit is in it */\nconst REACH = 0.6\n\n/**\n * Where a waygate leads, or nothing for one that is shut or leads to a point the map does not have\n *\n * @beta\n */\nexport function waygateTarget(world: World, gate: Entity): Vec2 | undefined {\n\tconst to = gate.get(waygate)\n\tif (!to || !gate.alive) return undefined\n\tif (typeof to !== 'string') return to\n\treturn world.map.points.some((point) => point.name === to) ? world.map.point(to) : undefined\n}\n\n/**\n * Says where a waygate leads (a point of the map by its name, or a place), or shuts it (`null`): what the editor's\n * \"Leads to\" field says of a placed one, in code. Any building can be made a waygate so\n *\n * @beta\n */\nexport function setWaygate(gate: Entity, to: string | Vec2 | null): void {\n\tgate.set(waygate, typeof to === 'object' && to ? { x: to.x, z: to.z } : to)\n}\n\n/**\n * Puts a unit somewhere at once, on the nearest ground it can stand on: what a waygate and a town portal do, for a game's\n * own rules. Told to everyone (`portalUsed`)\n *\n * @beta\n */\nexport function portal(world: World, entity: Entity, to: Vec2, gate?: Entity): void {\n\tconst from = { x: entity.pos.x, z: entity.pos.z }\n\tconst spot = (entity.flying ? world.air : world.nav).closestPoint(to, 6) ?? to\n\thalt(world, entity)\n\tworld.place(entity, spot)\n\tentity.prevPos.x = spot.x\n\tentity.prevPos.z = spot.z\n\tworld.events.emit(portalUsed, { entity: entity.id, from, to: { x: spot.x, z: spot.z }, gate: gate?.id })\n}\n\n/** Going through a waygate: walking into it, then out where it leads. Failed when it is shut, or there is no way to it */\nconst enterOrder: OrderBehavior<{ tried?: number }, Pick<OrderParams, 'target'>> = {\n\ttype: 'enterWaygate',\n\taccepts(world, entity, init) {\n\t\tconst gate = world.get(init.target)\n\t\treturn !!entity.get(moving) && !!gate && !!waygateTarget(world, gate)\n\t},\n\tupdate(world, entity, order) {\n\t\tconst gate = world.get(order.init.target)\n\t\tconst to = gate && waygateTarget(world, gate)\n\t\tif (!gate || !to) return 'failed'\n\t\tif (distanceToEdge(entity.pos, gate) - entity.def.radius <= REACH) {\n\t\t\tportal(world, entity, to, gate)\n\t\t\treturn 'done'\n\t\t}\n\t\tconst m = entity.get(moving)!\n\t\tif (m.status === 'moving') return 'running'\n\t\tif (m.status === 'failed' && order.state.tried === world.tick - 1) return 'failed'\n\t\torder.state.tried = world.tick\n\t\tmoveToEntity(world, entity, gate, REACH * 0.5)\n\t\treturn 'running'\n\t}\n}\n\n/** Offsets around a spot, nearest first: where those a town portal brings stand */\nconst AROUND: readonly Vec2[] = (() => {\n\tconst all: Vec2[] = []\n\tfor (let dz = -3; dz <= 3; dz++) for (let dx = -3; dx <= 3; dx++) all.push({ x: dx * 1.2, z: dz * 1.2 })\n\treturn all.sort((a, b) => a.x * a.x + a.z * a.z - (b.x * b.x + b.z * b.z))\n})()\n\n/**\n * Takes a unit and as many as `count` of its owner's units within `radius` of it, nearest first, to its side's home\n * nearest `near` (`homeOf`), spread around it: what the `townPortal` effect does, in code. Gives back who went, none\n * when the side has no home\n *\n * @beta\n */\nexport function townPortal(world: World, caster: Entity, near: Vec2, radius = 7, count = 12): Entity[] {\n\tconst home = homeOf(world, caster.owner, near)\n\tif (!home) return []\n\tconst others = world.spatial\n\t\t.query(caster.pos.x, caster.pos.z, radius)\n\t\t.filter(\n\t\t\t(entity) =>\n\t\t\t\tentity !== caster &&\n\t\t\t\tentity.alive &&\n\t\t\t\t!entity.hidden &&\n\t\t\t\tentity.owner === caster.owner &&\n\t\t\t\t!!entity.get(moving) &&\n\t\t\t\tdistanceToEdge(caster.pos, entity) <= radius\n\t\t)\n\t\t.map((entity) => ({ entity, d: distSq(entity.pos, caster.pos) }))\n\t\t.sort((a, b) => a.d - b.d || a.entity.id - b.entity.id)\n\t\t.slice(0, Math.max(0, count))\n\t\t.map(({ entity }) => entity)\n\tconst going = [caster, ...others]\n\tgoing.forEach((entity, i) => {\n\t\tconst offset = AROUND[i % AROUND.length]\n\t\tportal(world, entity, { x: home.x + offset.x, z: home.z + offset.z })\n\t})\n\treturn going\n}\n\nconst townPortalEffect = defineEffect({ type: 'townPortal', run: (context, effect) => {\n\t\tconst { world, caster, point, level } = context\n\t\ttownPortal(world, caster, point, valueOf(context, effect.radius, undefined, 7), Math.round(at(effect.count, level, 12)))\n\t}, fields: ['count'] })\n\n/**\n * Portals, as in classic RTS games: waygates (`UnitTypeDef.waygate`), which a unit told to (a right-click, as any building is\n * walked up to) walks into and comes out of where the gate leads (the \"Leads to\" field of a placed one, a point of the\n * map; `setWaygate` in code), and the `townPortal` effect (`EffectTypes.townPortal`), which takes the caster and its\n * units around it to its side's home nearest where it was aimed (`homeOf`: the map's `home.<team>` point, or the\n * nearest of its buildings). `portal` and `townPortal` do them in code\n *\n * @beta\n */\nexport function portalsPack(): GamePack {\n\t// told to walk up to a waygate that leads somewhere: through it\n\tconst intoGate = defineHook({\n\t\thook: 'beforeOrder',\n\t\tid: 'portals',\n\t\trun(world, event) {\n\t\t\tconst { order, entity } = event\n\t\t\tif (order.type !== 'move' || order.init.target === undefined) return\n\t\t\tconst gate = world.get(order.init.target)\n\t\t\tif (!gate?.def.waygate || !waygateTarget(world, gate) || !entity.get(moving)) return\n\t\t\tevent.rejected = true\n\t\t\tgiveOrder(world, entity, createOrder(world, { type: 'enterWaygate', target: gate.id }, order.groupId), event.queued)\n\t\t}\n\t})\n\treturn {\n\t\tid: PORTALS,\n\t\torders: [enterOrder],\n\t\tcomponents: [waygate],\n\t\tevents: [portalUsed],\n\t\teffects: [townPortalEffect],\n\t\thooks: [intoGate]\n\t}\n}\n"],"mappings":"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"}

package/dist/prefabs.d.ts

@@ -7,17 +7,22 @@ import type { World } from './world';
  * @beta
  */
 export interface PrefabObject {
+    /** The unit type id to spawn */
     type: string;
     /**
      * Whose: the player the prefab is spawned for (`'owner'`, the default), neutral, the creeps, or a player of the
      * map's by id (a file's objects say the id they had; one that is a player's becomes `'owner'` as the file is read)
      */
     owner?: 'owner' | 'neutral' | 'creeps' | PlayerId;
+    /** Where it stands east-west, in cells from the prefab's middle before the prefab's turn and size */
     x: number;
+    /** Where it stands north-south, in cells from the prefab's middle before the prefab's turn and size */
     z: number;
     /** Radians, the way entities face */
     facing?: number;
+    /** Size of the entity as a multiple of its type's own; the prefab's scale is applied on top */
     scale?: number;
+    /** The id of the look the entity is drawn with, in place of its type's own */
     look?: string;
     /** A name of its own, for the rules to find it by: made free where it is taken (a number added) */
     name?: string;
@@ -30,16 +35,22 @@ export interface PrefabObject {
  * @beta
  */
 export interface PrefabCamp {
+    /** East-west position of the camp from the prefab's middle, in cells */
     x: number;
+    /** North-south position of the camp from the prefab's middle, in cells */
     z: number;
+    /** Unit type ids of the creeps the camp holds */
     units: string[];
+    /** A name for the camp, for the rules to find it by */
     name?: string;
 }
 /** An area the rules watch, of a prefab: its id gets the spawn's own suffix, so that two of one prefab are two areas *
  * @beta
  */
 export interface PrefabArea {
+    /** The area's id before the spawn's own suffix is added, so two spawns of one prefab give two areas */
     id: string;
+    /** The area's shape, placed around the prefab's middle */
     shape: AreaShape;
 }
 /** A prefab inside a prefab: spawned with it, its middle where it says from the outer one's, turned and sized with it *
@@ -48,18 +59,24 @@ export interface PrefabArea {
 export interface PrefabInside {
     /** The prefab's id */
     prefab: string;
+    /** East-west position of the inner prefab's middle, from the outer one's middle, in cells */
     x: number;
+    /** North-south position of the inner prefab's middle, from the outer one's middle, in cells */
     z: number;
     /** Radians, the way facings turn: on top of the outer prefab's turn */
     facing?: number;
+    /** Size of the inner prefab as a multiple, on top of the outer prefab's scale */
     scale?: number;
 }
 /** What a prefab is made of, around its middle (0, 0) *
  * @beta
  */
 export interface PrefabContents {
+    /** The units and buildings it spawns */
     objects?: PrefabObject[];
+    /** The camps of creeps it spawns */
     camps?: PrefabCamp[];
+    /** The areas it adds for the rules to watch */
     areas?: PrefabArea[];
     /** Prefabs inside it, spawned with it (a prefab that holds itself, at any depth, is not spawned past the first) */
     prefabs?: PrefabInside[];
@@ -73,24 +90,28 @@ export interface PrefabContents {
 export interface PrefabDef {
     /** Shared by every game: give it a prefix of the game's (`'td.fortress'`) */
     id: string;
+    /** A readable name for the prefab, for tools that list prefabs */
     name?: string;
+    /** What the prefab is made of: plain data, or a function of the spawn point and the world that returns it */
     contents: PrefabContents | ((at: Vec2, world: World) => PrefabContents);
 }
 /**
  * Typed help for writing a prefab
  *
- * @beta
+ * @public
  */
 export declare const definePrefab: (def: PrefabDef) => PrefabDef;
 /** How a prefab is spawned: where its middle goes, for whom, turned and sized *
  * @beta
  */
 export interface SpawnPrefabOptions {
+    /** Where the prefab's middle goes, in world coordinates */
     at: Vec2;
     /** The player the prefab's `'owner'` objects are spawned for: neutral when left out */
     owner?: PlayerId;
     /** Radians, the way facings turn: the prefab turned around its middle */
     facing?: number;
+    /** Size multiplier of the prefab around its middle; whole size when left out */
     scale?: number;
     /** Parts left out, by their index in the prefab's lists: a gate without its towers */
     without?: {
@@ -104,7 +125,9 @@ export interface SpawnPrefabOptions {
  * @beta
  */
 export interface SpawnedPrefab {
+    /** The units and buildings spawned */
     entities: Entity[];
+    /** The camps of creeps spawned */
     camps: Camp[];
     /** The ids of the areas added */
     areas: string[];
@@ -132,7 +155,7 @@ export declare function nestedPartId(nested: number, id: number): number;
  * variant is read through its source and a prefab with prefabs inside through those, as the editor places them, from
  * the files given
  *
- * @beta
+ * @public
  */
 export declare function prefabsFrom(files: Record<string, unknown>, options?: {
     prefix?: string;