incanto 0.4.2 → 0.5.0

package/dist/{register-02aSywx2.js → register-DvPHJdVj.js}

@@ -1,12 +1,12 @@
-import { f as Node } from "./loader-CGs_G-r0.js";
-import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-DYuSUxvK.js";
+import { f as Node } from "./loader-B4OEXDZ8.js";
+import { i as applyParticlePreset, r as PARTICLE_PRESET_NAMES, t as ParticleSim } from "./particle-sim-CFkILGwh.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { t as registerCoreNodes } from "./register-BuUV1_KB.js";
+import { t as registerCoreNodes } from "./register-Dl_ixIJe.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-BVJ2HbCn.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.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, 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, 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);
@@ -286,7 +286,21 @@ var PhysicsBody3D = class extends Node3D {
 	static props = { collider: { default: {} } };
 	/** The unified collision model: every collider participant can emit these. */
 	static signals = ["triggerEnter", "triggerExit"];
-	collider = {};
+	_collider = {};
+	/** @internal Physics resync flag — raised when `collider` is REPLACED. */
+	_colliderChanged = false;
+	/**
+	* Collider shape prop. Change it by REPLACING the object
+	* (`body.collider = { shape: 'box', size: [...] }`) — physics rebuilds the
+	* body on replacement; in-place mutation of the old object is not watched.
+	*/
+	get collider() {
+		return this._collider;
+	}
+	set collider(value) {
+		this._collider = value;
+		this._colliderChanged = true;
+	}
 	/** Loader hook: bad collider shapes fail at LOAD, not at physics start. */
 	static validateJson(node) {
 		const body = node;
@@ -373,6 +387,78 @@ var CharacterBody3D = class extends PhysicsBody3D {
 	}
 };
 //#endregion
+//#region src/3d/nodes/joint-3d.ts
+/**
+* A physics joint linking its PARENT body to `target` (a node path to the
+* other body). Godot-style placement: the joint lives as a child of body A.
+*
+*   { "name": "Hinge", "type": "Joint3D",
+*     "props": { "type": "spherical", "target": "%Anchor", "anchor": [0, -20] } }
+*
+* Types: `fixed` welds the bodies rigidly · `spherical` is a ball joint at the
+* anchors · `rope` caps the anchor distance at `length` (m; 0 = measured at
+* creation) · `spring` pulls toward `length` with `stiffness`/`damping`.
+* Anchors are LOCAL meter offsets on each body.
+*/
+var Joint3D = class extends Node3D {
+	static typeName = "Joint3D";
+	static props = {
+		type: {
+			default: "spherical",
+			options: [
+				"fixed",
+				"spherical",
+				"rope",
+				"spring"
+			]
+		},
+		target: { default: "" },
+		anchor: { default: [
+			0,
+			0,
+			0
+		] },
+		targetAnchor: { default: [
+			0,
+			0,
+			0
+		] },
+		length: { default: 0 },
+		stiffness: { default: 50 },
+		damping: { default: 5 }
+	};
+	type = "spherical";
+	target = "";
+	anchor = [
+		0,
+		0,
+		0
+	];
+	targetAnchor = [
+		0,
+		0,
+		0
+	];
+	/** rope/spring rest length in m; 0 = measure body distance at creation. */
+	length = 0;
+	stiffness = 50;
+	damping = 5;
+	onEnterTree() {
+		if (!(this.parent instanceof PhysicsBody3D)) throw new IncantoError("TREE_VIOLATION", `Joint3D '${this.name}' must be a child of a physics body (its body A); parent is '${this.parent?.name ?? "none"}'.`);
+		if (this.target === "") throw new IncantoError("BAD_FORMAT", `Joint3D '${this.name}' needs a "target" node path to the body it links to.`);
+	}
+	/** @internal The two bodies, resolved (throws on a bad target at step time). */
+	_resolveBodies() {
+		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.`);
+		return {
+			a,
+			b
+		};
+	}
+};
+//#endregion
 //#region src/3d/terrain/splat-material.ts
 /** Splice `code` immediately AFTER `marker` — a missing marker is a hard error
 * (a silently unpatched terrain shader renders weight-colored vertex soup). */
@@ -1362,7 +1448,8 @@ const SHADOW_CONTACT_PUSH = .5;
 *
 * - `texture`: image URL (sRGB), empty = hidden
 * - `size [w,h]`: quad size in world metres
-* - `billboard`: `"y"` upright yaw-to-camera · `"full"` face camera · `"none"` fixed
+* - `billboard`: `"y"` upright, screen-aligned yaw (shares the camera heading, so
+*   off-center sprites never roll) · `"full"` face camera · `"none"` fixed
 * - `anchor [ax,ay]`: pivot in 0..1 that sits at the node origin; `[0.5,0]` = feet
 * - `pixelArt`: nearest-filter for crisp pixels · `alphaTest`: cutout that depth-sorts
 */
@@ -1395,7 +1482,7 @@ var Sprite3D = class extends Node3D {
 	texture = "";
 	/** Quad `[width, height]` in world units (metres). */
 	size = [1, 1];
-	/** `"y"` upright yaw-to-camera · `"full"` face camera · `"none"` fixed. */
+	/** `"y"` upright, screen-aligned yaw (no off-center roll) · `"full"` face camera · `"none"` fixed. */
 	billboard = "y";
 	/** Pivot in 0..1 of the sprite that sits at the node origin; `[0.5,0]` = feet. */
 	anchor = [.5, 0];
@@ -1538,7 +1625,11 @@ var Sprite3D = class extends Node3D {
 	*  caster at the light. Headless runs have no Renderer3D and never call this, so
 	*  plain trees pay nothing. */
 	_onRender3D(ctx) {
-		if (this.billboard !== "none") this._faceToward(this._quad(), ctx.camera.position);
+		if (this.billboard === "y") {
+			ctx.camera.getWorldDirection(_dir$1);
+			_dir$1.y = 0;
+			if (_dir$1.lengthSq() >= 1e-6) this._faceDir(this._quad(), _dir$1.negate());
+		} else if (this.billboard === "full") this._faceToward(this._quad(), ctx.camera.position);
 		const caster = this.shadowMesh;
 		if (caster?.castShadow && ctx.sunDir) {
 			this._faceDir(caster, ctx.sunDir);
@@ -1697,8 +1788,6 @@ function resolveFrames(frames, name) {
 //#region src/3d/nodes/billboard-3d.ts
 const _parentQ = new Quaternion();
 const _rotQ = new Quaternion();
-const _pos = new Vector3();
-const _camPos = new Vector3();
 const _dir = new Vector3();
 const Z_AXIS = new Vector3(0, 0, 1);
 /** Valid `Billboard3D.mode` values — drives the prop options AND validateJson. */
@@ -1736,7 +1825,7 @@ var Billboard3D = class extends Node3D {
 		options: BILLBOARD_GROUP_MODES
 	} };
 	/** `"screen"` copy the camera orientation (screen-aligned) · `"y"` upright
-	*  yaw-to-camera · `"none"` billboarding off (authored rotation applies). */
+	*  screen-aligned yaw (no off-center roll) · `"none"` off (authored rotation applies). */
 	mode = "screen";
 	/** Last successfully billboarded WORLD orientation — reapplied on the frames
 	*  where `"y"` has no answer (camera dead overhead), because `_syncObject3D`
@@ -1759,11 +1848,9 @@ var Billboard3D = class extends Node3D {
 		const o = this._ensureObject3D();
 		if (this.mode === "screen") ctx.camera.getWorldQuaternion(_rotQ);
 		else {
-			o.getWorldPosition(_pos);
-			ctx.camera.getWorldPosition(_camPos);
-			_dir.copy(_camPos).sub(_pos);
+			ctx.camera.getWorldDirection(_dir);
 			_dir.y = 0;
-			if (_dir.lengthSq() >= 1e-12) _rotQ.setFromUnitVectors(Z_AXIS, _dir.normalize());
+			if (_dir.lengthSq() >= 1e-6) _rotQ.setFromUnitVectors(Z_AXIS, _dir.negate().normalize());
 			else if (this._lastDesired) _rotQ.copy(this._lastDesired);
 			else return;
 		}
@@ -4884,6 +4971,9 @@ const MATERIAL_KEYS = [
 	"wireframe",
 	"flatShading",
 	"opacity",
+	"clearcoat",
+	"clearcoatRoughness",
+	"envMapIntensity",
 	"depthTest",
 	"depthWrite",
 	"map",
@@ -4896,7 +4986,8 @@ const MATERIAL_KEYS = [
 * - `size [x,y,z]`: box extents; sphere/gem radius = x; capsule radius = x,
 *   height = y; plane = x·z ground plane (laid flat); cylinder radius = x, height = y
 * - `material`: `{color, metalness, roughness, wireframe, flatShading, opacity,
-*   depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat}` —
+*   clearcoat, clearcoatRoughness, envMapIntensity, depthTest, depthWrite,
+*   emissive, emissiveIntensity, map, normalMap, repeat}` —
 *   `map`/`normalMap` are texture URLs loaded lazily (headless-safe: geometry and
 *   physics never wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading:
 *   true` + a low `roughness` reads as a sparkling faceted jewel (spin it for the
@@ -4937,13 +5028,13 @@ var MeshInstance3D = class extends Node3D {
 	receiveShadow = false;
 	/** Loader hook: malformed materials fail at LOAD time, not at render. */
 	static validateJson(node) {
-		validateMaterial(node.material, node.name);
+		validateMeshMaterial(node.material, node.name);
 	}
 	geometryKey = "";
 	textureKey = "";
 	loadedTextures = [];
 	_createObject3D() {
-		return new Mesh(new BoxGeometry(1, 1, 1), new MeshStandardMaterial());
+		return new Mesh(new BoxGeometry(1, 1, 1), new MeshPhysicalMaterial());
 	}
 	_syncObject3D() {
 		super._syncObject3D();
@@ -4955,22 +5046,7 @@ var MeshInstance3D = class extends Node3D {
 			this.geometryKey = key;
 		}
 		const mat = m.material;
-		mat.color.set(this.material.color ?? "#ffffff");
-		mat.metalness = this.material.metalness ?? 0;
-		mat.roughness = this.material.roughness ?? 1;
-		mat.wireframe = this.material.wireframe ?? false;
-		mat.emissive.set(this.material.emissive ?? "#000000");
-		mat.emissiveIntensity = this.material.emissiveIntensity ?? 1;
-		const opacity = this.material.opacity ?? 1;
-		mat.opacity = opacity;
-		mat.transparent = opacity < 1;
-		mat.depthTest = this.material.depthTest ?? true;
-		mat.depthWrite = this.material.depthWrite ?? true;
-		const flat = this.material.flatShading ?? false;
-		if (mat.flatShading !== flat) {
-			mat.flatShading = flat;
-			mat.needsUpdate = true;
-		}
+		applyMeshMaterial(mat, this.material);
 		this.syncTextures(mat);
 		m.castShadow = this.castShadow;
 		m.receiveShadow = this.receiveShadow;
@@ -5013,11 +5089,42 @@ var MeshInstance3D = class extends Node3D {
 		super.free();
 	}
 };
+/**
+* Apply the shared material-prop pipeline (everything except textures) with
+* reset-to-default semantics: the JSON object IS the material state — a
+* replaced `{color}` must not keep a stale wireframe from a previous value.
+* Shared by every node that takes a `MeshMaterialProps` (MeshInstance3D,
+* LoftMesh3D).
+*/
+function applyMeshMaterial(mat, props) {
+	mat.color.set(props.color ?? "#ffffff");
+	mat.metalness = props.metalness ?? 0;
+	mat.roughness = props.roughness ?? 1;
+	mat.wireframe = props.wireframe ?? false;
+	mat.emissive.set(props.emissive ?? "#000000");
+	mat.emissiveIntensity = props.emissiveIntensity ?? 1;
+	const opacity = props.opacity ?? 1;
+	mat.opacity = opacity;
+	mat.transparent = opacity < 1;
+	const clearcoat = props.clearcoat ?? 0;
+	if (mat.clearcoat > 0 !== clearcoat > 0) mat.needsUpdate = true;
+	mat.clearcoat = clearcoat;
+	mat.clearcoatRoughness = props.clearcoatRoughness ?? 0;
+	mat.envMapIntensity = props.envMapIntensity ?? 1;
+	mat.depthTest = props.depthTest ?? true;
+	mat.depthWrite = props.depthWrite ?? true;
+	const flat = props.flatShading ?? false;
+	if (mat.flatShading !== flat) {
+		mat.flatShading = flat;
+		mat.needsUpdate = true;
+	}
+}
 /** Hard-fail on malformed material JSON — typos and bad shapes surface at
-* load with the valid options, instead of silently rendering defaults. */
-function validateMaterial(material, name) {
+* load with the valid options, instead of silently rendering defaults.
+* Exported for nodes that reuse `MeshMaterialProps` (LoftMesh3D). */
+function validateMeshMaterial(material, name, typeName = "MeshInstance3D") {
 	const fail = (message) => {
-		throw new IncantoError("BAD_FORMAT", `MeshInstance3D '${name}' ${message}`, {
+		throw new IncantoError("BAD_FORMAT", `${typeName} '${name}' ${message}`, {
 			prop: "material",
 			validOptions: [...MATERIAL_KEYS]
 		});
@@ -5036,11 +5143,14 @@ function validateMaterial(material, name) {
 	for (const key of [
 		"metalness",
 		"roughness",
-		"opacity"
+		"opacity",
+		"clearcoat",
+		"clearcoatRoughness"
 	]) {
 		const value = material[key];
 		if (value !== void 0 && !(typeof value === "number" && value >= 0 && value <= 1)) fail(`material.${key} must be a number in 0..1, got ${JSON.stringify(value)}.`);
 	}
+	if (material.envMapIntensity !== void 0 && !(typeof material.envMapIntensity === "number" && Number.isFinite(material.envMapIntensity) && material.envMapIntensity >= 0)) fail(`material.envMapIntensity must be a number >= 0, got ${JSON.stringify(material.envMapIntensity)}.`);
 	for (const key of [
 		"wireframe",
 		"flatShading",
@@ -5070,6 +5180,185 @@ function buildGeometry(kind, size) {
 	}
 }
 //#endregion
+//#region src/3d/nodes/loft-mesh-3d.ts
+/**
+* A smooth swept hull ("loft"): superellipse cross-sections interpolated
+* along Z with rounded end caps and per-vertex normals — curved highlights
+* and sky reflections sweep across it like sheet metal, which no box/capsule
+* assembly can do. THE node for vehicle bodies, glass canopies, boat hulls,
+* fuselages.
+*
+* - `sections`: ≥2 stations front→back (see LoftSection)
+* - `slices`: vertices around each ring (8..64, default 24)
+* - `smooth`: interpolated rings per section gap (1..16, default 4)
+* - `material`: same object as MeshInstance3D **minus textures** (a loft has
+*   no UVs — map/normalMap/repeat hard-fail). Pair `clearcoat` paint or a
+*   high `envMapIntensity` glass with the smooth normals for the automotive
+*   look.
+*/
+var LoftMesh3D = class extends Node3D {
+	static typeName = "LoftMesh3D";
+	static props = {
+		sections: { default: [] },
+		slices: { default: 24 },
+		smooth: { default: 4 },
+		material: { default: {} },
+		castShadow: { default: false },
+		receiveShadow: { default: false }
+	};
+	sections = [];
+	slices = 24;
+	smooth = 4;
+	material = {};
+	castShadow = false;
+	receiveShadow = false;
+	/** Loader hook: malformed sections/materials fail at LOAD time. */
+	static validateJson(node) {
+		const loft = node;
+		validateSections(loft.sections, node.name);
+		validateMeshMaterial(loft.material, node.name, "LoftMesh3D");
+		for (const key of [
+			"map",
+			"normalMap",
+			"repeat"
+		]) if (loft.material[key] !== void 0) throw new IncantoError("BAD_FORMAT", `LoftMesh3D '${node.name}' material does not support '${key}' — a loft has no UVs; use color/metalness/roughness/clearcoat/envMapIntensity instead.`, { prop: "material" });
+	}
+	geometryKey = "";
+	_createObject3D() {
+		return new Mesh(new BufferGeometry(), new MeshPhysicalMaterial());
+	}
+	_syncObject3D() {
+		super._syncObject3D();
+		const m = this._ensureObject3D();
+		const key = JSON.stringify([
+			this.sections,
+			this.slices,
+			this.smooth
+		]);
+		if (key !== this.geometryKey && this.sections.length >= 2) {
+			m.geometry.dispose();
+			m.geometry = buildLoftGeometry(this.sections, this.slices, this.smooth);
+			this.geometryKey = key;
+		}
+		applyMeshMaterial(m.material, this.material);
+		m.castShadow = this.castShadow;
+		m.receiveShadow = this.receiveShadow;
+	}
+};
+function validateSections(sections, name) {
+	const fail = (message) => {
+		throw new IncantoError("BAD_FORMAT", `LoftMesh3D '${name}' ${message}`, { prop: "sections" });
+	};
+	if (!Array.isArray(sections) || sections.length < 2) fail(`sections needs at least 2 stations, got ${JSON.stringify(sections)}.`);
+	for (const [i, s] of sections.entries()) {
+		if (typeof s !== "object" || s === null) fail(`sections[${i}] must be an object.`);
+		for (const k of [
+			"z",
+			"width",
+			"height",
+			"y"
+		]) if (typeof s[k] !== "number" || !Number.isFinite(s[k])) fail(`sections[${i}].${k} must be a finite number, got ${JSON.stringify(s[k])}.`);
+		if (s.width <= 0 || s.height <= 0) fail(`sections[${i}] width/height must be positive, got ${s.width}×${s.height}.`);
+		if (s.corner !== void 0 && !(typeof s.corner === "number" && s.corner >= 0 && s.corner <= 1)) fail(`sections[${i}].corner must be in 0..1, got ${JSON.stringify(s.corner)}.`);
+		if (i > 0 && s.z <= sections[i - 1].z) fail(`sections[].z must be strictly ascending (sections[${i}].z=${s.z}).`);
+	}
+}
+/** Endpoint-clamped Catmull-Rom through scalar samples. */
+function catmullRom(p0, p1, p2, p3, t) {
+	const t2 = t * t;
+	const t3 = t2 * t;
+	return .5 * (2 * p1 + (p2 - p0) * t + (2 * p0 - 5 * p1 + 4 * p2 - p3) * t2 + (-p0 + 3 * p1 - 3 * p2 + p3) * t3);
+}
+/** Sample the section list into (K-1)*smooth+1 interpolated rings. */
+function sampleRings(sections, smooth) {
+	const get = (i) => {
+		const s = sections[Math.max(0, Math.min(sections.length - 1, i))];
+		return {
+			z: s.z,
+			width: s.width,
+			height: s.height,
+			y: s.y,
+			corner: s.corner ?? .7
+		};
+	};
+	const rings = [];
+	for (let i = 0; i < sections.length - 1; i++) {
+		const a = get(i - 1);
+		const b = get(i);
+		const c = get(i + 1);
+		const d = get(i + 2);
+		const steps = i === sections.length - 2 ? smooth + 1 : smooth;
+		for (let s = 0; s < steps; s++) {
+			const t = s / smooth;
+			rings.push({
+				z: catmullRom(a.z, b.z, c.z, d.z, t),
+				width: Math.max(1e-4, catmullRom(a.width, b.width, c.width, d.width, t)),
+				height: Math.max(1e-4, catmullRom(a.height, b.height, c.height, d.height, t)),
+				y: catmullRom(a.y, b.y, c.y, d.y, t),
+				corner: Math.min(1, Math.max(0, catmullRom(a.corner, b.corner, c.corner, d.corner, t)))
+			});
+		}
+	}
+	return rings;
+}
+/**
+* Build the swept surface: ring grid + two cap-centre vertices, indexed
+* without a seam so `computeVertexNormals` shades the hull perfectly smooth.
+*/
+function buildLoftGeometry(sections, slices, smooth) {
+	const S = Math.max(8, Math.min(64, Math.round(slices)));
+	const rings = sampleRings(sections, Math.max(1, Math.min(16, Math.round(smooth))));
+	const R = rings.length;
+	const positions = new Float32Array((R * S + 2) * 3);
+	const first = rings[0];
+	const last = rings[R - 1];
+	positions.set([
+		0,
+		first.y,
+		first.z
+	], 0);
+	positions.set([
+		0,
+		last.y,
+		last.z
+	], 3);
+	for (let i = 0; i < R; i++) {
+		const ring = rings[i];
+		const nTop = 8 - 6 * ring.corner;
+		const nBottom = Math.max(nTop, 5);
+		for (let j = 0; j < S; j++) {
+			const theta = j / S * Math.PI * 2;
+			const c = Math.cos(theta);
+			const sn = Math.sin(theta);
+			const n = sn >= 0 ? nTop : nBottom;
+			const x = ring.width / 2 * Math.sign(c) * Math.abs(c) ** (2 / n);
+			const yy = ring.height / 2 * Math.sign(sn) * Math.abs(sn) ** (2 / n);
+			const v = (2 + i * S + j) * 3;
+			positions[v] = x;
+			positions[v + 1] = ring.y + yy;
+			positions[v + 2] = ring.z;
+		}
+	}
+	const indices = [];
+	const at = (i, j) => 2 + i * S + j % S;
+	for (let i = 0; i < R - 1; i++) for (let j = 0; j < S; j++) {
+		const a = at(i, j);
+		const b = at(i, j + 1);
+		const c = at(i + 1, j);
+		const d = at(i + 1, j + 1);
+		indices.push(a, b, c, b, d, c);
+	}
+	for (let j = 0; j < S; j++) {
+		indices.push(0, at(0, j + 1), at(0, j));
+		indices.push(1, at(R - 1, j), at(R - 1, j + 1));
+	}
+	const geo = new BufferGeometry();
+	geo.setAttribute("position", new BufferAttribute(positions, 3));
+	geo.setIndex(indices);
+	geo.computeVertexNormals();
+	return geo;
+}
+//#endregion
 //#region src/3d/animation/rigmap.ts
 /**
 * Mixamo rig name → VRM humanoid bone name (the vibe-starter-3d /
@@ -5226,7 +5515,9 @@ var ModelInstance3D = class extends Node3D {
 		castShadow: { default: false },
 		animationLoop: { default: true },
 		receiveShadow: { default: false },
-		tint: { default: "" }
+		tint: { default: "" },
+		metalness: { default: -1 },
+		roughness: { default: -1 }
 	};
 	model = "";
 	animation = "";
@@ -5238,6 +5529,12 @@ var ModelInstance3D = class extends Node3D {
 	/** Hex colour multiplied into every material — RESKIN one shared GLB into many
 	*  variants (e.g. a sickly-green zombie from the base human). '' = untinted. */
 	tint = "";
+	/** Override every material's metalness (0..1); -1 keeps the authored value.
+	*  Low-poly kits often ship fully rough — 0.5–0.8 turns flat paint into a
+	*  glinting clear-coat under the scene's IBL. Cloned per instance like tint. */
+	metalness = -1;
+	/** Override every material's roughness (0..1); -1 keeps the authored value. */
+	roughness = -1;
 	store = null;
 	entry = null;
 	mountedRef = "";
@@ -5251,11 +5548,25 @@ var ModelInstance3D = class extends Node3D {
 	*  frames after `this.animation` already moved on). */
 	actionKeys = /* @__PURE__ */ new WeakMap();
 	warnedClaim = false;
-	/** Per-mesh original (shared) materials, captured at mount so `tint` can always
-	*  re-derive from the source. Our clones are tracked for disposal. */
+	/** Per-mesh original (shared) materials, captured at mount so tint/overrides
+	*  can always re-derive from the source. Our clones are tracked for disposal. */
 	tintTargets = [];
 	tintedClones = [];
-	appliedTint = "";
+	appliedMods = "";
+	/** Named sub-node poses (degrees), re-applied every sync — drive wheels,
+	*  turrets, doors from behaviors without touching three directly. */
+	nodePoses = /* @__PURE__ */ new Map();
+	/**
+	* Rotate a named sub-node of the loaded model (local Euler XYZ, degrees) —
+	* e.g. spin a GLB car's `wheel-front-left` every frame, aim a turret, swing a
+	* door. Poses persist and re-apply on every sync (safe to set before the
+	* model finishes loading). Unknown names are ignored. `npx incanto-model
+	* <file>` lists a model's node names.
+	*/
+	poseNode(name, rotation) {
+		this.nodePoses.set(name, rotation);
+		this.applyPoses();
+	}
 	_createObject3D() {
 		return new Group();
 	}
@@ -5309,7 +5620,7 @@ var ModelInstance3D = class extends Node3D {
 			});
 			this.tintTargets = [];
 			this.tintedClones = [];
-			this.appliedTint = "";
+			this.appliedMods = "";
 			instance.traverse((obj) => {
 				const mesh = obj;
 				if (mesh.isMesh && mesh.material) this.tintTargets.push({
@@ -5338,34 +5649,51 @@ var ModelInstance3D = class extends Node3D {
 				mesh.receiveShadow = this.receiveShadow;
 			}
 		});
-		this.applyTint();
+		this.applyMaterialMods();
+		this.applyPoses();
 		this.syncAnimation(assets);
 	}
-	/** Multiply `tint` into every material — a per-instance reskin of one shared
-	*  GLB (e.g. base human → green zombie). Clones the captured originals (never
-	*  mutates the shared source), disposing prior clones on change. */
-	applyTint() {
-		if (this.tint === this.appliedTint) return;
+	/** Apply per-instance material mods — `tint` (multiplied into colour) and the
+	*  `metalness`/`roughness` overrides — by cloning the captured originals
+	*  (never mutates the shared source), disposing prior clones on change. */
+	applyMaterialMods() {
+		const key = `${this.tint}|${this.metalness}|${this.roughness}`;
+		if (key === this.appliedMods) return;
 		for (const c of this.tintedClones) c.dispose();
 		this.tintedClones = [];
 		const tint = this.tint ? new Color(this.tint) : null;
+		const hasMods = tint !== null || this.metalness >= 0 || this.roughness >= 0;
 		for (const t of this.tintTargets) {
-			if (!tint) {
+			if (!hasMods) {
 				t.mesh.material = t.original;
 				continue;
 			}
-			const tintOne = (src) => {
+			const modOne = (src) => {
 				const clone = src.clone();
-				const cm = clone;
-				const sc = src.color;
-				if (cm.color) cm.color = sc ? sc.clone().multiply(tint) : tint.clone();
+				if (tint) {
+					const cm = clone;
+					const sc = src.color;
+					if (cm.color) cm.color = sc ? sc.clone().multiply(tint) : tint.clone();
+				}
+				const pbr = clone;
+				if (this.metalness >= 0 && typeof pbr.metalness === "number") pbr.metalness = this.metalness;
+				if (this.roughness >= 0 && typeof pbr.roughness === "number") pbr.roughness = this.roughness;
 				clone.userData.incantoTinted = true;
 				this.tintedClones.push(clone);
 				return clone;
 			};
-			t.mesh.material = Array.isArray(t.original) ? t.original.map(tintOne) : tintOne(t.original);
+			t.mesh.material = Array.isArray(t.original) ? t.original.map(modOne) : modOne(t.original);
+		}
+		this.appliedMods = key;
+	}
+	/** Re-apply every queued named-node pose onto the mounted instance. */
+	applyPoses() {
+		if (!this.fitGroup || this.nodePoses.size === 0) return;
+		const DEG = Math.PI / 180;
+		for (const [name, rot] of this.nodePoses) {
+			const obj = this.fitGroup.getObjectByName(name);
+			if (obj) obj.rotation.set(rot[0] * DEG, rot[1] * DEG, rot[2] * DEG);
 		}
-		this.appliedTint = this.tint;
 	}
 	syncAnimation(assets) {
 		if (!this.mixer || !this.entry || this.playing === this.animation) return;
@@ -5425,7 +5753,7 @@ var ModelInstance3D = class extends Node3D {
 		for (const c of this.tintedClones) c.dispose();
 		this.tintedClones = [];
 		this.tintTargets = [];
-		this.appliedTint = "";
+		this.appliedMods = "";
 		this.fitGroup = null;
 		this.mixer = null;
 		this.currentAction = null;
@@ -5572,7 +5900,7 @@ var Particles3D = class Particles3D extends Node3D {
 				gravity: [
 					(this.gravity[0] ?? 0) * PX_TO_M,
 					(this.gravity[1] ?? 0) * PX_TO_M,
-					0
+					(this.gravity[2] ?? 0) * PX_TO_M
 				],
 				drag: this.drag,
 				maxParticles: this.maxParticles,
@@ -5583,6 +5911,7 @@ var Particles3D = class Particles3D extends Node3D {
 	}
 	update(dt) {
 		const sim = this._ensureSim();
+		sim.setRate(this.emitting ? this.rate : 0);
 		if (this.burst > 0 && !this.bursted) {
 			this.bursted = true;
 			sim.burst(this.burst);
@@ -11094,11 +11423,13 @@ function registerNodes3D() {
 	registerNode(Node3D);
 	registerNode(Particles3D);
 	registerNode(MeshInstance3D);
+	registerNode(LoftMesh3D);
 	registerNode(Sprite3D);
 	registerNode(AnimatedSprite3D);
 	registerNode(Billboard3D);
 	registerNode(CharacterController3D);
 	registerNode(VoxelGrid3D);
+	registerNode(Joint3D);
 	registerNode(Terrain3D);
 	registerNode(Water3D);
 	registerNode(Foliage3D);
@@ -11114,4 +11445,4 @@ function registerNodes3D() {
 	registerNode(CharacterBody3D);
 }
 //#endregion
-export { validateCollider3D as A, terrainThemeLayers as C, RigidBody3D as D, PhysicsBody3D as E, rigPose as F, cameraRelative as M, keyboardIntensity as N, StaticBody3D as O, movementState as P, TERRAIN_THEMES as S, CharacterBody3D as T, CharacterController3D as _, VoxelGrid3D as a, Terrain3D as b, ModelInstance3D as c, OmniLight3D as d, Foliage3D as f, FLOWER_VARIETIES as g, resolveFlowerDensity as h, VOXEL_PALETTE as i, QUARTER_PITCH as j, Node3D as k, MeshInstance3D as l, Flowers3D as m, Water3D as n, Tree3D as o, DENSITY_PRESETS as p, WATER_MAX_RIPPLES as r, Particles3D as s, registerNodes3D as t, DirectionalLight3D as u, Camera3D as v, Area3D as w, DEFAULT_TERRAIN_TEXTURE_BASE as x, Billboard3D as y };
+export { StaticBody3D as A, TERRAIN_THEMES as C, CharacterBody3D as D, Area3D as E, keyboardIntensity as F, movementState as I, rigPose as L, validateCollider3D as M, QUARTER_PITCH as N, PhysicsBody3D as O, cameraRelative as P, DEFAULT_TERRAIN_TEXTURE_BASE as S, Joint3D as T, FLOWER_VARIETIES as _, VoxelGrid3D as a, Billboard3D as b, ModelInstance3D as c, DirectionalLight3D as d, OmniLight3D as f, resolveFlowerDensity as g, Flowers3D as h, VOXEL_PALETTE as i, Node3D as j, RigidBody3D as k, LoftMesh3D as l, DENSITY_PRESETS as m, Water3D as n, Tree3D as o, Foliage3D as p, WATER_MAX_RIPPLES as r, Particles3D as s, registerNodes3D as t, MeshInstance3D as u, CharacterController3D as v, terrainThemeLayers as w, Terrain3D as x, Camera3D as y };

package/dist/test.d.ts

@@ -1,6 +1,6 @@
 import { c as JsonValue, i as SceneJson } from "./schema-CcoWb32N.js";
-import { O as LogEntry, T as Node, n as BehaviorCtor, v as Engine, w as Scene } from "./behavior-BAQq7HGM.js";
-import { t as LoadSceneOptions } from "./loader-Mo0KghCv.js";
+import { O as LogEntry, T as Node, n as BehaviorCtor, v as Engine, w as Scene } from "./behavior-CWhW3oa6.js";
+import { t as LoadSceneOptions } from "./loader-D2u0fVW2.js";
 import { t as IncantoError } from "./errors-BMFaY68Q.js";
 
 //#region src/test/index.d.ts