incanto 0.69.0 → 0.71.0

package/dist/env.d.ts

@@ -1,4 +1,4 @@
-import { a as Rng, i as SceneJson, n as NodeJson, s as JsonObject } from "./schema-B6ugCV1Q.js";
+import { a as SceneJson, r as NodeJson, s as JsonObject, t as Rng } from "./rng-Bb-IutXB.js";
 
 //#region src/env/arena.d.ts
 /** Valid `generateArena` themes — drives the catalog options AND validation. */

package/dist/env.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { t as Rng } from "./rng-DP-SR7eg.js";
-import { t as createNoise2D } from "./noise-CGUMx44x.js";
-import { t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
+import { t as Rng } from "./rng-CDOMybym.js";
+import { t as createNoise2D } from "./noise-D3nPpmFg.js";
+import { t as buildHeightmap } from "./heightmap-BYgD5Edk.js";
 //#region src/env/round.ts
 /** 2-decimal rounding — keeps generated JSON readable without hurting determinism. */
 function round2(value) {
@@ -147,6 +147,7 @@ function rock(index, x, z, rng, sizeRange, color) {
 				round2(radius * squash * .6),
 				z
 			],
+			snapToGround: false,
 			rotation: [
 				0,
 				rng.int(0, 359),
@@ -1400,6 +1401,7 @@ function generateClouds(opts) {
 	return {
 		name: "Clouds",
 		type: "Node3D",
+		props: { snapToGround: false },
 		children
 	};
 }

package/dist/{environment-presets-BO-7XoFV.js → environment-presets-99BzP_L-.js}

@@ -1,13 +1,13 @@
-import { k as diagnose } from "./loader-DZE7B07H.js";
-import { L as translateOn, t as registerCoreNodes } from "./register-mmfugpaQ.js";
+import { Y as diagnose } from "./save-slots-Bvuh2p_r.js";
+import { M as translateOn, t as registerCoreNodes } from "./register-DuVdzxbq.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-CF70EArN.js";
-import { t as createNoise2D } from "./noise-CGUMx44x.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-CY-mrr1L.js";
-import { B as rejectScale, G as StaticBody3D, H as CharacterBody3D, I as worldPosition, K as Node3D, L as Water3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, X as colliderFootDrop, w as tolerateUnknownAction, z as WaterCutout3D } from "./gameplay-D1KixWK8.js";
+import { t as Rng } from "./rng-CDOMybym.js";
+import { c as getNodeSchema, h as didYouMean, p as registerNode } from "./touch-BnCyPA0G.js";
+import { t as createNoise2D } from "./noise-D3nPpmFg.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimations, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CqR2o3SA.js";
+import { B as rejectScale, D as effectRng, G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, Q as worldPosition, T as tolerateUnknownAction, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, X as colliderFootDrop, z as WaterCutout3D } from "./gameplay-CNULJvwh.js";
 import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
-import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
+import { n as splatWeights, t as buildHeightmap } from "./heightmap-BYgD5Edk.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
 //#region src/3d/textures.ts
@@ -141,7 +141,7 @@ var TextureCache3D = class {
 		return this.entries.size;
 	}
 	dispose() {
-		for (const entry of this.entries.values()) entry.texture.dispose();
+		for (const entry of this.entries.values()) entry.texture?.dispose();
 		this.entries.clear();
 	}
 };
@@ -716,7 +716,7 @@ var InstancedMesh3D = class extends Node3D {
 			for (let i = 0; i < this._transforms.length; i++) {
 				const row = this._transforms[i];
 				posScratch.set(row[0] ?? 0, row[1] ?? 0, row[2] ?? 0);
-				quatScratch$2.setFromAxisAngle(UP$1, (row[3] ?? 0) * Math.PI / 180);
+				quatScratch$2.setFromAxisAngle(UP$2, (row[3] ?? 0) * Math.PI / 180);
 				const s = row[4] ?? 1;
 				scaleScratch$3.set(s, s, s);
 				matScratch.compose(posScratch, quatScratch$2, scaleScratch$3);
@@ -734,7 +734,7 @@ var InstancedMesh3D = class extends Node3D {
 		super.free();
 	}
 };
-const UP$1 = new Vector3(0, 1, 0);
+const UP$2 = new Vector3(0, 1, 0);
 const posScratch = new Vector3();
 const quatScratch$2 = new Quaternion();
 const scaleScratch$3 = new Vector3();
@@ -835,6 +835,10 @@ var Joint3D = class extends Node3D {
 		const a = this.parent;
 		const b = this.getNodeOrNull(this.target);
 		if (!(b instanceof PhysicsBody3D)) throw new IncantoError("NODE_NOT_FOUND", `Joint3D '${this.name}': target '${this.target}' is not a physics body.`);
+		if (a === b) throw new IncantoError("BAD_FORMAT", `Joint3D '${this.name}': target '${this.target}' is the SAME body this joint hangs off, so it constrains nothing. A joint is a child of ONE body pointing at the OTHER — name the other body (e.g. "%Crate").`, {
+			prop: "target",
+			path: this.getPath()
+		});
 		return {
 			a,
 			b
@@ -1567,9 +1571,18 @@ var Terrain3D = class extends Node3D {
 			default: "island",
 			options: TERRAIN_THEMES
 		},
-		roughness: { default: .5 },
+		roughness: {
+			default: .5,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		detail: { default: 4 },
-		flatThreshold: { default: .95 },
+		flatThreshold: {
+			default: .95,
+			range: { min: 0 }
+		},
 		islandEdge: { default: null },
 		layers: { default: [] },
 		textureBase: { default: DEFAULT_TERRAIN_TEXTURE_BASE },
@@ -1591,7 +1604,32 @@ var Terrain3D = class extends Node3D {
 	roughness = .5;
 	/** Detail octave count. */
 	detail = 4;
-	/** Snap-flatten a plateau within ±0.6 m of maxHeight·flatThreshold. */
+	/**
+	* Snap-flatten a plateau within ±0.6 m of maxHeight·flatThreshold.
+	*
+	* A fraction of `maxHeight`, which is a SCALE and not the peak: heights
+	* realize at roughly 3.5–8× it, so the default 0.95 puts the plateau near the
+	* BOTTOM of the range rather than at the summit the name suggests. Measured
+	* on an alpine 200 m terrain, seed 3:
+	*
+	* ```
+	* maxHeight 28   realized 25..150   band at 26.6 = 18% of peak,  28 cells on it
+	* maxHeight  8   realized  8..43    band at  7.6 = 18% of peak,  99 cells on it
+	* ```
+	*
+	* It is doing something — that is a real terrace, and the ±0.6 m boundary
+	* between snapped and unsnapped cells is what `examples/water-ocean-3d` calls
+	* "a sawtooth band across the underwater flat". Read `heightAt` before
+	* choosing a value, the way `maxHeight`'s own note says to.
+	*
+	* 0..1 is the useful range, and anything ABOVE 1 turns the snap off, because
+	* the band then sits over every height the terrain realizes. `examples/water-ocean-3d` uses `20` for exactly that,
+	* with a comment explaining why, which is how a `max: 1` on this prop was
+	* caught the moment it was declared: at `maxHeight 0.1` the ±0.6 m band
+	* swallows the whole field and rips a sawtooth across the underwater flat.
+	* So the bound is `min: 0` and "off" is a documented idiom rather than an
+	* accident.
+	*/
 	flatThreshold = .95;
 	/** Wrap edges down into an island rim. null = theme decides (island: on). */
 	islandEdge = null;
@@ -1963,7 +2001,13 @@ const SHADOW_CONTACT_PUSH = .5;
 var Sprite3D = class extends Node3D {
 	static typeName = "Sprite3D";
 	static props = {
-		texture: { default: "" },
+		texture: {
+			default: "",
+			asset: {
+				kind: "texture",
+				urlOnly: true
+			}
+		},
 		size: { default: [1, 1] },
 		billboard: {
 			default: "y",
@@ -1975,10 +2019,22 @@ var Sprite3D = class extends Node3D {
 		},
 		anchor: { default: [.5, 0] },
 		tint: { default: "#ffffff" },
-		opacity: { default: 1 },
+		opacity: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		flipX: { default: false },
 		pixelArt: { default: true },
-		alphaTest: { default: .5 },
+		alphaTest: {
+			default: .5,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		castShadow: { default: false },
 		shadowMode: {
 			default: "silhouette",
@@ -2052,7 +2108,7 @@ var Sprite3D = class extends Node3D {
 		mat.opacity = this.opacity;
 		mat.transparent = this.opacity < 1;
 		mat.alphaTest = this.alphaTest;
-		quad.renderOrder = this.renderOrder;
+		quad.renderOrder = this.effectiveRenderOrder;
 		const wantShadow = this.castShadow && tex !== null;
 		quad.castShadow = false;
 		if (wantShadow && this.shadowMode === "silhouette") {
@@ -2159,7 +2215,6 @@ var Sprite3D = class extends Node3D {
 		mesh.quaternion.copy(_parent.invert()).multiply(_target);
 	}
 	free() {
-		this.loadedTexture?.dispose();
 		this.loadedTexture = null;
 		if (this.shadowMesh) {
 			this.shadowMesh.material.dispose();
@@ -2181,7 +2236,13 @@ var AnimatedSprite3D = class extends Sprite3D {
 	static typeName = "AnimatedSprite3D";
 	static signals = ["animationFinished"];
 	static props = {
-		sheet: { default: "" },
+		sheet: {
+			default: "",
+			asset: {
+				kind: "spritesheet",
+				urlOnly: true
+			}
+		},
 		frameWidth: { default: 0 },
 		frameHeight: { default: 0 },
 		animations: { default: {} },
@@ -2223,7 +2284,7 @@ var AnimatedSprite3D = class extends Sprite3D {
 		this.playing = false;
 	}
 	onReady() {
-		validateAnimationAliases(this.animations, this.name);
+		validateAnimations(this.animations, this.name);
 		if (this.autoplay) this.play(this.autoplay);
 	}
 	update(dt) {
@@ -2560,15 +2621,15 @@ var BoneLookAt3D = class extends Node3D {
 		if (targetNode && Array.isArray(targetNode.position)) {
 			bone.updateWorldMatrix(true, false);
 			bone.getWorldPosition(bonePosScratch);
-			targetScratch.set(targetNode.position[0] ?? 0, targetNode.position[1] ?? 0, targetNode.position[2] ?? 0);
-			dirScratch$1.copy(targetScratch).sub(bonePosScratch);
+			targetScratch$1.set(targetNode.position[0] ?? 0, targetNode.position[1] ?? 0, targetNode.position[2] ?? 0);
+			dirScratch$1.copy(targetScratch$1).sub(bonePosScratch);
 			if (dirScratch$1.lengthSq() > 1e-6) {
 				dirScratch$1.normalize();
 				axisScratch.copy(AXES[this.forwardAxis] ?? PLUS_Z);
 				animForwardScratch.copy(axisScratch).applyQuaternion(bone.getWorldQuaternion(quatScratch$1));
 				if (animForwardScratch.angleTo(dirScratch$1) < this.maxAngleDeg * Math.PI / 180) {
 					engaged = true;
-					lookMatrixScratch.lookAt(bonePosScratch, targetScratch, UP);
+					lookMatrixScratch.lookAt(bonePosScratch, targetScratch$1, UP$1);
 					desiredScratch.setFromRotationMatrix(lookMatrixScratch);
 					correctionScratch.setFromUnitVectors(axisScratch, MINUS_Z);
 					desiredScratch.multiply(correctionScratch);
@@ -2591,11 +2652,11 @@ const AXES = {
 	"+z": new Vector3(0, 0, 1),
 	"-z": new Vector3(0, 0, -1)
 };
-const UP = new Vector3(0, 1, 0);
+const UP$1 = new Vector3(0, 1, 0);
 const PLUS_Z = new Vector3(0, 0, 1);
 const MINUS_Z = new Vector3(0, 0, -1);
 const bonePosScratch = new Vector3();
-const targetScratch = new Vector3();
+const targetScratch$1 = new Vector3();
 const dirScratch$1 = new Vector3();
 const axisScratch = new Vector3();
 const animForwardScratch = new Vector3();
@@ -2606,6 +2667,13 @@ const parentScratch = new Quaternion();
 const quatScratch$1 = new Quaternion();
 //#endregion
 //#region src/3d/nodes/camera-3d.ts
+const RAD2DEG$1 = 180 / Math.PI;
+/** World up. The whole fix is that this argument exists. */
+const UP = new Vector3(0, 1, 0);
+const eyeScratch = new Vector3();
+const targetScratch = new Vector3();
+const lookScratch = new Matrix4();
+const eulerScratch$1 = new Euler(0, 0, 0, "XYZ");
 /**
 * A perspective camera. Mark exactly one camera `current: true`; with none
 * marked, the renderer falls back to the first camera in tree order.
@@ -2614,15 +2682,79 @@ const quatScratch$1 = new Quaternion();
 var Camera3D = class extends Node3D {
 	static typeName = "Camera3D";
 	static props = {
-		fov: { default: 60 },
-		near: { default: .1 },
-		far: { default: 1e3 },
-		current: { default: false }
+		fov: {
+			default: 60,
+			range: {
+				min: 0,
+				max: 180,
+				exclusiveMin: true,
+				exclusiveMax: true
+			}
+		},
+		near: {
+			default: .1,
+			range: {
+				min: 0,
+				exclusiveMin: true
+			}
+		},
+		far: {
+			default: 1e3,
+			range: {
+				min: 0,
+				exclusiveMin: true
+			}
+		},
+		current: { default: false },
+		lookAt: {
+			default: "",
+			nodePath: true
+		}
 	};
+	/** A frustum whose planes are the wrong way round draws nothing at all. */
+	static validateJson(node) {
+		const self = node;
+		if (self.near >= self.far) throw new IncantoError("PROP_TYPE_MISMATCH", `Camera3D '${node.name}' has an inverted depth range: near ${self.near} is not less than far ${self.far}. The near plane is the closest thing this camera can see and the far plane the furthest.`);
+	}
 	fov = 60;
 	near = .1;
 	far = 1e3;
 	current = false;
+	lookAt = "";
+	/**
+	* Aim, every frame, whenever `lookAt` names something.
+	*
+	* In `update` and not `_syncObject3D`: the second is the renderer's copy pass
+	* and a static node is pruned from it, which silently freezes anything driven
+	* there. `rotation` is written as an ordinary prop, so the editor, the
+	* serializer and `describeFraming` all see what the camera is actually doing.
+	*/
+	/** The `lookAt` path already reported as unlookable — cleared by a new one. */
+	warnedLookAt = "";
+	update(_dt) {
+		if (this.lookAt === "") return;
+		const target = this.getNodeOrNull(this.lookAt);
+		if (!target) return;
+		const to = worldPosition(target);
+		if (to.length < 3) {
+			if (this.warnedLookAt !== this.lookAt) {
+				this.warnedLookAt = this.lookAt;
+				diagnose(this.tree?.engine ?? null, "warn", `[incanto] ${this.getPath()}: lookAt '${this.lookAt}' resolves to a ${target.constructor.typeName ?? "Node"}, which has no world position — the camera keeps its authored rotation. Point it at a Node3D.`);
+			}
+			return;
+		}
+		const from = worldPosition(this);
+		eyeScratch.set(from[0] ?? 0, from[1] ?? 0, from[2] ?? 0);
+		targetScratch.set(to[0] ?? 0, to[1] ?? 0, to[2] ?? 0);
+		if (eyeScratch.distanceToSquared(targetScratch) < 1e-12) return;
+		lookScratch.lookAt(eyeScratch, targetScratch, UP);
+		eulerScratch$1.setFromRotationMatrix(lookScratch, "XYZ");
+		this.rotation = [
+			eulerScratch$1.x * RAD2DEG$1,
+			eulerScratch$1.y * RAD2DEG$1,
+			eulerScratch$1.z * RAD2DEG$1
+		];
+	}
 	_createObject3D() {
 		return new PerspectiveCamera(this.fov, 1, this.near, this.far);
 	}
@@ -2639,6 +2771,17 @@ var Camera3D = class extends Node3D {
 };
 //#endregion
 //#region src/3d/nodes/character-controller-3d.ts
+/**
+* The states this controller enters, and therefore the only keys its
+* `animations` map may carry.
+*/
+const MOVEMENT_STATES = [
+	"idle",
+	"walk",
+	"run",
+	"fastRun",
+	"airborne"
+];
 const ACC_DELTA_TIME = 8;
 const DRAG_DAMPING = .15;
 const SPRING_K = 1.2;
@@ -2725,7 +2868,13 @@ var CharacterController3D = class extends Node3D {
 			nodePath: true
 		},
 		skinYawOffset: { default: 0 },
-		animations: { default: {} }
+		animations: {
+			default: {},
+			asset: {
+				kind: "animation",
+				mapValues: true
+			}
+		}
 	};
 	view = "free";
 	camDistance = 4;
@@ -2825,6 +2974,27 @@ var CharacterController3D = class extends Node3D {
 	*                   "walk": "$walk", "airborne": "$jump" }
 	*/
 	animations = {};
+	/**
+	* Scene-load validation: an animation keyed by a state this controller never
+	* enters is a clip that never plays.
+	*
+	* The five state names live in one place in one skill, and `jumping`,
+	* `sprint`, `walking` and `falling` are what they are called in most other
+	* engines — `jump` is even the ACTION name in every template here. A wrong
+	* key was accepted and never looked at again, so the character walked and
+	* idled correctly and never animated its jump, which reads as broken
+	* animation rather than a wrong key.
+	*/
+	static validateJson(node) {
+		const ctl = node;
+		for (const state of Object.keys(ctl.animations)) {
+			if (MOVEMENT_STATES.includes(state)) continue;
+			throw new IncantoError("BAD_FORMAT", `CharacterController3D '${node.name}' maps an animation to '${state}', which is not a movement state.${didYouMean(state, MOVEMENT_STATES)} The states are [${MOVEMENT_STATES.join(", ")}].`, {
+				prop: "animations",
+				validOptions: [...MOVEMENT_STATES]
+			});
+		}
+	}
 	/** Camera yaw/pitch in radians (mouse look mutates these). */
 	yaw = 0;
 	pitch = 0;
@@ -3793,7 +3963,8 @@ var Flowers3D = class extends Node3D {
 	static props = {
 		density: {
 			default: "sparse",
-			options: DENSITY_OPTIONS
+			options: DENSITY_OPTIONS,
+			kinds: ["string", "number"]
 		},
 		area: { default: [20, 20] },
 		seed: { default: 1 },
@@ -5189,7 +5360,10 @@ var Foliage3D = class Foliage3D extends Node3D {
 			options: TUFT_STYLES
 		},
 		area: { default: [20, 20] },
-		density: { default: 12 },
+		density: {
+			default: 12,
+			range: { min: 0 }
+		},
 		maxInstances: { default: 5e4 },
 		height: { default: .25 },
 		colorA: { default: "#4d7232" },
@@ -5204,7 +5378,13 @@ var Foliage3D = class Foliage3D extends Node3D {
 		fadeEnd: { default: 90 },
 		sway: { default: .6 },
 		interaction: { default: true },
-		coverage: { default: .85 },
+		coverage: {
+			default: .85,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		flowers: { default: 0 },
 		seed: { default: 1 },
 		drape: { default: null },
@@ -6053,7 +6233,10 @@ var DirectionalLight3D = class extends Node3D {
 	static typeName = "DirectionalLight3D";
 	static props = {
 		color: { default: "#ffffff" },
-		intensity: { default: 1 },
+		intensity: {
+			default: 1,
+			range: { min: 0 }
+		},
 		castShadow: { default: false },
 		shadowArea: { default: 75 },
 		shadowMapSize: { default: 2048 },
@@ -6104,7 +6287,10 @@ var OmniLight3D = class extends Node3D {
 	static typeName = "OmniLight3D";
 	static props = {
 		color: { default: "#ffffff" },
-		intensity: { default: 1 },
+		intensity: {
+			default: 1,
+			range: { min: 0 }
+		},
 		range: { default: 0 }
 	};
 	color = "#ffffff";
@@ -6634,7 +6820,10 @@ var ModelInstance3D = class extends Node3D {
 		/** Seconds into the clip to start at — stagger a row of identical props. */
 		animationOffset: { default: 0 },
 		/** Upper-body layer clip ('' = off). One-shots auto-clear on finish. */
-		animationUpper: { default: "" },
+		animationUpper: {
+			default: "",
+			asset: { kind: "animation" }
+		},
 		/** Loop the upper layer (false = one-shot: attack, wave, throw). */
 		animationUpperLoop: { default: false },
 		/** Bone whose subtree the upper layer drives (forgiving lookup). */
@@ -6799,6 +6988,15 @@ var ModelInstance3D = class extends Node3D {
 		return [...embedded, ...assets];
 	}
 	/** Called by the 3D sync pass with the renderer's asset store. */
+	/**
+	* A model is ready when its GLB is. Freezing before that mounts nothing —
+	* see `Node3D._staticReady`.
+	*/
+	_staticReady(assets) {
+		if (!this.model) return true;
+		if (!assets) return false;
+		return assets.getModel(this.model).status === "ready";
+	}
 	_syncModel(assets) {
 		this.store = assets;
 		const root = this._ensureObject3D();
@@ -7205,8 +7403,20 @@ var Particles3D = class Particles3D extends Node3D {
 		colorStart: { default: "#ffffff" },
 		colorEnd: { default: "#ffffff" },
 		paletteColors: { default: [] },
-		alphaStart: { default: 1 },
-		alphaEnd: { default: 0 },
+		alphaStart: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
+		alphaEnd: {
+			default: 0,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		shimmer: { default: 0 },
 		blend: {
 			default: "add",
@@ -7276,7 +7486,7 @@ var Particles3D = class Particles3D extends Node3D {
 	_ensureSim() {
 		if (!this.sim) {
 			applyParticlePreset(this, this.preset, getNodeSchema(Particles3D.typeName));
-			const rng = this.tree?.engine?.rng ?? new Rng(4660);
+			const rng = effectRng(this);
 			this.sim = new ParticleSim({
 				rate: this.emitting ? this.rate : 0,
 				lifetime: [this.lifetime[0] ?? 1, this.lifetime[1] ?? 1],
@@ -7368,6 +7578,7 @@ var Particles3D = class Particles3D extends Node3D {
 			kind,
 			name: this.preset,
 			from: this.getPath(),
+			wiredAs: this.wiringPath(),
 			amount,
 			at: engine.time
 		});
@@ -7435,7 +7646,7 @@ var Particles3D = class Particles3D extends Node3D {
 			this.points.frustumCulled = false;
 			this._ensureObject3D().add(this.points);
 		}
-		this.points.renderOrder = this.renderOrder;
+		this.points.renderOrder = this.effectiveRenderOrder;
 		const material = this.points.material;
 		material.depthTest = this.depthTest;
 		material.blending = this.blend === "add" ? AdditiveBlending : NormalBlending;
@@ -8867,7 +9078,13 @@ var River3D = class River3D extends Node3D {
 		flowSpeed: { default: 1.6 },
 		colors: { default: {} },
 		absorption: { default: .5 },
-		opacity: { default: .85 },
+		opacity: {
+			default: .85,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		foam: { default: 1 },
 		ripples: { default: 1 },
 		sunDirection: { default: [
@@ -8876,7 +9093,10 @@ var River3D = class River3D extends Node3D {
 			.3
 		] },
 		sunColor: { default: "#fff6e0" },
-		sunIntensity: { default: 1 },
+		sunIntensity: {
+			default: 1,
+			range: { min: 0 }
+		},
 		terrain: {
 			default: "",
 			nodePath: true
@@ -9497,7 +9717,13 @@ var Trail3D = class extends Node3D {
 	static props = {
 		width: { default: .3 },
 		color: { default: "#ffffff" },
-		opacity: { default: .8 },
+		opacity: {
+			default: .8,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		seconds: { default: .6 },
 		emitting: { default: true },
 		additive: { default: false },
@@ -9546,6 +9772,7 @@ var Trail3D = class extends Node3D {
 				kind: "trail",
 				name: this.color,
 				from: this.getPath(),
+				wiredAs: this.wiringPath(),
 				amount: this.seconds,
 				at: engine.time
 			});
@@ -11327,7 +11554,13 @@ var Tree3D = class Tree3D extends Node3D {
 		area: { default: [10, 10] },
 		trunkColor: { default: "#7a5a3a" },
 		canopyColor: { default: "#4a7c3f" },
-		leafTexture: { default: "" },
+		leafTexture: {
+			default: "",
+			asset: {
+				kind: "texture",
+				urlOnly: true
+			}
+		},
 		leafFadeStart: { default: 0 },
 		leafFadeEnd: { default: 0 },
 		leafShadows: { default: true },
@@ -12661,9 +12894,25 @@ var VoxelGrid3D = class extends Node3D {
 	static typeName = "VoxelGrid3D";
 	static signals = ["blocksChanged"];
 	static props = { voxels: { default: [] } };
+	/**
+	* Hard-fail an authored grid that cannot all be DRAWN.
+	*
+	* The draw loop stops at `MAX_INSTANCES` and the excess blocks stay in the
+	* map — so `tileAt()` still reports them and a chunk collider builder still
+	* makes them solid. The world past the cap was invisible AND you walked into
+	* it. Every other 3D node whose instance count comes from authored data
+	* hard-fails at load; this one silently truncated.
+	*/
+	static validateJson(node) {
+		const self = node;
+		for (const [i, row] of self.voxels.entries()) if (!Array.isArray(row) || row.length < 3 || row.some((v) => typeof v !== "number")) throw new IncantoError("BAD_FORMAT", `VoxelGrid3D '${node.name}': voxels[${i}] must be [x, y, z, tile?] (numbers), got ${JSON.stringify(row)}.`);
+		if (self.voxels.length > MAX_INSTANCES) throw new IncantoError("BAD_FORMAT", `VoxelGrid3D '${node.name}': ${self.voxels.length} voxels exceeds the ${MAX_INSTANCES} this node can draw. Everything past the cap would still be SOLID and still be reported by tileAt(), and simply not appear. Split the world into several VoxelGrid3D nodes (one per chunk) and show the ones near the player.`);
+	}
 	/** JSON-authored blocks as [x, y, z, tile] tuples (generated terrains bake these). */
 	voxels = [];
 	appliedVoxels = null;
+	/** Said once per node: a runtime overflow must not spam a frame loop. */
+	reportedOverflow = false;
 	map = /* @__PURE__ */ new Map();
 	mesh = null;
 	dirty = false;
@@ -12729,6 +12978,10 @@ var VoxelGrid3D = class extends Node3D {
 				tile: t[3] ?? 0
 			})));
 		}
+		if (this.map.size > MAX_INSTANCES && !this.reportedOverflow) {
+			this.reportedOverflow = true;
+			diagnose(this.tree?.engine ?? null, "error", `[incanto] VoxelGrid3D '${this.getPath()}' holds ${this.map.size} blocks and can draw ${MAX_INSTANCES}. The rest are still solid and still reported by tileAt(), and do not appear. Split the world across several VoxelGrid3D nodes.`);
+		}
 		if (!this.dirty || !this.mesh) return;
 		this.dirty = false;
 		const m4 = new Matrix4();

package/dist/{frame-report-Dlq13Gyj.js → frame-report-D-_7YF2G.js}

@@ -177,7 +177,7 @@ const pct = (v) => `${(v * 100).toFixed(1)}%`;
 /** The report a person or an agent reads. Verdict first, numbers after. */
 function frameText(stats) {
 	const lines = [];
-	if (stats.hidden) lines.push("THE PAGE IS HIDDEN — a browser stops animating a window covered by another, so these pixels are whatever it last drew. Bring it to the front and capture again.");
+	if (stats.hidden) lines.push("the page is hidden, so the game is PAUSED — these pixels were rendered for this capture (current), but nothing is moving. A `--do` drive needs the window in front.");
 	if (stats.black) lines.push("BLACK SCREEN — nothing was drawn (no light, no camera, or nothing in view)");
 	else if (stats.uniform) lines.push("one flat colour — the camera may be inside geometry, or only the sky is drawn");
 	else if (!stats.subject) lines.push("nothing but background — the camera is pointed away from everything in the scene");