@v12-engine/engine 0.1.0 → 0.4.0

package/dist/life.js

@@ -0,0 +1,287 @@
+import { footprintOf } from "./defs.js";
+import { statsOf } from "./stats.js";
+import { damaged, entityDied, healed } from "./engineEvents.js";
+import { replicateEvent } from "./replication.js";
+import { deposit, fighting } from "./entity.js";
+import { absorb, healthFloor, isInvulnerable, overheal } from "./abilities/buffs.js";
+import { dashing } from "./dashing.js";
+import { cheatDeath } from "./abilities/triggers.js";
+import { clearOrders } from "./orders/queue.js";
+import { hurtWhileChannelling } from "./orders/cast.js";
+import { expose } from "./systems/fog.js";
+//#region src/life.ts
+/**
+* How things are hurt, healed and die in a world (`world.life`): damage through the hooks, armor and shields; healing;
+* death through its hooks, the entity leaving the world, a fallen hero waiting out of it. The world's `damage`, `heal`
+* and `kill` are this
+*/
+/**
+* How a world's entities are hurt, healed and die
+*
+* @beta
+*/
+var Life = class {
+	world;
+	/** Who died and is to be taken out of the world at the end of the tick (`World.step`) */
+	dead = [];
+	constructor(world) {
+		this.world = world;
+	}
+	/**
+	* Deals damage. In order:
+	* 1. the `beforeDamage` hook, which can change the amount or call it off;
+	* 2. armor or magic resist take their part, then the damage is made more or less (`incomingDamage`, `outgoingDamage`:
+	*    `RuleSettings.combat.damageScale`), and shields take theirs;
+	* 3. the rest comes off the target's health, and it dies when nothing is left (see `kill`);
+	* 4. the `afterDamage` hook, for what follows from a hit: life steal, effects on hit.
+	*/
+	damage(target, amount, source, options = {}) {
+		if (!target.alive || target.def.invulnerable || target.def.targetableBy || this.dying.has(target)) return;
+		if (this.world.cheats.invulnerable && this.world.debugPlayers.has(target.owner)) return;
+		if (target.buffs.length && isInvulnerable(this.world, target)) return;
+		const attack = options.attack ?? false;
+		const crit = options.crit ?? false;
+		const { ability, tags } = options;
+		let type = options.damageType ?? "physical";
+		const { hooks } = this.world;
+		if (hooks.has("beforeDamage")) {
+			const before = hooks.run("beforeDamage", {
+				target,
+				source,
+				amount,
+				type,
+				attack,
+				crit,
+				ability,
+				tags,
+				cancelled: false
+			});
+			if (before.cancelled || !target.alive) return;
+			amount = before.amount;
+			type = before.type;
+		}
+		const from = source ? statsOf(this.world, source) : void 0;
+		const { combat } = this.world.settings;
+		const own = statsOf(this.world, target);
+		const arrived = Math.max(amount * combat.mitigation(type, own, from) * combat.damageScale(type, own, from), 0);
+		let dealt = target.def.uses ? 1 : target.buffs.length ? absorb(target, arrived) : arrived;
+		if (target.buffs.length && dealt > 0) {
+			const floor = healthFloor(this.world, target);
+			if (floor > 0 && target.health - dealt < floor) dealt = Math.max(target.health - floor, 0);
+		}
+		const taken = Math.min(dealt, target.health);
+		target.health -= dealt;
+		target.hurtAt = this.world.time;
+		if (source && target.get(fighting)) target.get(fighting).lastAttacker = source.id;
+		if (dealt > 0 && target.orders.length) hurtWhileChannelling(this.world, target);
+		if (source && this.world.areEnemies(source.owner, target.owner)) expose(source, this.world.player(target.owner).team);
+		this.world.events.emit(damaged, {
+			target,
+			source,
+			amount: dealt,
+			type,
+			crit,
+			attack,
+			ability,
+			tags
+		});
+		if (target.health <= 0) this.die(target, source, attack, "damage", {
+			type,
+			amount: dealt,
+			overkill: Math.max(dealt - taken, 0),
+			crit,
+			ability,
+			tags,
+			...options.how && { how: options.how }
+		});
+		if (hooks.has("afterDamage")) hooks.run("afterDamage", {
+			target,
+			source,
+			dealt,
+			taken,
+			type,
+			attack,
+			crit,
+			ability,
+			tags
+		});
+	}
+	/**
+	* Gives health back, made more or less by what the target gets of it (`incomingHealing`:
+	* `RuleSettings.combat.healingScale`), then after the `beforeHeal` hook had its say. Returns how much of it was needed
+	*/
+	heal(target, amount, source) {
+		if (!target.alive || amount <= 0 || this.dying.has(target)) return 0;
+		amount *= this.world.settings.combat.healingScale(statsOf(this.world, target), source && statsOf(this.world, source));
+		if (amount <= 0) return 0;
+		const before = this.world.hooks.run("beforeHeal", {
+			target,
+			source,
+			amount,
+			cancelled: false
+		});
+		if (before.cancelled) return 0;
+		amount = before.amount;
+		const healed$1 = Math.min(amount, target.maxHealth - target.health);
+		if (amount > healed$1 && (target.buffs.length || source?.buffs.length)) overheal(this.world, target, source, amount - Math.max(healed$1, 0));
+		if (healed$1 <= 0) return 0;
+		target.health += healed$1;
+		this.world.events.emit(healed, {
+			target,
+			source,
+			amount: healed$1
+		});
+		return healed$1;
+	}
+	/**
+	* Kills an entity by the rules, not by damage: felled, cancelled, run out of time. `attack` says that an attack of
+	* the killer did it; `reason` why (`DeathReason`: `killed` when left out, or the game's own word, `sold`), for the
+	* hooks and the screen
+	*/
+	kill(entity, killer, attack = false, reason = "killed") {
+		this.die(entity, killer, attack, reason);
+	}
+	/**
+	* How anything dies. In order:
+	* 1. the `beforeDeath` hook, which can keep it alive;
+	* 2. its orders and production are called off;
+	* 3. the `death` hook, while it still stands where it was: experience, loot, bounty;
+	* 4. it leaves the world (a fallen hero waits out of it to be brought back);
+	* 5. the `afterDeath` hook, for what follows: effects of the killer on a kill.
+	*/
+	die(entity, killer, attack, reason, cause) {
+		if (!entity.alive || this.dying.has(entity)) return;
+		if (this.world.hooks.run("beforeDeath", {
+			entity,
+			killer,
+			attack,
+			fromDamage: !!cause,
+			cause,
+			reason,
+			cancelled: false
+		}).cancelled) return;
+		if ((cause || reason === "killed") && cheatDeath(this.world, entity)) return;
+		this.dying.add(entity);
+		try {
+			clearOrders(this.world, entity);
+			this.world.leave(entity);
+			const death = {
+				entity,
+				killer,
+				attack,
+				cause,
+				reason,
+				...cause?.how && { how: cause.how }
+			};
+			this.world.hooks.run("death", death);
+			this.fall(entity, killer, attack, cause, death);
+		} finally {
+			this.dying.delete(entity);
+		}
+	}
+	/** Who is being killed right now: their `death` hooks are running. They take no damage, no healing, and die once */
+	dying = /* @__PURE__ */ new Set();
+	/** Whether an entity is being killed right now: alive still, while its `death` hooks run, and past saving */
+	isDying(entity) {
+		return this.dying.has(entity);
+	}
+	/** What follows the `death` hooks: the entity is gone from the world, and it is told */
+	fall(entity, killer, attack, cause, death) {
+		entity.setAlive(false);
+		entity.health = 0;
+		if (entity.buffs.length) death.carried = entity.buffs.slice();
+		entity.clearBuffs();
+		entity.remove(dashing);
+		this.detach(entity);
+		if (!this.world.hooks.has("fallenHero") || !this.world.hooks.run("fallenHero", {
+			entity,
+			killer,
+			stays: false
+		}).stays) this.dead.push(entity);
+		this.world.events.emit(entityDied, {
+			entity,
+			killer,
+			attack,
+			cause,
+			how: death.how,
+			reason: death.reason
+		});
+		this.world.hooks.run("afterDeath", death);
+		const above = this.world.get(entity.get(deposit)?.under);
+		if (above?.alive && !this.isDying(above)) this.kill(above, void 0, false, "removed");
+	}
+	detach(entity) {
+		this.world.nav.removeAgent(entity.id);
+		if (entity.isStructure) this.world.spatial.removeStatic(entity);
+		if (entity.cell) {
+			const fp = footprintOf(entity.def);
+			this.world.grid.release(entity.cell.x, entity.cell.z, fp.w, fp.d, entity.id);
+			this.world.nav.removeObstacle(entity.id);
+		}
+		const under = this.world.get(entity.on);
+		if (under?.get(deposit) && under.cell) {
+			if (under.get(deposit).under === entity.id) under.get(deposit).under = void 0;
+			if (under.alive) {
+				const fp = footprintOf(under.def);
+				this.world.grid.occupy(under.cell.x, under.cell.z, fp.w, fp.d, under.id);
+			}
+		}
+	}
+};
+/** A death, to those who see the dead: who killed it where they see the killer too (`SessionEvent` `death`) */
+var toldDeath = replicateEvent(entityDied, "death", ({ entity, killer, attack, cause, how, reason }, view) => {
+	if (!view.knows(entity)) return void 0;
+	const seen = killer && killer !== entity && view.knows(killer) ? killer : void 0;
+	return {
+		type: "death",
+		id: entity.id,
+		from: seen && {
+			x: seen.pos.x,
+			z: seen.pos.z
+		},
+		killer: seen?.id,
+		killerType: seen?.def.id,
+		attack,
+		damageType: cause?.type,
+		ability: cause?.ability,
+		overkill: cause?.overkill,
+		crit: cause?.crit,
+		how,
+		...reason !== "damage" && { reason },
+		...cause?.tags?.length && { tags: [...cause.tags] }
+	};
+});
+/** A hit, to those who see who took it: who dealt it where they see them too */
+var toldDamage = replicateEvent(damaged, "damage", ({ target, source, amount, type, attack, crit, ability, tags }, view) => {
+	if (!view.knows(target)) return void 0;
+	const seen = source && view.knows(source) ? source : void 0;
+	return {
+		type: "damage",
+		id: target.id,
+		amount,
+		damageType: type,
+		source: seen?.id,
+		sourceType: seen?.def.id,
+		attack,
+		crit,
+		ability: seen ? ability : void 0,
+		tags
+	};
+});
+/** Healing, to those who see who was healed */
+var toldHeal = replicateEvent(healed, "heal", ({ target, source, amount }, view) => view.knows(target) ? {
+	type: "heal",
+	id: target.id,
+	amount,
+	source: source && view.knows(source) ? source.id : void 0
+} : void 0);
+/** A critical strike's number over who took it */
+var toldCrit = replicateEvent(damaged, "crit", ({ target, amount, crit }, view) => crit && view.knows(target) ? {
+	type: "crit",
+	id: target.id,
+	amount: Math.round(amount)
+} : void 0);
+//#endregion
+export { Life, toldCrit, toldDamage, toldDeath, toldHeal };
+
+//# sourceMappingURL=life.js.map

package/dist/life.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"life.js","names":["healed","healedEvent"],"sources":["../src/life.ts"],"sourcesContent":["/**\n * How things are hurt, healed and die in a world (`world.life`): damage through the hooks, armor and shields; healing;\n * death through its hooks, the entity leaving the world, a fallen hero waiting out of it. The world's `damage`, `heal`\n * and `kill` are this\n */\nimport { damaged, entityDied, healed as healedEvent } from '#engine/engineEvents'\nimport { dashing } from './dashing'\nimport { absorb, healthFloor, isInvulnerable, overheal } from './abilities/buffs'\nimport { footprintOf } from './defs'\nimport { type BuffInstance, type Entity, fighting, deposit } from './entity'\nimport type { Death } from './hooks'\nimport { hurtWhileChannelling } from './orders/cast'\nimport { cheatDeath } from './abilities/triggers'\nimport { clearOrders } from './orders/queue'\nimport { statsOf } from './stats'\nimport { expose } from './systems/fog'\nimport type { DamageOptions, DeathCause, DeathReason, World } from './world'\nimport { replicateEvent } from './replication'\n\n/**\n * How a world's entities are hurt, healed and die\n *\n * @beta\n */\nexport class Life {\n\t/** Who died and is to be taken out of the world at the end of the tick (`World.step`) */\n\treadonly dead: Entity[] = []\n\n\tconstructor(private readonly world: World) {}\n\n\t/**\n\t * Deals damage. In order:\n\t * 1. the `beforeDamage` hook, which can change the amount or call it off;\n\t * 2. armor or magic resist take their part, then the damage is made more or less (`incomingDamage`, `outgoingDamage`:\n\t *    `RuleSettings.combat.damageScale`), and shields take theirs;\n\t * 3. the rest comes off the target's health, and it dies when nothing is left (see `kill`);\n\t * 4. the `afterDamage` hook, for what follows from a hit: life steal, effects on hit.\n\t */\n\tdamage(target: Entity, amount: number, source?: Entity, options: DamageOptions = {}): void {\n\t\t// one already being killed takes no more: its death goes on as it began\n\t\tif (!target.alive || target.def.invulnerable || target.def.targetableBy || this.dying.has(target)) return\n\t\t// the cheat: what those who may use the debug tools own is not hurt\n\t\tif (this.world.cheats.invulnerable && this.world.debugPlayers.has(target.owner)) return\n\t\t// a buff that keeps it from harm (AB9): Divine Shield, a stasis\n\t\tif (target.buffs.length && isInvulnerable(this.world, target)) return\n\t\tconst attack = options.attack ?? false\n\t\tconst crit = options.crit ?? false\n\t\tconst { ability, tags } = options\n\t\tlet type = options.damageType ?? 'physical'\n\t\t// the event made only for a game that hears it: damage is dealt on every hit\n\t\tconst { hooks } = this.world\n\t\tif (hooks.has('beforeDamage')) {\n\t\t\tconst before = hooks.run('beforeDamage', { target, source, amount, type, attack, crit, ability, tags, cancelled: false })\n\t\t\tif (before.cancelled || !target.alive) return\n\t\t\tamount = before.amount\n\t\t\ttype = before.type\n\t\t}\n\t\tconst from = source ? statsOf(this.world, source) : undefined\n\t\tconst { combat } = this.world.settings\n\t\tconst own = statsOf(this.world, target)\n\t\t// armor or magic resist, then what makes it more or less for either side (`incomingDamage`, `outgoingDamage`)\n\t\tconst arrived = Math.max(amount * combat.mitigation(type, own, from) * combat.damageScale(type, own, from), 0)\n\t\t// what counts hits takes one, however hard it is struck\n\t\tlet dealt = target.def.uses ? 1 : target.buffs.length ? absorb(target, arrived) : arrived\n\t\t// a floor a buff keeps its health at (AB9): hurt down to it, never past it\n\t\tif (target.buffs.length && dealt > 0) {\n\t\t\tconst floor = healthFloor(this.world, target)\n\t\t\tif (floor > 0 && target.health - dealt < floor) dealt = Math.max(target.health - floor, 0)\n\t\t}\n\t\tconst taken = Math.min(dealt, target.health)\n\t\ttarget.health -= dealt\n\t\ttarget.hurtAt = this.world.time\n\t\tif (source && target.get(fighting)) target.get(fighting)!.lastAttacker = source.id\n\t\t// a recall, and whatever else is kept up only while unhurt, is broken off\n\t\tif (dealt > 0 && target.orders.length) hurtWhileChannelling(this.world, target)\n\t\tif (source && this.world.areEnemies(source.owner, target.owner)) expose(source, this.world.player(target.owner).team)\n\t\tthis.world.events.emit(damaged, { target, source, amount: dealt, type, crit, attack, ability, tags })\n\t\tif (target.health <= 0)\n\t\t\tthis.die(target, source, attack, 'damage', {\n\t\t\t\ttype,\n\t\t\t\tamount: dealt,\n\t\t\t\toverkill: Math.max(dealt - taken, 0),\n\t\t\t\tcrit,\n\t\t\t\tability,\n\t\t\t\ttags,\n\t\t\t\t...(options.how && { how: options.how })\n\t\t\t})\n\t\tif (hooks.has('afterDamage')) hooks.run('afterDamage', { target, source, dealt, taken, type, attack, crit, ability, tags })\n\t}\n\n\t/**\n\t * Gives health back, made more or less by what the target gets of it (`incomingHealing`:\n\t * `RuleSettings.combat.healingScale`), then after the `beforeHeal` hook had its say. Returns how much of it was needed\n\t */\n\theal(target: Entity, amount: number, source?: Entity): number {\n\t\tif (!target.alive || amount <= 0 || this.dying.has(target)) return 0\n\t\tamount *= this.world.settings.combat.healingScale(statsOf(this.world, target), source && statsOf(this.world, source))\n\t\tif (amount <= 0) return 0\n\t\tconst before = this.world.hooks.run('beforeHeal', { target, source, amount, cancelled: false })\n\t\tif (before.cancelled) return 0\n\t\tamount = before.amount\n\t\tconst healed = Math.min(amount, target.maxHealth - target.health)\n\t\t// what spills over full health, where a buff of the healer's or the healed one's makes it a shield (`BuffDef.overheal`)\n\t\tif (amount > healed && (target.buffs.length || source?.buffs.length)) overheal(this.world, target, source, amount - Math.max(healed, 0))\n\t\tif (healed <= 0) return 0\n\t\ttarget.health += healed\n\t\tthis.world.events.emit(healedEvent, { target, source, amount: healed })\n\t\treturn healed\n\t}\n\n\t/**\n\t * Kills an entity by the rules, not by damage: felled, cancelled, run out of time. `attack` says that an attack of\n\t * the killer did it; `reason` why (`DeathReason`: `killed` when left out, or the game's own word, `sold`), for the\n\t * hooks and the screen\n\t */\n\tkill(entity: Entity, killer?: Entity, attack = false, reason: DeathReason = 'killed'): void {\n\t\tthis.die(entity, killer, attack, reason)\n\t}\n\n\t/**\n\t * How anything dies. In order:\n\t * 1. the `beforeDeath` hook, which can keep it alive;\n\t * 2. its orders and production are called off;\n\t * 3. the `death` hook, while it still stands where it was: experience, loot, bounty;\n\t * 4. it leaves the world (a fallen hero waits out of it to be brought back);\n\t * 5. the `afterDeath` hook, for what follows: effects of the killer on a kill.\n\t */\n\tprivate die(entity: Entity, killer: Entity | undefined, attack: boolean, reason: DeathReason, cause?: DeathCause): void {\n\t\tif (!entity.alive || this.dying.has(entity)) return\n\t\tif (this.world.hooks.run('beforeDeath', { entity, killer, attack, fromDamage: !!cause, cause, reason, cancelled: false }).cancelled) return\n\t\t// a passive that cheats death (`onFatal`, AB9), of a blow or a kill, not of what the rules take away\n\t\tif ((cause || reason === 'killed') && cheatDeath(this.world, entity)) return\n\t\t// from here on it is dying: still alive and where it was for the `death` hooks, but what they do to it, or what\n\t\t// what they do does to it (a blast that kills a neighbour whose own blast comes back), kills it no second time\n\t\tthis.dying.add(entity)\n\t\ttry {\n\t\t\tclearOrders(this.world, entity)\n\t\t\tthis.world.leave(entity)\n\t\t\t// how the blow says it dies, for the `death` hook to keep or change\n\t\t\tconst death: Death = { entity, killer, attack, cause, reason, ...(cause?.how && { how: cause.how }) }\n\t\t\tthis.world.hooks.run('death', death)\n\t\t\tthis.fall(entity, killer, attack, cause, death)\n\t\t} finally {\n\t\t\tthis.dying.delete(entity)\n\t\t}\n\t}\n\n\t/** Who is being killed right now: their `death` hooks are running. They take no damage, no healing, and die once */\n\tprivate readonly dying = new Set<Entity>()\n\n\t/** Whether an entity is being killed right now: alive still, while its `death` hooks run, and past saving */\n\tisDying(entity: Entity): boolean {\n\t\treturn this.dying.has(entity)\n\t}\n\n\t/** What follows the `death` hooks: the entity is gone from the world, and it is told */\n\tprivate fall(entity: Entity, killer: Entity | undefined, attack: boolean, cause: DeathCause | undefined, death: Death): void {\n\t\tentity.setAlive(false)\n\t\tentity.health = 0\n\t\t// what it carried, for what asks it after (an `onKill`'s effects, B44)\n\t\tif (entity.buffs.length) (death as { carried?: readonly BuffInstance[] }).carried = entity.buffs.slice()\n\t\tentity.clearBuffs()\n\t\tentity.remove(dashing)\n\t\tthis.detach(entity)\n\t\t// what stays around, out of the world, until it is brought back: a fallen hero, where the heroes pack is on\n\t\tif (!this.world.hooks.has('fallenHero') || !this.world.hooks.run('fallenHero', { entity, killer, stays: false }).stays) this.dead.push(entity)\n\t\tthis.world.events.emit(entityDied, { entity, killer, attack, cause, how: death.how, reason: death.reason })\n\t\tthis.world.hooks.run('afterDeath', death)\n\t\t// a resource used up takes down what stood on it: there is nothing for it to stand on\n\t\tconst above = this.world.get(entity.get(deposit)?.under)\n\t\tif (above?.alive && !this.isDying(above)) this.kill(above, undefined, false, 'removed')\n\t}\n\n\tprivate detach(entity: Entity): void {\n\t\tthis.world.nav.removeAgent(entity.id)\n\t\tif (entity.isStructure) this.world.spatial.removeStatic(entity)\n\t\tif (entity.cell) {\n\t\t\tconst fp = footprintOf(entity.def)\n\t\t\tthis.world.grid.release(entity.cell.x, entity.cell.z, fp.w, fp.d, entity.id)\n\t\t\tthis.world.nav.removeObstacle(entity.id)\n\t\t}\n\t\t// what stood on a resource: the resource has its ground again, and is free to be built on\n\t\tconst under = this.world.get(entity.on)\n\t\tif (under?.get(deposit) && under.cell) {\n\t\t\tif (under.get(deposit)!.under === entity.id) under.get(deposit)!.under = undefined\n\t\t\tif (under.alive) {\n\t\t\t\tconst fp = footprintOf(under.def)\n\t\t\t\tthis.world.grid.occupy(under.cell.x, under.cell.z, fp.w, fp.d, under.id)\n\t\t\t}\n\t\t}\n\t}\n}\n\n/** A death, to those who see the dead: who killed it where they see the killer too (`SessionEvent` `death`) */\nexport const toldDeath = replicateEvent(entityDied, 'death', ({ entity, killer, attack, cause, how, reason }, view) => {\n\tif (!view.knows(entity)) return undefined\n\tconst seen = killer && killer !== entity && view.knows(killer) ? killer : undefined\n\treturn {\n\t\ttype: 'death',\n\t\tid: entity.id,\n\t\tfrom: seen && { x: seen.pos.x, z: seen.pos.z },\n\t\tkiller: seen?.id,\n\t\tkillerType: seen?.def.id,\n\t\tattack,\n\t\tdamageType: cause?.type,\n\t\tability: cause?.ability,\n\t\toverkill: cause?.overkill,\n\t\tcrit: cause?.crit,\n\t\thow,\n\t\t...(reason !== 'damage' && { reason }),\n\t\t...(cause?.tags?.length && { tags: [...cause.tags] })\n\t}\n})\n\n/** A hit, to those who see who took it: who dealt it where they see them too */\nexport const toldDamage = replicateEvent(damaged, 'damage', ({ target, source, amount, type, attack, crit, ability, tags }, view) => {\n\tif (!view.knows(target)) return undefined\n\tconst seen = source && view.knows(source) ? source : undefined\n\treturn {\n\t\ttype: 'damage',\n\t\tid: target.id,\n\t\tamount,\n\t\tdamageType: type,\n\t\tsource: seen?.id,\n\t\tsourceType: seen?.def.id,\n\t\tattack,\n\t\tcrit,\n\t\tability: seen ? ability : undefined,\n\t\ttags\n\t}\n})\n\n/** Healing, to those who see who was healed */\nexport const toldHeal = replicateEvent(healedEvent, 'heal', ({ target, source, amount }, view) =>\n\tview.knows(target) ? { type: 'heal', id: target.id, amount, source: source && view.knows(source) ? source.id : undefined } : undefined\n)\n\n/** A critical strike's number over who took it */\nexport const toldCrit = replicateEvent(damaged, 'crit', ({ target, amount, crit }, view) =>\n\tcrit && view.knows(target) ? { type: 'crit', id: target.id, amount: Math.round(amount) } : undefined\n)\n"],"mappings":"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"}

package/dist/log.d.ts

@@ -13,7 +13,11 @@
  * @beta
  */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-/** @beta */
+/**
+ * The levels of log entries from least to most important, in the order `Logger.says` ranks them
+ *
+ * @beta
+ */
 export declare const LOG_LEVELS: readonly LogLevel[];
 /**
  * One thing said. Plain data: it crosses a session, a worker and a file as it is
@@ -21,14 +25,17 @@ export declare const LOG_LEVELS: readonly LogLevel[];
  * @beta
  */
 export interface LogEntry {
+    /** How much the entry matters */
     level: LogLevel;
     /** What part said it: `server`, `game`, `assets`, a mod's own */
     category: string;
+    /** What was said, in words */
     message: string;
     /** What it is about, by name: an entity's id, a player, a file, an error (`errorFields`) */
     fields?: Record<string, unknown>;
     /** The game it was said in, and its tick, where it was said in one */
     game?: string;
+    /** The tick of the game it was said in, where it was said in a world */
     tick?: number;
     /** When, in milliseconds of the clock (`Date.now`). Never read by the simulation */
     time: number;
@@ -47,12 +54,17 @@ export type LogSink = (entry: LogEntry) => void;
 export type LogContext = () => Partial<Pick<LogEntry, 'game' | 'tick'>> & {
     fields?: Record<string, unknown>;
 };
-/** @beta */
+/**
+ * The options a `Logger` is made with
+ *
+ * @beta
+ */
 export interface LoggerOptions {
     /** The logger this one passes its entries up to. None for one that stands alone */
     parent?: Logger;
     /** The least an entry must matter to be said here: everything when left out */
     level?: LogLevel;
+    /** What the logger adds to each entry it passes on: the game, the tick and the fields */
     context?: LogContext;
 }
 /**
@@ -77,7 +89,11 @@ export declare function logLine(entry: LogEntry): string;
  * @beta
  */
 export declare const consoleSink: LogSink;
-/** @beta */
+/**
+ * A logger: it takes entries of a level and above and sends them to its sinks and its parent
+ *
+ * @beta
+ */
 export declare class Logger {
     /** The least an entry must matter to be said: what is under it is dropped here, and goes no further */
     level: LogLevel;
@@ -91,10 +107,15 @@ export declare class Logger {
     child(options?: Omit<LoggerOptions, 'parent'> | LogContext): Logger;
     /** Whether an entry of this level would be said: for not putting together what nobody will read */
     says(level: LogLevel): boolean;
+    /** Says an entry of the level, the category and the message, with its fields when given; dropped when the logger does not say that level */
     log(level: LogLevel, category: string, message: string, fields?: Record<string, unknown>): void;
+    /** Says a `debug` entry */
     debug(category: string, message: string, fields?: Record<string, unknown>): void;
+    /** Says an `info` entry */
     info(category: string, message: string, fields?: Record<string, unknown>): void;
+    /** Says a `warn` entry */
     warn(category: string, message: string, fields?: Record<string, unknown>): void;
+    /** Says an `error` entry */
     error(category: string, message: string, fields?: Record<string, unknown>): void;
     /**
      * Takes an entry made elsewhere (a world's, by the client that shows it; a server's, sent to a tool) as if it was
@@ -125,9 +146,11 @@ export declare const rootConsole: {
  * @beta
  */
 export interface LogRing {
+    /** The sink to give to a logger (`Logger.to`) to have the ring keep what it is sent */
     sink: LogSink;
     /** The entries kept, the oldest first */
     entries(): readonly LogEntry[];
+    /** Empties the ring of the entries it keeps */
     clear(): void;
     /** Calls back for each entry as it comes. Returns what stops it */
     onEntry(listener: LogSink): () => void;

package/dist/log.js

@@ -0,0 +1,192 @@
+//#region src/log.ts
+/**
+* The levels of log entries from least to most important, in the order `Logger.says` ranks them
+*
+* @beta
+*/
+var LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/**
+* An error as plain data, for an entry's fields: what it is called, what it says, and where it was thrown
+*
+* @beta
+*/
+function errorFields(error) {
+	if (error instanceof Error) return {
+		name: error.name,
+		message: error.message,
+		...error.stack && { stack: error.stack }
+	};
+	return {
+		name: "Error",
+		message: String(error)
+	};
+}
+/**
+* An entry as one line of text: `warn [server] tick 120 of td: a connection took in too slowly {bytes: 12}`
+*
+* @beta
+*/
+function logLine(entry) {
+	const where = entry.game !== void 0 ? ` ${entry.tick !== void 0 ? `tick ${entry.tick} of ` : ""}${entry.game}:` : "";
+	const fields = entry.fields && Object.keys(entry.fields).length ? ` ${JSON.stringify(entry.fields)}` : "";
+	return `${entry.level} [${entry.category}]${where} ${entry.message}${fields}`;
+}
+/**
+* Writes entries to the console, each by its level. An error among the fields is shown as the console shows errors
+*
+* @beta
+*/
+var consoleSink = (entry) => {
+	const { error, ...fields } = entry.fields ?? {};
+	const line = logLine({
+		...entry,
+		fields
+	});
+	const write = entry.level === "error" ? console.error : entry.level === "warn" ? console.warn : entry.level === "debug" ? console.debug : console.log;
+	const thrown = error && typeof error === "object" && "stack" in error ? error.stack : void 0;
+	if (thrown) write(line, `\n${thrown}`);
+	else write(line);
+};
+/**
+* A logger: it takes entries of a level and above and sends them to its sinks and its parent
+*
+* @beta
+*/
+var Logger = class Logger {
+	/** The least an entry must matter to be said: what is under it is dropped here, and goes no further */
+	level;
+	parent;
+	context;
+	sinks = /* @__PURE__ */ new Set();
+	constructor(options = {}) {
+		this.parent = options.parent;
+		this.level = options.level ?? "debug";
+		this.context = options.context;
+	}
+	/** Sends this logger's entries, and those of every logger under it, to a sink. Returns what stops it */
+	to(sink) {
+		this.sinks.add(sink);
+		return () => this.sinks.delete(sink);
+	}
+	/** A logger under this one: its entries carry what `context` adds, and are passed up here */
+	child(options = {}) {
+		return new Logger({
+			parent: this,
+			...typeof options === "function" ? { context: options } : options
+		});
+	}
+	/** Whether an entry of this level would be said: for not putting together what nobody will read */
+	says(level) {
+		return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(this.level);
+	}
+	/** Says an entry of the level, the category and the message, with its fields when given; dropped when the logger does not say that level */
+	log(level, category, message, fields) {
+		if (!this.says(level)) return;
+		this.pass({
+			level,
+			category,
+			message,
+			...fields && { fields },
+			time: Date.now()
+		});
+	}
+	/** Says a `debug` entry */
+	debug(category, message, fields) {
+		this.log("debug", category, message, fields);
+	}
+	/** Says an `info` entry */
+	info(category, message, fields) {
+		this.log("info", category, message, fields);
+	}
+	/** Says a `warn` entry */
+	warn(category, message, fields) {
+		this.log("warn", category, message, fields);
+	}
+	/** Says an `error` entry */
+	error(category, message, fields) {
+		this.log("error", category, message, fields);
+	}
+	/**
+	* Takes an entry made elsewhere (a world's, by the client that shows it; a server's, sent to a tool) as if it was
+	* said here: to this logger's sinks, and up. What it already says of its game and its tick is kept
+	*/
+	pass(entry) {
+		if (!this.says(entry.level)) return;
+		const added = this.context?.();
+		const full = added ? {
+			...entry,
+			...entry.game === void 0 && added.game !== void 0 && { game: added.game },
+			...entry.tick === void 0 && added.tick !== void 0 && { tick: added.tick },
+			...added.fields && { fields: {
+				...added.fields,
+				...entry.fields
+			} }
+		} : entry;
+		for (const sink of this.sinks) try {
+			sink(full);
+		} catch {
+			this.sinks.delete(sink);
+		}
+		this.parent?.pass(full);
+	}
+};
+/**
+* The logger everything is under when nothing else is said: a world's, a server's, the client's. It writes to the
+* console (`rootConsole.stop()` ends that, for a page or a server that keeps its log elsewhere), from `info` up
+*
+* @beta
+*/
+var rootLogger = new Logger({ level: "info" });
+/**
+* The root logger's writing to the console: stopped and started again
+*
+* @beta
+*/
+var rootConsole = (() => {
+	let stop = rootLogger.to(consoleSink);
+	return {
+		get on() {
+			return stop !== null;
+		},
+		stop() {
+			stop?.();
+			stop = null;
+		},
+		start() {
+			stop ??= rootLogger.to(consoleSink);
+		}
+	};
+})();
+/**
+* Keeps the last `size` entries (500 when left out) of whatever its sink is given
+*
+* @beta
+*/
+function createLogRing(size = 500) {
+	let kept = [];
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		sink(entry) {
+			kept.push(entry);
+			if (kept.length > size) kept = kept.slice(kept.length - size);
+			for (const listener of listeners) listener(entry);
+		},
+		entries: () => kept,
+		clear() {
+			kept = [];
+		},
+		onEntry(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+//#endregion
+export { LOG_LEVELS, Logger, consoleSink, createLogRing, errorFields, logLine, rootConsole, rootLogger };
+
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","names":[],"sources":["../src/log.ts"],"sourcesContent":["/**\n * The log: what the engine, a server, the client and a game say about what they do, as entries of plain data that go\n * to whoever asked for them (a sink). A world has its own (`world.log`), whose entries say which game and which tick\n * they are from; every logger passes its entries up to the one it was made under, so that a sink at the top\n * (`rootLogger.to`, or a server's own) sees all of them.\n *\n * The log says, and nothing else: it reads nothing of the simulation's chances, changes nothing in a world, and is\n * not kept in a save. Two runs of a game are the same whether anyone listens or not.\n */\n\n/**\n * How much an entry matters: `debug` for whoever looks closely, `error` for what went wrong\n *\n * @beta\n */\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error'\n\n/**\n * The levels of log entries from least to most important, in the order `Logger.says` ranks them\n *\n * @beta\n */\nexport const LOG_LEVELS: readonly LogLevel[] = ['debug', 'info', 'warn', 'error']\n\n/**\n * One thing said. Plain data: it crosses a session, a worker and a file as it is\n *\n * @beta\n */\nexport interface LogEntry {\n\t/** How much the entry matters */\n\tlevel: LogLevel\n\t/** What part said it: `server`, `game`, `assets`, a mod's own */\n\tcategory: string\n\t/** What was said, in words */\n\tmessage: string\n\t/** What it is about, by name: an entity's id, a player, a file, an error (`errorFields`) */\n\tfields?: Record<string, unknown>\n\t/** The game it was said in, and its tick, where it was said in one */\n\tgame?: string\n\t/** The tick of the game it was said in, where it was said in a world */\n\ttick?: number\n\t/** When, in milliseconds of the clock (`Date.now`). Never read by the simulation */\n\ttime: number\n}\n\n/**\n * Where entries go: the console, a file, a panel, a service\n *\n * @beta\n */\nexport type LogSink = (entry: LogEntry) => void\n\n/**\n * What a logger adds to each of its entries: the game and the tick of a world, the fields of a part\n *\n * @beta\n */\nexport type LogContext = () => Partial<Pick<LogEntry, 'game' | 'tick'>> & { fields?: Record<string, unknown> }\n\n/**\n * The options a `Logger` is made with\n *\n * @beta\n */\nexport interface LoggerOptions {\n\t/** The logger this one passes its entries up to. None for one that stands alone */\n\tparent?: Logger\n\t/** The least an entry must matter to be said here: everything when left out */\n\tlevel?: LogLevel\n\t/** What the logger adds to each entry it passes on: the game, the tick and the fields */\n\tcontext?: LogContext\n}\n\n/**\n * An error as plain data, for an entry's fields: what it is called, what it says, and where it was thrown\n *\n * @beta\n */\nexport function errorFields(error: unknown): { name: string; message: string; stack?: string } {\n\tif (error instanceof Error) return { name: error.name, message: error.message, ...(error.stack && { stack: error.stack }) }\n\treturn { name: 'Error', message: String(error) }\n}\n\n/**\n * An entry as one line of text: `warn [server] tick 120 of td: a connection took in too slowly {bytes: 12}`\n *\n * @beta\n */\nexport function logLine(entry: LogEntry): string {\n\tconst where = entry.game !== undefined ? ` ${entry.tick !== undefined ? `tick ${entry.tick} of ` : ''}${entry.game}:` : ''\n\tconst fields = entry.fields && Object.keys(entry.fields).length ? ` ${JSON.stringify(entry.fields)}` : ''\n\treturn `${entry.level} [${entry.category}]${where} ${entry.message}${fields}`\n}\n\n/**\n * Writes entries to the console, each by its level. An error among the fields is shown as the console shows errors\n *\n * @beta\n */\nexport const consoleSink: LogSink = (entry) => {\n\tconst { error, ...fields } = entry.fields ?? {}\n\tconst line = logLine({ ...entry, fields })\n\tconst write =\n\t\tentry.level === 'error' ? console.error : entry.level === 'warn' ? console.warn : entry.level === 'debug' ? console.debug : console.log\n\tconst thrown = error && typeof error === 'object' && 'stack' in error ? (error as { stack?: string }).stack : undefined\n\tif (thrown) write(line, `\\n${thrown}`)\n\telse write(line)\n}\n\n/**\n * A logger: it takes entries of a level and above and sends them to its sinks and its parent\n *\n * @beta\n */\nexport class Logger {\n\t/** The least an entry must matter to be said: what is under it is dropped here, and goes no further */\n\tlevel: LogLevel\n\tprivate readonly parent?: Logger\n\tprivate readonly context?: LogContext\n\tprivate readonly sinks = new Set<LogSink>()\n\n\tconstructor(options: LoggerOptions = {}) {\n\t\tthis.parent = options.parent\n\t\tthis.level = options.level ?? 'debug'\n\t\tthis.context = options.context\n\t}\n\n\t/** Sends this logger's entries, and those of every logger under it, to a sink. Returns what stops it */\n\tto(sink: LogSink): () => void {\n\t\tthis.sinks.add(sink)\n\t\treturn () => this.sinks.delete(sink)\n\t}\n\n\t/** A logger under this one: its entries carry what `context` adds, and are passed up here */\n\tchild(options: Omit<LoggerOptions, 'parent'> | LogContext = {}): Logger {\n\t\treturn new Logger({ parent: this, ...(typeof options === 'function' ? { context: options } : options) })\n\t}\n\n\t/** Whether an entry of this level would be said: for not putting together what nobody will read */\n\tsays(level: LogLevel): boolean {\n\t\treturn LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(this.level)\n\t}\n\n\t/** Says an entry of the level, the category and the message, with its fields when given; dropped when the logger does not say that level */\n\tlog(level: LogLevel, category: string, message: string, fields?: Record<string, unknown>): void {\n\t\tif (!this.says(level)) return\n\t\tthis.pass({ level, category, message, ...(fields && { fields }), time: Date.now() })\n\t}\n\n\t/** Says a `debug` entry */\n\tdebug(category: string, message: string, fields?: Record<string, unknown>): void {\n\t\tthis.log('debug', category, message, fields)\n\t}\n\t/** Says an `info` entry */\n\tinfo(category: string, message: string, fields?: Record<string, unknown>): void {\n\t\tthis.log('info', category, message, fields)\n\t}\n\t/** Says a `warn` entry */\n\twarn(category: string, message: string, fields?: Record<string, unknown>): void {\n\t\tthis.log('warn', category, message, fields)\n\t}\n\t/** Says an `error` entry */\n\terror(category: string, message: string, fields?: Record<string, unknown>): void {\n\t\tthis.log('error', category, message, fields)\n\t}\n\n\t/**\n\t * Takes an entry made elsewhere (a world's, by the client that shows it; a server's, sent to a tool) as if it was\n\t * said here: to this logger's sinks, and up. What it already says of its game and its tick is kept\n\t */\n\tpass(entry: LogEntry): void {\n\t\tif (!this.says(entry.level)) return\n\t\tconst added = this.context?.()\n\t\tconst full: LogEntry = added\n\t\t\t? {\n\t\t\t\t\t...entry,\n\t\t\t\t\t...(entry.game === undefined && added.game !== undefined && { game: added.game }),\n\t\t\t\t\t...(entry.tick === undefined && added.tick !== undefined && { tick: added.tick }),\n\t\t\t\t\t...(added.fields && { fields: { ...added.fields, ...entry.fields } })\n\t\t\t\t}\n\t\t\t: entry\n\t\t// a sink that throws is not a reason for what was being done to stop: the log is never the cause of a failure\n\t\tfor (const sink of this.sinks) {\n\t\t\ttry {\n\t\t\t\tsink(full)\n\t\t\t} catch {\n\t\t\t\tthis.sinks.delete(sink)\n\t\t\t}\n\t\t}\n\t\tthis.parent?.pass(full)\n\t}\n}\n\n/**\n * The logger everything is under when nothing else is said: a world's, a server's, the client's. It writes to the\n * console (`rootConsole.stop()` ends that, for a page or a server that keeps its log elsewhere), from `info` up\n *\n * @beta\n */\nexport const rootLogger = new Logger({ level: 'info' })\n\n/**\n * The root logger's writing to the console: stopped and started again\n *\n * @beta\n */\nexport const rootConsole = (() => {\n\tlet stop: (() => void) | null = rootLogger.to(consoleSink)\n\treturn {\n\t\tget on(): boolean {\n\t\t\treturn stop !== null\n\t\t},\n\t\tstop(): void {\n\t\t\tstop?.()\n\t\t\tstop = null\n\t\t},\n\t\tstart(): void {\n\t\t\tstop ??= rootLogger.to(consoleSink)\n\t\t}\n\t}\n})()\n\n/**\n * The last entries, kept: what a console panel shows, and what goes with a report of a crash\n *\n * @beta\n */\nexport interface LogRing {\n\t/** The sink to give to a logger (`Logger.to`) to have the ring keep what it is sent */\n\tsink: LogSink\n\t/** The entries kept, the oldest first */\n\tentries(): readonly LogEntry[]\n\t/** Empties the ring of the entries it keeps */\n\tclear(): void\n\t/** Calls back for each entry as it comes. Returns what stops it */\n\tonEntry(listener: LogSink): () => void\n}\n\n/**\n * Keeps the last `size` entries (500 when left out) of whatever its sink is given\n *\n * @beta\n */\nexport function createLogRing(size = 500): LogRing {\n\tlet kept: LogEntry[] = []\n\tconst listeners = new Set<LogSink>()\n\treturn {\n\t\tsink(entry) {\n\t\t\tkept.push(entry)\n\t\t\tif (kept.length > size) kept = kept.slice(kept.length - size)\n\t\t\tfor (const listener of listeners) listener(entry)\n\t\t},\n\t\tentries: () => kept,\n\t\tclear() {\n\t\t\tkept = []\n\t\t},\n\t\tonEntry(listener) {\n\t\t\tlisteners.add(listener)\n\t\t\treturn () => listeners.delete(listener)\n\t\t}\n\t}\n}\n"],"mappings":"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"}

package/dist/manaBurn.d.ts

@@ -1,4 +1,4 @@
-import { type DamageType } from './defs';
+import type { DamageType } from './defs';
 import type { Entity } from './entity';
 import type { GamePack } from './packs/pack';
 import type { World } from './world';
@@ -36,4 +36,4 @@ export declare function burnMana(world: World, target: Entity, amount: number, s
  *
  * @beta
  */
-export declare function withManaBurn(): GamePack;
+export declare function manaBurnPack(): GamePack;