incanto 0.69.0 → 0.71.0

package/dist/{physics-2d-CF5yyjbj.js → physics-2d-FhrXUc6B.js}

@@ -1,7 +1,7 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { k as diagnose } from "./loader-DZE7B07H.js";
+import { o as __exportAll } from "./json-CfTjpvW8.js";
+import { Y as diagnose } from "./save-slots-Bvuh2p_r.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-DbVArsns.js";
+import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-BYQCBySi.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
 //#region src/2d/physics/physics-2d.ts
@@ -108,8 +108,10 @@ var Physics2D = class {
 				}
 				const lv = e.body.linvel();
 				node.linearVelocity = [lv.x * SCALE, lv.y * SCALE];
+				node.angularVelocity = e.body.angvel();
 				e.lastVX = node.linearVelocity[0] ?? 0;
 				e.lastVY = node.linearVelocity[1] ?? 0;
+				e.lastAV = node.angularVelocity;
 			}
 			const t2 = e.body.translation();
 			e.lastX = t2.x * SCALE;
@@ -130,6 +132,29 @@ var Physics2D = class {
 			}
 		});
 	}
+	/**
+	* May `candidate` carry `rider`?
+	*
+	* The rule used to be "never a CharacterBody2D", which is the whole CLASS —
+	* and a `CharacterBody2D` animated by POSITION WRITES is the documented
+	* moving-platform path (`Oscillate`, `MoveTo`, `PathFollow`, or a behaviour of
+	* your own). `incanto-physics-and-input.md` promises twice that a character
+	* standing on ANY moving body is carried; it was not, and the rider reported
+	* `isOnFloor() === true` the whole time while sliding off in world space.
+	*
+	* What the guard was really for is a CYCLE: two characters standing on each
+	* other would carry each other forever. So the test is the rider's own
+	* carrier chain, not the type — a platform that is not (transitively) riding
+	* you can carry you.
+	*/
+	canCarry(rider, candidate) {
+		let at = candidate;
+		for (let depth = 0; depth < 8 && at; depth++) {
+			if (at === rider) return false;
+			at = this.entries.get(at)?.ground ?? null;
+		}
+		return true;
+	}
 	/** @internal Called by CharacterBody2D.moveAndSlide (during tree fixedUpdate). */
 	moveAndSlide(node) {
 		const e = this.ensureEntry(node);
@@ -137,6 +162,8 @@ var Physics2D = class {
 		if (node.stickToGround && vy >= 0) this.kcc.enableSnapToGround(.05);
 		else this.kcc.disableSnapToGround();
 		this.kcc.setMaxSlopeClimbAngle(node.slopeLimitDeg * DEG);
+		if (node.stepHeight > 0) this.kcc.enableAutostep(node.stepHeight / SCALE, node.stepHeight / SCALE / 2, false);
+		else this.kcc.disableAutostep();
 		let carryX = 0;
 		let carryY = 0;
 		if (e.ground && e.ground._physics === this) {
@@ -144,9 +171,10 @@ var Physics2D = class {
 			carryX = gx - (e.groundX ?? gx);
 			carryY = gy - (e.groundY ?? gy);
 		} else e.ground = null;
+		const vyTerm = carryY < -.1 && node.isOnFloor?.() === true && vy > 0 ? 0 : vy * this.lastDt;
 		const desired = {
 			x: ((node.velocity[0] ?? 0) * this.lastDt + carryX) / SCALE * 1,
-			y: (vy * this.lastDt + carryY) / SCALE * 1
+			y: (vyTerm + carryY) / SCALE * 1
 		};
 		const charBottomPx = e.body.translation().y * SCALE + charHalfHeight(node);
 		const predicate = (collider) => {
@@ -171,7 +199,7 @@ var Physics2D = class {
 		for (let i = 0; i < hits; i++) {
 			const n = this.kcc.computedCollision(i)?.normal1;
 			if (!n) continue;
-			if (Math.abs(n.y) > .7) {
+			if (n.y > .7) {
 				if (!node._grounded) node._onCeiling = true;
 			} else if (Math.abs(n.x) > .7) node._onWall = n.x > 0 ? -1 : 1;
 		}
@@ -179,7 +207,7 @@ var Physics2D = class {
 			const footX = (t.x + corrected.x) * SCALE;
 			const footY = (t.y + corrected.y) * SCALE + charHalfHeight(node) - 2;
 			const hit = this.castRay([footX, footY], [0, 1], 8, node);
-			if (hit?.node && !(hit.node instanceof CharacterBody2D)) {
+			if (hit?.node && this.canCarry(node, hit.node)) {
 				e.ground = hit.node;
 				const [gx, gy] = worldPosition2D(hit.node);
 				e.groundX = gx;
@@ -340,13 +368,48 @@ var Physics2D = class {
 		return [...set];
 	}
 	/**
-	* World-space raycast in PIXELS (y-down). `exclude` skips that body — a
+	* Mass the solver actually uses (collider-derived unless overridden).
+	*
+	* The 3D twin has had this since `CharacterController3D` needed it to size an
+	* impulse; 2D had no way to ask, so a 2D game scaling a push by mass had to
+	* read the AUTHORED `mass` prop and hope it was the number Rapier settled on.
+	*/
+	massOf(node) {
+		return this.entries.get(node)?.body.mass() ?? 1;
+	}
+	/**
+	* Current solver velocity in px/s (fresher than the node prop mid-step).
+	*
+	* `linearVelocity` is written back once per step, so a behavior reading it
+	* from inside `fixedUpdate` — after a collision, before the write-back — sees
+	* the value from BEFORE the impact. That is exactly when a game wants to know
+	* how hard it hit something.
+	*/
+	velocityOf(node) {
+		const v = this.entries.get(node)?.body.linvel();
+		return v ? [v.x * SCALE, v.y * SCALE] : [0, 0];
+	}
+	/**
+	* A world-space impulse in px.kg/s (y-down) — the 2D twin of
+	* `Physics3D.applyImpulse`, which the physics skill has documented for both
+	* adapters while only one of them had it.
+	*/
+	applyImpulse(node, impulse) {
+		this.entries.get(node)?.body.applyImpulse({
+			x: impulse[0] / SCALE,
+			y: impulse[1] / SCALE
+		}, true);
+	}
+	/**
+	* World-space raycast in PIXELS (y-down); `dir` may be any length (it is
+	* normalized), so `distance` and `maxLen` are pixels. `exclude` skips that body — a
 	* shooter probing from inside its own collider needs it. Sensors (Area2D)
 	* never block rays. Returns distance (px), the surface normal, and the hit
 	* body — or null.
 	*/
 	castRay(origin, dir, maxLen, exclude, opts) {
-		const len = Math.hypot(dir[0], dir[1]) || 1;
+		const len = Math.hypot(dir[0], dir[1]);
+		if (!(len > 0)) return null;
 		const ray = new this.R.Ray({
 			x: origin[0] / SCALE,
 			y: origin[1] / SCALE
@@ -358,9 +421,44 @@ var Physics2D = class {
 		const flags = opts?.staticOnly ? this.R.QueryFilterFlags.EXCLUDE_DYNAMIC | this.R.QueryFilterFlags.EXCLUDE_KINEMATIC : void 0;
 		const hit = this.world.castRayAndGetNormal(ray, maxLen / SCALE, true, flags, void 0, excludeCollider, void 0, (collider) => !collider.isSensor());
 		if (!hit) return null;
+		const distance = hit.timeOfImpact * SCALE;
 		return {
-			distance: hit.timeOfImpact * SCALE,
+			distance,
 			normal: [hit.normal.x, hit.normal.y],
+			node: this.byColliderHandle.get(hit.collider.handle) ?? null,
+			point: [origin[0] + dir[0] / len * distance, origin[1] + dir[1] / len * distance]
+		};
+	}
+	/**
+	* Sweep a CIRCLE of `radius` from `origin` along `dir` — a thick ray, in
+	* pixels. The 2D twin of `Physics3D.castSphere`.
+	*
+	* 3D has had this since the camera spring arm needed it and 2D never got it,
+	* so the shared `PhysicsQuery` interface declares it OPTIONAL and every 2D
+	* game that wanted a probe with THICKNESS — a shot that must not thread a
+	* one-pixel gap between two tiles, a ledge feeler, a camera that should not
+	* clip a wall it skims — had to fire several thin rays and hope.
+	*
+	* Same filters as `castRay`: sensors never hit, `staticOnly` ignores dynamic
+	* and kinematic bodies, `dir` may be any length. Returns the travel distance
+	* of the circle's CENTRE, or null when the sweep is clear.
+	*/
+	castSphere(origin, dir, radius, maxLen, exclude, opts) {
+		const R = this.R;
+		const len = Math.hypot(dir[0], dir[1]);
+		if (!(len > 0)) return null;
+		const excludeEntry = exclude ? this.entries.get(exclude) : void 0;
+		const flags = opts?.staticOnly ? R.QueryFilterFlags.EXCLUDE_DYNAMIC | R.QueryFilterFlags.EXCLUDE_KINEMATIC : void 0;
+		const hit = this.world.castShape({
+			x: origin[0] / SCALE,
+			y: origin[1] / SCALE
+		}, 0, {
+			x: dir[0] / len,
+			y: dir[1] / len
+		}, new R.Ball(radius / SCALE), 0, maxLen / SCALE, true, flags, void 0, excludeEntry?.collider, excludeEntry?.body, (collider) => !collider.isSensor());
+		if (!hit) return null;
+		return {
+			distance: hit.time_of_impact * SCALE,
 			node: this.byColliderHandle.get(hit.collider.handle) ?? null
 		};
 	}
@@ -465,13 +563,15 @@ var Physics2D = class {
 			const x = wx / SCALE;
 			const y = wy / SCALE;
 			let desc;
-			if (node instanceof RigidBody2D) desc = R.RigidBodyDesc.dynamic();
+			const dyn = node instanceof RigidBody2D;
+			if (dyn) desc = R.RigidBodyDesc.dynamic();
 			else if (node instanceof CharacterBody2D || node instanceof Area2D) desc = R.RigidBodyDesc.kinematicPositionBased();
 			else desc = R.RigidBodyDesc.fixed();
 			desc.setTranslation(x, y).setRotation(node.rotation * DEG);
 			if (node instanceof RigidBody2D) {
 				desc.setGravityScale(node.gravityScale);
 				desc.setLinvel((node.linearVelocity[0] ?? 0) / SCALE, (node.linearVelocity[1] ?? 0) / SCALE);
+				desc.setAngvel(node.fixedRotation ? 0 : node.angularVelocity);
 				if (node.fixedRotation) desc.lockRotations();
 			}
 			const body = this.world.createRigidBody(desc);
@@ -488,7 +588,12 @@ var Physics2D = class {
 				lastY: wy,
 				lastRot: node.rotation,
 				lastVX: 0,
-				lastVY: 0
+				lastVY: 0,
+				lastAV: dyn ? node.angularVelocity : 0,
+				lastMass: dyn ? node.mass : 1,
+				lastFriction: dyn ? node.friction : .5,
+				lastRestitution: dyn ? node.restitution : 0,
+				lastGravityScale: dyn ? node.gravityScale : 1
 			};
 			this.entries.set(node, e);
 			this.byColliderHandle.set(collider.handle, node);
@@ -530,6 +635,26 @@ var Physics2D = class {
 				e.lastVX = vx;
 				e.lastVY = vy;
 			}
+			if (node.angularVelocity !== e.lastAV) {
+				e.body.setAngvel(node.angularVelocity, true);
+				e.lastAV = node.angularVelocity;
+			}
+			if (node.gravityScale !== e.lastGravityScale) {
+				e.body.setGravityScale(node.gravityScale, true);
+				e.lastGravityScale = node.gravityScale;
+			}
+			if (node.mass !== e.lastMass) {
+				e.collider.setMass(node.mass);
+				e.lastMass = node.mass;
+			}
+			if (node.friction !== e.lastFriction) {
+				e.collider.setFriction(node.friction);
+				e.lastFriction = node.friction;
+			}
+			if (node.restitution !== e.lastRestitution) {
+				e.collider.setRestitution(node.restitution);
+				e.lastRestitution = node.restitution;
+			}
 		}
 		return e;
 	}

package/dist/{physics-3d-DbYaEcZy.js → physics-3d-CFEGxBXZ.js}

@@ -1,10 +1,10 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { k as diagnose } from "./loader-DZE7B07H.js";
+import { o as __exportAll } from "./json-CfTjpvW8.js";
+import { Y as diagnose } from "./save-slots-Bvuh2p_r.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-D1KixWK8.js";
+import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-CNULJvwh.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
-import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-BO-7XoFV.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-99BzP_L-.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**
@@ -386,6 +386,21 @@ var Physics3D = class {
 		this.world.propagateModifiedBodyPositionsToColliders();
 	}
 	/** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
+	/**
+	* May `candidate` carry `rider`? — see the 2D twin.
+	*
+	* "Never a CharacterBody3D" is the whole CLASS, and a CharacterBody3D
+	* animated by position writes is the documented moving-platform path. What
+	* the guard was really for is a carry CYCLE, so that is what it tests.
+	*/
+	canCarry(rider, candidate) {
+		let at = candidate;
+		for (let depth = 0; depth < 8 && at; depth++) {
+			if (at === rider) return false;
+			at = this.entries.get(at)?.ground ?? null;
+		}
+		return true;
+	}
 	moveAndSlide(node) {
 		const e = this.ensureEntry(node);
 		if (!e) return;
@@ -421,6 +436,20 @@ var Physics3D = class {
 			z: nz
 		});
 		node._grounded = this.kcc.computedGrounded();
+		node._onWall = null;
+		node._onCeiling = false;
+		const touches = this.kcc.numComputedCollisions();
+		for (let i = 0; i < touches; i++) {
+			const normal = this.kcc.computedCollision(i)?.normal1;
+			if (!normal) continue;
+			if (normal.y < -.7) {
+				if (!node._grounded) node._onCeiling = true;
+			} else if (Math.hypot(normal.x, normal.z) > .7) node._onWall = [
+				normal.x,
+				normal.y,
+				normal.z
+			];
+		}
 		if (node._grounded) {
 			const half = characterHalfHeight(node);
 			const hit = this.castRay([
@@ -432,7 +461,7 @@ var Physics3D = class {
 				-1,
 				0
 			], .4, node);
-			if (hit?.node && !(hit.node instanceof CharacterBody3D)) {
+			if (hit?.node && this.canCarry(node, hit.node)) {
 				e.ground = hit.node;
 				const at = worldPosition3D(hit.node);
 				e.groundAt = [
@@ -499,9 +528,28 @@ var Physics3D = class {
 	* off ONE fixed body — they never move, so there is nothing to step — and the
 	* whole set is rebuilt only when the tree's shape changes.
 	*/
+	/** Where each live scatter field was when its colliders were built. */
+	scatterState = /* @__PURE__ */ new Map();
+	/**
+	* Has any scatter field moved, or had its rows replaced, since the build?
+	*
+	* `transforms` is compared by IDENTITY, which is the operation the skill
+	* teaches ("replace the whole array"); the world position catches the field
+	* itself or an ancestor being moved.
+	*/
+	scattersMoved() {
+		for (const [field] of this.scatterBodies) {
+			const was = this.scatterState.get(field);
+			const [x, y, z] = worldPosition3D(field);
+			if (!was) return true;
+			if (was.rows !== field.transforms || was.x !== x || was.y !== y || was.z !== z) return true;
+		}
+		return false;
+	}
 	syncScatters(root) {
 		for (const [, entry] of this.scatterBodies) this.world.removeRigidBody(entry);
 		this.scatterBodies.clear();
+		this.scatterState.clear();
 		const fields = /* @__PURE__ */ new Set();
 		collectScatters(root, fields);
 		for (const field of fields) {
@@ -543,6 +591,12 @@ var Physics3D = class {
 				this.world.createCollider(desc, body);
 			}
 			this.scatterBodies.set(field, body);
+			this.scatterState.set(field, {
+				rows: field.transforms,
+				x: ox,
+				y: oy,
+				z: oz
+			});
 		}
 	}
 	syncBodies() {
@@ -577,6 +631,7 @@ var Physics3D = class {
 				this.syncScatters(scene.root);
 			}
 		}
+		if (this.scatterBodies.size > 0 && this.scattersMoved()) this.syncScatters(scene.root);
 		const seen = this.bodySet;
 		for (const node of seen) {
 			if (node.collider.shape === void 0) {
@@ -644,12 +699,13 @@ var Physics3D = class {
 			if (node instanceof RigidBody3D) {
 				desc.setGravityScale(node.gravityScale);
 				desc.setLinvel(node.linearVelocity[0] ?? 0, node.linearVelocity[1] ?? 0, node.linearVelocity[2] ?? 0);
+				const locked = node.fixedRotation;
 				desc.setAngvel({
-					x: node.angularVelocity[0] ?? 0,
-					y: node.angularVelocity[1] ?? 0,
-					z: node.angularVelocity[2] ?? 0
+					x: locked ? 0 : node.angularVelocity[0] ?? 0,
+					y: locked ? 0 : node.angularVelocity[1] ?? 0,
+					z: locked ? 0 : node.angularVelocity[2] ?? 0
 				});
-				if (node.fixedRotation) desc.lockRotations();
+				if (locked) desc.lockRotations();
 			}
 			const body = this.world.createRigidBody(desc);
 			colDesc.setActiveEvents(R.ActiveEvents.COLLISION_EVENTS);
@@ -674,7 +730,10 @@ var Physics3D = class {
 					0,
 					0,
 					0
-				]
+				],
+				lastMass: node instanceof RigidBody3D ? node.mass : 1,
+				lastFriction: node instanceof RigidBody3D ? node.friction : .5,
+				lastRestitution: node instanceof RigidBody3D ? node.restitution : 0
 			};
 			this.entries.set(node, e);
 			this.byColliderHandle.set(collider.handle, node);
@@ -735,6 +794,18 @@ var Physics3D = class {
 				e.lastV = v;
 			}
 			if (node.gravityScale !== e.body.gravityScale()) e.body.setGravityScale(node.gravityScale, true);
+			if (node.mass !== e.lastMass) {
+				e.collider.setMass(node.mass);
+				e.lastMass = node.mass;
+			}
+			if (node.friction !== e.lastFriction) {
+				e.collider.setFriction(node.friction);
+				e.lastFriction = node.friction;
+			}
+			if (node.restitution !== e.lastRestitution) {
+				e.collider.setRestitution(node.restitution);
+				e.lastRestitution = node.restitution;
+			}
 		}
 		return e;
 	}
@@ -864,21 +935,24 @@ var Physics3D = class {
 		return [...set];
 	}
 	/**
-	* World-space raycast (meters). `exclude` skips that body's collider —
+	* World-space raycast (meters). `dir` may be any length (it is normalized),
+	* so `distance` and `maxLen` are metres. `exclude` skips that body's collider —
 	* ground probes from inside a capsule need it. `opts.staticOnly` hits ONLY the
 	* fixed/static world (excludes both dynamic AND kinematic bodies): the camera
 	* spring arm uses it so neither a dynamic projectile nor a KINEMATIC enemy
 	* (CharacterBody3D) passing behind the player yanks the camera in.
 	*/
 	castRay(origin, dir, maxLen, exclude, opts) {
+		const len = Math.hypot(dir[0], dir[1], dir[2]);
+		if (!(len > 0)) return null;
 		const ray = new this.R.Ray({
 			x: origin[0],
 			y: origin[1],
 			z: origin[2]
 		}, {
-			x: dir[0],
-			y: dir[1],
-			z: dir[2]
+			x: dir[0] / len,
+			y: dir[1] / len,
+			z: dir[2] / len
 		});
 		const excludeCollider = exclude ? this.entries.get(exclude)?.collider : void 0;
 		const flags = opts?.staticOnly ? this.R.QueryFilterFlags.EXCLUDE_DYNAMIC | this.R.QueryFilterFlags.EXCLUDE_KINEMATIC : void 0;
@@ -891,7 +965,12 @@ var Physics3D = class {
 				hit.normal.y,
 				hit.normal.z
 			],
-			node: this.byColliderHandle.get(hit.collider.handle) ?? null
+			node: this.byColliderHandle.get(hit.collider.handle) ?? null,
+			point: [
+				origin[0] + dir[0] / len * hit.timeOfImpact,
+				origin[1] + dir[1] / len * hit.timeOfImpact,
+				origin[2] + dir[2] / len * hit.timeOfImpact
+			]
 		};
 	}
 	/**
@@ -906,6 +985,8 @@ var Physics3D = class {
 		const R = this.R;
 		const excludeEntry = exclude ? this.entries.get(exclude) : void 0;
 		const flags = opts?.staticOnly ? R.QueryFilterFlags.EXCLUDE_DYNAMIC | R.QueryFilterFlags.EXCLUDE_KINEMATIC : void 0;
+		const len = Math.hypot(dir[0], dir[1], dir[2]);
+		if (!(len > 0)) return null;
 		const hit = this.world.castShape({
 			x: origin[0],
 			y: origin[1],
@@ -916,9 +997,9 @@ var Physics3D = class {
 			z: 0,
 			w: 1
 		}, {
-			x: dir[0],
-			y: dir[1],
-			z: dir[2]
+			x: dir[0] / len,
+			y: dir[1] / len,
+			z: dir[2] / len
 		}, new R.Ball(radius), 0, maxLen, true, flags, void 0, excludeEntry?.collider, excludeEntry?.body, (collider) => !collider.isSensor());
 		if (!hit) return null;
 		return {
@@ -950,7 +1031,7 @@ function collectBodies(node, out) {
 * Convex, always: a hull is a few planes to test against, where a triangle
 * mesh is a tree of them, and nothing scattered across a map needs concavity.
 */
-function meshShapedDesc(R, kind, size, scale, who) {
+function meshShapedDesc(R, kind, size, scale, who, engine) {
 	const sx = scale[0] ?? 1;
 	const sy = scale[1] ?? 1;
 	const sz = scale[2] ?? 1;
@@ -958,7 +1039,7 @@ function meshShapedDesc(R, kind, size, scale, who) {
 	const y = (size[1] ?? 1) * sy;
 	const z = (size[2] ?? 1) * sz;
 	const radial = Math.max(Math.abs(sx), Math.abs(sz));
-	if (who && kind !== "box" && kind !== "plane" && Math.abs(sx - sz) > 1e-6) console.warn(`[incanto] Collider on '${who}': shape 'auto' fits a ${kind} to a mesh scaled [${sx}, ${sy}, ${sz}]. A ${kind} has one radius, so the widest of x/z (${radial}) is used. Use a box, or scale x and z the same.`);
+	if (who && kind !== "box" && kind !== "plane" && Math.abs(sx - sz) > 1e-6) diagnose(engine ?? null, "warn", `[incanto] Collider on '${who}': shape 'auto' fits a ${kind} to a mesh scaled [${sx}, ${sy}, ${sz}]. A ${kind} has one radius, so the widest of x/z (${radial}) is used. Use a box, or scale x and z the same.`);
 	switch (kind) {
 		case "box": return R.ColliderDesc.cuboid(x / 2, y / 2, z / 2);
 		case "sphere": return R.ColliderDesc.ball((size[0] ?? 1) * Math.max(radial, Math.abs(sy)));
@@ -1233,9 +1314,9 @@ function buildColliderDesc3D(R, collider, nodeName, node) {
 		const model = models[0];
 		if (!mesh && !model) throw new IncantoError("BAD_FORMAT", `Collider on '${nodeName}': shape 'auto' needs a MeshInstance3D or ModelInstance3D on the body (or as a child) to take its shape from.`);
 		const parts = meshes.length + models.length;
-		if (parts > 1) console.warn(`[incanto] Collider on '${nodeName}': shape 'auto' fits ONE mesh and took '${(mesh ?? model)?.name}'; ${parts - 1} other mesh(es) here are not solid. Give each part its own body.`);
+		if (parts > 1) diagnose(node?.tree?.engine ?? null, "warn", `[incanto] Collider on '${nodeName}': shape 'auto' fits ONE mesh and took '${(mesh ?? model)?.name}'; ${parts - 1} other mesh(es) here are not solid. Give each part its own body.`);
 		if (mesh) {
-			const desc = meshShapedDesc(R, mesh.mesh, mesh.size, mesh.scale, nodeName);
+			const desc = meshShapedDesc(R, mesh.mesh, mesh.size, mesh.scale, nodeName, node?.tree?.engine);
 			if (desc) {
 				desc.setTranslation(mesh.at[0], mesh.at[1], mesh.at[2]);
 				if (mesh.turn[0] !== 0 || mesh.turn[1] !== 0 || mesh.turn[2] !== 0) {
@@ -1253,7 +1334,7 @@ function buildColliderDesc3D(R, collider, nodeName, node) {
 			const tri = modelTriangles(node, model);
 			if (!tri) return null;
 			if (isStaticShape(node)) {
-				if (tri.triangles > TRIMESH_BUDGET) console.warn(`[incanto] Collider on '${nodeName}': shape 'auto' built a ${tri.triangles}-triangle mesh from '${model.name}'. Consider a low-poly collision model or an explicit box.`);
+				if (tri.triangles > TRIMESH_BUDGET) diagnose(node?.tree?.engine ?? null, "warn", `[incanto] Collider on '${nodeName}': shape 'auto' built a ${tri.triangles}-triangle mesh from '${model.name}'. Consider a low-poly collision model or an explicit box.`);
 				return R.ColliderDesc.trimesh(tri.vertices, tri.indices);
 			}
 			return R.ColliderDesc.convexHull(tri.vertices);

package/dist/{teardown-CMqFVxO9.js → picking-DVo7fI13.js}

@@ -1,6 +1,7 @@
-import { _ as AudioPlayer } from "./register-mmfugpaQ.js";
-import { i as logReport, o as parseDrive } from "./webgl-unavailable-Z5_g8x9H.js";
-import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-Dlq13Gyj.js";
+import { _ as AudioPlayer } from "./register-DuVdzxbq.js";
+import { i as logReport, o as parseDrive } from "./webgl-unavailable-C8aDbGmR.js";
+import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-D-_7YF2G.js";
+import { Q as worldPosition } from "./gameplay-CNULJvwh.js";
 //#region src/core/audio-errors.ts
 /** Every AudioPlayer under `root` whose source could not be played. */
 function audioErrors(root) {
@@ -100,6 +101,74 @@ function wireDevChannel(opts) {
 	return cleanups;
 }
 //#endregion
+//#region src/core/drive-apply.ts
+/**
+* Long enough for the page to draw a frame between the press and the release.
+*
+* Both edges in one tick would still FIRE — the input settles them together and
+* `Clickable` reads press then release in the same update — but no real cursor
+* does that, and everything a game shows for a held button (a pressed state, a
+* hover tint, the sound) would never be on screen. Two frames at 60 Hz.
+*/
+const FRAME_MS = 34;
+/** Apply one step of a drive script to a running game. */
+async function applyDriveStep(target, step) {
+	const { engine } = target;
+	switch (step.kind) {
+		case "press":
+			engine.input.pressAction(step.action);
+			return;
+		case "release":
+			engine.input.releaseAction(step.action);
+			return;
+		case "vector":
+			engine.input.setActionVector(step.action, step.x, step.y);
+			return;
+		case "key":
+			engine.input.handleKey(step.code, step.down);
+			return;
+		case "pointer":
+			engine.input.handlePointerMove(step.dx, step.dy);
+			return;
+		case "at":
+			engine.input.setPointerPosition(step.x, step.y);
+			return;
+		case "atNode": {
+			const node = engine.scene?.root.getNodeOrNull(step.path);
+			const at = node ? worldPosition(node) : [];
+			if (at.length === 0) {
+				engine.log.error(`[incanto] drive: at '${step.path}' — no such node, so the cursor did not move.`);
+				return;
+			}
+			const screen = target.project(at[0] ?? 0, at[1] ?? 0, at[2] ?? 0);
+			if (!screen) {
+				engine.log.error(`[incanto] drive: at '${step.path}' — this renderer cannot say where a world point is on screen, so the cursor did not move.`);
+				return;
+			}
+			if (screen.behind === true) {
+				engine.log.error(`[incanto] drive: at '${step.path}' — it is BEHIND the camera, so there is no pixel to put the cursor on.`);
+				return;
+			}
+			engine.input.setPointerPosition(screen.x, screen.y);
+			return;
+		}
+		case "click":
+			engine.input.handleMouseButton(step.button, true);
+			await target.wait(FRAME_MS);
+			engine.input.handleMouseButton(step.button, false);
+			await target.wait(FRAME_MS);
+			return;
+		case "mouse":
+			engine.input.handleMouseButton(step.button, step.down);
+			await target.wait(FRAME_MS);
+			return;
+		case "step":
+			await target.wait(step.ms);
+			return;
+		default: return;
+	}
+}
+//#endregion
 //#region src/core/editor-switch.ts
 /**
 * Cover the page while it changes what it is.
@@ -347,27 +416,20 @@ function pauseWhenHidden(engine, doc = typeof document === "undefined" ? null :
 	if (!doc) return () => {};
 	/** The scale to come back to — null when we did not pause anything. */
 	let heldScale = null;
-	let mutedByUs = false;
 	const onChange = () => {
 		if (doc.hidden) {
 			if (heldScale === null && engine.timeScale > 0) {
 				heldScale = engine.timeScale;
 				engine.timeScale = 0;
 			}
-			if (!engine.audio.muted) {
-				engine.audio.muted = true;
-				mutedByUs = true;
-			}
+			engine.audio.suspend(true);
 			return;
 		}
 		if (heldScale !== null) {
 			if (engine.timeScale === 0) engine.timeScale = heldScale;
 			heldScale = null;
 		}
-		if (mutedByUs) {
-			engine.audio.muted = false;
-			mutedByUs = false;
-		}
+		engine.audio.suspend(false);
 	};
 	doc.addEventListener("visibilitychange", onChange);
 	return () => doc.removeEventListener("visibilitychange", onChange);
@@ -397,4 +459,33 @@ function defaultReport(what, error) {
 	console.error(`[incanto] teardown: ${what} failed (continuing)`, error);
 }
 //#endregion
-export { openBundledEditor as a, claimCanvasGestures as c, devServerLibrary as i, audioErrors as l, pauseWhenHidden as n, poseFromRenderer as o, crossFade as r, wireDevChannel as s, teardown as t };
+//#region src/core/picking.ts
+/** Is this object, and every ancestor up to the scene, drawn? */
+function drawn(object) {
+	for (let at = object; at; at = at.parent) if (!at.visible) return false;
+	return true;
+}
+/**
+* The `incantoNode` under a set of raycast hits, or null.
+*
+* Hits are expected in the order three produces them: nearest first.
+*/
+function nodeFromHits(hits, opts = {}) {
+	let best = null;
+	for (const hit of hits) {
+		if (!drawn(hit.object)) continue;
+		let obj = hit.object;
+		while (obj && !obj.userData?.incantoNode) obj = obj.parent;
+		const node = obj?.userData?.incantoNode;
+		if (node === void 0) continue;
+		if (!opts.byRenderOrder) return node;
+		const order = hit.object.renderOrder ?? 0;
+		if (!best || order >= best.order) best = {
+			node,
+			order
+		};
+	}
+	return best?.node ?? null;
+}
+//#endregion
+export { devServerLibrary as a, applyDriveStep as c, audioErrors as d, crossFade as i, wireDevChannel as l, teardown as n, openBundledEditor as o, pauseWhenHidden as r, poseFromRenderer as s, nodeFromHits as t, claimCanvasGestures as u };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-rm8vVzu_.js";
-import { c as JsonValue } from "./schema-B6ugCV1Q.js";
+import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-Dcz0fr1S.js";
+import { c as JsonValue } from "./rng-Bb-IutXB.js";
 import { CSSProperties, ReactNode } from "react";
 
 //#region src/react/index.d.ts

package/dist/react.js

@@ -1,4 +1,4 @@
-import { n as jsonEquals, t as jsonClone } from "./json-CwwhxQgb.js";
+import { n as jsonEquals, t as jsonClone } from "./json-CfTjpvW8.js";
 import { createContext, useContext, useEffect, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/index.tsx
@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-CvJ1wSRP.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CwxEDlCm.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-LCHBLfA4.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CH4kt78v.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;