incanto 0.48.0 → 0.50.0

package/dist/{register-BSXV8T9F.js → register-uvaZj1KX.js}

@@ -1,4 +1,4 @@
-import { E as Signal, _ as InputMap, b as behaviorSchema, f as Node, g as resolveOrderGroups, m as ORDER_GROUP_BASE, v as diagnose } from "./loader-r49nDwB4.js";
+import { E as Signal, _ as InputMap, b as behaviorSchema, f as Node, g as resolveOrderGroups, m as ORDER_GROUP_BASE, v as diagnose } from "./loader-DwazzlQb.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { l as registerNode } from "./registry-IyWCGe4q.js";
@@ -2558,28 +2558,73 @@ var UiText = class extends HudWidgetBase {
 	static props = {
 		...HudWidgetBase.props,
 		text: { default: "" },
+		format: { default: "" },
 		size: { default: 16 },
 		color: { default: "#ffffff" },
 		shadow: { default: true }
 	};
 	text = "";
+	/**
+	* A template with a `{}` slot that `setText` fills — `"Gems {} / 8"`.
+	*
+	* Empty (the default) means `setText` replaces the whole line. Resolved at
+	* PAINT like `text`, so `"@t:hud.gems"` works and changing locale re-reads
+	* it: the value lives here, the words live in the strings table.
+	*/
+	format = "";
 	size = 16;
 	color = "#ffffff";
 	shadow = true;
 	last = "\0";
+	/** null until something has actually set a value — see `shown`. */
+	slot = null;
+	/**
+	* Put a signal's value on screen — `scoreChanged → setText`.
+	*
+	* A `connections[]` handler must be a METHOD and `text` is a property, so the
+	* one wire every game needs (score to screen) could not be declared: every
+	* HUD began with a behavior whose whole job was one assignment.
+	*/
+	setText(value) {
+		this.slot = String(value ?? "");
+		if (!this.format) this.text = this.slot;
+	}
+	/**
+	* What it actually paints, after the template and the locale.
+	*
+	* Before the first value arrives, a formatted widget shows `text` — its
+	* authored opening line. Filling the slot with nothing instead would put
+	* `"Gems  / 8"` on screen for every game's first frame, and a score line
+	* that starts blank looks broken rather than empty.
+	*/
+	get shown() {
+		if (this.format && this.slot !== null) return this._t(this.format).replace("{}", this.slot);
+		return this._t(this.text);
+	}
 	_build() {
 		const el = document.createElement("div");
 		el.style.cssText = `font-size:${this.size}px;color:${this.color};${this.shadow ? "text-shadow:0 1px 3px rgba(0,0,0,.7);" : ""}white-space:pre;`;
 		return el;
 	}
 	_sync() {
-		const shown = this._t(this.text);
+		const shown = this.shown;
 		if (shown !== this.last && this._element) {
 			this.last = shown;
 			this._element.textContent = shown;
 		}
 	}
 };
+/**
+* A bar fed the wrong argument shows a plausible wrong number forever.
+*
+* The trap is one signal away: `Health.damaged` is `(amount, current)`, so
+* wiring it to `setValue` paints the DAMAGE as the health and looks like a
+* working health bar. Say which signal has the shape a bar wants.
+*/
+function requireNumber(value, node, method) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw new IncantoError("PROP_TYPE_MISMATCH", `UiBar '${node.getPath()}'.${method} needs a number, got ${JSON.stringify(value)}. Check what the wired signal passes FIRST — 'damaged' is (amount, current), 'healthChanged' is (current, max), which is the shape a bar wants.`);
+}
 /** A labeled progress bar (health, stamina, reload, boss HP). */
 var UiBar = class extends HudWidgetBase {
 	static typeName = "UiBar";
@@ -2612,6 +2657,21 @@ var UiBar = class extends HudWidgetBase {
 	get ratio() {
 		return this.max > 0 ? Math.min(1, Math.max(0, this.value / this.max)) : 0;
 	}
+	/**
+	* Drive the bar from a signal — `healthChanged → setValue`.
+	*
+	* Takes the max as a second argument because that is the shape the signal
+	* already has, so a bar whose ceiling moves (a max-HP upgrade) needs no
+	* second wire.
+	*/
+	setValue(value, max) {
+		this.value = requireNumber(value, this, "setValue");
+		if (max !== void 0) this.max = requireNumber(max, this, "setValue");
+	}
+	/** Move the ceiling on its own, leaving the fill where it is. */
+	setMax(max) {
+		this.max = requireNumber(max, this, "setMax");
+	}
 	_build() {
 		const wrap = document.createElement("div");
 		wrap.style.cssText = "display:flex;align-items:center;gap:6px;";

package/dist/{replay-CAphXMyM.d.ts → replay-DYdy1wb0.d.ts}

@@ -62,7 +62,11 @@ interface ReplayJson {
   /** File-format marker for forward compatibility. */
   replay: 1;
   /** Tick timestamps (ms) exactly as the loop delivered them. */
-  ticks: number[];
+  /**
+  * One entry per recorded FRAME: the `nowMs` it was ticked with, or `null` for
+  * a fixed `step()`. Older recordings are all numbers and still replay.
+  */
+  ticks: Array<number | null>;
   events: ReplayEvent[];
 }
 interface Recorder {

package/dist/{replay-DilbZgQI.js → replay-j-m6lJ4W.js}

@@ -1,4 +1,4 @@
-import { M as translationKey } from "./register-BSXV8T9F.js";
+import { M as translationKey } from "./register-uvaZj1KX.js";
 //#region src/core/audit.ts
 const ANIMATED_TYPES = new Set([
 	"Particles2D",
@@ -109,13 +109,25 @@ function auditStrings(scene) {
 }
 //#endregion
 //#region src/core/replay.ts
+/**
+* Every entry point that can change what the game is being told, because one
+* left out is a replay that reproduces a character standing still.
+*
+* `setActionVector` was the omission that mattered: the playtest driver moves
+* with it and presses buttons with `pressAction`, so its replays recorded all
+* the jumping and none of the walking, and played back as a character hopping
+* on the spot where the real run had walked off a ledge.
+*/
 const RECORDED_METHODS = [
 	"handleKey",
 	"handleMouseButton",
 	"handlePointerMove",
 	"handleWheel",
 	"pressAction",
-	"releaseAction"
+	"releaseAction",
+	"setActionVector",
+	"setPointerPosition",
+	"clearInjected"
 ];
 /**
 * Tap the engine's input entry points and tick clock. Recording starts at
@@ -139,17 +151,23 @@ function startRecording(engine) {
 		};
 	}
 	const originalTick = engine.tick.bind(engine);
+	const originalStep = engine.step.bind(engine);
 	const engineAny = engine;
 	engineAny.tick = (nowMs) => {
 		ticks.push(nowMs);
 		originalTick(nowMs);
 	};
+	engineAny.step = () => {
+		ticks.push(null);
+		originalStep();
+	};
 	let stopped = false;
 	return { stop() {
 		if (!stopped) {
 			stopped = true;
 			for (const [name, fn] of originals) input[name] = fn;
 			engineAny.tick = originalTick;
+			engineAny.step = originalStep;
 		}
 		return {
 			replay: 1,
@@ -173,7 +191,9 @@ function replay(engine, recording, opts) {
 			if (typeof fn === "function") fn.apply(engine.input, args);
 			cursor += 1;
 		}
-		engine.tick(recording.ticks[i]);
+		const at = recording.ticks[i];
+		if (at === null) engine.step();
+		else engine.tick(at);
 		opts?.onTick?.(i);
 	}
 }

package/dist/sprite-animation-CMr6f1K2.d.ts

@@ -0,0 +1,44 @@
+//#region src/core/sprite-animation.d.ts
+interface AnimationDef {
+  /**
+  * Two numbers = inclusive [start, end] frame RANGE.
+  * Any other length = explicit frame list.
+  */
+  frames: number[];
+  fps: number;
+  loop?: boolean;
+}
+/**
+* A clip, or the NAME of another clip in the same map.
+*
+* The alias exists because the character a game is built from and the character
+* a controller describes are not the same vocabulary.
+* `CharacterController2D`/`3D` emit `idle`/`run`/`jump`/`fall`/`wallSlide`/
+* `dash`; the sheets in the engine's own catalog carry `idle`/`move`/`attack`,
+* and no sheet anywhere ships a `fall`. So the documented one-line wiring —
+* `movementStateChanged → play` — asked for clips that do not exist, and the
+* hard error was correct and useless: there is nothing to rename it TO.
+*
+* An alias is the missing half. `"fall": "idle"` says what to show while
+* falling, in the scene, next to everything else about that character.
+*/
+type AnimationEntry = AnimationDef | string;
+/**
+* Follow aliases to the clip that actually plays.
+*
+* Chains are allowed (`fall → jump → idle`) because they are how a fallback
+* ladder reads, and a cycle is a hard error rather than a hang.
+*/
+declare function resolveAnimation(animations: Record<string, AnimationEntry>, name: string, owner: string): {
+  name: string;
+  def: AnimationDef;
+};
+/**
+* `[start, end]` is a RANGE; anything else is an explicit list.
+*
+* Two ascending numbers are overwhelmingly a range in every sheet format, and
+* a two-frame flip-book is spelled `[3, 3, 4, 4]` or a descending pair.
+*/
+declare function resolveFrames(frames: number[], name: string): number[];
+//#endregion
+export { resolveFrames as i, AnimationEntry as n, resolveAnimation as r, AnimationDef as t };

package/dist/{particle-sim-Bw7hB93B.js → sprite-animation-D_p28jwU.js}

@@ -1,3 +1,4 @@
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as jsonEquals } from "./json-BLk7H2Qa.js";
 //#region src/core/particle-presets.ts
 const PARTICLE_PRESETS = {
@@ -264,4 +265,65 @@ var ParticleSim = class {
 	}
 };
 //#endregion
-export { applyParticlePreset as i, PARTICLE_PRESETS as n, PARTICLE_PRESET_NAMES as r, ParticleSim as t };
+//#region src/core/sprite-animation.ts
+/**
+* The animation MAP a spritesheet node is driven by — shared by 2D and 3D.
+*
+* Core, not an adapter: no three.js, and the two sprite nodes had grown
+* byte-identical copies of the frame reader.
+*/
+/**
+* Follow aliases to the clip that actually plays.
+*
+* Chains are allowed (`fall → jump → idle`) because they are how a fallback
+* ladder reads, and a cycle is a hard error rather than a hang.
+*/
+function resolveAnimation(animations, name, owner) {
+	const seen = [];
+	let key = name;
+	for (;;) {
+		const entry = animations[key];
+		if (entry === void 0) {
+			const via = seen.length > 0 ? ` (via ${seen.join(" → ")})` : "";
+			throw new IncantoError("UNKNOWN_ANIMATION", `No animation '${key}' on '${owner}'${via}. Available: [${Object.keys(animations).join(", ")}].`);
+		}
+		if (typeof entry !== "string") return {
+			name: key,
+			def: entry
+		};
+		if (seen.includes(key)) throw new IncantoError("UNKNOWN_ANIMATION", `Animation aliases on '${owner}' point in a circle: ${[...seen, key].join(" → ")}.`);
+		seen.push(key);
+		key = entry;
+	}
+}
+/**
+* Every alias resolves — checked once, at ready, rather than on the frame the
+* character first jumps.
+*
+* A cosmetic map that only fails the moment a state is first entered is the
+* shape of bug that reaches players: the game loads, plays, and dies on a
+* ledge twenty minutes in.
+*/
+function validateAnimationAliases(animations, owner) {
+	for (const [name, entry] of Object.entries(animations)) if (typeof entry === "string") resolveAnimation(animations, name, owner);
+}
+/**
+* `[start, end]` is a RANGE; anything else is an explicit list.
+*
+* Two ascending numbers are overwhelmingly a range in every sheet format, and
+* a two-frame flip-book is spelled `[3, 3, 4, 4]` or a descending pair.
+*/
+function resolveFrames(frames, name) {
+	if (!Array.isArray(frames) || frames.length === 0) throw new IncantoError("BAD_FORMAT", `Animation '${name}': "frames" must be a non-empty array.`);
+	if (frames.length === 2) {
+		const [start, end] = frames;
+		if (end >= start) {
+			const out = [];
+			for (let f = start; f <= end; f++) out.push(f);
+			return out;
+		}
+	}
+	return [...frames];
+}
+//#endregion
+export { PARTICLE_PRESETS as a, ParticleSim as i, resolveFrames as n, PARTICLE_PRESET_NAMES as o, validateAnimationAliases as r, applyParticlePreset as s, resolveAnimation as t };

package/dist/{src-Bl1Kire1.js → src-B3HrKuAi.js}

@@ -161,6 +161,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.48.0";
+const VERSION = "0.50.0";
 //#endregion
 export { findPath as a, preloadUrls as i, newUid as n, gridFromRows as o, assetUrls as r, VERSION as t };