incanto 0.74.0 → 0.76.0

package/dist/{physics-3d-rOzeg890.js → physics-3d-C5MOujfQ.js}

@@ -1,10 +1,10 @@
 import { o as __exportAll } from "./json-CfTjpvW8.js";
-import { Y as diagnose } from "./save-slots-CEUGeLuB.js";
+import { et as diagnose } from "./pose-ByFB_J3O.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { G as PhysicsBody3D, J as Node3D, K as RigidBody3D, U as Area3D, W as CharacterBody3D, Y as validateCollider3D, q as StaticBody3D } from "./gameplay-Bxe1sMVT.js";
+import { $ as Water3D, at as PhysicsBody3D, ct as Node3D, it as CharacterBody3D, lt as validateCollider3D, ot as RigidBody3D, rt as Area3D, st as StaticBody3D } from "./gameplay-Bfff_beb.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
-import { F as Joint3D, I as InstancedMesh3D, R as buildMeshGeometry, j as Terrain3D } from "./environment-presets-BkqlWewf.js";
+import { B as InstancedMesh3D, F as Terrain3D, H as buildMeshGeometry, z as Joint3D } from "./environment-presets-e_9YCnGu.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**
@@ -210,6 +210,89 @@ var physics_3d_exports = /* @__PURE__ */ __exportAll({
 });
 const DEG = Math.PI / 180;
 /**
+* A hinge's angle: body A's rotation relative to body B, about A's local
+* `axis`, in degrees on (-180, 180]. The twist of the relative quaternion
+* about the axis — `2·atan2(q·n, q.w)` — which is exactly the turn when the
+* joint holds every other axis still.
+*/
+/**
+* How far two bodies disagree about a joint axis, in degrees: the part of
+* their relative rotation that is NOT about `axis`. Zero when they share a
+* rotation, or differ only by a turn about the axis itself.
+*/
+function axisDisagreementDeg(qa, qb, axis) {
+	const bx = -qb.x;
+	const by = -qb.y;
+	const bz = -qb.z;
+	const bw = qb.w;
+	const rx = bw * qa.x + bx * qa.w + by * qa.z - bz * qa.y;
+	const ry = bw * qa.y - bx * qa.z + by * qa.w + bz * qa.x;
+	const rz = bw * qa.z + bx * qa.y - by * qa.x + bz * qa.w;
+	const rw = bw * qa.w - bx * qa.x - by * qa.y - bz * qa.z;
+	const n = Math.hypot(axis[0] ?? 0, axis[1] ?? 0, axis[2] ?? 0) || 1;
+	const ux = (axis[0] ?? 0) / n;
+	const uy = (axis[1] ?? 0) / n;
+	const uz = (axis[2] ?? 0) / n;
+	const proj = rx * ux + ry * uy + rz * uz;
+	const tw = Math.hypot(proj, rw) || 1;
+	const twist = {
+		x: proj * ux / tw,
+		y: proj * uy / tw,
+		z: proj * uz / tw,
+		w: rw / tw
+	};
+	const sw = rw * twist.w + rx * twist.x + ry * twist.y + rz * twist.z;
+	return Math.abs(2 * Math.acos(Math.min(1, Math.abs(sw))) / DEG);
+}
+/** `v` turned by the quaternion `q`. */
+function rotateVec3(q, x, y, z) {
+	const cx = q.y * z - q.z * y;
+	const cy = q.z * x - q.x * z;
+	const cz = q.x * y - q.y * x;
+	return [
+		x + 2 * (q.w * cx + (q.y * cz - q.z * cy)),
+		y + 2 * (q.w * cy + (q.z * cx - q.x * cz)),
+		z + 2 * (q.w * cz + (q.x * cy - q.y * cx))
+	];
+}
+/** `offset`, turned by the rotation that takes `qFrom` to `qNow` (world frame). */
+function rotateByDelta(qNow, qFrom, ox, oy, oz) {
+	const [fx, fy, fz, fw] = [
+		-qFrom[0],
+		-qFrom[1],
+		-qFrom[2],
+		qFrom[3]
+	];
+	const dx = qNow.w * fx + qNow.x * fw + qNow.y * fz - qNow.z * fy;
+	const dy = qNow.w * fy - qNow.x * fz + qNow.y * fw + qNow.z * fx;
+	const dz = qNow.w * fz + qNow.x * fy - qNow.y * fx + qNow.z * fw;
+	const dw = qNow.w * fw - qNow.x * fx - qNow.y * fy - qNow.z * fz;
+	const cx = dy * oz - dz * oy;
+	const cy = dz * ox - dx * oz;
+	const cz = dx * oy - dy * ox;
+	return [
+		ox + 2 * (dw * cx + (dy * cz - dz * cy)),
+		oy + 2 * (dw * cy + (dz * cx - dx * cz)),
+		oz + 2 * (dw * cz + (dx * cy - dy * cx))
+	];
+}
+function hingeAngle3D(qa, qb, axis) {
+	const bx = -qb.x;
+	const by = -qb.y;
+	const bz = -qb.z;
+	const bw = qb.w;
+	const rx = bw * qa.x + bx * qa.w + by * qa.z - bz * qa.y;
+	const ry = bw * qa.y - bx * qa.z + by * qa.w + bz * qa.x;
+	const rz = bw * qa.z + bx * qa.y - by * qa.x + bz * qa.w;
+	const rw = bw * qa.w - bx * qa.x - by * qa.y - bz * qa.z;
+	const n = Math.hypot(axis[0] ?? 0, axis[1] ?? 0, axis[2] ?? 0) || 1;
+	const proj = (rx * (axis[0] ?? 0) + ry * (axis[1] ?? 0) + rz * (axis[2] ?? 0)) / n;
+	let deg = 2 * Math.atan2(proj, rw) / DEG;
+	if (deg > 180) deg -= 360;
+	if (deg <= -180) deg += 360;
+	return deg;
+}
+/**
 * Enable 3D physics for an engine. Dynamically imports Rapier (compat build)
 * so games without physics never pay its bundle cost. 1 unit = 1 meter, y-up —
 * three's native space, no conversion.
@@ -232,6 +315,11 @@ var Physics3D = class {
 	warnedNoCollider = /* @__PURE__ */ new WeakSet();
 	entries = /* @__PURE__ */ new Map();
 	byColliderHandle = /* @__PURE__ */ new Map();
+	/** Every Water3D in the tree, rescanned when the structure changes. */
+	waters = [];
+	watersStale = true;
+	/** Raycast vehicles, one per Vehicle3D in the tree, on their chassis entries. */
+	vehicles = /* @__PURE__ */ new Map();
 	world;
 	events;
 	kcc;
@@ -294,16 +382,18 @@ var Physics3D = class {
 			}
 		}
 		this.syncBodies();
+		this.applyBuoyancy(dt);
 		this.world.timestep = dt;
 		this.world.step(this.events);
 		for (const [node, e] of this.entries) {
 			const t = e.body.translation();
 			if (!e.body.isFixed() && !(node instanceof Area3D)) {
-				const [ox, oy, oz] = parentWorldOffset3D(node);
+				parentPose3D(node);
+				localV.set(t.x, t.y, t.z).sub(parentPosV).applyQuaternion(invQ.copy(parentQuatQ).invert());
 				const next = [
-					t.x - ox,
-					t.y - oy,
-					t.z - oz
+					localV.x,
+					localV.y,
+					localV.z
 				];
 				node._interpPrev = node._interpCurr ?? next;
 				node._interpCurr = next;
@@ -315,7 +405,14 @@ var Physics3D = class {
 			if (node instanceof RigidBody3D) {
 				if (!node.fixedRotation) {
 					const q = e.body.rotation();
-					eulerScratch.setFromQuaternion(quatScratch.set(q.x, q.y, q.z, q.w), "XYZ");
+					quatScratch.set(q.x, q.y, q.z, q.w);
+					e.lastQuat[0] = q.x;
+					e.lastQuat[1] = q.y;
+					e.lastQuat[2] = q.z;
+					e.lastQuat[3] = q.w;
+					parentPose3D(node);
+					localQ.copy(parentQuatQ).invert().multiply(quatScratch);
+					eulerScratch.setFromQuaternion(localQ, "XYZ");
 					const rot = node.rotation;
 					rot[0] = eulerScratch.x / DEG;
 					rot[1] = eulerScratch.y / DEG;
@@ -337,6 +434,9 @@ var Physics3D = class {
 				e.lastV[0] = lv.x;
 				e.lastV[1] = lv.y;
 				e.lastV[2] = lv.z;
+				e.lastAV[0] = av.x;
+				e.lastAV[1] = av.y;
+				e.lastAV[2] = av.z;
 			}
 			const t2 = e.body.translation();
 			e.last[0] = t2.x;
@@ -347,6 +447,7 @@ var Physics3D = class {
 			const a = this.byColliderHandle.get(h1);
 			const b = this.byColliderHandle.get(h2);
 			if (!a || !b) return;
+			if (!a.enabled || !b.enabled) return;
 			const sig = started ? "triggerEnter" : "triggerExit";
 			if (started === (this.overlaps.get(a)?.has(b) ?? false)) return;
 			this.trackOverlap(a, b, started);
@@ -370,13 +471,12 @@ var Physics3D = class {
 	*/
 	poseFromTree() {
 		for (const [node, e] of this.entries) {
-			const [wx, wy, wz] = worldPosition3D(node);
+			worldPose3D(node, wpV, quatScratch);
 			e.body.setTranslation({
-				x: wx,
-				y: wy,
-				z: wz
+				x: wpV.x,
+				y: wpV.y,
+				z: wpV.z
 			}, false);
-			quatScratch.setFromEuler(eulerScratch.set((node.rotation[0] ?? 0) * DEG, (node.rotation[1] ?? 0) * DEG, (node.rotation[2] ?? 0) * DEG, "XYZ"));
 			e.body.setRotation({
 				x: quatScratch.x,
 				y: quatScratch.y,
@@ -386,6 +486,77 @@ var Physics3D = class {
 		}
 		this.world.propagateModifiedBodyPositionsToColliders();
 	}
+	/**
+	* @internal Called by Vehicle3D.fixedUpdate: push the throttle, steer and
+	* brake into Rapier's raycast vehicle on the chassis and let it apply the
+	* step's forces; read the wheels back. The controller is made on first
+	* use and remade if the chassis body was rebuilt.
+	*/
+	_driveVehicle(node, dt) {
+		const e = this.ensureEntry(node.body);
+		if (!e) return;
+		const R = this.R;
+		let v = this.vehicles.get(node);
+		if (!v || v.chassis !== e.body) {
+			if (v) v.ctrl.free();
+			const ctrl = new R.DynamicRayCastVehicleController(e.body, this.world.broadPhase, this.world.narrowPhase, this.world.bodies, this.world.colliders);
+			ctrl.indexUpAxis = 1;
+			ctrl.setIndexForwardAxis = 2;
+			node.specs().forEach((w, i) => {
+				ctrl.addWheel({
+					x: w.position[0],
+					y: w.position[1],
+					z: w.position[2]
+				}, {
+					x: 0,
+					y: -1,
+					z: 0
+				}, {
+					x: -1,
+					y: 0,
+					z: 0
+				}, w.rest, w.radius);
+				ctrl.setWheelSuspensionStiffness(i, node.suspensionStiffness);
+				ctrl.setWheelSuspensionCompression(i, node.suspensionCompression);
+				ctrl.setWheelSuspensionRelaxation(i, node.suspensionRelaxation);
+				ctrl.setWheelMaxSuspensionTravel(i, node.maxTravel);
+				ctrl.setWheelFrictionSlip(i, node.friction);
+				ctrl.setWheelSideFrictionStiffness(i, node.sideFriction);
+			});
+			v = {
+				ctrl,
+				chassis: e.body
+			};
+			this.vehicles.set(node, v);
+		}
+		const ctrl = v.ctrl;
+		const specs = node.specs();
+		const steer = Math.max(-1, Math.min(1, node.steer)) * node.maxSteer;
+		const throttle = Math.max(-1, Math.min(1, node.throttle)) * node.engineForce;
+		const brake = Math.max(0, Math.min(1, node.brake)) * node.brakeForce;
+		specs.forEach((w, i) => {
+			ctrl.setWheelSteering(i, w.steer ? -steer : 0);
+			ctrl.setWheelEngineForce(i, w.drive ? throttle : 0);
+			ctrl.setWheelBrake(i, brake);
+		});
+		e.body.wakeUp();
+		const own = e.collider.handle;
+		ctrl.updateVehicle(dt, void 0, void 0, (c) => c.handle !== own && !(this.byColliderHandle.get(c.handle) instanceof Area3D));
+		node.speed = ctrl.currentVehicleSpeed();
+		node._states = specs.map((w, i) => ({
+			contact: ctrl.wheelIsInContact(i),
+			suspension: ctrl.wheelSuspensionLength(i) ?? w.rest,
+			rotation: ctrl.wheelRotation(i) ?? 0,
+			steering: ctrl.wheelSteering(i) ?? 0
+		}));
+	}
+	/** @internal The Vehicle3D left the tree: drop its controller. */
+	_freeVehicle(node) {
+		const v = this.vehicles.get(node);
+		if (!v) return;
+		v.ctrl.free();
+		this.vehicles.delete(node);
+	}
 	/** @internal Called by CharacterBody3D.moveAndSlide (during tree fixedUpdate). */
 	/**
 	* May `candidate` carry `rider`? — see the 2D twin.
@@ -395,6 +566,7 @@ var Physics3D = class {
 	* the guard was really for is a carry CYCLE, so that is what it tests.
 	*/
 	canCarry(rider, candidate) {
+		if (this.jointed.get(rider)?.has(candidate)) return false;
 		let at = candidate;
 		for (let depth = 0; depth < 8 && at; depth++) {
 			if (at === rider) return false;
@@ -419,13 +591,34 @@ var Physics3D = class {
 			carryX = gx - e.groundAt[0];
 			carryY = gy - e.groundAt[1];
 			carryZ = gz - e.groundAt[2];
+			const gb = this.entries.get(e.ground);
+			if (gb && e.groundRot && e.riderAt) {
+				const q = gb.body.rotation();
+				const [ox, oy, oz] = [
+					e.riderAt[0] - e.groundAt[0],
+					e.riderAt[1] - e.groundAt[1],
+					e.riderAt[2] - e.groundAt[2]
+				];
+				const [rx, ry, rz] = rotateByDelta(q, e.groundRot, ox, oy, oz);
+				carryX += rx - ox;
+				carryY += ry - oy;
+				carryZ += rz - oz;
+			}
 		} else e.ground = null;
 		const desired = {
 			x: (node.velocity[0] ?? 0) * this.lastDt + carryX,
 			y: vy * this.lastDt + carryY,
 			z: (node.velocity[2] ?? 0) * this.lastDt + carryZ
 		};
-		const others = node.collideWithCharacters ? void 0 : (c) => !(this.byColliderHandle.get(c.handle) instanceof CharacterBody3D);
+		const jointedTo = this.jointed.get(node);
+		const noContact = jointedTo && [...jointedTo.values()].some((on) => !on) ? jointedTo : null;
+		const others = node.collideWithCharacters && !noContact ? void 0 : (c) => {
+			const other = this.byColliderHandle.get(c.handle);
+			if (!node.collideWithCharacters && other instanceof CharacterBody3D) return false;
+			return !(other && noContact?.get(other) === false);
+		};
+		this.kcc.setApplyImpulsesToDynamicBodies(node.pushes > 0);
+		if (node.pushes > 0) this.kcc.setCharacterMass(node.pushes);
 		this.kcc.computeColliderMovement(e.collider, desired, this.R.QueryFilterFlags.EXCLUDE_SENSORS, void 0, others);
 		const c = this.kcc.computedMovement();
 		const t = e.body.translation();
@@ -465,6 +658,18 @@ var Physics3D = class {
 			], .4, node);
 			if (hit?.node && this.canCarry(node, hit.node)) {
 				e.ground = hit.node;
+				const gq = this.entries.get(hit.node)?.body.rotation();
+				e.groundRot = gq ? [
+					gq.x,
+					gq.y,
+					gq.z,
+					gq.w
+				] : void 0;
+				e.riderAt = [
+					nx,
+					ny - half,
+					nz
+				];
 				const at = worldPosition3D(hit.node);
 				e.groundAt = [
 					at[0],
@@ -519,6 +724,42 @@ var Physics3D = class {
 	lastRoot = null;
 	jointSet = /* @__PURE__ */ new Set();
 	joints = /* @__PURE__ */ new Map();
+	/** The two bodies each live joint ties, so a departed joint can be unlinked. */
+	jointBodies = /* @__PURE__ */ new Map();
+	/** What a hinge's limits/motor were last pushed as, so a write re-applies. */
+	hingeState = /* @__PURE__ */ new Map();
+	/** Joints refused at creation (bodies that disagree about the axis) — said once. */
+	refusedJoints = /* @__PURE__ */ new Set();
+	/** A rope's or spring's numbers as last made, so a write REMAKES the joint. */
+	tetherState = /* @__PURE__ */ new Map();
+	tetherKey(joint) {
+		return `${joint.length}/${joint.stiffness}/${joint.damping}`;
+	}
+	/**
+	* Who is jointed to whom, and whether that pair's contacts are on.
+	*
+	* A joint's own bodies are not the world to the character controller: a
+	* body jointed to a character with its contacts off is not an obstacle to
+	* its shape-cast (the joint said so, for the contact solver; the cast asks
+	* its own question), and a body jointed to it is never its GROUND — a
+	* chain hanging from a crane hook was the hook's "moving platform", and the
+	* carry dragged the hook along by however far the hook had just moved.
+	*/
+	jointed = /* @__PURE__ */ new Map();
+	linkJointed(a, b, contacts) {
+		for (const [x, y] of [[a, b], [b, a]]) {
+			let m = this.jointed.get(x);
+			if (!m) {
+				m = /* @__PURE__ */ new Map();
+				this.jointed.set(x, m);
+			}
+			m.set(y, contacts);
+		}
+	}
+	unlinkJointed(a, b) {
+		this.jointed.get(a)?.delete(b);
+		this.jointed.get(b)?.delete(a);
+	}
 	/** One fixed body per solid scatter field, carrying a collider per row. */
 	scatterBodies = /* @__PURE__ */ new Map();
 	bodySet = /* @__PURE__ */ new Set();
@@ -676,6 +917,7 @@ var Physics3D = class {
 		}
 		this.syncJoints(structureChanged);
 		if (structureChanged) {
+			this.watersStale = true;
 			for (const [node, e] of this.entries) if (!seen.has(node)) {
 				this.byColliderHandle.delete(e.collider.handle);
 				this.world.removeRigidBody(e.body);
@@ -770,6 +1012,94 @@ var Physics3D = class {
 	* meantime. syncBodies runs every step, so the body appears the moment the
 	* download lands.
 	*/
+	/**
+	* Lift every buoyant dynamic body by the water it is in — before the solver
+	* step, so the impulses are part of this step's motion.
+	*
+	* `Water3D.heightAt` had answered "so gameplay can float a raft, bob a
+	* buoy" since the water shipped, and nothing floated anything but the
+	* swimmer: a RigidBody3D dropped into a lake fell through it to the bed,
+	* whatever it weighed. This is Archimedes on eight sample points: each
+	* octant of the collider is an eighth of its volume, lifted by the water's
+	* density times however much of it is under the surface AT THAT POINT, at
+	* that point — so a tilted hull's low corners push harder and it rights
+	* itself, and a wave under one end rocks it. The water's `drag` then bleeds
+	* velocity and spin in proportion to how much is under, which is what stops
+	* a pushed crate and lets a bob die out.
+	*/
+	applyBuoyancy(dt) {
+		if (this.watersStale) {
+			this.waters.length = 0;
+			const root = this.engine.scene?.root;
+			if (root) collectWaters(root, this.waters);
+			this.watersStale = false;
+		}
+		if (this.waters.length === 0) return;
+		const g = Math.abs(this.world.gravity.y) || 9.81;
+		for (const [node, e] of this.entries) {
+			if (!(node instanceof RigidBody3D) || !(node.buoyancy > 0)) continue;
+			if (node.children.some((c) => typeNameOf(c) === "CharacterController3D")) continue;
+			if (e.hull === void 0) e.hull = hullOf(e.collider, this.R.ShapeType.Capsule);
+			const hull = e.hull;
+			if (!hull) continue;
+			const t = e.body.translation();
+			const q = e.body.rotation();
+			quatScratch.set(q.x, q.y, q.z, q.w);
+			let submerged = 0;
+			let water = null;
+			for (const [ox, oy, oz] of OCTANTS) {
+				buoyScratch.set(ox * hull.hx / 2, oy * hull.hy / 2, oz * hull.hz / 2).applyQuaternion(quatScratch);
+				const px = t.x + buoyScratch.x;
+				const py = t.y + buoyScratch.y;
+				const pz = t.z + buoyScratch.z;
+				const here = this.waterAt(px, pz);
+				if (!here) continue;
+				const f = Math.min(1, Math.max(0, (here.heightAt(px, pz) - (py - hull.hy / 4)) / (hull.hy / 2)));
+				if (f <= 0) continue;
+				water = here;
+				submerged += f / 8;
+				const lift = WATER_DENSITY * g * (hull.volume / 8) * f * node.buoyancy * dt;
+				e.body.applyImpulseAtPoint({
+					x: 0,
+					y: lift,
+					z: 0
+				}, {
+					x: px,
+					y: py,
+					z: pz
+				}, true);
+			}
+			if (submerged <= 0 || !water) continue;
+			const m = e.body.mass();
+			const lv = e.body.linvel();
+			const waterplane = 4 * hull.hx * hull.hz;
+			const heaveK = WATER_DENSITY * g * waterplane * node.buoyancy;
+			const heave = Math.min(1, 2 * HEAVE_ZETA * Math.sqrt(heaveK * m) / m * dt);
+			const k = Math.min(1, water.drag * Math.min(1, 4 * submerged) * dt);
+			e.body.applyImpulse({
+				x: -lv.x * m * k,
+				y: -lv.y * m * heave,
+				z: -lv.z * m * k
+			}, true);
+			if (k <= 0) continue;
+			const inertia = m * (hull.hx * hull.hx + hull.hy * hull.hy + hull.hz * hull.hz) / 3;
+			const spin = Math.min(1, k * SPIN_DRAG);
+			const av = e.body.angvel();
+			e.body.applyTorqueImpulse({
+				x: -av.x * inertia * spin,
+				y: -av.y * inertia * spin,
+				z: -av.z * inertia * spin
+			}, true);
+		}
+	}
+	/** The water whose footprint covers world (x, z), or null. */
+	waterAt(x, z) {
+		for (const w of this.waters) {
+			if (w.tree === null) continue;
+			if (w._waterYAt(x, z) !== null) return w;
+		}
+		return null;
+	}
 	ensureEntry(node) {
 		let e = this.entries.get(node);
 		const R = this.R;
@@ -780,9 +1110,11 @@ var Physics3D = class {
 			if (node instanceof RigidBody3D) desc = R.RigidBodyDesc.dynamic();
 			else if (node instanceof CharacterBody3D || node instanceof Area3D) desc = R.RigidBodyDesc.kinematicPositionBased();
 			else desc = R.RigidBodyDesc.fixed();
-			const [wx, wy, wz] = worldPosition3D(node);
+			worldPose3D(node, wpV, quatScratch);
+			const wx = wpV.x;
+			const wy = wpV.y;
+			const wz = wpV.z;
 			desc.setTranslation(wx, wy, wz);
-			quatScratch.setFromEuler(eulerScratch.set((node.rotation[0] ?? 0) * DEG, (node.rotation[1] ?? 0) * DEG, (node.rotation[2] ?? 0) * DEG, "XYZ"));
 			desc.setRotation({
 				x: quatScratch.x,
 				y: quatScratch.y,
@@ -821,11 +1153,22 @@ var Physics3D = class {
 					node.rotation[1] ?? 0,
 					node.rotation[2] ?? 0
 				],
+				lastQuat: [
+					quatScratch.x,
+					quatScratch.y,
+					quatScratch.z,
+					quatScratch.w
+				],
 				lastV: [
 					0,
 					0,
 					0
 				],
+				lastAV: [
+					node instanceof RigidBody3D && !node.fixedRotation ? node.angularVelocity[0] ?? 0 : 0,
+					node instanceof RigidBody3D && !node.fixedRotation ? node.angularVelocity[1] ?? 0 : 0,
+					node instanceof RigidBody3D && !node.fixedRotation ? node.angularVelocity[2] ?? 0 : 0
+				],
 				lastMass: node instanceof RigidBody3D ? node.mass : 1,
 				lastFriction: node.friction ?? .5,
 				lastRestitution: node.restitution ?? 0,
@@ -853,7 +1196,11 @@ var Physics3D = class {
 			node._enabledChanged = false;
 			if (node.enabled) this.armOverlaps(node, e.collider);
 		}
-		const p = worldPosition3D(node);
+		worldPose3D(node, wpV, quatScratch);
+		const p = posScratch;
+		p[0] = wpV.x;
+		p[1] = wpV.y;
+		p[2] = wpV.z;
 		if (p[0] !== e.last[0] || p[1] !== e.last[1] || p[2] !== e.last[2]) {
 			e.body.setTranslation({
 				x: p[0],
@@ -868,14 +1215,17 @@ var Physics3D = class {
 		const rx = node.rotation[0] ?? 0;
 		const ry = node.rotation[1] ?? 0;
 		const rz = node.rotation[2] ?? 0;
-		if (rx !== e.lastRot[0] || ry !== e.lastRot[1] || rz !== e.lastRot[2]) {
-			quatScratch.setFromEuler(eulerScratch.set(rx * DEG, ry * DEG, rz * DEG, "XYZ"));
+		if (quatScratch.x !== e.lastQuat[0] || quatScratch.y !== e.lastQuat[1] || quatScratch.z !== e.lastQuat[2] || quatScratch.w !== e.lastQuat[3]) {
 			e.body.setRotation({
 				x: quatScratch.x,
 				y: quatScratch.y,
 				z: quatScratch.z,
 				w: quatScratch.w
 			}, true);
+			e.lastQuat[0] = quatScratch.x;
+			e.lastQuat[1] = quatScratch.y;
+			e.lastQuat[2] = quatScratch.z;
+			e.lastQuat[3] = quatScratch.w;
 			e.lastRot[0] = rx;
 			e.lastRot[1] = ry;
 			e.lastRot[2] = rz;
@@ -894,6 +1244,19 @@ var Physics3D = class {
 				}, true);
 				e.lastV = v;
 			}
+			const av = [
+				node.angularVelocity[0] ?? 0,
+				node.angularVelocity[1] ?? 0,
+				node.angularVelocity[2] ?? 0
+			];
+			if (av[0] !== e.lastAV[0] || av[1] !== e.lastAV[1] || av[2] !== e.lastAV[2]) {
+				if (!node.fixedRotation) e.body.setAngvel({
+					x: av[0],
+					y: av[1],
+					z: av[2]
+				}, true);
+				e.lastAV = av;
+			}
 			if (node.gravityScale !== e.body.gravityScale()) e.body.setGravityScale(node.gravityScale, true);
 			if (node.mass !== e.lastMass) {
 				e.collider.setMass(node.mass);
@@ -923,16 +1286,55 @@ var Physics3D = class {
 	}
 	/** Apply a world-space impulse to a dynamic body (character controllers). */
 	applyImpulse(node, impulse) {
-		this.entries.get(node)?.body.applyImpulse({
+		const e = this.entries.get(node);
+		if (!e) return;
+		if (node instanceof RigidBody3D) {
+			const v = node.linearVelocity;
+			const vx = v[0] ?? 0;
+			const vy = v[1] ?? 0;
+			const vz = v[2] ?? 0;
+			if (vx !== e.lastV[0] || vy !== e.lastV[1] || vz !== e.lastV[2]) e.body.setLinvel({
+				x: vx,
+				y: vy,
+				z: vz
+			}, true);
+		}
+		e.body.applyImpulse({
 			x: impulse[0],
 			y: impulse[1],
 			z: impulse[2]
 		}, true);
+		if (node instanceof RigidBody3D) {
+			const lv = e.body.linvel();
+			node.linearVelocity[0] = lv.x;
+			node.linearVelocity[1] = lv.y;
+			node.linearVelocity[2] = lv.z;
+			e.lastV = [
+				lv.x,
+				lv.y,
+				lv.z
+			];
+		}
 	}
 	/** Mass the solver actually uses (collider-derived unless overridden). */
 	massOf(node) {
 		return this.entries.get(node)?.body.mass() ?? 1;
 	}
+	/** The solver's rotation of a body, as a quaternion `[x, y, z, w]`. */
+	rotationOf(node) {
+		const q = this.entries.get(node)?.body.rotation();
+		return q ? [
+			q.x,
+			q.y,
+			q.z,
+			q.w
+		] : [
+			0,
+			0,
+			0,
+			1
+		];
+	}
 	/** Current solver velocity (fresher than the node prop mid-step). */
 	velocityOf(node) {
 		const v = this.entries.get(node)?.body.linvel();
@@ -953,14 +1355,27 @@ var Physics3D = class {
 			for (const [joint, impulse] of this.joints) if (!this.jointSet.has(joint)) {
 				this.world.removeImpulseJoint(impulse, true);
 				this.joints.delete(joint);
+				const pair = this.jointBodies.get(joint);
+				if (pair) this.unlinkJointed(pair[0], pair[1]);
+				this.jointBodies.delete(joint);
+				this.hingeState.delete(joint);
+				this.tetherState.delete(joint);
 			}
 		}
 		for (const joint of this.jointSet) {
-			if (this.joints.has(joint)) continue;
+			if (this.joints.has(joint) || this.refusedJoints.has(joint)) continue;
 			const { a, b } = joint._resolveBodies();
 			const ea = this.entries.get(a);
 			const eb = this.entries.get(b);
 			if (!ea || !eb) continue;
+			if (joint.type === "revolute" || joint.type === "prismatic") {
+				const off = axisDisagreementDeg(ea.body.rotation(), eb.body.rotation(), joint.axis);
+				if (off > .5) {
+					this.refusedJoints.add(joint);
+					diagnose(this.engine, "error", `[incanto] Joint3D '${joint.getPath()}': its two bodies disagree about the ${joint.type} axis by ${off.toFixed(1)}° — '${a.name}' and '${b.name}' are authored with rotations that differ by more than a turn about ${JSON.stringify(joint.axis)}, and Rapier reads the axis in BOTH bodies' local frames. Give both bodies the same rotation (turn the MESH inside the body instead — an 'auto' collider follows it), or rotate one only about the axis. The joint was not made.`);
+					continue;
+				}
+			}
 			const a1 = {
 				x: joint.anchor[0] ?? 0,
 				y: joint.anchor[1] ?? 0,
@@ -987,10 +1402,93 @@ var Physics3D = class {
 			if (joint.type === "fixed") data = R.JointData.fixed(a1, identity, a2, identity);
 			else if (joint.type === "rope") data = R.JointData.rope(length, a1, a2);
 			else if (joint.type === "spring") data = R.JointData.spring(length, joint.stiffness, joint.damping, a1, a2);
-			else data = R.JointData.spherical(a1, a2);
+			else if (joint.type === "revolute" || joint.type === "prismatic") {
+				const ax = joint.axis[0] ?? 0;
+				const ay = joint.axis[1] ?? 0;
+				const az = joint.axis[2] ?? 0;
+				const n = Math.hypot(ax, ay, az) || 1;
+				const axis = {
+					x: ax / n,
+					y: ay / n,
+					z: az / n
+				};
+				data = joint.type === "revolute" ? R.JointData.revolute(a1, a2, axis) : R.JointData.prismatic(a1, a2, axis);
+			} else data = R.JointData.spherical(a1, a2);
 			const made = this.world.createImpulseJoint(data, ea.body, eb.body, true);
-			made.setContactsEnabled(jointContacts(joint.type, joint.collide));
+			if (joint.type === "revolute" || joint.type === "prismatic") this.applyHinge(joint, made, true);
+			const contacts = jointContacts(joint.type, joint.collide);
+			made.setContactsEnabled(contacts);
 			this.joints.set(joint, made);
+			this.jointBodies.set(joint, [a, b]);
+			this.linkJointed(a, b, contacts);
+			if (joint.type === "rope" || joint.type === "spring") this.tetherState.set(joint, this.tetherKey(joint));
+		}
+		for (const [joint, made] of this.joints) {
+			if (joint.type !== "rope" && joint.type !== "spring") continue;
+			const key = this.tetherKey(joint);
+			if (this.tetherState.get(joint) === key) continue;
+			this.world.removeImpulseJoint(made, true);
+			this.joints.delete(joint);
+			const pair = this.jointBodies.get(joint);
+			if (pair) this.unlinkJointed(pair[0], pair[1]);
+			this.jointBodies.delete(joint);
+			this.tetherState.delete(joint);
+		}
+		for (const [joint, made] of this.joints) {
+			if (joint.type !== "revolute" && joint.type !== "prismatic") continue;
+			this.applyHinge(joint, made, false);
+			const pair = this.jointBodies.get(joint);
+			const ea = pair && this.entries.get(pair[0]);
+			const eb = pair && this.entries.get(pair[1]);
+			if (!ea || !eb) continue;
+			if (joint.type === "revolute") joint.angle = hingeAngle3D(ea.body.rotation(), eb.body.rotation(), joint.axis);
+			else {
+				const qa = ea.body.rotation();
+				const ta = ea.body.translation();
+				const tb = eb.body.translation();
+				const wa = rotateVec3(qa, joint.anchor[0] ?? 0, joint.anchor[1] ?? 0, joint.anchor[2] ?? 0);
+				const wb = rotateVec3(eb.body.rotation(), joint.targetAnchor[0] ?? 0, joint.targetAnchor[1] ?? 0, joint.targetAnchor[2] ?? 0);
+				const ax = rotateVec3(qa, joint.axis[0] ?? 0, joint.axis[1] ?? 0, joint.axis[2] ?? 0);
+				const n = Math.hypot(ax[0], ax[1], ax[2]) || 1;
+				const dx = ta.x + wa[0] - (tb.x + wb[0]);
+				const dy = ta.y + wa[1] - (tb.y + wb[1]);
+				const dz = ta.z + wa[2] - (tb.z + wb[2]);
+				joint.travel = (dx * ax[0] + dy * ax[1] + dz * ax[2]) / n;
+			}
+		}
+	}
+	/**
+	* Push a hinge's `limits` and motor to the solver — on creation, and again
+	* whenever either changes. Limits and `angle` are this body relative to the
+	* target; Rapier measures the other way round, hence the flip.
+	*/
+	applyHinge(joint, made, first) {
+		const limits = JSON.stringify(joint.limits);
+		const motor = `${joint.motorSpeed}/${joint.motorStrength}`;
+		const last = this.hingeState.get(joint);
+		const unit = made;
+		const unitScale = joint.type === "revolute" ? DEG : 1;
+		if (first || last?.limits !== limits) {
+			if (joint.limits.length === 2) {
+				const lo = (joint.limits[0] ?? 0) * unitScale;
+				const hi = (joint.limits[1] ?? 0) * unitScale;
+				unit.setLimits(-Math.max(lo, hi), -Math.min(lo, hi));
+			} else if (!first) unit.setLimits(-1e9, 1e9);
+		}
+		if (first || last?.motor !== motor) {
+			if (joint.motorSpeed !== 0) unit.configureMotorVelocity(-joint.motorSpeed * unitScale, joint.motorStrength);
+			else if (!first) unit.configureMotorVelocity(0, 0);
+		}
+		this.hingeState.set(joint, {
+			limits,
+			motor
+		});
+		if (joint.motorSpeed !== 0) {
+			const pair = this.jointBodies.get(joint);
+			for (const b of pair ?? []) {
+				const e = this.entries.get(b);
+				if (e && !e.body.isFixed() && e.body.isSleeping()) e.body.wakeUp();
+			}
 		}
 	}
 	/** Who is currently inside each sensor/body, maintained from the event drain. */
@@ -1168,6 +1666,111 @@ var Physics3D = class {
 };
 const quatScratch = new Quaternion();
 const eulerScratch = new Euler();
+const buoyScratch = new Vector3();
+/** Fresh water, kg/m³ — the reference `RigidBody3D.buoyancy: 1` scales. */
+const WATER_DENSITY = 1e3;
+/** Damping ratio of a floating body's bob: under 1 so it still rocks once. */
+const HEAVE_ZETA = .7;
+/** Spin loses `drag` × this per second — rotation in water is the slow thing. */
+const SPIN_DRAG = 3;
+/** The eight octant centres of a collider, in units of its half extents. */
+const OCTANTS = [
+	[
+		-1,
+		-1,
+		-1
+	],
+	[
+		1,
+		-1,
+		-1
+	],
+	[
+		-1,
+		-1,
+		1
+	],
+	[
+		1,
+		-1,
+		1
+	],
+	[
+		-1,
+		1,
+		-1
+	],
+	[
+		1,
+		1,
+		-1
+	],
+	[
+		-1,
+		1,
+		1
+	],
+	[
+		1,
+		1,
+		1
+	]
+];
+const typeNameOf = (node) => node.constructor.typeName;
+function collectWaters(node, out) {
+	if (node instanceof Water3D) out.push(node);
+	for (const child of node.children) collectWaters(child, out);
+}
+/**
+* Half extents and volume of a collider, from the shape Rapier built — so an
+* `auto` box, a fitted hull and an authored sphere all answer. A hull or mesh
+* is taken as the box around its vertices: a rock floats like its crate,
+* which is the right answer for a rock and a wrong one nobody will ship.
+*/
+function hullOf(collider, capsuleType) {
+	const he = collider.halfExtents();
+	if (he) return {
+		hx: he.x,
+		hy: he.y,
+		hz: he.z,
+		volume: 8 * he.x * he.y * he.z
+	};
+	const r = collider.radius();
+	const hh = collider.halfHeight();
+	if (r !== null && hh !== null && hh > 0) {
+		const capsule = collider.shapeType() === capsuleType;
+		const caps = capsule ? 4 / 3 * Math.PI * r ** 3 : 0;
+		return {
+			hx: r,
+			hy: hh + (capsule ? r : 0),
+			hz: r,
+			volume: Math.PI * r * r * 2 * hh + caps
+		};
+	}
+	if (r !== null) return {
+		hx: r,
+		hy: r,
+		hz: r,
+		volume: 4 / 3 * Math.PI * r ** 3
+	};
+	const v = collider.vertices();
+	if (!v || v.length < 3) return null;
+	let maxX = 0;
+	let maxY = 0;
+	let maxZ = 0;
+	for (let i = 0; i + 2 < v.length; i += 3) {
+		maxX = Math.max(maxX, Math.abs(v[i] ?? 0));
+		maxY = Math.max(maxY, Math.abs(v[i + 1] ?? 0));
+		maxZ = Math.max(maxZ, Math.abs(v[i + 2] ?? 0));
+	}
+	if (maxX === 0 || maxY === 0 || maxZ === 0) return null;
+	return {
+		hx: maxX,
+		hy: maxY,
+		hz: maxZ,
+		volume: 8 * maxX * maxY * maxZ
+	};
+}
 function collectJoints(node, out) {
 	if (node instanceof Joint3D) out.add(node);
 	for (const c of node.children) collectJoints(c, out);
@@ -1379,39 +1982,58 @@ function characterHalfHeight(node) {
 	if (collider.shape === "sphere" && typeof collider.radius === "number") return collider.radius;
 	return 1;
 }
-function worldPosition3D(node) {
-	let x = 0;
-	let y = 0;
-	let z = 0;
-	for (let n = node; n; n = n.parent) if (n instanceof Node3D) {
-		x += n.position[0] ?? 0;
-		y += n.position[1] ?? 0;
-		z += n.position[2] ?? 0;
+const poseChain = [];
+const poseV = new Vector3();
+const poseQ = new Quaternion();
+const poseStepQ = new Quaternion();
+const poseEuler = new Euler();
+/**
+* The WORLD pose of `node` — position and orientation composed through every
+* Node3D ancestor, the way the renderer composes them. This used to sum
+* positions only: a child two metres down +z of a hull turned 90° was put at
+* world +z while the renderer drew it at world +x, so a guard's grab box "in
+* front" of a turned guard, a turret's muzzle and a tank's barrel-tip sensor
+* all sat where nothing was drawn. `outQuat` may be omitted when only the
+* position is wanted. Scale is not composed (it never was).
+*/
+function worldPose3D(node, outPos, outQuat) {
+	poseChain.length = 0;
+	for (let n = node; n; n = n.parent) if (n instanceof Node3D) poseChain.push(n);
+	outPos.set(0, 0, 0);
+	const q = outQuat ?? poseQ;
+	q.identity();
+	for (let i = poseChain.length - 1; i >= 0; i--) {
+		const n = poseChain[i];
+		poseV.set(n.position[0] ?? 0, n.position[1] ?? 0, n.position[2] ?? 0).applyQuaternion(q);
+		outPos.add(poseV);
+		const r = n.rotation;
+		if ((r[0] ?? 0) !== 0 || (r[1] ?? 0) !== 0 || (r[2] ?? 0) !== 0) {
+			poseStepQ.setFromEuler(poseEuler.set((r[0] ?? 0) * DEG, (r[1] ?? 0) * DEG, (r[2] ?? 0) * DEG, "XYZ"));
+			q.multiply(poseStepQ);
+		}
 	}
-	posScratch[0] = x;
-	posScratch[1] = y;
-	posScratch[2] = z;
+}
+const wpV = new Vector3();
+function worldPosition3D(node) {
+	worldPose3D(node, wpV, null);
+	posScratch[0] = wpV.x;
+	posScratch[1] = wpV.y;
+	posScratch[2] = wpV.z;
 	return posScratch;
 }
-const offsetScratch = [
-	0,
-	0,
-	0
-];
-/** Writes into the shared scratch — consume before the next call. */
-function parentWorldOffset3D(node) {
-	let x = 0;
-	let y = 0;
-	let z = 0;
+const parentPosV = new Vector3();
+const parentQuatQ = new Quaternion();
+const localV = new Vector3();
+const localQ = new Quaternion();
+const invQ = new Quaternion();
+/** The pose of `node`'s PARENT frame in world space — what a body's world pose is measured against. */
+function parentPose3D(node) {
+	let parent = null;
 	for (let n = node.parent; n; n = n.parent) if (n instanceof Node3D) {
-		x += n.position[0] ?? 0;
-		y += n.position[1] ?? 0;
-		z += n.position[2] ?? 0;
+		parent = n;
+		break;
 	}
-	offsetScratch[0] = x;
-	offsetScratch[1] = y;
-	offsetScratch[2] = z;
-	return offsetScratch;
+	worldPose3D(parent, parentPosV, parentQuatQ);
 }
 function parseCollider3D(R, node) {
 	const collider = node.collider;