incanto 0.12.0 → 0.14.0

package/dist/{register-ysLR3WQS.js → register-C9-16x_t.js}

@@ -1,12 +1,12 @@
-import { f as Node } from "./loader-B4OEXDZ8.js";
-import { t as registerCoreNodes } from "./register-DJZXxwAn.js";
+import { f as Node } from "./loader-BZqOKfI2.js";
+import { t as registerCoreNodes } from "./register-nObreUQR.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-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
 import { i as applyParticlePreset, o as effectiveOrder, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-CyUU7HVU.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CroQPEER.js";
-import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, Color, ConeGeometry, CubeCamera, CylinderGeometry, DataTexture, DepthTexture, DirectionalLight, DoubleSide, Euler, FloatType, Frustum, Group, HalfFloatType, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, MathUtils, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NormalBlending, Object3D, PerspectiveCamera, Plane, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, Sphere, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector2, Vector3, Vector4, VectorKeyframeTrack, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
+import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, Color, ConeGeometry, CubeCamera, CylinderGeometry, DataTexture, DepthTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, FloatType, Frustum, Group, HalfFloatType, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, MathUtils, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NormalBlending, Object3D, PerspectiveCamera, Plane, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, Sphere, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector2, Vector3, Vector4, VectorKeyframeTrack, WebGLCubeRenderTarget, WebGLRenderTarget } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
 //#region src/3d/camera-rig.ts
 const QUARTER_PITCH = Math.atan(1 / Math.SQRT2);
@@ -1950,8 +1950,8 @@ var BoneAttachment3D = class extends Node3D {
 		boneObj.updateWorldMatrix(true, false);
 		parent.updateWorldMatrix(true, false);
 		obj.matrixAutoUpdate = false;
-		boneObj.matrixWorld.decompose(bonePosScratch, boneQuatScratch, boneScaleScratch);
-		boneScratch.compose(bonePosScratch, boneQuatScratch, unitScale);
+		boneObj.matrixWorld.decompose(bonePosScratch$1, boneQuatScratch, boneScaleScratch);
+		boneScratch.compose(bonePosScratch$1, boneQuatScratch, unitScale);
 		obj.updateMatrix();
 		offsetScratch.copy(obj.matrix);
 		obj.matrix.copy(parent.matrixWorld).invert().multiply(boneScratch).multiply(offsetScratch);
@@ -1963,11 +1963,125 @@ var BoneAttachment3D = class extends Node3D {
 };
 const offsetScratch = new Matrix4();
 const boneScratch = new Matrix4();
-const bonePosScratch = new Vector3();
+const bonePosScratch$1 = new Vector3();
 const boneQuatScratch = new Quaternion();
 const boneScaleScratch = new Vector3();
 const unitScale = new Vector3(1, 1, 1);
 //#endregion
+//#region src/3d/nodes/bone-look-at-3d.ts
+/**
+* Look-at IK for one bone — the character's head (or chest, or turret) turns
+* toward a target node ON TOP of whatever the animation is doing. Runs after
+* the mixer each rendered frame, blends in/out smoothly, and DISENGAGES when
+* the target leaves the comfort cone (no owl necks).
+*
+*   { "name": "HeadTrack", "type": "BoneLookAt3D",
+*     "props": { "target": "../Skin", "bone": "Head", "lookAt": "%Player" } }
+*
+* `forwardAxis` names the bone's local facing axis (mixamo heads face +z,
+* the default). Purely visual — headless it's a no-op.
+*/
+var BoneLookAt3D = class extends Node3D {
+	static typeName = "BoneLookAt3D";
+	static props = {
+		/** Node path to the ModelInstance3D whose bone to steer. */
+		target: { default: "" },
+		/** Bone name ("Head", "Neck", "Spine2" — Mixamo spellings matched). */
+		bone: { default: "Head" },
+		/** Node path to LOOK AT ('' = idle). */
+		lookAt: { default: "" },
+		/** Comfort cone half-angle, degrees — beyond it the head returns to the anim. */
+		maxAngleDeg: { default: 75 },
+		/** Blend weight 0..1 (how far toward the target the bone turns). */
+		weight: { default: .85 },
+		/** The bone's local facing axis. */
+		forwardAxis: {
+			default: "+z",
+			options: [
+				"+x",
+				"-x",
+				"+y",
+				"-y",
+				"+z",
+				"-z"
+			]
+		}
+	};
+	target = "";
+	bone = "Head";
+	lookAt = "";
+	maxAngleDeg = 75;
+	weight = .85;
+	forwardAxis = "+z";
+	boneObj = null;
+	lookedUpFor = "";
+	/** 0..1 engage blend — eases in/out so tracking never snaps. */
+	engage = 0;
+	/** Test hook. */
+	get attachedBone() {
+		return this.boneObj;
+	}
+	_onRender3D(_ctx) {
+		if (this.target === "" || this.bone === "") return;
+		const key = `${this.target} ${this.bone}`;
+		if (this.lookedUpFor !== key || this.boneObj === null || !this.boneObj.parent) {
+			this.lookedUpFor = key;
+			this.boneObj = null;
+			const source = this.getNodeOrNull(this.target);
+			if (source && typeof source.findBone === "function") this.boneObj = source.findBone(this.bone);
+		}
+		const bone = this.boneObj;
+		if (!bone?.parent) return;
+		const targetNode = this.lookAt === "" ? null : this.getNodeOrNull(this.lookAt);
+		let engaged = false;
+		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);
+			if (dirScratch$1.lengthSq() > 1e-6) {
+				dirScratch$1.normalize();
+				axisScratch.copy(AXES[this.forwardAxis] ?? PLUS_Z);
+				animForwardScratch.copy(axisScratch).applyQuaternion(bone.getWorldQuaternion(quatScratch$2));
+				if (animForwardScratch.angleTo(dirScratch$1) < this.maxAngleDeg * Math.PI / 180) {
+					engaged = true;
+					lookMatrixScratch.lookAt(bonePosScratch, targetScratch, UP$1);
+					desiredScratch.setFromRotationMatrix(lookMatrixScratch);
+					correctionScratch.setFromUnitVectors(axisScratch, MINUS_Z);
+					desiredScratch.multiply(correctionScratch);
+					bone.parent.getWorldQuaternion(parentScratch).invert();
+					desiredScratch.premultiply(parentScratch);
+					const k = this.weight * this.engage;
+					bone.quaternion.slerp(desiredScratch, k);
+				}
+			}
+		}
+		this.engage += ((engaged ? 1 : 0) - this.engage) * ENGAGE_RATE;
+	}
+};
+const ENGAGE_RATE = .18;
+const AXES = {
+	"+x": new Vector3(1, 0, 0),
+	"-x": new Vector3(-1, 0, 0),
+	"+y": new Vector3(0, 1, 0),
+	"-y": new Vector3(0, -1, 0),
+	"+z": new Vector3(0, 0, 1),
+	"-z": new Vector3(0, 0, -1)
+};
+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 dirScratch$1 = new Vector3();
+const axisScratch = new Vector3();
+const animForwardScratch = new Vector3();
+const lookMatrixScratch = new Matrix4();
+const desiredScratch = new Quaternion();
+const correctionScratch = new Quaternion();
+const parentScratch = new Quaternion();
+const quatScratch$2 = new Quaternion();
+//#endregion
 //#region src/3d/nodes/camera-3d.ts
 /**
 * A perspective camera. Mark exactly one camera `current: true`; with none
@@ -2022,7 +2136,7 @@ const CAM_GROUND_CLEARANCE = .3;
 *  near-plane band around the boom (the Emberwood hedge-maze lesson). */
 const CAM_PROBE_RADIUS = .25;
 const eulerScratch = new Euler();
-const quatScratch = new Quaternion();
+const quatScratch$1 = new Quaternion();
 const matrixScratch$3 = new Matrix4();
 const camVecScratch = new Vector3();
 const eyeVecScratch = new Vector3();
@@ -2309,12 +2423,12 @@ var CharacterController3D = class extends Node3D {
 			camVecScratch.set(camera.position[0] ?? 0, camera.position[1] ?? 0, camera.position[2] ?? 0);
 			eyeVecScratch.set(eye[0], eye[1], eye[2]);
 			matrixScratch$3.lookAt(camVecScratch, eyeVecScratch, UP_VEC);
-			quatScratch.setFromRotationMatrix(matrixScratch$3);
-			eulerScratch.setFromQuaternion(quatScratch, "XYZ");
+			quatScratch$1.setFromRotationMatrix(matrixScratch$3);
+			eulerScratch.setFromQuaternion(quatScratch$1, "XYZ");
 		} else {
 			eulerScratch.set(pose.rotation[0], pose.rotation[1], pose.rotation[2], "YXZ");
-			quatScratch.setFromEuler(eulerScratch);
-			eulerScratch.setFromQuaternion(quatScratch, "XYZ");
+			quatScratch$1.setFromEuler(eulerScratch);
+			eulerScratch.setFromQuaternion(quatScratch$1, "XYZ");
 		}
 		camera.rotation = [
 			eulerScratch.x * RAD2DEG,
@@ -2952,7 +3066,7 @@ var Flowers3D = class extends Node3D {
 		height: { default: .45 },
 		clustering: { default: .6 },
 		sway: { default: .5 },
-		drape: { default: false },
+		drape: { default: null },
 		terrain: { default: "" }
 	};
 	/** 'lush' | 'sparse' | 'none' | plants per m² (load-time check + budget). */
@@ -2973,9 +3087,13 @@ var Flowers3D = class extends Node3D {
 	clustering = .6;
 	/** Gentle head-bob wind strength — 0 holds still. */
 	sway = .5;
-	/** Drape each plant onto a Terrain3D's surface so flowers root on the ground
-	* instead of a flat plane (lets ONE bed cover rolling terrain). */
-	drape = false;
+	/**
+	* null (the default) is AUTO: whenever the scene has a Terrain3D, instances
+	* root on it — flat ground behaves as before, rolling terrain just works.
+	* true forces it (keeps retrying until a terrain appears), false disables
+	* draping entirely.
+	*/
+	drape = null;
 	/** Drape target: a node path to the Terrain3D. Empty = auto-find the first
 	* Terrain3D in the tree (the zero-config default when `drape` is on). */
 	terrain = "";
@@ -3005,7 +3123,7 @@ var Flowers3D = class extends Node3D {
 		if (!(f.height > 0)) throw new IncantoError("BAD_FORMAT", `Flowers3D '${node.name}' height must be > 0 meters, got ${f.height}.`, { prop: "height" });
 		if (!(f.clustering >= 0) || !(f.clustering <= 1)) throw new IncantoError("BAD_FORMAT", `Flowers3D '${node.name}' clustering must be in [0, 1] (0 uniform … 1 tight patches), got ${f.clustering}.`, { prop: "clustering" });
 		if (!(f.sway >= 0)) throw new IncantoError("BAD_FORMAT", `Flowers3D '${node.name}' sway must be >= 0, got ${f.sway}.`, { prop: "sway" });
-		if (typeof f.drape !== "boolean") throw new IncantoError("BAD_FORMAT", `Flowers3D '${node.name}' drape must be a boolean, got ${JSON.stringify(f.drape)}.`, { prop: "drape" });
+		if (f.drape !== null && typeof f.drape !== "boolean") throw new IncantoError("BAD_FORMAT", `Flowers3D '${node.name}' drape must be true, false or null (null = auto: drape whenever the scene has a Terrain3D), got ${JSON.stringify(f.drape)}.`, { prop: "drape" });
 		if (typeof f.terrain !== "string") throw new IncantoError("BAD_FORMAT", `Flowers3D '${node.name}' terrain must be a node-path string (empty = auto-find), got ${JSON.stringify(f.terrain)}.`, { prop: "terrain" });
 	}
 	time = 0;
@@ -3058,7 +3176,7 @@ var Flowers3D = class extends Node3D {
 	/** Resolve the drape target + cache the bed's world position for `bedY`. */
 	resolveDrape() {
 		this.drapeTerrain = null;
-		if (!this.drape) return;
+		if (this.drape === false) return;
 		const terrain = findDrapeTerrain(this, this.terrain);
 		if (terrain) {
 			this.drapeTerrain = terrain;
@@ -3110,8 +3228,8 @@ var Flowers3D = class extends Node3D {
 				const p = plants[i];
 				positionScratch$2.set(p.x, this.bedY(p.x, p.z), p.z);
 				quaternionScratch$2.setFromAxisAngle(Y_AXIS$2, p.rotY);
-				scaleScratch$2.setScalar(this.height * p.scale);
-				matrixScratch$2.compose(positionScratch$2, quaternionScratch$2, scaleScratch$2);
+				scaleScratch$3.setScalar(this.height * p.scale);
+				matrixScratch$2.compose(positionScratch$2, quaternionScratch$2, scaleScratch$3);
 				structureMesh.setMatrixAt(i, matrixScratch$2);
 				petalMesh.setMatrixAt(i, matrixScratch$2);
 				const pick = Math.min(Math.floor(p.color01 * palette.length), palette.length - 1);
@@ -3183,7 +3301,7 @@ const Y_AXIS$2 = new Vector3(0, 1, 0);
 const matrixScratch$2 = new Matrix4();
 const positionScratch$2 = new Vector3();
 const quaternionScratch$2 = new Quaternion();
-const scaleScratch$2 = new Vector3();
+const scaleScratch$3 = new Vector3();
 const colorScratch$1 = new Color();
 /**
 * Nearest-k benders whose influence circle touches the field rectangle,
@@ -4335,7 +4453,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 		coverage: { default: .85 },
 		flowers: { default: 0 },
 		seed: { default: 1 },
-		drape: { default: false },
+		drape: { default: null },
 		terrain: { default: "" },
 		renderOrder: { default: 2 }
 	};
@@ -4394,9 +4512,14 @@ var Foliage3D = class Foliage3D extends Node3D {
 	flowers = 0;
 	/** Placement seed — the field is identical across runs and machines. */
 	seed = 1;
-	/** Drape each instance onto a Terrain3D's surface so blades root on the
-	* ground instead of a flat plane (lets ONE field cover rolling terrain). */
-	drape = false;
+	/**
+	* Drape each instance onto a Terrain3D's surface so blades root on the
+	* ground instead of a flat plane. null (the default) is AUTO: whenever the
+	* scene has a Terrain3D, instances root on it — flat ground behaves as
+	* before, rolling terrain just works. true forces it (keeps retrying until
+	* a terrain appears), false disables draping entirely.
+	*/
+	drape = null;
 	/** Drape target: a node path to the Terrain3D. Empty = auto-find the first
 	* Terrain3D in the tree (the zero-config default when `drape` is on). */
 	terrain = "";
@@ -4430,7 +4553,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 		if (!Array.isArray(sun) || sun.length !== 3 || !sun.every((v) => Number.isFinite(v)) || Math.hypot(sun[0] ?? 0, sun[1] ?? 0, sun[2] ?? 0) === 0) throw new IncantoError("BAD_FORMAT", `Foliage3D '${node.name}' sunDirection must be a non-zero [x, y, z] vector, got ${JSON.stringify(sun)}.`, { prop: "sunDirection" });
 		if (!(f.coverage > 0) || !(f.coverage <= 1)) throw new IncantoError("BAD_FORMAT", `Foliage3D '${node.name}' coverage must be in (0, 1] (carpet fill — 1 is solid, lower carves dirt patches), got ${f.coverage}.`, { prop: "coverage" });
 		if (!(f.flowers >= 0) || !(f.flowers <= .2)) throw new IncantoError("BAD_FORMAT", `Foliage3D '${node.name}' flowers must be in [0, 0.2] (fraction of instances rendered as flower heads — for a whole flower FIELD use kind: 'flowers'), got ${f.flowers}.`, { prop: "flowers" });
-		if (typeof f.drape !== "boolean") throw new IncantoError("BAD_FORMAT", `Foliage3D '${node.name}' drape must be a boolean, got ${JSON.stringify(f.drape)}.`, { prop: "drape" });
+		if (f.drape !== null && typeof f.drape !== "boolean") throw new IncantoError("BAD_FORMAT", `Foliage3D '${node.name}' drape must be true, false or null (null = auto: drape whenever the scene has a Terrain3D), got ${JSON.stringify(f.drape)}.`, { prop: "drape" });
 		if (typeof f.terrain !== "string") throw new IncantoError("BAD_FORMAT", `Foliage3D '${node.name}' terrain must be a node-path string (empty = auto-find), got ${JSON.stringify(f.terrain)}.`, { prop: "terrain" });
 	}
 	time = 0;
@@ -4476,16 +4599,33 @@ var Foliage3D = class Foliage3D extends Node3D {
 	update(dt) {
 		this.time += dt;
 		this.pickedBenders = this.computeBenders();
+		this.writeAnimationUniforms();
+	}
+	/** Wind time/strength + the ≤4 character-bend slots (no-op before first build). */
+	writeAnimationUniforms() {
+		if (this.isShaderField && this.bladesMaterial) {
+			const u = this.bladesMaterial.uniforms;
+			if (u.time) u.time.value = this.time;
+			if (u.windStrength) u.windStrength.value = this.sway * (this.isMesh ? MESH_SWAY_TO_WIND : SWAY_TO_WIND);
+			const slots = this.benderSlots;
+			if (slots) for (let i = 0; i < 4; i++) {
+				const b = this.pickedBenders[i];
+				if (b) slots[i]?.set(b.x, b.y, b.z, b.radius);
+				else slots[i]?.set(0, 0, 0, 0);
+			}
+		} else if (this.isTufts) {
+			if (this.tuftTime) this.tuftTime.value = this.time;
+			if (this.tuftStrength) this.tuftStrength.value = this.sway * TUFT_SWAY_TO_WIND;
+		}
 	}
 	_syncObject3D() {
 		super._syncObject3D();
 		this.rebuildIfNeeded();
 		const pivot = this.pivot;
+		this.writeAnimationUniforms();
 		if (this.isShaderField) {
 			pivot.matrix.identity();
 			const u = this.bladesMaterial.uniforms;
-			if (u.time) u.time.value = this.time;
-			if (u.windStrength) u.windStrength.value = this.sway * (this.isMesh ? MESH_SWAY_TO_WIND : SWAY_TO_WIND);
 			(u.bottomColor?.value).set(this.colorA);
 			(u.topColor?.value).set(this.colorB);
 			if (this.isMesh) {
@@ -4494,17 +4634,8 @@ var Foliage3D = class Foliage3D extends Node3D {
 				if (u.fadeStart) u.fadeStart.value = this.fadeStart;
 				if (u.fadeEnd) u.fadeEnd.value = this.fadeEnd;
 			}
-			const slots = this.benderSlots;
-			for (let i = 0; i < 4; i++) {
-				const b = this.pickedBenders[i];
-				if (b) slots[i]?.set(b.x, b.y, b.z, b.radius);
-				else slots[i]?.set(0, 0, 0, 0);
-			}
-		} else if (this.isTufts) {
-			pivot.matrix.identity();
-			if (this.tuftTime) this.tuftTime.value = this.time;
-			if (this.tuftStrength) this.tuftStrength.value = this.sway * TUFT_SWAY_TO_WIND;
-		} else if (this.sway > 0) {
+		} else if (this.isTufts) pivot.matrix.identity();
+		else if (this.sway > 0) {
 			const leanX = Math.sin(this.time * 1.7) * SWAY_LEAN * this.sway;
 			const leanZ = Math.sin(this.time * 1.3 + 1.7) * SWAY_LEAN * this.sway * .6;
 			pivot.matrix.makeShear(0, 0, leanX, leanZ, 0, 0);
@@ -4531,7 +4662,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 	computeBenders() {
 		if (!this.interaction || !this.isShaderField) return [];
 		const [fx, fy, fz] = worldXZY(this);
-		if (this.drape && !this.drapeTerrain) this.resolveDrape();
+		if (this.drape === true && !this.drapeTerrain) this.resolveDrape();
 		const terrain = this.drapeTerrain;
 		const candidates = [];
 		for (const b of movingBodiesFor(this)) {
@@ -4592,7 +4723,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 	/** Resolve the drape target + cache the field's world position for `bedY`. */
 	resolveDrape() {
 		this.drapeTerrain = null;
-		if (!this.drape) return;
+		if (this.drape === false) return;
 		const terrain = findDrapeTerrain(this, this.terrain);
 		if (terrain) {
 			this.drapeTerrain = terrain;
@@ -4672,8 +4803,8 @@ var Foliage3D = class Foliage3D extends Node3D {
 			const bladeHeight = this.height * regional * (.55 + p.scale * .6);
 			positionScratch$1.set(p.x, this.bedY(p.x, p.z), p.z);
 			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, p.rotY);
-			scaleScratch$1.set(widthJitter, bladeHeight, widthJitter);
-			mesh.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$1));
+			scaleScratch$2.set(widthJitter, bladeHeight, widthJitter);
+			mesh.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2));
 			const leanDir = clump.leanDir + rng.range(-.6, .6);
 			const lean = (MESH_LEAN_BASE + MESH_LEAN_RANGE * (.5 * clump.lean + .5 * rng.next())) * (1 + MESH_TALL_LEAN_BOOST * tall);
 			blade[i * 4] = Math.cos(leanDir) * lean;
@@ -4711,8 +4842,8 @@ var Foliage3D = class Foliage3D extends Node3D {
 			const stem = this.height * regional * (.85 + rng.next() * .35);
 			positionScratch$1.set(p.x, this.bedY(p.x, p.z), p.z);
 			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, p.rotY);
-			scaleScratch$1.set(1, stem, 1);
-			mesh.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$1));
+			scaleScratch$2.set(1, stem, 1);
+			mesh.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2));
 			const pick = rng.next();
 			const color = FLOWER_COLORS[pick < .45 ? 0 : pick < .75 ? 1 : 2];
 			mesh.setColorAt(i, colorScratchC$1.set(color));
@@ -4764,8 +4895,8 @@ var Foliage3D = class Foliage3D extends Node3D {
 			const cardW = cardH * TUFT_ASPECT * rng.range(TUFT_WIDTH_JITTER[0], TUFT_WIDTH_JITTER[1]);
 			positionScratch$1.set(p.x, this.bedY(p.x, p.z), p.z);
 			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, p.rotY);
-			scaleScratch$1.set(cardW, cardH, cardW);
-			mesh.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$1));
+			scaleScratch$2.set(cardW, cardH, cardW);
+			mesh.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2));
 			const clump = clumpAt(p.x, p.z);
 			const t = Math.min(1, Math.max(0, .5 + .35 * clump.hue + (rng.next() - .5) * .3));
 			const dry = Math.min(1, Math.max(0, dryFieldAt(p.x, p.z, this.seed) * .8 - .1));
@@ -4822,11 +4953,11 @@ var Foliage3D = class Foliage3D extends Node3D {
 		for (let i = 0; i < count; i++) {
 			const p = placements[i];
 			positionScratch$1.set(p.x, this.bedY(p.x, p.z), p.z);
-			scaleScratch$1.setScalar(p.scale);
+			scaleScratch$2.setScalar(p.scale);
 			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, p.rotY);
-			first.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$1));
+			first.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2));
 			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, p.rotY + Math.PI / 2);
-			second.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$1));
+			second.setMatrixAt(i, matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2));
 		}
 		first.instanceMatrix.needsUpdate = true;
 		second.instanceMatrix.needsUpdate = true;
@@ -4851,8 +4982,8 @@ var Foliage3D = class Foliage3D extends Node3D {
 			const sz = rng.range(-halfZ, halfZ);
 			positionScratch$1.set(sx, this.bedY(sx, sz), sz);
 			quaternionScratch$1.setFromAxisAngle(Y_AXIS$1, rng.range(0, Math.PI * 2));
-			scaleScratch$1.set(1, this.height * rng.range(HEIGHT_JITTER$1[0], HEIGHT_JITTER$1[1]), 1);
-			matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$1);
+			scaleScratch$2.set(1, this.height * rng.range(HEIGHT_JITTER$1[0], HEIGHT_JITTER$1[1]), 1);
+			matrixScratch$1.compose(positionScratch$1, quaternionScratch$1, scaleScratch$2);
 			mesh.setMatrixAt(i, matrixScratch$1);
 			mesh.setColorAt(i, colorScratchC$1.copy(colorA).lerp(colorB, rng.next()));
 		}
@@ -5001,88 +5132,12 @@ const Y_AXIS$1 = new Vector3(0, 1, 0);
 const matrixScratch$1 = new Matrix4();
 const positionScratch$1 = new Vector3();
 const quaternionScratch$1 = new Quaternion();
-const scaleScratch$1 = new Vector3();
+const scaleScratch$2 = new Vector3();
 const colorScratchA$1 = new Color();
 const colorScratchB$1 = new Color();
 const colorScratchC$1 = new Color();
 const tuftDryScratch = new Color();
 //#endregion
-//#region src/3d/nodes/lights-3d.ts
-/** Sun-style light. Direction comes from the node's rotation. */
-var DirectionalLight3D = class extends Node3D {
-	static typeName = "DirectionalLight3D";
-	static props = {
-		color: { default: "#ffffff" },
-		intensity: { default: 1 },
-		castShadow: { default: false },
-		shadowArea: { default: 75 },
-		shadowMapSize: { default: 2048 },
-		shadowFollowsCamera: { default: false }
-	};
-	color = "#ffffff";
-	intensity = 1;
-	castShadow = false;
-	/** Half-extent of the directional shadow frustum (template default ±75). */
-	shadowArea = 75;
-	shadowMapSize = 2048;
-	/**
-	* Re-center the shadow frustum on the camera every frame. A directional sun's
-	* shadow map covers a fixed ortho box; in a big roaming world that box must be
-	* huge (and so low-resolution that the player's own shadow nearly vanishes).
-	* With this on, a SMALL `shadowArea` tracks the camera, so contact shadows stay
-	* crisp wherever you go. The renderer supplies the camera position.
-	*/
-	shadowFollowsCamera = false;
-	_createObject3D() {
-		return new DirectionalLight();
-	}
-	_syncObject3D() {
-		super._syncObject3D();
-		const light = this._ensureObject3D();
-		light.color.set(this.color);
-		light.intensity = this.intensity;
-		light.castShadow = this.castShadow;
-		if (this.castShadow && "shadow" in light) {
-			const cam = light.shadow.camera;
-			if ("left" in cam) {
-				cam.left = -this.shadowArea;
-				cam.right = this.shadowArea;
-				cam.top = this.shadowArea;
-				cam.bottom = -this.shadowArea;
-				cam.near = .5;
-				cam.far = 500;
-				cam.updateProjectionMatrix();
-			}
-			light.shadow.mapSize.set(this.shadowMapSize, this.shadowMapSize);
-			light.shadow.bias = -2e-4;
-			light.shadow.normalBias = .002;
-		}
-	}
-};
-/** Point light with a range (Godot's OmniLight3D). */
-var OmniLight3D = class extends Node3D {
-	static typeName = "OmniLight3D";
-	static props = {
-		color: { default: "#ffffff" },
-		intensity: { default: 1 },
-		range: { default: 0 }
-	};
-	color = "#ffffff";
-	intensity = 1;
-	/** 0 = unlimited (three `distance` semantics). */
-	range = 0;
-	_createObject3D() {
-		return new PointLight();
-	}
-	_syncObject3D() {
-		super._syncObject3D();
-		const light = this._ensureObject3D();
-		light.color.set(this.color);
-		light.intensity = this.intensity;
-		light.distance = this.range;
-	}
-};
-//#endregion
 //#region src/3d/nodes/mesh-instance-3d.ts
 /** Every key `material` accepts — validation lists these on a typo. */
 const MATERIAL_KEYS = [
@@ -5165,7 +5220,7 @@ var MeshInstance3D = class extends Node3D {
 		const key = `${this.mesh}:${JSON.stringify(this.size)}`;
 		if (key !== this.geometryKey) {
 			m.geometry.dispose();
-			m.geometry = buildGeometry(this.mesh, this.size);
+			m.geometry = buildMeshGeometry(this.mesh, this.size);
 			this.geometryKey = key;
 		}
 		const mat = m.material;
@@ -5284,7 +5339,8 @@ function validateMeshMaterial(material, name, typeName = "MeshInstance3D") {
 		if (value !== void 0 && typeof value !== "boolean") fail(`material.${key} must be a boolean, got ${JSON.stringify(value)}.`);
 	}
 }
-function buildGeometry(kind, size) {
+/** Geometry factory shared by MeshInstance3D and InstancedMesh3D. */
+function buildMeshGeometry(kind, size) {
 	const x = size[0] ?? 1;
 	const y = size[1] ?? 1;
 	const z = size[2] ?? 1;
@@ -5303,6 +5359,206 @@ function buildGeometry(kind, size) {
 	}
 }
 //#endregion
+//#region src/3d/nodes/instanced-mesh-3d.ts
+/**
+* Hundreds of copies of one mesh in ONE draw call — scattered rocks, fence
+* posts, pillars, crates, gravestones. Same `mesh`/`size`/`material` surface
+* as MeshInstance3D; `transforms` places the copies:
+*
+*   { "name": "Rocks", "type": "InstancedMesh3D",
+*     "props": { "mesh": "gem", "size": [0.7, 0.5, 0.7],
+*       "material": { "color": "#8a8f98", "roughness": 0.9, "flatShading": true },
+*       "transforms": [[12, 0.2, -8, 40, 1.3], [-6, 0.1, 14, 210, 0.8]] } }
+*
+* Each row is `[x, y, z, yawDeg?, scale?]` (yaw 0 and scale 1 when omitted) —
+* dense enough to generate hundreds inline. REPLACE the array to update
+* (mutations are not watched).
+*/
+var InstancedMesh3D = class extends Node3D {
+	static typeName = "InstancedMesh3D";
+	static props = {
+		mesh: {
+			default: "box",
+			options: [
+				"box",
+				"sphere",
+				"capsule",
+				"plane",
+				"cylinder",
+				"gem"
+			]
+		},
+		size: { default: [
+			1,
+			1,
+			1
+		] },
+		material: { default: {} },
+		/** `[x, y, z, yawDeg?, scale?]` per instance. */
+		transforms: { default: [] },
+		castShadow: { default: false },
+		receiveShadow: { default: false }
+	};
+	mesh = "box";
+	size = [
+		1,
+		1,
+		1
+	];
+	material = {};
+	castShadow = false;
+	receiveShadow = false;
+	_transforms = [];
+	transformsDirty = true;
+	get transforms() {
+		return this._transforms;
+	}
+	set transforms(value) {
+		this._transforms = value;
+		this.transformsDirty = true;
+	}
+	instanced = null;
+	builtKey = "";
+	static validateJson(node) {
+		const self = node;
+		validateMeshMaterial(self.material, node.name);
+		for (const [i, row] of self._transforms.entries()) if (!Array.isArray(row) || row.length < 3 || row.length > 5 || row.some((v) => typeof v !== "number")) throw new IncantoError("BAD_FORMAT", `InstancedMesh3D '${node.name}': transforms[${i}] must be [x, y, z, yawDeg?, scale?] (numbers), got ${JSON.stringify(row)}.`);
+	}
+	/** Test hook: the live instance count. */
+	get instanceCount() {
+		return this.instanced?.count ?? 0;
+	}
+	_syncObject3D(alpha) {
+		super._syncObject3D(alpha);
+		const root = this._ensureObject3D();
+		const key = `${this.mesh} ${JSON.stringify(this.size)} ${this._transforms.length}`;
+		if (key !== this.builtKey) {
+			this.builtKey = key;
+			if (this.instanced) {
+				root.remove(this.instanced);
+				this.instanced.geometry.dispose();
+				this.instanced.material.dispose();
+				this.instanced = null;
+			}
+			if (this._transforms.length > 0) {
+				const geometry = buildMeshGeometry(this.mesh, this.size);
+				const material = new MeshPhysicalMaterial();
+				this.instanced = new InstancedMesh(geometry, material, this._transforms.length);
+				this.instanced.instanceMatrix.setUsage(DynamicDrawUsage);
+				root.add(this.instanced);
+			}
+			this.transformsDirty = true;
+		}
+		const inst = this.instanced;
+		if (!inst) return;
+		inst.castShadow = this.castShadow;
+		inst.receiveShadow = this.receiveShadow;
+		applyMeshMaterial(inst.material, this.material);
+		if (this.transformsDirty) {
+			this.transformsDirty = false;
+			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.setFromAxisAngle(UP, (row[3] ?? 0) * Math.PI / 180);
+				const s = row[4] ?? 1;
+				scaleScratch$1.set(s, s, s);
+				matScratch.compose(posScratch, quatScratch, scaleScratch$1);
+				inst.setMatrixAt(i, matScratch);
+			}
+			inst.instanceMatrix.needsUpdate = true;
+			inst.computeBoundingSphere();
+		}
+	}
+	free() {
+		if (this.instanced) {
+			this.instanced.geometry.dispose();
+			this.instanced.material.dispose();
+		}
+		super.free();
+	}
+};
+const UP = new Vector3(0, 1, 0);
+const posScratch = new Vector3();
+const quatScratch = new Quaternion();
+const scaleScratch$1 = new Vector3();
+const matScratch = new Matrix4();
+//#endregion
+//#region src/3d/nodes/lights-3d.ts
+/** Sun-style light. Direction comes from the node's rotation. */
+var DirectionalLight3D = class extends Node3D {
+	static typeName = "DirectionalLight3D";
+	static props = {
+		color: { default: "#ffffff" },
+		intensity: { default: 1 },
+		castShadow: { default: false },
+		shadowArea: { default: 75 },
+		shadowMapSize: { default: 2048 },
+		shadowFollowsCamera: { default: false }
+	};
+	color = "#ffffff";
+	intensity = 1;
+	castShadow = false;
+	/** Half-extent of the directional shadow frustum (template default ±75). */
+	shadowArea = 75;
+	shadowMapSize = 2048;
+	/**
+	* Re-center the shadow frustum on the camera every frame. A directional sun's
+	* shadow map covers a fixed ortho box; in a big roaming world that box must be
+	* huge (and so low-resolution that the player's own shadow nearly vanishes).
+	* With this on, a SMALL `shadowArea` tracks the camera, so contact shadows stay
+	* crisp wherever you go. The renderer supplies the camera position.
+	*/
+	shadowFollowsCamera = false;
+	_createObject3D() {
+		return new DirectionalLight();
+	}
+	_syncObject3D() {
+		super._syncObject3D();
+		const light = this._ensureObject3D();
+		light.color.set(this.color);
+		light.intensity = this.intensity;
+		light.castShadow = this.castShadow;
+		if (this.castShadow && "shadow" in light) {
+			const cam = light.shadow.camera;
+			if ("left" in cam) {
+				cam.left = -this.shadowArea;
+				cam.right = this.shadowArea;
+				cam.top = this.shadowArea;
+				cam.bottom = -this.shadowArea;
+				cam.near = .5;
+				cam.far = 500;
+				cam.updateProjectionMatrix();
+			}
+			light.shadow.mapSize.set(this.shadowMapSize, this.shadowMapSize);
+			light.shadow.bias = -2e-4;
+			light.shadow.normalBias = .002;
+		}
+	}
+};
+/** Point light with a range (Godot's OmniLight3D). */
+var OmniLight3D = class extends Node3D {
+	static typeName = "OmniLight3D";
+	static props = {
+		color: { default: "#ffffff" },
+		intensity: { default: 1 },
+		range: { default: 0 }
+	};
+	color = "#ffffff";
+	intensity = 1;
+	/** 0 = unlimited (three `distance` semantics). */
+	range = 0;
+	_createObject3D() {
+		return new PointLight();
+	}
+	_syncObject3D() {
+		super._syncObject3D();
+		const light = this._ensureObject3D();
+		light.color.set(this.color);
+		light.intensity = this.intensity;
+		light.distance = this.range;
+	}
+};
+//#endregion
 //#region src/3d/nodes/loft-mesh-3d.ts
 /**
 * A smooth swept hull ("loft"): superellipse cross-sections interpolated
@@ -5482,6 +5738,42 @@ function buildLoftGeometry(sections, slices, smooth) {
 	return geo;
 }
 //#endregion
+//#region src/3d/animation/layering.ts
+/**
+* Clip masking for two-layer animation (upper-body attack over lower-body
+* locomotion). three has no per-bone action weights, so layering is done at
+* the CLIP level: the upper action gets only the tracks under the layer root
+* (e.g. Spine), and the base action gets everything else — no track overlap,
+* no half-blended bones.
+*/
+/** Bone name a track drives — "mixamorigSpine.quaternion" → "mixamorigSpine". */
+function trackBone(trackName) {
+	const dot = trackName.lastIndexOf(".");
+	return dot === -1 ? trackName : trackName.slice(0, dot);
+}
+/**
+* A copy of `clip` with only the tracks whose bone IS (mode 'keep') or is
+* NOT (mode 'drop') in `bones`. Track arrays are shared (cheap); the clip
+* duration is preserved so layered actions stay time-aligned.
+*/
+function maskClip(clip, bones, mode) {
+	const tracks = clip.tracks.filter((t) => {
+		const inSet = bones.has(trackBone(t.name));
+		return mode === "keep" ? inSet : !inSet;
+	});
+	return new AnimationClip(`${clip.name}#${mode}`, clip.duration, tracks);
+}
+/** Collect the bone-name subtree from `root` (inclusive) — the layer mask. */
+function boneSubtree(root) {
+	const out = /* @__PURE__ */ new Set();
+	const walk = (o) => {
+		out.add(o.name);
+		for (const c of o.children) walk(c);
+	};
+	walk(root);
+	return out;
+}
+//#endregion
 //#region src/3d/animation/rigmap.ts
 /**
 * Mixamo rig name → VRM humanoid bone name (the vibe-starter-3d /
@@ -5615,6 +5907,8 @@ function retargetClipToVrm(clip, sourceScene, vrm) {
 //#region src/3d/nodes/model-instance-3d.ts
 /** Crossfade duration (s) between animation clips — smooths idle↔walk↔run↔jump. */
 const ANIM_CROSSFADE = .2;
+/** Upper-layer fade — snappier than locomotion blends (attacks must feel instant). */
+const UPPER_FADE = .12;
 /**
 * A GLB/glTF/VRM model. `model` is a `$key` into the scene's assets header
 * ({type:"model", url}) or a direct URL. `targetHeight` (>0) uniformly scales
@@ -5637,6 +5931,12 @@ var ModelInstance3D = class extends Node3D {
 		targetHeight: { default: 0 },
 		castShadow: { default: false },
 		animationLoop: { default: true },
+		/** Upper-body layer clip ('' = off). One-shots auto-clear on finish. */
+		animationUpper: { default: "" },
+		/** Loop the upper layer (false = one-shot: attack, wave, throw). */
+		animationUpperLoop: { default: false },
+		/** Bone whose subtree the upper layer drives (forgiving lookup). */
+		upperBodyRoot: { default: "Spine" },
 		receiveShadow: { default: false },
 		tint: { default: "" },
 		metalness: { default: -1 },
@@ -5648,6 +5948,16 @@ var ModelInstance3D = class extends Node3D {
 	castShadow = false;
 	/** false = play the clip once, then emit `animationFinished`. */
 	animationLoop = true;
+	/**
+	* Two-layer animation: play this clip on the UPPER BODY ONLY (the
+	* `upperBodyRoot` bone subtree) while `animation` keeps driving the rest —
+	* attack while running, wave while walking. One-shot by default
+	* (`animationUpperLoop: false`): finishes, emits `animationFinished` with
+	* this key, and auto-clears back to ''.
+	*/
+	animationUpper = "";
+	animationUpperLoop = false;
+	upperBodyRoot = "Spine";
 	receiveShadow = false;
 	/** Hex colour multiplied into every material — RESKIN one shared GLB into many
 	*  variants (e.g. a sickly-green zombie from the base human). '' = untinted. */
@@ -5666,6 +5976,12 @@ var ModelInstance3D = class extends Node3D {
 	mixer = null;
 	playing = "";
 	currentAction = null;
+	playingUpper = "";
+	upperAction = null;
+	/** Which variant the BASE action is playing ('lower' while a layer is on). */
+	baseMode = "full";
+	/** Masked-clip cache: source clip uuid + layer root → {upper, lower}. */
+	maskCache = /* @__PURE__ */ new Map();
 	/** action → the `animation` key that played it, so `animationFinished` reports
 	*  the clip that ACTUALLY finished (a crossfaded-away one-shot can finish a few
 	*  frames after `this.animation` already moved on). */
@@ -5759,6 +6075,12 @@ var ModelInstance3D = class extends Node3D {
 			this.mixer.addEventListener("finished", (e) => {
 				const action = e.action;
 				const key = (action && this.actionKeys.get(action)) ?? this.animation;
+				if (action && action === this.upperAction) {
+					action.fadeOut(UPPER_FADE);
+					this.upperAction = null;
+					this.playingUpper = "";
+					this.animationUpper = "";
+				}
 				this.emit("animationFinished", key);
 			});
 			this.playing = "";
@@ -5801,6 +6123,7 @@ var ModelInstance3D = class extends Node3D {
 		this.applyMaterialMods();
 		this.applyPoses();
 		this.syncAnimation(assets);
+		this.syncUpperAnimation(assets);
 	}
 	/** Apply per-instance material mods — `tint` (multiplied into colour) and the
 	*  `metalness`/`roughness` overrides — by cloning the captured originals
@@ -5844,33 +6167,68 @@ var ModelInstance3D = class extends Node3D {
 			if (obj) obj.rotation.set(rot[0] * DEG, rot[1] * DEG, rot[2] * DEG);
 		}
 	}
+	/** Resolve a clip ref: embedded name → '$asset' / URL (VRM-retargeted when
+	*  needed). 'loading' = asset still fetching, try again next frame. */
+	resolveClip(ref, assets) {
+		if (!this.entry) return null;
+		const embedded = this.entry.animations.find((c) => c.name === ref);
+		if (embedded) return embedded;
+		if (!(ref.startsWith("$") || /\.(glb|gltf)$/i.test(ref))) return null;
+		const anim = assets.getAnimation(ref);
+		if (anim.status === "loading") return "loading";
+		if (anim.status !== "ready" || !anim.scene) return null;
+		const source = (anim.clip ? anim.clips.find((c) => c.name === anim.clip) : void 0) ?? anim.clips[0];
+		if (!source) return null;
+		if (this.entry.isVrm && this.entry.vrm) {
+			const cached = this.entry.retargeted.get(ref);
+			if (cached) return cached;
+			const result = retargetClipToVrm(source, anim.scene, this.entry.vrm);
+			if (result.skippedBones.length > 0) console.warn(`incanto: retarget '${ref}' skipped bones: ${result.skippedBones.join(", ")}`);
+			this.entry.retargeted.set(ref, result.clip);
+			return result.clip;
+		}
+		return source;
+	}
+	/** Masked upper/lower variants of a clip for two-layer playback (cached). */
+	layerVariants(clip) {
+		const rootBone = this.findBone(this.upperBodyRoot);
+		if (!rootBone) return null;
+		const key = `${clip.uuid} ${rootBone.name}`;
+		let v = this.maskCache.get(key);
+		if (!v) {
+			const bones = boneSubtree(rootBone);
+			v = {
+				upper: maskClip(clip, bones, "keep"),
+				lower: maskClip(clip, bones, "drop")
+			};
+			this.maskCache.set(key, v);
+		}
+		return v;
+	}
+	upperLayerActive() {
+		return this.animationUpper !== "" || this.upperAction !== null;
+	}
 	syncAnimation(assets) {
-		if (!this.mixer || !this.entry || this.playing === this.animation) return;
+		if (!this.mixer || !this.entry) return;
+		const mode = this.upperLayerActive() ? "lower" : "full";
+		if (this.playing === this.animation && this.baseMode === mode) return;
 		if (this.animation === "") {
 			if (this.currentAction) this.currentAction.fadeOut(ANIM_CROSSFADE);
 			this.currentAction = null;
 			this.playing = "";
+			this.baseMode = mode;
 			return;
 		}
-		let clip = this.entry.animations.find((c) => c.name === this.animation) ?? null;
-		if (!clip && (this.animation.startsWith("$") || /\.(glb|gltf)$/i.test(this.animation))) {
-			const anim = assets.getAnimation(this.animation);
-			if (anim.status === "loading") return;
-			if (anim.status === "ready" && anim.scene) {
-				const source = (anim.clip ? anim.clips.find((c) => c.name === anim.clip) : void 0) ?? anim.clips[0];
-				if (source) if (this.entry.isVrm && this.entry.vrm) {
-					const cached = this.entry.retargeted.get(this.animation);
-					if (cached) clip = cached;
-					else {
-						const result = retargetClipToVrm(source, anim.scene, this.entry.vrm);
-						if (result.skippedBones.length > 0) console.warn(`incanto: retarget '${this.animation}' skipped bones: ${result.skippedBones.join(", ")}`);
-						this.entry.retargeted.set(this.animation, result.clip);
-						clip = result.clip;
-					}
-				} else clip = source;
-			}
+		const resolved = this.resolveClip(this.animation, assets);
+		if (resolved === "loading") return;
+		let clip = resolved;
+		if (clip && mode === "lower") {
+			const variants = this.layerVariants(clip);
+			if (variants) clip = variants.lower;
 		}
+		const samePlaying = this.playing === this.animation;
 		this.playing = this.animation;
+		this.baseMode = mode;
 		if (clip) {
 			const action = this.mixer.clipAction(clip);
 			action.reset();
@@ -5883,12 +6241,50 @@ var ModelInstance3D = class extends Node3D {
 			action.play();
 			this.actionKeys.set(action, this.animation);
 			if (this.currentAction && this.currentAction !== action) {
+				if (samePlaying && clip.duration > 0) action.time = this.currentAction.time % clip.duration;
 				const warp = clip.duration > 0 && this.currentAction.getClip().duration > 0;
 				action.crossFadeFrom(this.currentAction, ANIM_CROSSFADE, warp);
 			}
 			this.currentAction = action;
 		} else console.warn(`incanto: model '${this.model}' has no animation '${this.animation}' — embedded: ${this.entry.animations.map((c) => c.name).join(", ") || "(none)"}; assets: ${assets.animationRefs().join(", ") || "(none)"}`);
 	}
+	/** The upper-body layer: masked clip on the `upperBodyRoot` subtree. */
+	syncUpperAnimation(assets) {
+		if (!this.mixer || !this.entry || this.playingUpper === this.animationUpper) return;
+		if (this.animationUpper === "") {
+			this.upperAction?.fadeOut(UPPER_FADE);
+			this.upperAction = null;
+			this.playingUpper = "";
+			return;
+		}
+		const resolved = this.resolveClip(this.animationUpper, assets);
+		if (resolved === "loading") return;
+		if (!resolved) {
+			console.warn(`incanto: model '${this.model}' has no animation '${this.animationUpper}' for the upper layer.`);
+			this.playingUpper = this.animationUpper;
+			return;
+		}
+		const variants = this.layerVariants(resolved);
+		if (!variants) {
+			console.warn(`incanto: upperBodyRoot '${this.upperBodyRoot}' not found in '${this.model}' — upper layer skipped.`);
+			this.playingUpper = this.animationUpper;
+			return;
+		}
+		const action = this.mixer.clipAction(variants.upper);
+		action.reset();
+		if (this.animationUpperLoop) action.setLoop(LoopRepeat, Infinity);
+		else {
+			action.setLoop(LoopOnce, 1);
+			action.clampWhenFinished = true;
+		}
+		action.setEffectiveWeight(1);
+		action.fadeIn(UPPER_FADE);
+		action.play();
+		this.actionKeys.set(action, this.animationUpper);
+		if (this.upperAction && this.upperAction !== action) this.upperAction.fadeOut(UPPER_FADE);
+		this.upperAction = action;
+		this.playingUpper = this.animationUpper;
+	}
 	update(dt) {
 		this.mixer?.update(dt);
 		if (this.entry?.isVrm && this.entry.claimedBy === this) this.entry.vrm?.update(dt);
@@ -5906,6 +6302,10 @@ var ModelInstance3D = class extends Node3D {
 		this.fitGroup = null;
 		this.mixer = null;
 		this.currentAction = null;
+		this.upperAction = null;
+		this.playingUpper = "";
+		this.baseMode = "full";
+		this.maskCache.clear();
 		this.entry = null;
 		this.mountedRef = "";
 		this.playing = "";
@@ -8028,7 +8428,7 @@ var Tree3D = class Tree3D extends Node3D {
 		leafFadeStart: { default: 0 },
 		leafFadeEnd: { default: 0 },
 		leafShadows: { default: true },
-		drape: { default: false },
+		drape: { default: null },
 		terrain: { default: "" }
 	};
 	/** 'simple' (primitive low-poly) | 'medium' (light ez-trees) | 'high' (full). */
@@ -8057,11 +8457,14 @@ var Tree3D = class Tree3D extends Node3D {
 	/** Let leaves cast shadows. false keeps trunk/branch shadows but drops the
 	* expensive alpha-cutout leaf shadow pass (the dappled floor) for big FPS. */
 	leafShadows = true;
-	/** Drape the grove over a Terrain3D: each scattered instance roots at the
-	* ground height under it (not the node's single Y), so a patch on rolling or
-	* carved terrain never floats/buries. No effect on a count:1 tree placed by
-	* hand unless it sits off the ground. */
-	drape = false;
+	/**
+	* Drape the grove over a Terrain3D: each scattered instance roots at the
+	* ground height under it (not the node's single Y), so a patch on rolling
+	* or carved terrain never floats/buries. null (the default) is AUTO:
+	* whenever the scene has a Terrain3D the grove drapes onto it. true forces
+	* it (keeps retrying until a terrain appears), false disables draping.
+	*/
+	drape = null;
 	/** Node path to the Terrain3D to drape onto ('' = auto-find the first one). */
 	terrain = "";
 	/** Resolved drape target + the grove's world position, set per rebuild. */
@@ -8080,7 +8483,7 @@ var Tree3D = class Tree3D extends Node3D {
 		if (!((t.area[0] ?? 0) > 0) || !((t.area[1] ?? 0) > 0)) throw new IncantoError("BAD_FORMAT", `Tree3D '${node.name}' area must be positive [x, z] meters, got ${JSON.stringify(t.area)}.`, { prop: "area" });
 		if (t.leafFadeEnd !== 0 && !(t.leafFadeEnd > t.leafFadeStart && t.leafFadeStart >= 0)) throw new IncantoError("BAD_FORMAT", `Tree3D '${node.name}' needs leafFadeEnd > leafFadeStart >= 0 (the leaf LOD window) or 0/0 to disable, got start ${t.leafFadeStart}, end ${t.leafFadeEnd}.`, { prop: "leafFadeStart" });
 		if (typeof t.leafShadows !== "boolean") throw new IncantoError("BAD_FORMAT", `Tree3D '${node.name}' leafShadows must be a boolean, got ${JSON.stringify(t.leafShadows)}.`, { prop: "leafShadows" });
-		if (typeof t.drape !== "boolean") throw new IncantoError("BAD_FORMAT", `Tree3D '${node.name}' drape must be a boolean, got ${JSON.stringify(t.drape)}.`, { prop: "drape" });
+		if (t.drape !== null && typeof t.drape !== "boolean") throw new IncantoError("BAD_FORMAT", `Tree3D '${node.name}' drape must be true, false or null (null = auto: drape whenever the scene has a Terrain3D), got ${JSON.stringify(t.drape)}.`, { prop: "drape" });
 		if (typeof t.terrain !== "string") throw new IncantoError("BAD_FORMAT", `Tree3D '${node.name}' terrain must be a node-path string (empty = auto-find), got ${JSON.stringify(t.terrain)}.`, { prop: "terrain" });
 		if (t.tier === "simple") return;
 		const perTree = maxVariantTriangles(t.tier, t.type);
@@ -8157,7 +8560,7 @@ var Tree3D = class Tree3D extends Node3D {
 	/** Resolve the drape target + cache the grove's world position for `bedY`. */
 	resolveDrape() {
 		this.drapeTerrain = null;
-		if (!this.drape) return;
+		if (this.drape === false) return;
 		const terrain = findDrapeTerrain(this, this.terrain);
 		if (terrain) {
 			this.drapeTerrain = terrain;
@@ -11716,6 +12119,8 @@ function registerNodes3D() {
 	registerNode(Joint3D);
 	registerNode(Trail3D);
 	registerNode(BoneAttachment3D);
+	registerNode(BoneLookAt3D);
+	registerNode(InstancedMesh3D);
 	registerNode(Terrain3D);
 	registerNode(Water3D);
 	registerNode(Foliage3D);
@@ -11731,4 +12136,4 @@ function registerNodes3D() {
 	registerNode(CharacterBody3D);
 }
 //#endregion
-export { PhysicsBody3D as A, Terrain3D as C, Joint3D as D, terrainThemeLayers as E, QUARTER_PITCH as F, cameraRelative as I, keyboardIntensity as L, StaticBody3D as M, Node3D as N, Area3D as O, validateCollider3D as P, movementState as R, Billboard3D as S, TERRAIN_THEMES as T, resolveFlowerDensity as _, VoxelGrid3D as a, Camera3D as b, Particles3D as c, MeshInstance3D as d, DirectionalLight3D as f, Flowers3D as g, DENSITY_PRESETS as h, VOXEL_PALETTE as i, RigidBody3D as j, CharacterBody3D as k, ModelInstance3D as l, Foliage3D as m, Water3D as n, Tree3D as o, OmniLight3D as p, WATER_MAX_RIPPLES as r, Trail3D as s, registerNodes3D as t, LoftMesh3D as u, FLOWER_VARIETIES as v, DEFAULT_TERRAIN_TEXTURE_BASE as w, BoneAttachment3D as x, CharacterController3D as y, rigPose as z };
+export { Area3D as A, movementState as B, BoneAttachment3D as C, TERRAIN_THEMES as D, DEFAULT_TERRAIN_TEXTURE_BASE as E, Node3D as F, validateCollider3D as I, QUARTER_PITCH as L, PhysicsBody3D as M, RigidBody3D as N, terrainThemeLayers as O, StaticBody3D as P, cameraRelative as R, BoneLookAt3D as S, Terrain3D as T, rigPose as V, Flowers3D as _, VoxelGrid3D as a, CharacterController3D as b, Particles3D as c, DirectionalLight3D as d, OmniLight3D as f, DENSITY_PRESETS as g, Foliage3D as h, VOXEL_PALETTE as i, CharacterBody3D as j, Joint3D as k, ModelInstance3D as l, MeshInstance3D as m, Water3D as n, Tree3D as o, InstancedMesh3D as p, WATER_MAX_RIPPLES as r, Trail3D as s, registerNodes3D as t, LoftMesh3D as u, resolveFlowerDensity as v, Billboard3D as w, Camera3D as x, FLOWER_VARIETIES as y, keyboardIntensity as z };