incanto 0.36.2 → 0.38.0

package/dist/{create-game-DnOu2aAa.js → create-game-DqY2lMBc.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-DAZlgqeC.js";
-import { h as Engine, m as AudioPlayer } from "./register-BHAwM4bK.js";
+import { n as loadScene, v as diagnose, w as registerBehavior } from "./loader-r49nDwB4.js";
+import { h as Engine, m as AudioPlayer, v as qualityRendering } from "./register-Dm7nrd-E.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
 import { a as poseFromRenderer, i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-CCtAMDLB.js";
-import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-C0MUMSak.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-CsJDUQh_.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-fK9oyrrR.js";
-import { n as enablePhysics3D } from "./physics-3d-DFJVMYET.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-C0Axpfth.js";
+import { n as enablePhysics3D } from "./physics-3d-C8242nXr.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, 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";
@@ -172,762 +172,814 @@ var AssetStore3D = class {
 	}
 };
 //#endregion
-//#region src/3d/adaptive-resolution.ts
-const DEFAULTS = {
-	slowMs: 20,
-	fastMs: 13,
-	minScale: .6,
-	step: .15,
-	window: 45
-};
-var AdaptiveResolution = class {
-	opts;
-	samples = [];
-	scale = 1;
-	constructor(options = {}) {
-		this.opts = {
-			...DEFAULTS,
-			...options
-		};
-	}
-	/** The fraction of the requested pixel ratio to render at right now. */
-	current() {
-		return this.scale;
-	}
-	/**
-	* Feed one frame's duration. Returns the new scale when it CHANGED (the
-	* caller then resizes), else null — so a steady frame rate costs nothing.
-	*/
-	push(frameMs) {
-		if (!(frameMs > 0) || !Number.isFinite(frameMs)) return null;
-		this.samples.push(frameMs);
-		if (this.samples.length < this.opts.window) return null;
-		const sorted = [...this.samples].sort((a, b) => a - b);
-		const median = sorted[Math.floor(sorted.length / 2)];
-		this.samples = [];
-		const before = this.scale;
-		if (median > this.opts.slowMs) this.scale = Math.max(this.opts.minScale, this.scale - this.opts.step);
-		else if (median < this.opts.fastMs && this.scale < 1) this.scale = Math.min(1, this.scale + this.opts.step);
-		return this.scale === before ? null : this.scale;
-	}
-	/** Forget the window (a paused or backgrounded game is not "slow"). */
-	reset() {
-		this.samples = [];
-	}
-};
-//#endregion
-//#region src/3d/bloom/bloom-composite.ts
+//#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 BLOOM_KEYS = ["threshold", "strength"];
+const POST_KEYS = [
+	"vignette",
+	"saturation",
+	"contrast"
+];
+const SHADOW_KEYS = [
+	"mapSize",
+	"radius",
+	"static"
+];
+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),
+		bloom: parseBloom(env?.bloom),
+		post: parsePost(env?.post),
+		shadows: parseShadows(env?.shadows)
+	};
+}
 /**
-* HDR bloom post pass:
-*
-*   scene → offscreen HalfFloat target (raw linear HDR — three applies neither
-*     tone mapping nor the sRGB transform when rendering into a target)
-*   bright-pass at HALF resolution (keep only luminance above `threshold`;
-*     with HDR buffers, emissives and sun glints sit above 1.0)
-*   separable 9-tap Gaussian blur (H then V) at half res
-*   composite: scene + glow × strength, THEN the standard postprocessing tail
-*     (ACES tone mapping + linear→sRGB) — skipping that tail is exactly the
-*     dark/oversaturated bug the volumetric-clouds pipeline shipped with.
+* elevation/azimuth (degrees) → unit direction. Matches three's Sky example
+* (`Vector3.setFromSphericalCoords`): azimuth 0 = +Z, 90 = +X; elevation 90 =
+* straight up.
 */
-const VERT = `
-varying vec2 vUv;
-void main() {
-  vUv = uv;
-  gl_Position = vec4(position.xy, 0.0, 1.0);
+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)
+	];
 }
-`;
-const BRIGHT_FRAG = `
-precision highp float;
-varying vec2 vUv;
-uniform sampler2D tScene;
-uniform float uThreshold;
-void main() {
-  vec3 c = texture2D(tScene, vUv).rgb;
-  // HDR luminance knee: the scene buffer is raw linear HDR (tone mapping is
-  // applied later, in the composite), so emissives/sun glints sit ABOVE 1.0 —
-  // keep only the energy above the threshold, in proportion
-  float l = dot(c, vec3(0.2126, 0.7152, 0.0722));
-  float k = max(l - uThreshold, 0.0);
-  gl_FragColor = vec4(c * (k / max(l, 1e-4)), 1.0);
+/** 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
+	];
 }
-`;
-const BLUR_FRAG = `
-precision highp float;
-varying vec2 vUv;
-uniform sampler2D tTex;
-uniform vec2 uDir;
-void main() {
-  // 9-tap Gaussian, sigma ~2 texels (same recipe as the cloud blur)
-  vec4 sum = texture2D(tTex, vUv) * 0.227027;
-  sum += texture2D(tTex, vUv + uDir * 1.3846) * 0.3162162;
-  sum += texture2D(tTex, vUv - uDir * 1.3846) * 0.3162162;
-  sum += texture2D(tTex, vUv + uDir * 3.2308) * 0.0702703;
-  sum += texture2D(tTex, vUv - uDir * 3.2308) * 0.0702703;
-  gl_FragColor = sum;
+/**
+* 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("")}`;
 }
-`;
-const COMPOSITE_FRAG = `
-precision highp float;
-varying vec2 vUv;
-uniform sampler2D tScene;
-uniform sampler2D tBloom;
-uniform float uStrength;
-uniform float uVignette;
-uniform float uSaturation;
-uniform float uContrast;
-void main() {
-  vec3 base = texture2D(tScene, vUv).rgb;
-  vec3 glow = texture2D(tBloom, vUv).rgb;
-  gl_FragColor = vec4(base + glow * uStrength, 1.0);
-  // three skips BOTH tone mapping and the output colorspace transform when the
-  // scene renders into an offscreen target — the buffer holds raw linear HDR.
-  // This is the final to-screen pass, so apply the standard postprocessing
-  // tail here (ACES then linear→sRGB); without it the frame comes out dark
-  // and oversaturated (the volumetric-clouds pipeline bug, root-caused).
-  #include <tonemapping_fragment>
-  // color grade AFTER tone mapping (values are display-referred now) and
-  // BEFORE the colorspace transform: saturation → contrast → vignette
-  vec3 graded = gl_FragColor.rgb;
-  float luma = dot(graded, vec3(0.2126, 0.7152, 0.0722));
-  graded = mix(vec3(luma), graded, uSaturation);
-  graded = (graded - 0.5) * uContrast + 0.5;
-  float dist = distance(vUv, vec2(0.5));
-  graded *= 1.0 - uVignette * smoothstep(0.3, 0.78, dist);
-  gl_FragColor.rgb = max(graded, 0.0);
-  #include <colorspace_fragment>
+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 quad(fragment, uniforms) {
-	const material = new ShaderMaterial({
-		vertexShader: VERT,
-		fragmentShader: fragment,
-		depthTest: false,
-		depthWrite: false,
-		uniforms
+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
 	});
-	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
-	mesh.frustumCulled = false;
-	return mesh;
+	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
+	};
 }
-/** Half-res bright-pass quad — keeps only pixels brighter than the threshold. */
-function createBloomBrightQuad() {
-	const mesh = quad(BRIGHT_FRAG, {
-		tScene: { value: null },
-		uThreshold: { value: 1 }
+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 parseBloom(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.bloom must be an object ({ threshold?, strength? }), got ${JSON.stringify(value)}.`, { prop: "bloom" });
+	const b = value;
+	for (const key of Object.keys(b)) if (!BLOOM_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.bloom has unknown key '${key}'. Valid keys: [${BLOOM_KEYS.join(", ")}].`, {
+		prop: "bloom",
+		validOptions: BLOOM_KEYS
+	});
+	const threshold = numberOr(b.threshold, 1, "bloom.threshold");
+	if (threshold < 0 || threshold > 8) throw new IncantoError("BAD_FORMAT", `environment.bloom.threshold must be in [0, 8] (linear-HDR luminance; 1 = white), got ${threshold}.`, { prop: "bloom" });
+	const strength = numberOr(b.strength, .8, "bloom.strength");
+	if (strength < 0) throw new IncantoError("BAD_FORMAT", `environment.bloom.strength must be >= 0, got ${strength}.`, { prop: "bloom" });
+	return {
+		threshold,
+		strength
+	};
+}
+function parsePost(value) {
+	if (value === void 0) return null;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.post must be an object ({ vignette?, saturation?, contrast? }), got ${JSON.stringify(value)}.`, { prop: "post" });
+	const p = value;
+	for (const key of Object.keys(p)) if (!POST_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.post has unknown key '${key}'. Valid keys: [${POST_KEYS.join(", ")}].`, {
+		prop: "post",
+		validOptions: POST_KEYS
 	});
+	const vignette = numberOr(p.vignette, 0, "post.vignette");
+	if (vignette < 0 || vignette > 1) throw new IncantoError("BAD_FORMAT", `environment.post.vignette must be in [0, 1], got ${vignette}.`, { prop: "post" });
+	const saturation = numberOr(p.saturation, 1, "post.saturation");
+	if (saturation < 0 || saturation > 4) throw new IncantoError("BAD_FORMAT", `environment.post.saturation must be in [0, 4] (1 = neutral), got ${saturation}.`, { prop: "post" });
+	const contrast = numberOr(p.contrast, 1, "post.contrast");
+	if (contrast < .2 || contrast > 3) throw new IncantoError("BAD_FORMAT", `environment.post.contrast must be in [0.2, 3] (1 = neutral), got ${contrast}.`, { prop: "post" });
 	return {
-		mesh,
-		uniforms: mesh.material.uniforms
+		vignette,
+		saturation,
+		contrast
 	};
 }
-/** Separable-blur quad (run twice: uDir = (1/w, 0) then (0, 1/h)). */
-function createBloomBlurQuad() {
-	const mesh = quad(BLUR_FRAG, {
-		tTex: { value: null },
-		uDir: { value: new Vector2() }
-	});
-	return {
-		mesh,
-		uniforms: mesh.material.uniforms
+function parseShadows(value) {
+	if (value === void 0) return null;
+	if (value === false) return false;
+	if (value === true) return {
+		mapSize: 2048,
+		radius: 1,
+		static: false
 	};
-}
-/** Full-res composite quad — adds the blurred glow over the scene. */
-function createBloomCompositeQuad() {
-	const mesh = quad(COMPOSITE_FRAG, {
-		tScene: { value: null },
-		tBloom: { value: null },
-		uStrength: { value: .85 },
-		uVignette: { value: 0 },
-		uSaturation: { value: 1 },
-		uContrast: { value: 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" });
+	const staticShadows = shadows.static === void 0 ? false : shadows.static;
+	if (typeof staticShadows !== "boolean") throw new IncantoError("BAD_FORMAT", `environment.shadows.static must be a boolean, got ${JSON.stringify(shadows.static)}.`, { prop: "shadows" });
 	return {
-		mesh,
-		uniforms: mesh.material.uniforms
+		mapSize,
+		radius,
+		static: staticShadows
 	};
 }
+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/clouds/clouds-composite.ts
+//#region src/3d/environment-runtime.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:
+* Live environment editing — the renderer re-applies `scene.environment`
+* every frame (cheap when unchanged), so changing the LOOK at runtime is
+* just writing that object. This helper does it safely:
 *
-*   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.
+*   setEnvironment3D(engine, { sky: { elevationDeg: 4 }, exposure: 0.8 });
+*   setEnvironment3D(engine, { fog: null });          // null DELETES a key
 *
-* 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.
+* - one-level deep merge (patching `sky.elevationDeg` keeps the other sky keys)
+* - hard-validates the merged result NOW (in your call stack), so a bad patch
+*   throws where you wrote it — never inside the render loop
 */
-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;
+function setEnvironment3D(engine, patch) {
+	const scene = engine.scene;
+	if (!scene) throw new IncantoError("BAD_FORMAT", "setEnvironment3D: the engine has no scene.");
+	const merged = { ...scene.environment ?? {} };
+	for (const [key, value] of Object.entries(patch)) if (value === null) delete merged[key];
+	else if (typeof value === "object" && !Array.isArray(value) && typeof merged[key] === "object" && merged[key] !== null && !Array.isArray(merged[key])) merged[key] = {
+		...merged[key],
+		...value
+	};
+	else merged[key] = value;
+	parseEnvironment3D(merged);
+	scene.environment = merged;
 }
-
-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);
+//#endregion
+//#region src/3d/adaptive-resolution.ts
+const DEFAULTS = {
+	slowMs: 20,
+	fastMs: 13,
+	minScale: .6,
+	step: .15,
+	window: 45
+};
+var AdaptiveResolution = class {
+	opts;
+	samples = [];
+	scale = 1;
+	/** Thresholds the caller pinned by hand — `setTarget` must not move these. */
+	pinned;
+	constructor(options = {}) {
+		this.opts = {
+			...DEFAULTS,
+			...options
+		};
+		this.pinned = {
+			slowMs: options.slowMs !== void 0,
+			fastMs: options.fastMs !== void 0
+		};
+	}
+	/**
+	* Judge frames against `fps` instead of 60.
+	*
+	* The defaults above are a 60 fps budget with a margin: 1000/60 × 1.2 = 20.0
+	* and × 0.8 = 13.3, which is exactly `slowMs` and `fastMs`. That was fine
+	* while 60 was the only target anyone had — and then the frame cap arrived.
+	*
+	* Cap a game at 30 and every frame takes 33 ms BY DESIGN. Against a hardcoded
+	* 20 ms budget the governor reads that as a game missing its frames, sheds
+	* pixels every window until it hits `minScale`, and never hands them back:
+	* the player asks for 30 fps to save the battery and silently gets 30 fps at
+	* 60% resolution. The budget has to come from the target, so that "slow"
+	* means "slower than what we asked for".
+	*/
+	setTarget(fps) {
+		const frameMs = 1e3 / (fps > 0 ? fps : 60);
+		if (!this.pinned.slowMs) this.opts.slowMs = frameMs * 1.2;
+		if (!this.pinned.fastMs) this.opts.fastMs = frameMs * .8;
+	}
+	/** The fraction of the requested pixel ratio to render at right now. */
+	current() {
+		return this.scale;
+	}
+	/**
+	* Feed one frame's duration. Returns the new scale when it CHANGED (the
+	* caller then resizes), else null — so a steady frame rate costs nothing.
+	*/
+	push(frameMs) {
+		if (!(frameMs > 0) || !Number.isFinite(frameMs)) return null;
+		this.samples.push(frameMs);
+		if (this.samples.length < this.opts.window) return null;
+		const sorted = [...this.samples].sort((a, b) => a - b);
+		const median = sorted[Math.floor(sorted.length / 2)];
+		this.samples = [];
+		const before = this.scale;
+		if (median > this.opts.slowMs) this.scale = Math.max(this.opts.minScale, this.scale - this.opts.step);
+		else if (median < this.opts.fastMs && this.scale < 1) this.scale = Math.min(1, this.scale + this.opts.step);
+		return this.scale === before ? null : this.scale;
+	}
+	/** Forget the window (a paused or backgrounded game is not "slow"). */
+	reset() {
+		this.samples = [];
+	}
+};
+//#endregion
+//#region src/3d/bloom/bloom-composite.ts
+/**
+* HDR bloom post pass:
+*
+*   scene → offscreen HalfFloat target (raw linear HDR — three applies neither
+*     tone mapping nor the sRGB transform when rendering into a target)
+*   bright-pass at HALF resolution (keep only luminance above `threshold`;
+*     with HDR buffers, emissives and sun glints sit above 1.0)
+*   separable 9-tap Gaussian blur (H then V) at half res
+*   composite: scene + glow × strength, THEN the standard postprocessing tail
+*     (ACES tone mapping + linear→sRGB) — skipping that tail is exactly the
+*     dark/oversaturated bug the volumetric-clouds pipeline shipped with.
+*/
+const VERT = `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
 }
 `;
-/** 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 = `
+const BRIGHT_FRAG = `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D tScene;
+uniform float uThreshold;
+void main() {
+  vec3 c = texture2D(tScene, vUv).rgb;
+  // HDR luminance knee: the scene buffer is raw linear HDR (tone mapping is
+  // applied later, in the composite), so emissives/sun glints sit ABOVE 1.0 —
+  // keep only the energy above the threshold, in proportion
+  float l = dot(c, vec3(0.2126, 0.7152, 0.0722));
+  float k = max(l - uThreshold, 0.0);
+  gl_FragColor = vec4(c * (k / max(l, 1e-4)), 1.0);
+}
+`;
+const BLUR_FRAG = `
 precision highp float;
 varying vec2 vUv;
 uniform sampler2D tTex;
-uniform vec2 uDir; // (texel, 0) horizontal pass, then (0, texel) vertical
+uniform vec2 uDir;
 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;
+  // 9-tap Gaussian, sigma ~2 texels (same recipe as the cloud blur)
+  vec4 sum = texture2D(tTex, vUv) * 0.227027;
+  sum += texture2D(tTex, vUv + uDir * 1.3846) * 0.3162162;
+  sum += texture2D(tTex, vUv - uDir * 1.3846) * 0.3162162;
+  sum += texture2D(tTex, vUv + uDir * 3.2308) * 0.0702703;
+  sum += texture2D(tTex, vUv - uDir * 3.2308) * 0.0702703;
+  gl_FragColor = sum;
 }
 `;
-/** Composite pass: blend the (pre-blurred) low-res cloud buffer over the scene. */
-const CLOUDS_COMPOSITE_FRAG = `
+const COMPOSITE_FRAG = `
 precision highp float;
 varying vec2 vUv;
 uniform sampler2D tScene;
-uniform sampler2D tClouds;
+uniform sampler2D tBloom;
+uniform float uStrength;
+uniform float uVignette;
+uniform float uSaturation;
+uniform float uContrast;
 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);
+  vec3 base = texture2D(tScene, vUv).rgb;
+  vec3 glow = texture2D(tBloom, vUv).rgb;
+  gl_FragColor = vec4(base + glow * uStrength, 1.0);
+  // three skips BOTH tone mapping and the output colorspace transform when the
+  // scene renders into an offscreen target — the buffer holds raw linear HDR.
+  // This is the final to-screen pass, so apply the standard postprocessing
+  // tail here (ACES then linear→sRGB); without it the frame comes out dark
+  // and oversaturated (the volumetric-clouds pipeline bug, root-caused).
+  #include <tonemapping_fragment>
+  // color grade AFTER tone mapping (values are display-referred now) and
+  // BEFORE the colorspace transform: saturation → contrast → vignette
+  vec3 graded = gl_FragColor.rgb;
+  float luma = dot(graded, vec3(0.2126, 0.7152, 0.0722));
+  graded = mix(vec3(luma), graded, uSaturation);
+  graded = (graded - 0.5) * uContrast + 0.5;
+  float dist = distance(vUv, vec2(0.5));
+  graded *= 1.0 - uVignette * smoothstep(0.3, 0.78, dist);
+  gl_FragColor.rgb = max(graded, 0.0);
+  #include <colorspace_fragment>
 }
 `;
-/** 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() {
+function quad(fragment, uniforms) {
 	const material = new ShaderMaterial({
-		vertexShader: CLOUDS_VERT,
-		fragmentShader: CLOUDS_BLUR_FRAG,
+		vertexShader: VERT,
+		fragmentShader: fragment,
 		depthTest: false,
 		depthWrite: false,
-		uniforms: {
-			tTex: { value: null },
-			uDir: { value: new Vector2() }
-		}
+		uniforms
 	});
 	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
 	mesh.frustumCulled = false;
-	return {
-		mesh,
-		uniforms: material.uniforms
-	};
+	return mesh;
 }
-/** 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 }
-		}
+/** Half-res bright-pass quad — keeps only pixels brighter than the threshold. */
+function createBloomBrightQuad() {
+	const mesh = quad(BRIGHT_FRAG, {
+		tScene: { value: null },
+		uThreshold: { value: 1 }
 	});
-	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
-	mesh.frustumCulled = false;
 	return {
 		mesh,
-		uniforms: material.uniforms
+		uniforms: mesh.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 }
-		}
+/** Separable-blur quad (run twice: uDir = (1/w, 0) then (0, 1/h)). */
+function createBloomBlurQuad() {
+	const mesh = quad(BLUR_FRAG, {
+		tTex: { value: null },
+		uDir: { value: new Vector2() }
 	});
-	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 BLOOM_KEYS = ["threshold", "strength"];
-const POST_KEYS = [
-	"vignette",
-	"saturation",
-	"contrast"
-];
-const SHADOW_KEYS = [
-	"mapSize",
-	"radius",
-	"static"
-];
-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) {
+		uniforms: mesh.material.uniforms
+	};
+}
+/** Full-res composite quad — adds the blurred glow over the scene. */
+function createBloomCompositeQuad() {
+	const mesh = quad(COMPOSITE_FRAG, {
+		tScene: { value: null },
+		tBloom: { value: null },
+		uStrength: { value: .85 },
+		uVignette: { value: 0 },
+		uSaturation: { value: 1 },
+		uContrast: { value: 1 }
+	});
 	return {
-		exposure: parseExposure(env?.exposure),
-		sky: parseSky(env?.sky),
-		fog: parseFog(env?.fog, env?.sky !== void 0),
-		clouds: parseClouds(env?.clouds),
-		bloom: parseBloom(env?.bloom),
-		post: parsePost(env?.post),
-		shadows: parseShadows(env?.shadows)
+		mesh,
+		uniforms: mesh.material.uniforms
 	};
 }
+//#endregion
+//#region src/3d/clouds/clouds-composite.ts
 /**
-* elevation/azimuth (degrees) → unit direction. Matches three's Sky example
-* (`Vector3.setFromSphericalCoords`): azimuth 0 = +Z, 90 = +X; elevation 90 =
-* straight up.
+* 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.
 */
-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)
-	];
+const CLOUDS_VERT = `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
 }
-/** 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
-	];
+`;
+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));
 }
-/**
-* 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("")}`;
+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);
 }
-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;
+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;
 }
-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
-	};
+
+// 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);
 }
-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
-	};
+`;
+/** 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;
 }
-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
-	};
+`;
+/** 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);
 }
-function parseBloom(value) {
-	if (value === void 0) return null;
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.bloom must be an object ({ threshold?, strength? }), got ${JSON.stringify(value)}.`, { prop: "bloom" });
-	const b = value;
-	for (const key of Object.keys(b)) if (!BLOOM_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.bloom has unknown key '${key}'. Valid keys: [${BLOOM_KEYS.join(", ")}].`, {
-		prop: "bloom",
-		validOptions: BLOOM_KEYS
+`;
+/** 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 threshold = numberOr(b.threshold, 1, "bloom.threshold");
-	if (threshold < 0 || threshold > 8) throw new IncantoError("BAD_FORMAT", `environment.bloom.threshold must be in [0, 8] (linear-HDR luminance; 1 = white), got ${threshold}.`, { prop: "bloom" });
-	const strength = numberOr(b.strength, .8, "bloom.strength");
-	if (strength < 0) throw new IncantoError("BAD_FORMAT", `environment.bloom.strength must be >= 0, got ${strength}.`, { prop: "bloom" });
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
 	return {
-		threshold,
-		strength
+		mesh,
+		uniforms: material.uniforms
 	};
 }
-function parsePost(value) {
-	if (value === void 0) return null;
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new IncantoError("BAD_FORMAT", `environment.post must be an object ({ vignette?, saturation?, contrast? }), got ${JSON.stringify(value)}.`, { prop: "post" });
-	const p = value;
-	for (const key of Object.keys(p)) if (!POST_KEYS.includes(key)) throw new IncantoError("BAD_FORMAT", `environment.post has unknown key '${key}'. Valid keys: [${POST_KEYS.join(", ")}].`, {
-		prop: "post",
-		validOptions: POST_KEYS
+/** 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 vignette = numberOr(p.vignette, 0, "post.vignette");
-	if (vignette < 0 || vignette > 1) throw new IncantoError("BAD_FORMAT", `environment.post.vignette must be in [0, 1], got ${vignette}.`, { prop: "post" });
-	const saturation = numberOr(p.saturation, 1, "post.saturation");
-	if (saturation < 0 || saturation > 4) throw new IncantoError("BAD_FORMAT", `environment.post.saturation must be in [0, 4] (1 = neutral), got ${saturation}.`, { prop: "post" });
-	const contrast = numberOr(p.contrast, 1, "post.contrast");
-	if (contrast < .2 || contrast > 3) throw new IncantoError("BAD_FORMAT", `environment.post.contrast must be in [0.2, 3] (1 = neutral), got ${contrast}.`, { prop: "post" });
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
 	return {
-		vignette,
-		saturation,
-		contrast
+		mesh,
+		uniforms: material.uniforms
 	};
 }
-function parseShadows(value) {
-	if (value === void 0) return null;
-	if (value === false) return false;
-	if (value === true) return {
-		mapSize: 2048,
-		radius: 1,
-		static: false
-	};
-	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)
+/** 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 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" });
-	const staticShadows = shadows.static === void 0 ? false : shadows.static;
-	if (typeof staticShadows !== "boolean") throw new IncantoError("BAD_FORMAT", `environment.shadows.static must be a boolean, got ${JSON.stringify(shadows.static)}.`, { prop: "shadows" });
+	const mesh = new Mesh(new PlaneGeometry(2, 2), material);
+	mesh.frustumCulled = false;
 	return {
-		mapSize,
-		radius,
-		static: staticShadows
+		mesh,
+		uniforms: material.uniforms
 	};
 }
-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-3d.ts
 /** Shadow ortho half-extent when the env header forces a light to cast and the
@@ -1566,8 +1618,8 @@ var Renderer3D = class {
 		this.ownsAssets = !opts.assets;
 		this.assets = opts.assets ?? new AssetStore3D(this.engine);
 		const rendering = resolveRendering(opts.engine.scene?.environment, {
-			antialias: true,
-			pixelRatio: Math.min(globalThis.devicePixelRatio ?? 1, 2),
+			antialias: opts.qualityDefaults?.antialias ?? true,
+			pixelRatio: opts.qualityDefaults?.pixelRatio ?? Math.min(globalThis.devicePixelRatio ?? 1, 2),
 			preserveDrawingBuffer: false
 		}, globalThis.devicePixelRatio ?? 1, {
 			pixelRatio: opts.pixelRatio,
@@ -1609,6 +1661,8 @@ var Renderer3D = class {
 	/** The pixel ratio the scene ASKED for — the governor scales this, never replaces it. */
 	basePixelRatio;
 	adaptive;
+	renderScale = 1;
+	adaptiveScale = 1;
 	lastFrameAt = 0;
 	debugLines;
 	selectionLines;
@@ -1654,7 +1708,32 @@ var Renderer3D = class {
 		}
 		const scale = gov.push(frameMs);
 		if (scale === null) return;
-		this.webgl.setPixelRatio(this.basePixelRatio * scale);
+		this.adaptiveScale = scale;
+		this.applyPixelRatio();
+	}
+	/**
+	* The player's resolution multiplier, on top of whatever the scene and the
+	* quality tier resolved to.
+	*
+	* The cheapest lever there is on a weak GPU: at 0.66 the fragment shaders run
+	* over 44% of the pixels for a soft image and nothing else, where dropping a
+	* quality tier costs the shadows outright. Live — a settings menu writes it
+	* mid-game — and it multiplies with the adaptive governor rather than
+	* fighting it, so a player who has already scaled down does not get scaled
+	* down twice as hard.
+	*/
+	setRenderScale(scale) {
+		const next = Math.min(2, Math.max(.25, scale > 0 ? scale : 1));
+		if (next === this.renderScale) return;
+		this.renderScale = next;
+		this.applyPixelRatio();
+	}
+	/** Judge frames against `fps` — see AdaptiveResolution.setTarget. */
+	setFrameTarget(fps) {
+		this.adaptive?.setTarget(fps);
+	}
+	applyPixelRatio() {
+		this.webgl.setPixelRatio(this.basePixelRatio * this.renderScale * this.adaptiveScale);
 		const size = this.lastSize;
 		if (size.w > 0 && size.h > 0) this.webgl.setSize(size.w, size.h, false);
 	}
@@ -2210,9 +2289,14 @@ async function createGame3D(opts) {
 			});
 		}
 	}
+	const tierRendering = qualityRendering(engine.settings.autoQuality());
 	const renderer = opts._rendererFactory ? opts._rendererFactory(engine, opts.canvas) : new Renderer3D({
 		canvas: opts.canvas,
 		engine,
+		qualityDefaults: {
+			antialias: tierRendering.antialias,
+			pixelRatio: tierRendering.pixelRatio
+		},
 		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {},
 		...opts.adaptiveResolution !== void 0 ? { adaptiveResolution: opts.adaptiveResolution } : {},
 		...opts.preserveDrawingBuffer !== void 0 ? { preserveDrawingBuffer: opts.preserveDrawingBuffer } : {}
@@ -2277,6 +2361,16 @@ async function createGame3D(opts) {
 	} catch {}
 	cleanups.push(engine.settings.bindAudio(engine.audio));
 	cleanups.push(engine.settings.bindLocale(engine.locale));
+	cleanups.push(engine.settings.bindQuality((patch) => {
+		setEnvironment3D(engine, patch);
+	}));
+	cleanups.push(engine.settings.bindFrameCap((fps) => {
+		engine.maxFps = fps;
+		renderer.setFrameTarget?.(fps || 60);
+	}));
+	cleanups.push(engine.settings.bindRenderScale((scale) => {
+		renderer.setRenderScale?.(scale);
+	}));
 	await report(1, "ready");
 	function disposeGame() {
 		teardown([
@@ -2363,4 +2457,4 @@ function wireAudioUnlock(engine, root, canvas) {
 	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 };
+export { Environment3D as a, parseEnvironment3D as c, AssetStore3D as d, syncTree as i, sunDirectionFromElevationAzimuth as l, create_game_exports as n, setEnvironment3D as o, Renderer3D as r, horizonColorFromSky as s, createGame3D as t, sunDirectionFromSky as u };