incanto 0.1.0

package/dist/create-game-BdjpTHrW.js

@@ -0,0 +1,1725 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { _ as registerBehavior, n as loadScene } from "./loader-CGs_G-r0.js";
+import { a as Engine } from "./particle-sim-DYuSUxvK.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { r as AudioPlayer } from "./register-BuUV1_KB.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
+import { n as registerGameplayBehaviors } from "./gameplay-Ccruc3Wd.js";
+import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
+import { O as Node3D, T as PhysicsBody3D, c as ModelInstance3D, t as registerNodes3D, u as DirectionalLight3D, v as Camera3D } from "./register-CNlYAS1_.js";
+import { n as enablePhysics3D } from "./physics-3d-Dl67vOLT.js";
+import { ACESFilmicToneMapping, AmbientLight, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
+import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
+import { Sky } from "three/examples/jsm/objects/Sky.js";
+//#region src/3d/assets.ts
+/**
+* GLB/glTF/VRM store for the 3D adapter. Scene `assets` entries:
+*
+*   {type:"model",     url}            → ModelInstance3D `model: "$key"`
+*   {type:"animation", url, clip?}     → ModelInstance3D `animation: "$key"`
+*                                        (clips live in memory, never drawn)
+*
+* Raw URLs also work anywhere a `$key` does. VRM files load through
+* @pixiv/three-vrm (VRM 0.x facing fixed via rotateVRM0).
+*/
+var AssetStore3D = class {
+	models = /* @__PURE__ */ new Map();
+	animations = /* @__PURE__ */ new Map();
+	modelKeys = /* @__PURE__ */ new Map();
+	animationKeys = /* @__PURE__ */ new Map();
+	loader;
+	constructor() {
+		this.loader = new GLTFLoader();
+		this.loader.register((parser) => new VRMLoaderPlugin(parser));
+	}
+	/** Map a scene's `assets` header. */
+	load(assets) {
+		for (const [key, def] of Object.entries(assets)) {
+			const entry = def;
+			if (typeof entry.url !== "string") continue;
+			if (entry.type === "model") this.modelKeys.set(`$${key}`, entry.url);
+			else if (entry.type === "animation") this.animationKeys.set(`$${key}`, {
+				url: entry.url,
+				clip: entry.clip
+			});
+		}
+	}
+	/** Animation `$key`s declared by the scene (editor dropdowns). */
+	animationRefs() {
+		return [...this.animationKeys.keys()];
+	}
+	modelRefs() {
+		return [...this.modelKeys.keys()];
+	}
+	/** Resolve `$key` or URL; kicks off the load on first sight. */
+	getModel(ref) {
+		const url = this.modelKeys.get(ref) ?? ref;
+		let entry = this.models.get(url);
+		if (entry) return entry;
+		entry = {
+			status: "loading",
+			scene: null,
+			animations: [],
+			isVrm: false,
+			vrm: null,
+			claimedBy: null,
+			retargeted: /* @__PURE__ */ new Map()
+		};
+		this.models.set(url, entry);
+		this.loader.load(url, (gltf) => {
+			const vrm = gltf.userData.vrm;
+			if (vrm) {
+				VRMUtils.removeUnnecessaryVertices(gltf.scene);
+				VRMUtils.combineSkeletons(gltf.scene);
+				VRMUtils.rotateVRM0(vrm);
+				entry.scene = vrm.scene;
+				entry.vrm = vrm;
+				entry.isVrm = true;
+			} else entry.scene = gltf.scene;
+			entry.animations = gltf.animations ?? [];
+			entry.status = "ready";
+		}, void 0, (error) => {
+			entry.status = "error";
+			entry.error = error instanceof Error ? error.message : String(error);
+			console.error(`incanto: failed to load model '${url}':`, error);
+		});
+		return entry;
+	}
+	/** Resolve an animation `$key` or URL; clips load into memory only. */
+	getAnimation(ref) {
+		const def = this.animationKeys.get(ref) ?? { url: ref };
+		let entry = this.animations.get(def.url);
+		if (entry) return entry;
+		entry = {
+			status: "loading",
+			clips: [],
+			scene: null,
+			clip: def.clip
+		};
+		this.animations.set(def.url, entry);
+		this.loader.load(def.url, (gltf) => {
+			entry.clips = gltf.animations ?? [];
+			entry.scene = gltf.scene;
+			entry.status = "ready";
+			if (entry.clips.length === 0) console.warn(`incanto: animation asset '${def.url}' contains no clips`);
+		}, void 0, (error) => {
+			entry.status = "error";
+			entry.error = error instanceof Error ? error.message : String(error);
+			console.error(`incanto: failed to load animation '${def.url}':`, error);
+		});
+		return entry;
+	}
+	dispose() {
+		for (const entry of this.models.values()) entry.scene?.traverse((obj) => {
+			const mesh = obj;
+			mesh.geometry?.dispose();
+			const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+			for (const mat of mats) {
+				if (!mat) continue;
+				for (const value of Object.values(mat)) value?.isTexture && value.dispose();
+				mat.dispose();
+			}
+		});
+		this.models.clear();
+		this.animations.clear();
+	}
+};
+//#endregion
+//#region src/3d/clouds/clouds-composite.ts
+/**
+* Volumetric clouds — a raymarched cloud DECK the camera flies through, drawn as
+* ONE depth-aware fullscreen composite (the engine has no post pipeline, so this
+* mirrors the underwater-caustics pass). It runs only when `environment.clouds`
+* is declared:
+*
+*   1. the renderer renders the scene to an offscreen target (color + depth)
+*   2. this fullscreen material reconstructs each pixel's view RAY from the
+*      depth/inverse-view-proj, marches it through a world-space altitude slab
+*      [uBase, uTop], accumulates fractal-noise cloud density with cheap
+*      single-scatter sun lighting, and composites the result OVER the scene —
+*      clipped to the scene depth so clouds behind solid geometry are hidden.
+*
+* Because the clouds live in world space (noise sampled at the marched world
+* position), they have real parallax: they sit still as you bank, grow as you
+* approach, and swallow the screen as you punch through them.
+*/
+const CLOUDS_VERT = `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+const CLOUDS_FRAG = `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D tDepth;
+uniform mat4 uInvViewProj;
+uniform vec3 uCameraPos;
+uniform float uTime;
+uniform vec3 uSunDir;       // unit, toward the sun
+uniform vec3 uSunColor;
+uniform vec3 uCloudColor;   // sunlit
+uniform vec3 uShadeColor;   // shaded underside
+uniform vec3 uHorizonColor; // distant haze the clouds fade into
+uniform float uBase;
+uniform float uTop;
+uniform float uCoverage;    // 0..1
+uniform float uDensity;     // optical thickness multiplier
+uniform float uScale;       // feature size (world units)
+uniform vec2 uWind;         // drift dir * speed
+uniform float uFarFade;     // distance over which clouds melt into haze
+
+// ---- value noise + FBM (hash-based, no texture) ----------------------------------
+float hash(vec3 p) {
+  p = fract(p * 0.3183099 + 0.1);
+  p *= 17.0;
+  return fract(p.x * p.y * p.z * (p.x + p.y + p.z));
+}
+float vnoise(vec3 x) {
+  vec3 i = floor(x);
+  vec3 f = fract(x);
+  f = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(mix(hash(i + vec3(0,0,0)), hash(i + vec3(1,0,0)), f.x),
+        mix(hash(i + vec3(0,1,0)), hash(i + vec3(1,1,0)), f.x), f.y),
+    mix(mix(hash(i + vec3(0,0,1)), hash(i + vec3(1,0,1)), f.x),
+        mix(hash(i + vec3(0,1,1)), hash(i + vec3(1,1,1)), f.x), f.y),
+    f.z);
+}
+float fbm(vec3 p) {
+  float s = 0.0;
+  float a = 0.5;
+  for (int i = 0; i < 3; i++) {
+    s += a * vnoise(p);
+    p = p * 2.04 + vec3(11.7, 3.1, 5.3);
+    a *= 0.5;
+  }
+  return s;
+}
+
+// vertical envelope: wispy base + top, dense middle → cumulus, not a flat slab
+float cloudEnv(vec3 wp) {
+  float h = clamp((wp.y - uBase) / (uTop - uBase), 0.0, 1.0);
+  return smoothstep(0.0, 0.18, h) * smoothstep(1.0, 0.55, h);
+}
+
+// COARSE density (base FBM only) — used for the sun light-march, which doesn't
+// need the fine erosion detail, so each lit step stays cheap (one fbm).
+float cloudDensityCoarse(vec3 wp) {
+  float env = cloudEnv(wp);
+  if (env <= 0.0) return 0.0;
+  vec3 q = wp / uScale;
+  q.xz += uWind * uTime * 0.03;
+  return max(0.0, fbm(q) - (1.0 - uCoverage)) * env * 2.0;
+}
+
+// FULL density: coarse shape eroded by two higher-frequency layers → crisp
+// billowy cauliflower edges instead of soft amorphous blobs.
+float cloudDensity(vec3 wp) {
+  float env = cloudEnv(wp);
+  if (env <= 0.0) return 0.0;
+  vec3 q = wp / uScale;
+  q.xz += uWind * uTime * 0.03;
+  float d = fbm(q) - (1.0 - uCoverage);
+  if (d <= 0.0) return 0.0; // empty space — skip the erosion noise (cheap)
+  d -= 0.30 * vnoise(q * 3.2 + 4.0);
+  d -= 0.14 * vnoise(q * 8.5 + 9.0);
+  return max(0.0, d) * env * 2.0;
+}
+
+void main() {
+  float depth = texture2D(tDepth, vUv).x;
+
+  // view ray (world space) for this pixel
+  vec4 farNdc = vec4(vUv * 2.0 - 1.0, 1.0, 1.0);
+  vec4 farW = uInvViewProj * farNdc;
+  farW.xyz /= farW.w;
+  vec3 ro = uCameraPos;
+  vec3 rd = normalize(farW.xyz - ro);
+
+  // distance to the nearest solid surface along the ray (sky = far away)
+  float sceneDist = 1e9;
+  if (depth < 1.0) {
+    vec4 ndc = vec4(vUv * 2.0 - 1.0, depth * 2.0 - 1.0, 1.0);
+    vec4 wp = uInvViewProj * ndc;
+    wp.xyz /= wp.w;
+    sceneDist = distance(wp.xyz, ro);
+  }
+
+  // intersect the ray with the altitude slab [uBase, uTop]
+  float t0 = 0.0;
+  float t1 = uFarFade * 1.6;
+  if (abs(rd.y) > 1e-4) {
+    float ta = (uBase - ro.y) / rd.y;
+    float tb = (uTop - ro.y) / rd.y;
+    t0 = max(t0, min(ta, tb));
+    t1 = min(t1, max(ta, tb));
+  } else {
+    // ray nearly parallel to the slab: only valid if we're inside it
+    if (ro.y < uBase || ro.y > uTop) { gl_FragColor = vec4(0.0); return; }
+  }
+  t1 = min(t1, sceneDist);
+  if (t1 <= t0) { gl_FragColor = vec4(0.0); return; }
+
+  // raymarch (capped step count; clamp the marched span so steps stay dense)
+  // Break step-aliasing rings with INTERLEAVED GRADIENT NOISE (IGN) rather than a
+  // Bayer matrix (which upscaled into a regular halftone GRID) or no dither (which
+  // left banding RINGS). IGN is high-quality de-correlated noise that, softened by
+  // the composite blur, dissolves into smooth cloud — affordable at a modest step
+  // count instead of brute-forcing steps (which blew the frame budget).
+  const int STEPS = 32;
+  float span = min(t1 - t0, 2000.0);
+  float step = span / float(STEPS);
+  float ign = fract(52.9829189 * fract(0.06711056 * gl_FragCoord.x + 0.00583715 * gl_FragCoord.y));
+  float t = t0 + step * ign;
+  float trans = 1.0;
+  vec3 accum = vec3(0.0);
+  vec3 litColor = mix(vec3(1.0), uSunColor, 0.35) * uCloudColor; // mostly-white
+  // EXT = per-metre extinction. step is in metres, so without this the optical
+  // depth per step is enormous (one step → solid white blobs). ~0.03/m + the
+  // uDensity dial gives clouds that build up gradually and keep their FORM.
+  float ext = 0.03 * uDensity;
+  for (int i = 0; i < STEPS; i++) {
+    if (trans < 0.02) break;
+    vec3 p = ro + rd * t;
+    float d = cloudDensity(p);
+    if (d > 0.001) {
+      // single-scatter: ONE coarse tap toward the sun (cheap — keeps per-step cost
+      // low) → sunlit crests vs softly shaded sides. Clouds multi-scatter a LOT, so
+      // shadows are gentle (low extinction *1.5) and floored bright (0.45..1) — real
+      // cumulus from above are mostly white, not dark-grey blotches.
+      float sunTau = cloudDensityCoarse(p + uSunDir * 110.0) * 110.0 * ext;
+      float light = mix(0.45, 1.0, exp(-sunTau * 1.5));
+      vec3 col = mix(uShadeColor, litColor, light);
+      float a = d * ext * step;          // optical depth this step
+      float w = (1.0 - exp(-a)) * trans; // energy scattered toward the eye
+      accum += col * w;
+      trans *= exp(-a);
+    }
+    t += step;
+  }
+
+  float alpha = clamp(1.0 - trans, 0.0, 1.0);
+  // Melt distant clouds fully into the horizon haze BEFORE they smear: looking
+  // edge-on through the thin slab, far samples streak — so fade the whole cloud
+  // contribution out over distance and drop alpha to 0 by the far edge.
+  float distFade = 1.0 - smoothstep(uFarFade * 0.25, uFarFade * 0.7, t0);
+  accum = mix(uHorizonColor * alpha, accum, distFade);
+  alpha *= distFade;
+
+  // output PREMULTIPLIED cloud color + coverage — composited over the scene in
+  // a separate full-res pass (this raymarch runs at HALF res for performance)
+  gl_FragColor = vec4(accum, alpha);
+}
+`;
+/** Separable Gaussian blur on the low-res cloud buffer — run twice (H then V).
+* Wide enough to fully dissolve the raymarch dither (incl. IGN's diagonal grain)
+* into smooth cloud; cheap because it runs at the low cloud-buffer resolution. */
+const CLOUDS_BLUR_FRAG = `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D tTex;
+uniform vec2 uDir; // (texel, 0) horizontal pass, then (0, texel) vertical
+void main() {
+  // 9-tap Gaussian (sigma ~2.2 texels) — weights sum to 1
+  vec4 c = texture2D(tTex, vUv) * 0.20;
+  c += texture2D(tTex, vUv + uDir * 1.0) * 0.166;
+  c += texture2D(tTex, vUv - uDir * 1.0) * 0.166;
+  c += texture2D(tTex, vUv + uDir * 2.0) * 0.096;
+  c += texture2D(tTex, vUv - uDir * 2.0) * 0.096;
+  c += texture2D(tTex, vUv + uDir * 3.0) * 0.04;
+  c += texture2D(tTex, vUv - uDir * 3.0) * 0.04;
+  c += texture2D(tTex, vUv + uDir * 4.0) * 0.015;
+  c += texture2D(tTex, vUv - uDir * 4.0) * 0.015;
+  gl_FragColor = c;
+}
+`;
+/** Composite pass: blend the (pre-blurred) low-res cloud buffer over the scene. */
+const CLOUDS_COMPOSITE_FRAG = `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D tScene;
+uniform sampler2D tClouds;
+void main() {
+  vec4 scene = texture2D(tScene, vUv);
+  vec4 cloud = texture2D(tClouds, vUv); // already separable-blurred + premultiplied
+  gl_FragColor = vec4(scene.rgb * (1.0 - cloud.a) + cloud.rgb, 1.0);
+}
+`;
+/** Separable-blur quad (run twice: horizontal then vertical) over the low-res
+* cloud buffer — set `uDir` to (1/w, 0) then (0, 1/h). */
+function createCloudsBlurQuad() {
+	const material = new ShaderMaterial({
+		vertexShader: CLOUDS_VERT,
+		fragmentShader: CLOUDS_BLUR_FRAG,
+		depthTest: false,
+		depthWrite: false,
+		uniforms: {
+			tTex: { value: null },
+			uDir: { value: new Vector2() }
+		}
+	});
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
+	return {
+		mesh,
+		uniforms: material.uniforms
+	};
+}
+/** The half-res raymarch quad — writes premultiplied cloud color + coverage. */
+function createCloudsQuad() {
+	const material = new ShaderMaterial({
+		vertexShader: CLOUDS_VERT,
+		fragmentShader: CLOUDS_FRAG,
+		depthTest: false,
+		depthWrite: false,
+		uniforms: {
+			tDepth: { value: null },
+			uInvViewProj: { value: new Matrix4() },
+			uCameraPos: { value: new Vector3() },
+			uTime: { value: 0 },
+			uSunDir: { value: new Vector3(0, 1, 0) },
+			uSunColor: { value: new Color("#fff3da") },
+			uCloudColor: { value: new Color("#ffffff") },
+			uShadeColor: { value: new Color("#9fb0c8") },
+			uHorizonColor: { value: new Color("#cdd9e6") },
+			uBase: { value: 120 },
+			uTop: { value: 320 },
+			uCoverage: { value: .5 },
+			uDensity: { value: 1 },
+			uScale: { value: 240 },
+			uWind: { value: new Vector2(1, .3) },
+			uFarFade: { value: 6e3 }
+		}
+	});
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
+	return {
+		mesh,
+		uniforms: material.uniforms
+	};
+}
+/** The full-res composite quad — blends the half-res cloud buffer over the scene. */
+function createCloudsCompositeQuad() {
+	const material = new ShaderMaterial({
+		vertexShader: CLOUDS_VERT,
+		fragmentShader: CLOUDS_COMPOSITE_FRAG,
+		depthTest: false,
+		depthWrite: false,
+		uniforms: {
+			tScene: { value: null },
+			tClouds: { value: null }
+		}
+	});
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
+	return {
+		mesh,
+		uniforms: material.uniforms
+	};
+}
+//#endregion
+//#region src/3d/environment.ts
+const SKY_KEYS = [
+	"type",
+	"sunPosition",
+	"elevationDeg",
+	"azimuthDeg",
+	"turbidity",
+	"rayleigh"
+];
+const FOG_KEYS = [
+	"color",
+	"near",
+	"far"
+];
+const CLOUD_KEYS = [
+	"coverage",
+	"density",
+	"base",
+	"top",
+	"color",
+	"shadeColor",
+	"speed",
+	"scale"
+];
+const SHADOW_KEYS = ["mapSize", "radius"];
+const SHADOW_MAP_SIZES = [1024, 2048];
+const DEFAULT_TURBIDITY = 2;
+const DEFAULT_RAYLEIGH = 1;
+const DEFAULT_FOG_NEAR = 50;
+const DEFAULT_FOG_FAR = 800;
+/** Fallback haze when fog is declared without a sky to derive a horizon from. */
+const DEFAULT_FOG_COLOR = "#cfd8e0";
+const DEG2RAD = Math.PI / 180;
+/** Parse + hard-validate the 3D slice of a scene's `environment` header. */
+function parseEnvironment3D(env) {
+	return {
+		exposure: parseExposure(env?.exposure),
+		sky: parseSky(env?.sky),
+		fog: parseFog(env?.fog, env?.sky !== void 0),
+		clouds: parseClouds(env?.clouds),
+		shadows: parseShadows(env?.shadows)
+	};
+}
+/**
+* elevation/azimuth (degrees) → unit direction. Matches three's Sky example
+* (`Vector3.setFromSphericalCoords`): azimuth 0 = +Z, 90 = +X; elevation 90 =
+* straight up.
+*/
+function sunDirectionFromElevationAzimuth(elevationDeg, azimuthDeg) {
+	const phi = (90 - elevationDeg) * DEG2RAD;
+	const theta = azimuthDeg * DEG2RAD;
+	return [
+		Math.sin(phi) * Math.sin(theta),
+		Math.cos(phi),
+		Math.sin(phi) * Math.cos(theta)
+	];
+}
+/** The sky's sun as a UNIT vector — what Water3D/Foliage3D uniforms consume. */
+function sunDirectionFromSky(sky) {
+	const [x, y, z] = sky.sunPosition;
+	const len = Math.hypot(x, y, z) || 1;
+	return [
+		x / len,
+		y / len,
+		z / len
+	];
+}
+/**
+* A horizon-ish haze color derived from the sky config — the default fog
+* color. Cheap model, judged by eye: clear skies haze blue-grey, turbid skies
+* whiten, and a low sun warms the band toward amber.
+*/
+function horizonColorFromSky(sky) {
+	const clear = [
+		191,
+		213,
+		232
+	];
+	const hazy = [
+		233,
+		228,
+		217
+	];
+	const warm = [
+		242,
+		201,
+		150
+	];
+	const t = clamp01((sky.turbidity - DEFAULT_TURBIDITY) / 8);
+	const dir = sunDirectionFromSky(sky);
+	const w = clamp01((18 - Math.asin(clamp(dir[1], -1, 1)) / DEG2RAD) / 18) * .8;
+	const mix = (i) => Math.round(lerp(lerp(clear[i], hazy[i], t), warm[i], w));
+	return `#${[
+		mix(0),
+		mix(1),
+		mix(2)
+	].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+}
+function parseExposure(value) {
+	if (value === void 0) return 1;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new IncantoError("BAD_FORMAT", `environment.exposure must be a finite number > 0 (tone-mapping exposure, default 1), got ${JSON.stringify(value)}.`, { prop: "exposure" });
+	return value;
+}
+function parseSky(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.sky must be an object ({ type?: "atmosphere", sunPosition? | elevationDeg?+azimuthDeg?, turbidity?, rayleigh? }), got ${JSON.stringify(value)}.`, { prop: "sky" });
+	const sky = value;
+	for (const key of Object.keys(sky)) if (!SKY_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.sky has unknown key '${key}'. Valid keys: [${SKY_KEYS.join(", ")}].`, {
+		prop: "sky",
+		validOptions: SKY_KEYS
+	});
+	if (sky.type !== void 0 && sky.type !== "atmosphere") throw new IncantoError("BAD_FORMAT", `environment.sky.type must be 'atmosphere' (the only sky type so far), got ${JSON.stringify(sky.type)}.`, {
+		prop: "sky",
+		validOptions: ["atmosphere"]
+	});
+	const hasAngles = sky.elevationDeg !== void 0 || sky.azimuthDeg !== void 0;
+	if (sky.sunPosition !== void 0 && hasAngles) throw new IncantoError("BAD_FORMAT", `environment.sky takes sunPosition OR elevationDeg/azimuthDeg, not both.`, {
+		prop: "sky",
+		validOptions: ["sunPosition", "elevationDeg+azimuthDeg"]
+	});
+	let sunPosition;
+	if (sky.sunPosition !== void 0) {
+		const sp = sky.sunPosition;
+		if (!Array.isArray(sp) || sp.length !== 3 || !sp.every((v) => typeof v === "number" && Number.isFinite(v)) || Math.hypot(sp[0], sp[1], sp[2]) === 0) throw new IncantoError("BAD_FORMAT", `environment.sky.sunPosition must be a non-zero [x, y, z] vector, got ${JSON.stringify(sp)}.`, { prop: "sky" });
+		sunPosition = [
+			sp[0],
+			sp[1],
+			sp[2]
+		];
+	} else {
+		const elevation = numberOr(sky.elevationDeg, 32, "sky.elevationDeg");
+		const azimuth = numberOr(sky.azimuthDeg, 135, "sky.azimuthDeg");
+		if (elevation < -90 || elevation > 90) throw new IncantoError("BAD_FORMAT", `environment.sky.elevationDeg must be in [-90, 90] (degrees above the horizon), got ${elevation}.`, { prop: "sky" });
+		sunPosition = sunDirectionFromElevationAzimuth(elevation, azimuth);
+	}
+	const turbidity = numberOr(sky.turbidity, DEFAULT_TURBIDITY, "sky.turbidity");
+	if (turbidity <= 0) throw new IncantoError("BAD_FORMAT", `environment.sky.turbidity must be > 0 (atmospheric haze; 2 ≈ clear day), got ${turbidity}.`, { prop: "sky" });
+	const rayleigh = numberOr(sky.rayleigh, DEFAULT_RAYLEIGH, "sky.rayleigh");
+	if (rayleigh < 0) throw new IncantoError("BAD_FORMAT", `environment.sky.rayleigh must be >= 0 (Rayleigh scattering; 1 ≈ earth-like), got ${rayleigh}.`, { prop: "sky" });
+	return {
+		sunPosition,
+		turbidity,
+		rayleigh
+	};
+}
+function parseFog(value, hasSky) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.fog must be an object ({ color?, near?, far? }), got ${JSON.stringify(value)}.`, { prop: "fog" });
+	const fog = value;
+	for (const key of Object.keys(fog)) if (!FOG_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.fog has unknown key '${key}'. Valid keys: [${FOG_KEYS.join(", ")}].`, {
+		prop: "fog",
+		validOptions: FOG_KEYS
+	});
+	if (fog.color !== void 0 && typeof fog.color !== "string") throw new IncantoError("BAD_FORMAT", `environment.fog.color must be a hex color string, got ${JSON.stringify(fog.color)}.`, { prop: "fog" });
+	const near = numberOr(fog.near, DEFAULT_FOG_NEAR, "fog.near");
+	const far = numberOr(fog.far, DEFAULT_FOG_FAR, "fog.far");
+	if (near < 0) throw new IncantoError("BAD_FORMAT", `environment.fog.near must be >= 0 meters, got ${near}.`, { prop: "fog" });
+	if (far <= near) throw new IncantoError("BAD_FORMAT", `environment.fog.far must be > near (got near ${near}, far ${far}).`, { prop: "fog" });
+	return {
+		color: fog.color ?? (hasSky ? "" : DEFAULT_FOG_COLOR),
+		near,
+		far
+	};
+}
+function parseClouds(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.clouds must be an object ({ coverage?, density?, base?, top?, color?, shadeColor?, speed?, scale? }), got ${JSON.stringify(value)}.`, { prop: "clouds" });
+	const c = value;
+	for (const key of Object.keys(c)) if (!CLOUD_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.clouds has unknown key '${key}'. Valid keys: [${CLOUD_KEYS.join(", ")}].`, {
+		prop: "clouds",
+		validOptions: CLOUD_KEYS
+	});
+	for (const k of ["color", "shadeColor"]) if (c[k] !== void 0 && typeof c[k] !== "string") throw new IncantoError("BAD_FORMAT", `environment.clouds.${k} must be a hex color string, got ${JSON.stringify(c[k])}.`, { prop: "clouds" });
+	const coverage = numberOr(c.coverage, .5, "clouds.coverage");
+	if (coverage < 0 || coverage > 1) throw new IncantoError("BAD_FORMAT", `environment.clouds.coverage must be in [0, 1] (how much sky is cloudy), got ${coverage}.`, { prop: "clouds" });
+	const density = numberOr(c.density, 1, "clouds.density");
+	if (density < 0) throw new IncantoError("BAD_FORMAT", `environment.clouds.density must be >= 0 (optical thickness), got ${density}.`, { prop: "clouds" });
+	const base = numberOr(c.base, 120, "clouds.base");
+	const top = numberOr(c.top, 320, "clouds.top");
+	if (top <= base) throw new IncantoError("BAD_FORMAT", `environment.clouds.top must be > base (got base ${base}, top ${top}).`, { prop: "clouds" });
+	const speed = numberOr(c.speed, 1, "clouds.speed");
+	const scale = numberOr(c.scale, 240, "clouds.scale");
+	if (scale <= 0) throw new IncantoError("BAD_FORMAT", `environment.clouds.scale must be > 0 (feature size in world units), got ${scale}.`, { prop: "clouds" });
+	return {
+		coverage,
+		density,
+		base,
+		top,
+		color: c.color ?? "#ffffff",
+		shadeColor: c.shadeColor ?? "#9fb0c8",
+		speed,
+		scale
+	};
+}
+function parseShadows(value) {
+	if (value === void 0) return null;
+	if (value === false) return false;
+	if (value === true) return {
+		mapSize: 2048,
+		radius: 1
+	};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.shadows must be true, false or an object ({ mapSize?, radius? }), got ${JSON.stringify(value)}.`, { prop: "shadows" });
+	const shadows = value;
+	for (const key of Object.keys(shadows)) if (!SHADOW_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.shadows has unknown key '${key}'. Valid keys: [${SHADOW_KEYS.join(", ")}].`, {
+		prop: "shadows",
+		validOptions: SHADOW_KEYS
+	});
+	const mapSize = shadows.mapSize === void 0 ? 2048 : shadows.mapSize;
+	if (!SHADOW_MAP_SIZES.includes(mapSize)) throw new IncantoError("BAD_FORMAT", `environment.shadows.mapSize must be one of [${SHADOW_MAP_SIZES.join(", ")}], got ${JSON.stringify(shadows.mapSize)}.`, {
+		prop: "shadows",
+		validOptions: SHADOW_MAP_SIZES.map(String)
+	});
+	const radius = numberOr(shadows.radius, 1, "shadows.radius");
+	if (radius < 0) throw new IncantoError("BAD_FORMAT", `environment.shadows.radius must be >= 0, got ${radius}.`, { prop: "shadows" });
+	return {
+		mapSize,
+		radius
+	};
+}
+function numberOr(value, fallback, at) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new IncantoError("BAD_FORMAT", `environment.${at} must be a finite number, got ${JSON.stringify(value)}.`, { prop: at });
+	return value;
+}
+function clamp(v, min, max) {
+	return Math.min(Math.max(v, min), max);
+}
+function clamp01(v) {
+	return clamp(v, 0, 1);
+}
+function lerp(a, b, t) {
+	return a + (b - a) * t;
+}
+//#endregion
+//#region src/3d/environment-presets.ts
+/**
+* drei-compatible environment presets: each name maps to a 1k HDRI (the exact
+* Poly Haven CC0 files @react-three/drei ships), so `preset="sunset"` lights the
+* same here. Served from the agent8 CDN (the only sanctioned external host, same
+* as the terrain splat) — set `environment.hdri` to override with your own URL.
+*/
+const CDN = "https://agent8-games.verse8.io/assets/3D/default/textures/hdri";
+const ENVIRONMENT_PRESETS = {
+	apartment: "lebombo_1k.hdr",
+	city: "potsdamer_platz_1k.hdr",
+	dawn: "kiara_1_dawn_1k.hdr",
+	forest: "forest_slope_1k.hdr",
+	lobby: "st_fagans_interior_1k.hdr",
+	night: "dikhololo_night_1k.hdr",
+	park: "rooitou_park_1k.hdr",
+	studio: "studio_small_03_1k.hdr",
+	sunset: "venice_sunset_1k.hdr",
+	warehouse: "empty_warehouse_01_1k.hdr"
+};
+/** Resolve `environment.preset` / `environment.hdri` to the HDR url (or null). */
+function resolveEnvironmentHdri(env) {
+	if (typeof env.hdri === "string" && env.hdri !== "") return env.hdri;
+	if (typeof env.preset === "string") {
+		const file = ENVIRONMENT_PRESETS[env.preset];
+		if (!file) throw new Error(`Unknown environment preset '${env.preset}'. Available: ${Object.keys(ENVIRONMENT_PRESETS).join(", ")}.`);
+		return `${CDN}/${file}`;
+	}
+	return null;
+}
+//#endregion
+//#region src/3d/environment-3d.ts
+/** Shadow ortho half-extent when the env header forces a light to cast and the
+* light node configured nothing itself. One static box around the origin — no
+* cascaded shadow maps yet, so huge worlds trade shadow sharpness for reach. */
+const DEFAULT_SHADOW_AREA = 75;
+/**
+* Applies the scene `environment` header to a three scene — the rendering
+* stage Renderer3D delegates to. One instance per renderer; `apply` runs once
+* per frame but re-parses/rebuilds only when the env JSON actually changed.
+*
+* Headless-safe: `gl` is nullable, and everything GPU-bound (PMREM
+* image-based lighting, exposure, shadow-map switches) is skipped without it
+* while the scene-graph side (Sky object, fog, background, ambient) still
+* applies — that's what the node-environment tests assert against.
+*/
+var Environment3D = class {
+	scene;
+	ambient = new AmbientLight("#ffffff", 0);
+	envKey = null;
+	config = parseEnvironment3D(void 0);
+	hdriUrl = null;
+	hdriTexture = null;
+	/** @internal The Sky backdrop object (tests reach in). */
+	_sky = null;
+	skyKey = "";
+	skyEnvKey = "";
+	skyEnvTarget = null;
+	fog = new Fog("#ffffff", 1, 1e3);
+	/** Underwater fog/tint, created lazily the first time the camera submerges. */
+	underwaterFog = null;
+	underwaterBg = new Color();
+	constructor(scene) {
+		this.scene = scene;
+		this.scene.add(this.ambient);
+	}
+	/** The sky's unit sun direction, or null when no sky is declared. */
+	get sunDirection() {
+		return this.config.sky ? sunDirectionFromSky(this.config.sky) : null;
+	}
+	/** Parsed volumetric-cloud config, or null when no cloud layer is declared. */
+	get clouds() {
+		return this.config.clouds;
+	}
+	/** The live scene fog (color/near/far) the cloud composite fades into, or null. */
+	get sceneFog() {
+		return this.scene.fog instanceof Fog ? this.scene.fog : null;
+	}
+	/** Apply the env header. Cheap when unchanged; hard-validates on change. */
+	apply(env, gl) {
+		const key = env === void 0 ? "" : JSON.stringify(env);
+		if (key !== this.envKey) {
+			this.envKey = key;
+			this.config = parseEnvironment3D(env);
+		}
+		const cfg = this.config;
+		const ambient = env?.ambient;
+		this.ambient.color.set(ambient?.color ?? "#ffffff");
+		this.ambient.intensity = ambient?.intensity ?? 0;
+		if (gl) {
+			gl.toneMappingExposure = cfg.exposure;
+			gl.shadowMap.enabled = cfg.shadows !== false;
+		}
+		this.applyHdri(env);
+		this.applySky(cfg.sky, gl);
+		if (this._sky) this._sky.visible = true;
+		this.applyFog(cfg);
+		this.scene.environment = this.hdriTexture ?? this.skyEnvTarget?.texture ?? null;
+		this.scene.environmentIntensity = (this.scene.environment === this.skyEnvTarget?.texture && this.skyEnvTarget ? .55 : 1) * parseIblIntensity(env?.iblIntensity);
+		if (env?.skybox === true && this.hdriTexture) this.scene.background = this.hdriTexture;
+		else {
+			const background = env?.background;
+			this.scene.background = typeof background === "string" ? new Color(background) : null;
+		}
+	}
+	/**
+	* Per-frame hand-off for the scene's MAIN DirectionalLight (the renderer
+	* passes the brightest one after the sync pass — never auto-created):
+	*
+	* - sky declared → the light's backing object is re-aimed along the sun
+	*   direction (its distance from origin is kept, so the node's `position`
+	*   keeps meaning "how far out the sun sits")
+	* - `shadows` declared truthy → the light casts; env mapSize/radius win,
+	*   and lights that configured nothing themselves get the default ortho box
+	*/
+	applySunLight(light, focus = null) {
+		if (!light) return;
+		const sun = this.sunDirection;
+		if (focus) {
+			const distance = light.position.length() || 100;
+			let dx;
+			let dy;
+			let dz;
+			if (sun) [dx, dy, dz] = sun;
+			else {
+				dx = light.position.x - light.target.position.x;
+				dy = light.position.y - light.target.position.y;
+				dz = light.position.z - light.target.position.z;
+				const len = Math.hypot(dx, dy, dz) || 1;
+				dx /= len;
+				dy /= len;
+				dz /= len;
+			}
+			light.target.position.set(focus.x, focus.y, focus.z);
+			light.target.updateMatrixWorld();
+			light.position.set(focus.x + dx * distance, focus.y + dy * distance, focus.z + dz * distance);
+		} else if (sun) {
+			const distance = light.position.length() || 100;
+			light.position.set(sun[0], sun[1], sun[2]).multiplyScalar(distance);
+		}
+		const shadows = this.config.shadows;
+		if (shadows && typeof shadows === "object") {
+			if (!light.castShadow) {
+				const cam = light.shadow.camera;
+				if ("left" in cam && cam.left === -5) {
+					cam.left = -75;
+					cam.right = DEFAULT_SHADOW_AREA;
+					cam.top = DEFAULT_SHADOW_AREA;
+					cam.bottom = -75;
+					cam.near = .5;
+					cam.far = 500;
+					cam.updateProjectionMatrix();
+				}
+				light.castShadow = true;
+			}
+			if (light.shadow.mapSize.x !== shadows.mapSize) {
+				light.shadow.mapSize.set(shadows.mapSize, shadows.mapSize);
+				light.shadow.map?.dispose();
+				light.shadow.map = null;
+			}
+			light.shadow.radius = shadows.radius;
+		}
+	}
+	/**
+	* Underwater override (the renderer passes the resolved config from whichever
+	* water the camera is submerged in, or null). When submerged, the scene
+	* switches to a short-range underwater fog + matching background AND the sky
+	* dome is hidden — without that you'd see the bright sky through the surface
+	* and the murk would never read. `null` is a no-op: the per-frame `apply`
+	* already (re)established the normal fog/background/sky, so surfacing restores
+	* the look for free.
+	*/
+	applyUnderwater(config) {
+		if (!config) return;
+		if (!this.underwaterFog) this.underwaterFog = new Fog("#000000", .5, config.visibility);
+		this.underwaterFog.color.set(config.color);
+		this.underwaterFog.near = .5;
+		this.underwaterFog.far = config.visibility;
+		this.scene.fog = this.underwaterFog;
+		this.scene.background = this.underwaterBg.set(config.color);
+		if (this._sky) this._sky.visible = false;
+	}
+	applyHdri(env) {
+		const url = resolveEnvironmentHdri(env ?? {});
+		if (url === this.hdriUrl) return;
+		this.hdriUrl = url;
+		this.hdriTexture?.dispose();
+		this.hdriTexture = null;
+		if (url) new RGBELoader().load(url, (texture) => {
+			if (this.hdriUrl !== url) {
+				texture.dispose();
+				return;
+			}
+			texture.mapping = EquirectangularReflectionMapping;
+			this.hdriTexture = texture;
+		});
+	}
+	applySky(sky, gl) {
+		const skyKey = sky ? JSON.stringify(sky) : "";
+		if (skyKey !== this.skyKey) {
+			this.skyKey = skyKey;
+			if (this._sky) {
+				this.scene.remove(this._sky);
+				this._sky.material.dispose();
+				this._sky.geometry.dispose();
+				this._sky = null;
+			}
+			if (sky) {
+				this._sky = new Sky();
+				this._sky.scale.setScalar(45e4);
+				const u = this._sky.material.uniforms;
+				(u.sunPosition?.value).set(...sky.sunPosition);
+				if (u.turbidity) u.turbidity.value = sky.turbidity;
+				if (u.rayleigh) u.rayleigh.value = sky.rayleigh;
+				this.scene.add(this._sky);
+			}
+		}
+		if (sky && gl && this._sky && this.skyEnvKey !== skyKey) {
+			this.skyEnvKey = skyKey;
+			this.skyEnvTarget?.dispose();
+			const pmrem = new PMREMGenerator(gl);
+			const skyOnly = new Scene();
+			skyOnly.add(this._sky);
+			this.skyEnvTarget = pmrem.fromScene(skyOnly);
+			pmrem.dispose();
+			this.scene.add(this._sky);
+		}
+		if (!sky && this.skyEnvTarget) {
+			this.skyEnvTarget.dispose();
+			this.skyEnvTarget = null;
+			this.skyEnvKey = "";
+		}
+	}
+	applyFog(cfg) {
+		if (!cfg.fog) {
+			this.scene.fog = null;
+			return;
+		}
+		const color = cfg.fog.color || (cfg.sky ? horizonColorFromSky(cfg.sky) : "#cfd8e0");
+		this.fog.color.set(color);
+		this.fog.near = cfg.fog.near;
+		this.fog.far = cfg.fog.far;
+		this.scene.fog = this.fog;
+	}
+	dispose() {
+		this.hdriTexture?.dispose();
+		this.hdriTexture = null;
+		this.skyEnvTarget?.dispose();
+		this.skyEnvTarget = null;
+		if (this._sky) {
+			this.scene.remove(this._sky);
+			this._sky.material.dispose();
+			this._sky.geometry.dispose();
+			this._sky = null;
+		}
+	}
+};
+/** Hard-validate `environment.iblIntensity` (default 1 = keep the base). */
+function parseIblIntensity(value) {
+	if (value === void 0) return 1;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new IncantoError("BAD_FORMAT", `environment.iblIntensity must be a finite number >= 0 (multiplies the image-based ambience: sky-derived base 0.55, HDRI base 1; default 1), got ${JSON.stringify(value)}.`, { prop: "iblIntensity" });
+	return value;
+}
+//#endregion
+//#region src/3d/sync.ts
+function isSpatialConsumer(node) {
+	return node.spatial === true && typeof node._setSpatialPose === "function";
+}
+function createSyncScratch() {
+	const visited = /* @__PURE__ */ new Set();
+	const cameras = [];
+	const renderHooks = [];
+	const emitters = [];
+	return {
+		visited,
+		cameras,
+		renderHooks,
+		emitters,
+		state: {
+			visited,
+			cameras,
+			renderHooks,
+			emitters,
+			assets: void 0,
+			sunDirection: null,
+			sunLight: null,
+			alpha: 1
+		}
+	};
+}
+/**
+* Mirror an Incanto node tree onto a three.js scene (dirty-push, once per frame):
+*
+* - every Node3D's backing Object3D is parented under its nearest Node3D
+*   ancestor's object (plain Nodes are transparent), falling back to the scene
+* - transforms/props are pushed via `_syncObject3D`
+* - backing objects whose nodes left the tree are pruned
+* - returns the active camera (`current: true` wins, else first in tree order)
+*
+* Pure scene-graph math — no WebGL — so it tests headlessly with real three.
+*/
+function syncTree(root, threeScene, assets, opts, scratch) {
+	const s = scratch ?? createSyncScratch();
+	s.visited.clear();
+	s.cameras.length = 0;
+	s.renderHooks.length = 0;
+	s.emitters.length = 0;
+	const state = s.state;
+	state.assets = assets;
+	state.sunDirection = opts?.sunDirection ?? null;
+	state.sunLight = null;
+	state.alpha = opts?.alpha ?? 1;
+	walk(root, threeScene, state);
+	prune(threeScene, s.visited);
+	let current = null;
+	for (let i = 0; i < s.cameras.length; i++) {
+		const c = s.cameras[i];
+		if (c.current) {
+			current = c;
+			break;
+		}
+	}
+	if (!current) current = s.cameras[0] ?? null;
+	const activeCamera = current ? current._ensureObject3D() : null;
+	feedSpatialEmitters(s.emitters, activeCamera);
+	return {
+		activeCamera,
+		renderHooks: s.renderHooks,
+		sunLight: state.sunLight
+	};
+}
+const emitterScratch = new Vector3();
+const listenerScratch = new Vector3();
+const forwardScratch = new Vector3();
+const upScratch = new Vector3();
+/**
+* Push each spatial AudioPlayer the live listener (active camera) pose + its own
+* world position, so the WebAudio panner / src distance-attenuation tracks the
+* scene each frame. Runs AFTER the walk so matrices are current and the active
+* camera is known. With no camera there's no listener → skip (headless-safe).
+*/
+function feedSpatialEmitters(emitters, camera) {
+	if (emitters.length === 0 || !camera) return;
+	camera.updateWorldMatrix(true, false);
+	camera.getWorldPosition(listenerScratch);
+	camera.getWorldDirection(forwardScratch);
+	upScratch.set(0, 1, 0).applyQuaternion(camera.quaternion);
+	const listener = {
+		position: [
+			listenerScratch.x,
+			listenerScratch.y,
+			listenerScratch.z
+		],
+		forward: [
+			forwardScratch.x,
+			forwardScratch.y,
+			forwardScratch.z
+		],
+		up: [
+			upScratch.x,
+			upScratch.y,
+			upScratch.z
+		]
+	};
+	for (const { node, parent } of emitters) {
+		parent.updateWorldMatrix(true, false);
+		parent.getWorldPosition(emitterScratch);
+		node._setSpatialPose({
+			position: [
+				emitterScratch.x,
+				emitterScratch.y,
+				emitterScratch.z
+			],
+			listener
+		});
+	}
+}
+function walk(node, parentObj, state) {
+	let nextParent = parentObj;
+	if (node instanceof Node3D) {
+		const obj = node._ensureObject3D();
+		if (obj.parent !== parentObj) parentObj.add(obj);
+		node._syncObject3D(state.alpha);
+		if (state.assets && node instanceof ModelInstance3D) node._syncModel(state.assets);
+		if (typeof node._onRender3D === "function") state.renderHooks.push(node);
+		if (state.sunDirection) {
+			const applySun = node._applySunDirection;
+			if (typeof applySun === "function") applySun.call(node, state.sunDirection);
+		}
+		if (node instanceof DirectionalLight3D) {
+			if (!state.sunLight || node.intensity > state.sunLight.intensity) state.sunLight = node;
+		}
+		state.visited.add(obj);
+		if (node instanceof Camera3D) state.cameras.push(node);
+		nextParent = obj;
+	} else if (isSpatialConsumer(node)) state.emitters.push({
+		node,
+		parent: nextParent
+	});
+	for (const child of node.children) walk(child, nextParent, state);
+}
+function prune(obj, visited) {
+	const ch = obj.children;
+	for (let i = ch.length - 1; i >= 0; i--) {
+		const child = ch[i];
+		if (child.userData.incantoNode && !visited.has(child)) obj.remove(child);
+		else prune(child, visited);
+	}
+}
+//#endregion
+//#region src/3d/water/caustics.ts
+/**
+* Underwater caustics — the dancing refracted-light pattern the water surface
+* throws onto everything below it. The engine has no post-processing pipeline,
+* so the renderer does this as ONE depth-aware composite pass, and ONLY while
+* the camera is genuinely underwater (so normal above-water rendering — even
+* standing at the water's edge — is completely untouched):
+*
+*   1. render the scene to an offscreen target (color + depth)
+*   2. draw this fullscreen material, which reconstructs each pixel's WORLD
+*      position from the depth buffer and adds an animated caustic highlight
+*      wherever that world point sits below the water surface
+*
+* Because the pattern is keyed to reconstructed world XZ, it STICKS to the
+* floor/walls/props (it isn't a flat screen overlay) and fades with depth +
+* view distance so it melts into the underwater fog.
+*/
+/** Fullscreen triangle/quad — the vertex stage ignores the camera entirely. */
+const CAUSTICS_VERT = `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+const CAUSTICS_FRAG = `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D tColor;
+uniform sampler2D tDepth;
+uniform mat4 uInvViewProj;
+uniform vec3 uCameraPos;
+uniform float uWaterLevel;
+uniform float uTime;
+uniform vec3 uCausticColor;
+uniform float uCausticIntensity;
+uniform float uCausticScale;
+uniform float uMaxDist;
+
+// The classic animated caustic (layered moving cells). Returns 0..1.
+float caustic(vec2 uv, float t) {
+  vec2 p = mod(uv * 6.28318, 6.28318) - 250.0;
+  vec2 i = p;
+  float c = 1.0;
+  float inten = 0.005;
+  for (int n = 0; n < 5; n++) {
+    float ti = t * (1.0 - (3.5 / float(n + 1)));
+    i = p + vec2(cos(ti - i.x) + sin(ti + i.y), sin(ti - i.y) + cos(ti + i.x));
+    c += 1.0 / length(vec2(p.x / (sin(i.x + ti) / inten), p.y / (cos(i.y + ti) / inten)));
+  }
+  c /= 5.0;
+  c = 1.17 - pow(c, 1.4);
+  return clamp(pow(abs(c), 8.0), 0.0, 1.0);
+}
+
+void main() {
+  vec4 color = texture2D(tColor, vUv);
+  float depth = texture2D(tDepth, vUv).x;
+  // depth == 1 is the far plane (sky/background) — nothing to light there
+  if (depth < 1.0) {
+    vec4 ndc = vec4(vUv * 2.0 - 1.0, depth * 2.0 - 1.0, 1.0);
+    vec4 world = uInvViewProj * ndc;
+    world.xyz /= world.w;
+    float below = uWaterLevel - world.y;
+    if (below > 0.0) {
+      float dist = distance(world.xyz, uCameraPos);
+      // caustics — fade with distance (melt into the fog) + a touch with depth
+      float distFade = 1.0 - clamp(dist / uMaxDist, 0.0, 1.0);
+      float depthFade = 1.0 - clamp(below / (uMaxDist * 0.5), 0.0, 0.6);
+      // two octaves at offset speeds = the shimmering interference of real caustics
+      float c =
+        caustic(world.xz * uCausticScale, uTime) * 0.65 +
+        caustic(world.xz * uCausticScale * 1.7 + 30.0, uTime * 0.8) * 0.35;
+      color.rgb += uCausticColor * (c * uCausticIntensity * distFade * distFade * depthFade);
+    }
+  }
+  gl_FragColor = color;
+}
+`;
+/** Build the fullscreen composite mesh (a 2×2 clip-space quad). */
+function createCausticsQuad() {
+	const material = new ShaderMaterial({
+		vertexShader: CAUSTICS_VERT,
+		fragmentShader: CAUSTICS_FRAG,
+		depthTest: false,
+		depthWrite: false,
+		uniforms: {
+			tColor: { value: null },
+			tDepth: { value: null },
+			uInvViewProj: { value: new Matrix4() },
+			uCameraPos: { value: new Vector3() },
+			uWaterLevel: { value: 0 },
+			uTime: { value: 0 },
+			uCausticColor: { value: new Color("#cdeeff") },
+			uCausticIntensity: { value: .55 },
+			uCausticScale: { value: .32 },
+			uMaxDist: { value: 22 }
+		}
+	});
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
+	return {
+		mesh,
+		uniforms: material.uniforms
+	};
+}
+//#endregion
+//#region src/3d/renderer.ts
+/**
+* WebGL presentation layer: subscribes to `engine.updated`, mirrors the active
+* scene's node tree onto a three.js scene, applies the scene `environment`
+* header (ambient/background/sky/fog/shadows/exposure — see Environment3D),
+* and renders with the current Camera3D under ACES filmic tone mapping.
+*
+* Keep this class thin — everything testable lives in `syncTree`, the node
+* classes and `Environment3D`; this file is the only place that touches WebGL.
+*/
+var Renderer3D = class {
+	/**
+	* When set, the render uses THIS free camera instead of the scene's active
+	* Camera3D — tooling (the scene editor) orbits/pans without touching scene
+	* data. `null` restores normal camera behavior.
+	*/
+	viewOverride = null;
+	overrideCam = new PerspectiveCamera(60, 1, .05, 5e3);
+	lastCamera = null;
+	lastSize = {
+		w: 1,
+		h: 1
+	};
+	webgl;
+	threeScene = new Scene();
+	environment = new Environment3D(this.threeScene);
+	engine;
+	disconnect;
+	canvas;
+	assets;
+	ownsAssets;
+	loadedAssetScenes = /* @__PURE__ */ new WeakSet();
+	/** The scene whose GPU programs have been pre-compiled (warm-up, see render). */
+	compiledScene = null;
+	/** Reused per-frame walk scratch (instance-scoped — never a module global). */
+	syncScratch = createSyncScratch();
+	/** Reused render-hook context — gl/scene are stable, camera reassigned/frame. */
+	renderCtx = null;
+	/** Underwater caustics pass (lazy — only created the first time submerged). */
+	causticsTarget = null;
+	causticsScene = null;
+	causticsUniforms = null;
+	/** Volumetric cloud pass (lazy — only created when environment.clouds is set).
+	* The raymarch runs at HALF resolution into `cloudsHalfTarget`, then a cheap
+	* full-res composite blends it over the scene — keeps the heavy fullscreen
+	* raymarch off the critical path so it holds 60fps at retina. */
+	cloudsTarget = null;
+	cloudsHalfTarget = null;
+	cloudsBlurTarget = null;
+	cloudsScene = null;
+	cloudsUniforms = null;
+	cloudsBlurScene = null;
+	cloudsBlurUniforms = null;
+	cloudsCompositeScene = null;
+	cloudsCompositeUniforms = null;
+	constructor(opts) {
+		this.canvas = opts.canvas;
+		this.engine = opts.engine;
+		this.ownsAssets = !opts.assets;
+		this.assets = opts.assets ?? new AssetStore3D();
+		const rendering = resolveRendering(opts.engine.scene?.environment, {
+			antialias: true,
+			pixelRatio: Math.min(globalThis.devicePixelRatio ?? 1, 2)
+		}, globalThis.devicePixelRatio ?? 1, { pixelRatio: opts.pixelRatio });
+		this.webgl = new WebGLRenderer({
+			canvas: opts.canvas,
+			antialias: rendering.antialias
+		});
+		this.webgl.setPixelRatio(rendering.pixelRatio);
+		this.webgl.shadowMap.enabled = true;
+		this.webgl.shadowMap.type = PCFShadowMap;
+		this.webgl.toneMapping = ACESFilmicToneMapping;
+		this.webgl.toneMappingExposure = 1;
+		this.debugLines = new LineSegments(new BufferGeometry(), new LineBasicMaterial({
+			color: "#00ff6e",
+			depthTest: false
+		}));
+		this.debugLines.frustumCulled = false;
+		this.debugLines.renderOrder = 9999;
+		this.debugLines.visible = false;
+		this.threeScene.add(this.debugLines);
+		this.disconnect = this.engine.updated.connect(() => this.render());
+	}
+	debugLines;
+	syncDebugLines() {
+		let vertices = null;
+		for (const source of debugSources("3d")) {
+			vertices = source.debugLines();
+			if (vertices) break;
+		}
+		this.debugLines.visible = vertices !== null;
+		if (vertices) this.debugLines.geometry.setAttribute("position", new BufferAttribute(vertices, 3));
+	}
+	render() {
+		const scene = this.engine.scene;
+		if (!scene) return;
+		this.syncDebugLines();
+		if (scene.assets && !this.loadedAssetScenes.has(scene)) {
+			this.assets.load(scene.assets);
+			this.loadedAssetScenes.add(scene);
+		}
+		this.environment.apply(scene.environment, this.webgl);
+		const { activeCamera: sceneCamera, renderHooks, sunLight } = syncTree(scene.root, this.threeScene, this.assets, {
+			sunDirection: this.environment.sunDirection,
+			alpha: this.engine.interpolationAlpha
+		}, this.syncScratch);
+		let activeCamera = sceneCamera;
+		if (this.viewOverride) {
+			const [px, py, pz] = this.viewOverride.position;
+			const [tx, ty, tz] = this.viewOverride.target;
+			this.overrideCam.position.set(px, py, pz);
+			this.overrideCam.lookAt(lookScratch.set(tx, ty, tz));
+			activeCamera = this.overrideCam;
+		}
+		if (!activeCamera) return;
+		this.lastCamera = activeCamera;
+		activeCamera.updateWorldMatrix(true, false);
+		const camWorld = activeCamera.getWorldPosition(camPosScratch);
+		const threeLight = sunLight ? sunLight._ensureObject3D() : null;
+		const followsCamera = !!threeLight && sunLight.shadowFollowsCamera === true;
+		this.environment.applySunLight(threeLight, followsCamera ? camWorld : null);
+		if (this.compiledScene !== scene) {
+			this.compiledScene = scene;
+			this.webgl.compile(this.threeScene, activeCamera);
+		}
+		const w = this.canvas.clientWidth || this.canvas.width;
+		const h = this.canvas.clientHeight || this.canvas.height;
+		const size = this.webgl.getSize(sizeScratch);
+		if (size.x !== w || size.y !== h) this.webgl.setSize(w, h, false);
+		this.lastSize = {
+			w,
+			h
+		};
+		const aspect = h === 0 ? 1 : w / h;
+		if (activeCamera.aspect !== aspect) {
+			activeCamera.aspect = aspect;
+			activeCamera.updateProjectionMatrix();
+		}
+		if (!this.renderCtx) this.renderCtx = {
+			gl: this.webgl,
+			scene: this.threeScene,
+			camera: activeCamera
+		};
+		const ctx = this.renderCtx;
+		ctx.camera = activeCamera;
+		for (let i = 0; i < renderHooks.length; i++) renderHooks[i]?._onRender3D(ctx);
+		let underwater = null;
+		for (let i = 0; i < renderHooks.length; i++) {
+			const uw = renderHooks[i].underwaterAt?.(camWorld.x, camWorld.y, camWorld.z);
+			if (uw) {
+				underwater = uw;
+				break;
+			}
+		}
+		this.environment.applyUnderwater(underwater);
+		const clouds = this.environment.clouds;
+		if (underwater?.caustics.enabled) this.renderWithCaustics(activeCamera, underwater);
+		else if (clouds && !underwater) this.renderWithClouds(activeCamera, clouds, threeLight);
+		else this.webgl.render(this.threeScene, activeCamera);
+	}
+	/**
+	* Volumetric cloud pass (only when `environment.clouds` is declared — scenes
+	* without it render exactly as before, zero cost). Three steps:
+	*   1. scene → full-res offscreen target (color + depth)
+	*   2. raymarch the cloud slab → HALF-res target (the heavy fullscreen work,
+	*      run at ¼ the pixels so it holds 60fps even at retina)
+	*   3. composite the half-res cloud buffer over the full-res scene → screen
+	*/
+	renderWithClouds(camera, clouds, sunLight) {
+		const buf = this.webgl.getDrawingBufferSize(sizeScratch);
+		const w = Math.max(1, buf.x);
+		const h = Math.max(1, buf.y);
+		const hw = Math.max(1, Math.ceil(w / 3));
+		const hh = Math.max(1, Math.ceil(h / 3));
+		if (this.cloudsTarget && (this.cloudsTarget.width !== w || this.cloudsTarget.height !== h)) {
+			this.cloudsTarget.depthTexture?.dispose();
+			this.cloudsTarget.dispose();
+			this.cloudsTarget = null;
+			this.cloudsHalfTarget?.dispose();
+			this.cloudsHalfTarget = null;
+			this.cloudsBlurTarget?.dispose();
+			this.cloudsBlurTarget = null;
+		}
+		if (!this.cloudsTarget) {
+			const depthTexture = new DepthTexture(w, h);
+			depthTexture.type = FloatType;
+			this.cloudsTarget = new WebGLRenderTarget(w, h, {
+				depthTexture,
+				depthBuffer: true
+			});
+		}
+		if (!this.cloudsHalfTarget) {
+			this.cloudsHalfTarget = new WebGLRenderTarget(hw, hh, { depthBuffer: false });
+			this.cloudsBlurTarget = new WebGLRenderTarget(hw, hh, { depthBuffer: false });
+		}
+		if (!this.cloudsScene) {
+			const { mesh, uniforms } = createCloudsQuad();
+			this.cloudsScene = new Scene();
+			this.cloudsScene.add(mesh);
+			this.cloudsUniforms = uniforms;
+		}
+		if (!this.cloudsBlurScene) {
+			const { mesh, uniforms } = createCloudsBlurQuad();
+			this.cloudsBlurScene = new Scene();
+			this.cloudsBlurScene.add(mesh);
+			this.cloudsBlurUniforms = uniforms;
+		}
+		if (!this.cloudsCompositeScene) {
+			const { mesh, uniforms } = createCloudsCompositeQuad();
+			this.cloudsCompositeScene = new Scene();
+			this.cloudsCompositeScene.add(mesh);
+			this.cloudsCompositeUniforms = uniforms;
+		}
+		this.webgl.setRenderTarget(this.cloudsTarget);
+		this.webgl.render(this.threeScene, camera);
+		const u = this.cloudsUniforms;
+		u.tDepth.value = this.cloudsTarget.depthTexture;
+		u.uInvViewProj.value.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse).invert();
+		camera.getWorldPosition(u.uCameraPos.value);
+		u.uTime.value = (globalThis.performance?.now() ?? 0) * .001 * clouds.speed;
+		const sun = this.environment.sunDirection ?? [
+			.4,
+			.8,
+			.3
+		];
+		u.uSunDir.value.set(sun[0], sun[1], sun[2]).normalize();
+		if (sunLight) u.uSunColor.value.copy(sunLight.color);
+		u.uCloudColor.value.set(clouds.color);
+		u.uShadeColor.value.set(clouds.shadeColor);
+		const fog = this.environment.sceneFog;
+		if (fog) {
+			u.uHorizonColor.value.copy(fog.color);
+			u.uFarFade.value = fog.far;
+		} else {
+			u.uHorizonColor.value.set("#cdd9e6");
+			u.uFarFade.value = 6e3;
+		}
+		u.uBase.value = clouds.base;
+		u.uTop.value = clouds.top;
+		u.uCoverage.value = clouds.coverage;
+		u.uDensity.value = clouds.density;
+		u.uScale.value = clouds.scale;
+		u.uWind.value.set(1, .35);
+		this.webgl.setRenderTarget(this.cloudsHalfTarget);
+		this.webgl.render(this.cloudsScene, camera);
+		const bu = this.cloudsBlurUniforms;
+		const blurScene = this.cloudsBlurScene;
+		bu.tTex.value = this.cloudsHalfTarget.texture;
+		bu.uDir.value.set(1 / hw, 0);
+		this.webgl.setRenderTarget(this.cloudsBlurTarget);
+		this.webgl.render(blurScene, camera);
+		bu.tTex.value = this.cloudsBlurTarget.texture;
+		bu.uDir.value.set(0, 1 / hh);
+		this.webgl.setRenderTarget(this.cloudsHalfTarget);
+		this.webgl.render(blurScene, camera);
+		this.webgl.setRenderTarget(null);
+		const cu = this.cloudsCompositeUniforms;
+		cu.tScene.value = this.cloudsTarget.texture;
+		cu.tClouds.value = this.cloudsHalfTarget.texture;
+		this.webgl.render(this.cloudsCompositeScene, camera);
+	}
+	/**
+	* Underwater caustics pass (only while submerged — normal rendering never
+	* touches this). Render the scene to an offscreen color+depth target, then a
+	* fullscreen composite that reconstructs each pixel's WORLD position from depth
+	* and adds an animated caustic highlight below the water line. World-keyed, so
+	* the pattern sticks to the floor/props instead of being a flat screen overlay.
+	*/
+	renderWithCaustics(camera, underwater) {
+		const buf = this.webgl.getDrawingBufferSize(sizeScratch);
+		const w = Math.max(1, buf.x);
+		const h = Math.max(1, buf.y);
+		if (this.causticsTarget && (this.causticsTarget.width !== w || this.causticsTarget.height !== h)) {
+			this.causticsTarget.depthTexture?.dispose();
+			this.causticsTarget.dispose();
+			this.causticsTarget = null;
+		}
+		if (!this.causticsTarget) {
+			const depthTexture = new DepthTexture(w, h);
+			depthTexture.type = FloatType;
+			this.causticsTarget = new WebGLRenderTarget(w, h, {
+				depthTexture,
+				depthBuffer: true
+			});
+		}
+		if (!this.causticsScene) {
+			const { mesh, uniforms } = createCausticsQuad();
+			this.causticsScene = new Scene();
+			this.causticsScene.add(mesh);
+			this.causticsUniforms = uniforms;
+		}
+		this.webgl.setRenderTarget(this.causticsTarget);
+		this.webgl.render(this.threeScene, camera);
+		this.webgl.setRenderTarget(null);
+		const u = this.causticsUniforms;
+		u.tColor.value = this.causticsTarget.texture;
+		u.tDepth.value = this.causticsTarget.depthTexture;
+		u.uInvViewProj.value.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse).invert();
+		camera.getWorldPosition(u.uCameraPos.value);
+		u.uWaterLevel.value = underwater.surfaceY;
+		u.uTime.value = (globalThis.performance?.now() ?? 0) * .001 * underwater.caustics.speed;
+		u.uCausticColor.value.set(underwater.caustics.color);
+		u.uCausticIntensity.value = underwater.caustics.intensity;
+		u.uCausticScale.value = underwater.caustics.scale;
+		u.uMaxDist.value = underwater.visibility;
+		this.webgl.render(this.causticsScene, camera);
+	}
+	/**
+	* Project a world point through the LAST rendered camera to canvas CSS px.
+	* `behind` is true when the point sits behind the camera (don't draw it).
+	*/
+	screenFromWorld(wx, wy, wz) {
+		const cam = this.lastCamera;
+		if (!cam) return {
+			x: 0,
+			y: 0,
+			behind: true
+		};
+		projScratch.set(wx, wy, wz).project(cam);
+		return {
+			x: (projScratch.x + 1) / 2 * this.lastSize.w,
+			y: (1 - projScratch.y) / 2 * this.lastSize.h,
+			behind: projScratch.z > 1
+		};
+	}
+	/**
+	* The node rendered under canvas pixel (sx, sy), or null — raycasts the last
+	* rendered camera into the scene and resolves the hit up to its `incantoNode`
+	* (every Node3D stamps that in `_ensureObject3D`). 3D depth-sorts, so the
+	* nearest hit wins. Mirrors `Renderer2D.pick` for click-to-select in the editor.
+	*/
+	pick(sx, sy) {
+		const cam = this.lastCamera;
+		if (!cam) return null;
+		pickNdc.set(sx / this.lastSize.w * 2 - 1, -(sy / this.lastSize.h * 2 - 1));
+		pickRaycaster.setFromCamera(pickNdc, cam);
+		const hits = pickRaycaster.intersectObjects(this.threeScene.children, true);
+		for (const hit of hits) {
+			let obj = hit.object;
+			while (obj && !obj.userData.incantoNode) obj = obj.parent;
+			const node = obj?.userData.incantoNode;
+			if (node) return node;
+		}
+		return null;
+	}
+	/**
+	* GPU counters for the LAST rendered frame, straight from three's
+	* per-frame-maintained `renderer.info` (render pass + GPU memory).
+	*/
+	stats() {
+		const info = this.webgl.info;
+		return {
+			triangles: info.render.triangles,
+			drawCalls: info.render.calls,
+			geometries: info.memory.geometries,
+			textures: info.memory.textures
+		};
+	}
+	/** The last rendered camera's world-space basis (for screen-plane dragging). */
+	cameraBasis() {
+		const cam = this.lastCamera;
+		const q = cam ? cam.getWorldQuaternion(basisQuat) : basisQuat.identity();
+		return {
+			right: new Vector3(1, 0, 0).applyQuaternion(q),
+			up: new Vector3(0, 1, 0).applyQuaternion(q),
+			forward: new Vector3(0, 0, -1).applyQuaternion(q)
+		};
+	}
+	dispose() {
+		this.disconnect();
+		this.threeScene.traverse((obj) => {
+			const mesh = obj;
+			if (!mesh.isMesh || mesh.userData?.incantoModelShared) return;
+			mesh.geometry?.dispose();
+			if (Array.isArray(mesh.material)) for (const m of mesh.material) m.dispose();
+			else mesh.material?.dispose();
+		});
+		this.causticsTarget?.depthTexture?.dispose();
+		this.causticsTarget?.dispose();
+		const causticsMesh = this.causticsScene?.children[0];
+		causticsMesh?.geometry?.dispose();
+		causticsMesh?.material?.dispose();
+		this.cloudsTarget?.depthTexture?.dispose();
+		this.cloudsTarget?.dispose();
+		this.cloudsHalfTarget?.dispose();
+		this.cloudsBlurTarget?.dispose();
+		for (const s of [
+			this.cloudsScene,
+			this.cloudsBlurScene,
+			this.cloudsCompositeScene
+		]) {
+			const m = s?.children[0];
+			m?.geometry?.dispose();
+			m?.material?.dispose();
+		}
+		if (this.ownsAssets) this.assets.dispose();
+		this.environment.dispose();
+		this.webgl.dispose();
+	}
+};
+const sizeScratch = new Vector2();
+const lookScratch = new Vector3();
+const projScratch = new Vector3();
+const basisQuat = new Quaternion();
+/** Reused camera world-position scratch (shadow-follow focus + underwater test). */
+const camPosScratch = new Vector3();
+/** Reused click-pick scratches (no per-pick allocation). */
+const pickRaycaster = new Raycaster();
+const pickNdc = new Vector2();
+//#endregion
+//#region src/3d/create-game.ts
+var create_game_exports = /* @__PURE__ */ __exportAll({ createGame3D: () => createGame3D });
+/**
+* One-call 3D boot/teardown — the 3D twin of createGame2D: register → load
+* (engine attached for onReady) → physics (auto) → input → renderer → start.
+*/
+async function createGame3D(opts) {
+	registerNodes3D();
+	if (opts.gameplay ?? true) registerGameplayBehaviors();
+	for (const [name, ctor] of Object.entries(opts.behaviors ?? {})) registerBehavior(name, ctor, { replace: true });
+	const engine = new Engine({
+		seed: opts.seed,
+		fixedHz: opts.fixedHz,
+		...opts._scheduler ? { scheduler: opts._scheduler } : {}
+	});
+	const scene = loadScene(cloneSceneJson(opts.scene), {
+		resolveScene: opts.resolveScene,
+		engine
+	});
+	engine.setScene(scene);
+	let physics = null;
+	if (opts.physics === true || (opts.physics ?? "auto") === "auto" && hasBody(scene.root)) physics = await enablePhysics3D(engine);
+	const cleanups = [];
+	const keyboard = opts.keyboard ?? (typeof window !== "undefined" ? window : false);
+	if (keyboard) engine.input.attachKeyboard(keyboard);
+	if (opts.pointer) {
+		const lockOnClick = typeof opts.pointer === "object" ? opts.pointer.lockOnClick ?? true : true;
+		engine.input.attachPointer(opts.canvas, { lockOnClick });
+	}
+	cleanups.push(wireAudioUnlock(engine, scene.root, opts.canvas));
+	const touchMode = opts.touch ?? "auto";
+	if (touchMode !== false) {
+		const host = opts.touchContainer ?? opts.canvas.parentElement ?? null;
+		if (host) {
+			const touchOpts = {
+				force: touchMode === true,
+				...opts._touchDoc ? { doc: opts._touchDoc } : {}
+			};
+			let touchControls = attachTouchControls(engine, host, touchOpts);
+			const offSceneChanged = engine.sceneChanged.connect(() => {
+				touchControls?.dispose();
+				touchControls = attachTouchControls(engine, host, touchOpts);
+			});
+			cleanups.push(() => {
+				offSceneChanged();
+				touchControls?.dispose();
+			});
+		}
+	}
+	const renderer = opts._rendererFactory ? opts._rendererFactory(engine, opts.canvas) : new Renderer3D({
+		canvas: opts.canvas,
+		engine,
+		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {}
+	});
+	if (opts.debug ?? false) {
+		const host = opts.touchContainer ?? opts.canvas.parentElement ?? (typeof document !== "undefined" ? document.body : null);
+		if (host) {
+			const { attachDebugOverlay } = await import("./debug.js");
+			const overlay = attachDebugOverlay(engine, {
+				container: host,
+				statsSource: () => renderer.stats?.() ?? {},
+				...opts._debugDoc ? { doc: opts._debugDoc } : {}
+			});
+			if (overlay) cleanups.push(() => overlay.dispose());
+		}
+	}
+	engine.start();
+	return {
+		engine,
+		scene,
+		renderer,
+		physics,
+		stats() {
+			return {
+				triangles: 0,
+				drawCalls: 0,
+				geometries: 0,
+				textures: 0,
+				...engine.stats(),
+				...renderer.stats?.()
+			};
+		},
+		dispose() {
+			renderer.dispose();
+			physics?.dispose();
+			for (const cleanup of cleanups) cleanup();
+			engine.dispose();
+		}
+	};
+}
+function cloneSceneJson(json) {
+	try {
+		return structuredClone(json);
+	} catch {
+		throw new IncantoError("BAD_FORMAT", "createGame \"scene\" must be plain scene JSON (the imported *.scene.json object) — got something unclonable (a loaded Scene, class instances, or functions).");
+	}
+}
+function hasBody(root) {
+	if (root instanceof PhysicsBody3D) return true;
+	for (const child of root.children) if (hasBody(child)) return true;
+	return false;
+}
+/**
+* Browsers gate audio behind a user gesture — retry pending players on the
+* first pointer or key gesture, then stop listening once nothing is pending.
+*/
+function wireAudioUnlock(engine, root, canvas) {
+	const sources = [];
+	const canvasTarget = canvas;
+	if (canvasTarget.addEventListener) sources.push({
+		target: canvasTarget,
+		type: "pointerdown"
+	});
+	if (typeof window !== "undefined") sources.push({
+		target: window,
+		type: "keydown"
+	});
+	if (sources.length === 0) return () => {};
+	function detachAll() {
+		for (const s of sources) s.target.removeEventListener?.(s.type, unlock);
+	}
+	function unlock() {
+		engine.sfx.unlock();
+		engine.music.unlock();
+		let pending = false;
+		const walk = (node) => {
+			if (node instanceof AudioPlayer) {
+				node.retryPending();
+				if (node.pendingGesture) pending = true;
+			}
+			for (const child of node.children) walk(child);
+		};
+		walk(root);
+		if (!pending) detachAll();
+	}
+	for (const s of sources) s.target.addEventListener?.(s.type, unlock, { passive: true });
+	return detachAll;
+}
+//#endregion
+export { Environment3D as a, sunDirectionFromElevationAzimuth as c, syncTree as i, sunDirectionFromSky as l, create_game_exports as n, horizonColorFromSky as o, Renderer3D as r, parseEnvironment3D as s, createGame3D as t, AssetStore3D as u };