incanto 0.52.0 → 0.54.0

package/dist/{register-Trx7WHnD.js → register-en63AEZO.js}

@@ -1,9 +1,9 @@
-import { b as effectiveOrder, f as Node } from "./loader-B-Gft32x.js";
-import { t as registerCoreNodes } from "./register-DVwlnZAZ.js";
+import { C as diagnose, b as effectiveOrder, f as Node } from "./loader-BTkHYrQn.js";
+import { t as registerCoreNodes } from "./register-p48lHE2o.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-C7u42TID.js";
-import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-D_p28jwU.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-7qvUxF6Z.js";
 import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, Object3D, PlaneGeometry } from "three";
 //#region src/2d/physics/collider-validate.ts
 /**
@@ -305,6 +305,59 @@ var Joint2D = class extends Node2D {
 	}
 };
 //#endregion
+//#region src/2d/sheet-grid.ts
+/**
+* Does this spritesheet's grid actually fit the image?
+*
+* `frameWidth`/`frameHeight` are taken on trust, and the frame math floors the
+* division — so a frame size that does not divide the sheet slices every row a
+* little further off, and an animation naming a frame past the end of the grid
+* reads whatever texels are there. Both draw WRONG ART with no error anywhere,
+* which is the one symptom an author cannot tell apart from having picked the
+* wrong sheet in the first place.
+*
+* Pure arithmetic on numbers that are known the moment the image loads, so it
+* costs nothing and it is exact.
+*/
+/**
+* Frame sizes that divide `total` cleanly, biggest first.
+*
+* Bounded to grids of 2–32 cells so the suggestion is a frame size someone
+* might actually have meant, not every factor of the number.
+*/
+function divisors(total) {
+	const out = [];
+	for (let cells = 2; cells <= 32; cells++) if (total % cells === 0) out.push(total / cells);
+	return out.sort((a, b) => b - a).slice(0, 6);
+}
+/**
+* The problem with this grid, or null when there is none.
+*
+* `highestFrame` is the largest frame index the scene asks for, when it is
+* known — an animation range that runs off the end is the other half of the
+* same mistake.
+*/
+function checkSheetGrid(key, frameWidth, frameHeight, imageWidth, imageHeight, highestFrame) {
+	if (!imageWidth || !imageHeight || !frameWidth || !frameHeight) return null;
+	if (imageWidth % frameWidth !== 0 || imageHeight % frameHeight !== 0) {
+		const parts = [];
+		if (imageWidth % frameWidth !== 0) {
+			const fits = divisors(imageWidth);
+			parts.push(`${imageWidth} px wide is not a whole number of ${frameWidth} px frames` + (fits.length > 0 ? ` (${fits.join(", ")} would divide it)` : ""));
+		}
+		if (imageHeight % frameHeight !== 0) {
+			const fits = divisors(imageHeight);
+			parts.push(`${imageHeight} px tall is not a whole number of ${frameHeight} px frames` + (fits.length > 0 ? ` (${fits.join(", ")} would divide it)` : ""));
+		}
+		return `[incanto] spritesheet '${key}' does not fit its frame size: ${parts.join("; ")}. Every row after the first is cut off centre.`;
+	}
+	if (highestFrame !== void 0) {
+		const frames = imageWidth / frameWidth * (imageHeight / frameHeight);
+		if (highestFrame >= frames) return `[incanto] spritesheet '${key}' has ${frames} frames (0–${frames - 1}), and an animation asks for frame ${highestFrame}. Those frames draw whatever is at the wrong end of the sheet.`;
+	}
+	return null;
+}
+//#endregion
 //#region src/2d/nodes/sprite-2d.ts
 /** Shared unit quad — sprites are sized via the quad's scale, never THREE.Sprite. */
 const UNIT_PLANE$2 = new PlaneGeometry(1, 1);
@@ -452,6 +505,30 @@ var AnimatedSprite2D = class extends Sprite2D {
 		}
 		this.currentFrame = this.frameList[this.frameIndex] ?? 0;
 	}
+	/** Sheets already reported, so a bad grid says so ONCE, not every frame. */
+	gridChecked = "";
+	/**
+	* Tell the author their grid does not fit, the first time it is drawn.
+	*
+	* Both halves of this were silent: a frame size that does not divide the
+	* sheet slices every row further off centre, and an animation naming a frame
+	* past the end of the grid draws whatever is at the wrong end of the image.
+	*/
+	checkGrid(ref, frameWidth, frameHeight, width, height) {
+		if (this.gridChecked === ref) return;
+		this.gridChecked = ref;
+		let highest = 0;
+		for (const [name, entry] of Object.entries(this.animations)) {
+			if (typeof entry === "string") continue;
+			try {
+				for (const frame of resolveFrames(entry.frames, name)) if (frame > highest) highest = frame;
+			} catch {
+				return;
+			}
+		}
+		const problem = checkSheetGrid(ref, frameWidth, frameHeight, width, height, highest);
+		if (problem) diagnose(this.tree?.engine ?? null, "error", problem);
+	}
 	resolveTexture(assets) {
 		if (!this.sheet || !assets) return null;
 		const info = assets.getSheet(this.sheet);
@@ -463,6 +540,7 @@ var AnimatedSprite2D = class extends Sprite2D {
 		const tex = this.ownTexture;
 		const image = info.texture.image;
 		if (!image?.width || !image.height) return null;
+		this.checkGrid(this.sheet, info.frameWidth, info.frameHeight, image.width, image.height);
 		const cols = Math.max(1, Math.floor(image.width / info.frameWidth));
 		const col = this.currentFrame % cols;
 		const row = Math.floor(this.currentFrame / cols);
@@ -871,6 +949,8 @@ var Particles2D = class Particles2D extends Node2D {
 			options: ["custom", ...PARTICLE_PRESET_NAMES]
 		},
 		emitting: { default: true },
+		/** Particles keep the place they were born instead of following the node. */
+		worldSpace: { default: false },
 		rate: { default: 40 },
 		burst: { default: 0 },
 		lifetime: { default: [.6, 1.2] },
@@ -895,6 +975,18 @@ var Particles2D = class Particles2D extends Node2D {
 	};
 	preset = "custom";
 	emitting = true;
+	/**
+	* Where a particle LIVES once it is born.
+	*
+	* `false` (default) — the emitter's local space: the plume moves with the
+	* node, which is what a torch on a moving platform wants.
+	*
+	* `true` — the world: a particle keeps the place it was born, so dust is left
+	* BEHIND a running player instead of glued to it, and moving a one-shot to
+	* the next explosion (the documented `p.position = …; p.replay()` recipe)
+	* stops dragging the previous one across the level.
+	*/
+	worldSpace = false;
 	rate = 40;
 	burst = 0;
 	lifetime = [.6, 1.2];
@@ -954,11 +1046,38 @@ var Particles2D = class Particles2D extends Node2D {
 		}
 		return this.sim;
 	}
+	/** Particles alive this frame — an emitter that is running, told from one
+	*  that is not. `framing()` says where it IS; this says whether it is going. */
+	get aliveCount() {
+		return this.sim?.count ?? 0;
+	}
+	/** A snapshot of the live particles — positions are in whichever space
+	*  `worldSpace` selects, relative to the emitter. */
+	particles() {
+		const out = [];
+		this.sim?.forEach((p) => {
+			out.push({ ...p });
+		});
+		return out;
+	}
+	/** The emitter's world position last frame, for world-space counter-motion. */
+	lastWorld = null;
+	/** Last frame's `emitting`, so turning one ON is a reportable event. */
+	wasEmitting = false;
 	update(dt) {
 		const sim = this._ensureSim();
-		if (this.burst > 0 && !this.bursted) {
+		this.holdWorldSpace(sim);
+		sim.setRate(this.emitting ? this.rate : 0);
+		if (this.burst > 0 && !this.bursted && (this.emitting || this.armedByReplay)) {
 			this.bursted = true;
+			this.armedByReplay = false;
 			sim.burst(this.burst);
+			this.report("burst", this.burst);
+		}
+		const on = this.emitting && this.rate > 0;
+		if (on !== this.wasEmitting) {
+			this.wasEmitting = on;
+			if (on) this.report("emit", this.rate);
 		}
 		sim.update(dt);
 		if ((!this.emitting || this.rate === 0) && this.bursted && sim.done && !this.finishedEmitted) {
@@ -966,11 +1085,51 @@ var Particles2D = class Particles2D extends Node2D {
 			this.emit("finished");
 		}
 	}
+	/**
+	* Undo the emitter's own motion on everything already alive.
+	*
+	* Ancestor-summed like the physics helpers, so it follows a moving PARENT
+	* (dust under a player) as well as the node's own position.
+	*/
+	holdWorldSpace(sim) {
+		if (!this.worldSpace) {
+			this.lastWorld = null;
+			return;
+		}
+		let x = 0;
+		let y = 0;
+		const z = 0;
+		for (let n = this; n; n = n.parent) if (n instanceof Node2D) {
+			x += n.position[0] ?? 0;
+			y += n.position[1] ?? 0;
+		}
+		const prev = this.lastWorld;
+		if (prev) sim.translateAll(prev[0] - x, prev[1] - y, prev[2] - z);
+		this.lastWorld = [
+			x,
+			y,
+			z
+		];
+	}
+	/** Tell the engine an effect fired — the visual half of the audio record. */
+	report(kind, amount) {
+		const engine = this.tree?.engine;
+		engine?.effects.record({
+			kind,
+			name: this.preset,
+			from: this.getPath(),
+			amount,
+			at: engine.time
+		});
+	}
 	/** Restart a one-shot (re-burst + allow finished to fire again). */
 	replay() {
 		this.bursted = false;
 		this.finishedEmitted = false;
+		this.armedByReplay = true;
 	}
+	/** `replay()` asked for this burst, so `emitting: false` does not hold it. */
+	armedByReplay = false;
 	mesh = null;
 	/** Parsed `paletteColors`, reused; rebuilt only when the hex list changes. */
 	paletteCache = [];