incanto 0.28.0 → 0.30.0

package/dist/{create-game-71TJjW1T.js → create-game-5z_QVtLx.js}

@@ -1,12 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { _ as registerBehavior, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-BZqOKfI2.js";
-import { l as AudioPlayer, u as Engine } from "./register-nObreUQR.js";
+import { l as AudioPlayer, u as Engine } from "./register-BTg0EM7s.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { n as registerGameplayBehaviors } from "./gameplay-DEG-TP7D.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-CvpSUU3O.js";
-import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { n as enablePhysics2D } from "./physics-2d-DiVFFlH3.js";
+import { i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-ByzfDPyu.js";
+import { n as registerGameplayBehaviors } from "./gameplay-Cfr6aFZ1.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DWcWq4QG.js";
+import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
+import { n as enablePhysics2D } from "./physics-2d-3kOQCtgd.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**
@@ -266,6 +267,7 @@ var Renderer2D = class {
 			canvas: opts.canvas,
 			antialias: rendering.antialias
 		});
+		this.webgl.info.autoReset = false;
 		this.webgl.setPixelRatio(rendering.pixelRatio);
 		this.webgl.info.autoReset = false;
 		this.debugLines = new LineSegments(new BufferGeometry(), new LineBasicMaterial({
@@ -308,7 +310,7 @@ var Renderer2D = class {
 	}
 	syncDebugLines() {
 		let vertices = null;
-		for (const source of debugSources("2d")) {
+		for (const source of debugSources("2d", this.engine)) {
 			vertices = source.debugLines();
 			if (vertices) break;
 		}
@@ -386,6 +388,7 @@ var Renderer2D = class {
 		}
 		frame(this.worldCam, center.x, center.y, uiW / zoom, uiH / zoom);
 		frame(this.uiCam, uiW / 2, uiH / 2, uiW, uiH);
+		this.webgl.info.reset();
 		this.webgl.autoClear = true;
 		this.webgl.render(this.worldScene, this.worldCam);
 		this.webgl.autoClear = false;
@@ -405,8 +408,8 @@ var Renderer2D = class {
 		return { ...this.lastView };
 	}
 	/**
-	* GPU counters for the LAST rendered frame (world + UI passes combined),
-	* straight from three's per-frame-maintained `renderer.info`.
+	* GPU counters for the LAST rendered frame — world + UI passes combined (see
+	* the `info.reset()` in the render pass), plus GPU memory.
 	*/
 	stats() {
 		const info = this.webgl.info;
@@ -517,7 +520,8 @@ async function createGame2D(opts) {
 		fixedHz: opts.fixedHz,
 		...opts._scheduler ? { scheduler: opts._scheduler } : {}
 	});
-	const scene = loadScene(cloneSceneJson(opts.scene), {
+	const sourceJson = cloneSceneJson(opts.scene);
+	const scene = loadScene(cloneSceneJson(sourceJson), {
 		resolveScene: opts.resolveScene,
 		engine
 	});
@@ -553,22 +557,65 @@ async function createGame2D(opts) {
 		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {},
 		...opts.antialias !== void 0 ? { antialias: opts.antialias } : {}
 	});
-	if (opts.debug ?? false) {
+	const wantDebug = opts.debug ?? false;
+	const wantEditor = opts.editor ?? wantDebug;
+	const editorSwitch = wantEditor === true ? {} : wantEditor ? wantEditor : null;
+	const editorAction = {
+		label: "✎ edit this scene",
+		run: async () => {
+			if (!editorSwitch) return;
+			const open = editorSwitch.open ?? openBundledEditor;
+			const reboot = async (working) => {
+				await createGame2D({
+					...opts,
+					scene: working
+				});
+			};
+			await crossFade(async () => {
+				disposeGame();
+				try {
+					await open({
+						scene: sourceJson,
+						play: reboot,
+						exit: () => reboot(sourceJson),
+						...editorSwitch.save ? { save: editorSwitch.save } : {},
+						...editorSwitch.library ? { library: editorSwitch.library === true ? devServerLibrary() : editorSwitch.library } : {}
+					});
+				} catch (error) {
+					console.error("[incanto] could not open the editor:", error);
+					await reboot(sourceJson);
+				}
+			}, "opening the editor…");
+		}
+	};
+	if (wantDebug) {
 		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?.() ?? {},
+				...editorSwitch ? { actions: [editorAction] } : {},
 				...opts._debugDoc ? { doc: opts._debugDoc } : {}
 			});
 			if (overlay) cleanups.push(() => overlay.dispose());
 		}
 	}
 	engine.start();
+	function disposeGame() {
+		teardown([
+			physics ? ["physics", () => physics?.dispose()] : null,
+			["app cleanups", () => {
+				for (const cleanup of cleanups) cleanup();
+			}],
+			["engine", () => engine.dispose()],
+			["renderer", () => renderer.dispose()]
+		]);
+	}
 	return {
 		engine,
 		scene,
+		sourceJson,
 		renderer,
 		physics,
 		stats() {
@@ -581,12 +628,8 @@ async function createGame2D(opts) {
 				...renderer.stats?.()
 			};
 		},
-		dispose() {
-			renderer.dispose();
-			physics?.dispose();
-			for (const cleanup of cleanups) cleanup();
-			engine.dispose();
-		}
+		openEditor: editorSwitch ? editorAction.run : null,
+		dispose: disposeGame
 	};
 }
 function cloneSceneJson(json) {

package/dist/{create-game-BRgWpNsa.js → create-game-DuBTv2zI.js}

@@ -1,12 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { _ as registerBehavior, n as loadScene } from "./loader-BZqOKfI2.js";
-import { l as AudioPlayer, u as Engine } from "./register-nObreUQR.js";
+import { l as AudioPlayer, u as Engine } from "./register-BTg0EM7s.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
-import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-DEG-TP7D.js";
-import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { S as Camera3D, f as DirectionalLight3D, t as registerNodes3D, u as ModelInstance3D } from "./register-6R75AC7-.js";
-import { n as enablePhysics3D } from "./physics-3d--y5clE2j.js";
+import { a as poseFromRenderer, i as openBundledEditor, n as crossFade, r as devServerLibrary, t as teardown } from "./teardown-ByzfDPyu.js";
+import { B as createCausticsQuad, F as PhysicsBody3D, R as Node3D, n as registerGameplayBehaviors } from "./gameplay-Cfr6aFZ1.js";
+import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
+import { T as Camera3D, _ as DirectionalLight3D, h as ModelInstance3D, t as registerNodes3D } from "./register-DJ0SByQg.js";
+import { n as enablePhysics3D } from "./physics-3d-CeRH-Ff_.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";
@@ -1163,49 +1164,132 @@ function parseIblIntensity(value) {
 //#endregion
 //#region src/3d/selection-outline.ts
 /**
-* Where IS the node the dev-overlay selected? — world-space outline segments
-* for the renderer's highlight pass. A renderable node gets its actual
-* bounding box (children included); a node with no visual extent gets a
-* small marker cube at its world position so it is still findable.
+* Where IS the node the dev-overlay selected? — outline segments for the
+* renderer's highlight pass. A renderable node gets its actual bounding box
+* (children included); a node with no visual extent gets a small marker cube at
+* its world position so it is still findable.
+*
+* The box is ORIENTED — measured in the node's own frame, then turned by its
+* world matrix. A world-axis-aligned box lies about anything rotated: a 14 m
+* footbridge deck turned 143° would be wrapped in a 12.5 × 10.2 m rectangle,
+* three times its real footprint, and the outline would sit nowhere near the
+* plank it is supposed to be pointing at.
 */
 const box = new Box3();
-const size = new Vector3();
+const childBox = new Box3();
+const toLocal = new Matrix4();
+const childMat = new Matrix4();
+const corner = new Vector3();
+/** Reused every frame — the outline refreshes while a node stays selected. */
+const points = Array.from({ length: 8 }, () => new Vector3());
 const MARKER_HALF = .4;
 /** 12 box edges = 24 points × xyz. */
 const OUT = new Float32Array(72);
+/** The eight corners in the order the edge list below indexes them. */
+const CORNERS = [
+	[
+		0,
+		0,
+		0
+	],
+	[
+		1,
+		0,
+		0
+	],
+	[
+		1,
+		0,
+		1
+	],
+	[
+		0,
+		0,
+		1
+	],
+	[
+		0,
+		1,
+		0
+	],
+	[
+		1,
+		1,
+		0
+	],
+	[
+		1,
+		1,
+		1
+	],
+	[
+		0,
+		1,
+		1
+	]
+];
+const EDGES = [
+	[0, 1],
+	[1, 2],
+	[2, 3],
+	[3, 0],
+	[4, 5],
+	[5, 6],
+	[6, 7],
+	[7, 4],
+	[0, 4],
+	[1, 5],
+	[2, 6],
+	[3, 7]
+];
+/** The subtree's extent in `root`'s own frame — no ancestor rotation baked in. */
+function localBox(root, out) {
+	out.makeEmpty();
+	toLocal.copy(root.matrixWorld).invert();
+	root.traverse((child) => {
+		const mesh = child;
+		let source;
+		if (mesh.isInstancedMesh) {
+			if (!mesh.boundingBox) mesh.computeBoundingBox?.();
+			source = mesh.boundingBox;
+		} else if (mesh.geometry) {
+			if (!mesh.geometry.boundingBox) mesh.geometry.computeBoundingBox();
+			source = mesh.geometry.boundingBox;
+		}
+		if (!source) return;
+		childBox.copy(source).applyMatrix4(childMat.multiplyMatrices(toLocal, child.matrixWorld));
+		out.union(childBox);
+	});
+}
 function selectionOutline3D(node) {
 	if (!(node instanceof Node3D)) return null;
 	const obj = node._ensureObject3D();
 	obj.updateWorldMatrix(true, true);
-	box.setFromObject(obj);
-	box.getSize(size);
-	if (!Number.isFinite(size.x) || size.x === 0 && size.y === 0 && size.z === 0) {
-		const p = new Vector3().setFromMatrixPosition(obj.matrixWorld);
-		box.min.set(p.x - MARKER_HALF, p.y - MARKER_HALF, p.z - MARKER_HALF);
-		box.max.set(p.x + MARKER_HALF, p.y + MARKER_HALF, p.z + MARKER_HALF);
+	localBox(obj, box);
+	let oriented = true;
+	if (box.isEmpty()) {
+		oriented = false;
+		corner.setFromMatrixPosition(obj.matrixWorld);
+		box.min.set(corner.x - MARKER_HALF, corner.y - MARKER_HALF, corner.z - MARKER_HALF);
+		box.max.set(corner.x + MARKER_HALF, corner.y + MARKER_HALF, corner.z + MARKER_HALF);
 	} else box.expandByScalar(.02);
 	const { min, max } = box;
+	for (let c = 0; c < 8; c++) {
+		const [cx, cy, cz] = CORNERS[c];
+		const p = points[c].set(cx ? max.x : min.x, cy ? max.y : min.y, cz ? max.z : min.z);
+		if (oriented) p.applyMatrix4(obj.matrixWorld);
+	}
 	let i = 0;
-	const seg = (x1, y1, z1, x2, y2, z2) => {
-		OUT[i++] = x1;
-		OUT[i++] = y1;
-		OUT[i++] = z1;
-		OUT[i++] = x2;
-		OUT[i++] = y2;
-		OUT[i++] = z2;
-	};
-	seg(min.x, min.y, min.z, max.x, min.y, min.z);
-	seg(max.x, min.y, min.z, max.x, min.y, max.z);
-	seg(max.x, min.y, max.z, min.x, min.y, max.z);
-	seg(min.x, min.y, max.z, min.x, min.y, min.z);
-	seg(min.x, max.y, min.z, max.x, max.y, min.z);
-	seg(max.x, max.y, min.z, max.x, max.y, max.z);
-	seg(max.x, max.y, max.z, min.x, max.y, max.z);
-	seg(min.x, max.y, max.z, min.x, max.y, min.z);
-	seg(min.x, min.y, min.z, min.x, max.y, min.z);
-	seg(max.x, min.y, min.z, max.x, max.y, min.z);
-	seg(max.x, min.y, max.z, max.x, max.y, max.z);
-	seg(min.x, min.y, max.z, min.x, max.y, max.z);
+	for (const [a, b] of EDGES) {
+		const p = points[a];
+		const q = points[b];
+		OUT[i++] = p.x;
+		OUT[i++] = p.y;
+		OUT[i++] = p.z;
+		OUT[i++] = q.x;
+		OUT[i++] = q.y;
+		OUT[i++] = q.z;
+	}
 	return OUT;
 }
 //#endregion
@@ -1420,6 +1504,11 @@ var Renderer3D = class {
 	loadedAssetScenes = /* @__PURE__ */ new WeakSet();
 	/** The scene whose GPU programs have been pre-compiled (warm-up, see render). */
 	compiledScene = null;
+	/** The camera the last frame drew with — what warmUp compiles against. */
+	warmCamera = null;
+	/** Set while a caller intends to run {@link warmUp} instead: the first frame
+	* then compiles only what it actually draws, and the rest goes async. */
+	deferCompile = false;
 	/** Reused per-frame walk scratch (instance-scoped — never a module global). */
 	syncScratch = createSyncScratch();
 	/** Editors set this: keep syncing `static: true` subtrees every frame. */
@@ -1465,6 +1554,7 @@ var Renderer3D = class {
 			canvas: opts.canvas,
 			antialias: rendering.antialias
 		});
+		this.webgl.info.autoReset = false;
 		this.basePixelRatio = rendering.pixelRatio;
 		this.webgl.setPixelRatio(rendering.pixelRatio);
 		this.adaptive = opts.adaptiveResolution === false ? null : new AdaptiveResolution();
@@ -1511,7 +1601,7 @@ var Renderer3D = class {
 	}
 	syncDebugLines() {
 		let vertices = null;
-		for (const source of debugSources("3d")) {
+		for (const source of debugSources("3d", this.engine)) {
 			vertices = source.debugLines();
 			if (vertices) break;
 		}
@@ -1543,9 +1633,56 @@ var Renderer3D = class {
 		const size = this.lastSize;
 		if (size.w > 0 && size.h > 0) this.webgl.setSize(size.w, size.h, false);
 	}
+	/**
+	* Compile the scene's GPU programs off the critical path.
+	*
+	* The compile itself is unavoidable — a dressed outdoor scene is 40+ programs
+	* and a driver takes hundreds of milliseconds each (measured: SEVEN SECONDS
+	* for this engine's creek template on macOS/Metal). What is avoidable is
+	* doing it in ONE synchronous block, which freezes the tab and leaves a
+	* loading bar with nothing to say.
+	*
+	* Called by `createGame3D` behind the app's loading screen.
+	*/
+	/** @internal Tell the next frame to leave the bulk compile to {@link warmUp}. */
+	deferFirstCompile() {
+		this.deferCompile = true;
+	}
+	async warmUp(onProgress) {
+		this.deferCompile = false;
+		const camera = this.warmCamera;
+		if (!camera) return;
+		const drawn = [];
+		this.threeScene.traverse((obj) => {
+			if (obj.isMesh) drawn.push(obj);
+			else if (obj.isPoints) drawn.push(obj);
+		});
+		const hidden = drawn.filter((o) => o.visible);
+		if (hidden.length === 0) {
+			this.webgl.compile(this.threeScene, camera);
+			onProgress?.(1);
+			return;
+		}
+		for (const obj of hidden) obj.visible = false;
+		const slices = Math.min(WARMUP_SLICES, hidden.length);
+		const per = Math.ceil(hidden.length / slices);
+		try {
+			for (let i = 0; i < slices; i++) {
+				for (let k = i * per; k < Math.min((i + 1) * per, hidden.length); k++) hidden[k].visible = true;
+				this.webgl.compile(this.threeScene, camera);
+				onProgress?.((i + 1) / slices);
+				if (typeof requestAnimationFrame === "function") await new Promise((resolve) => {
+					requestAnimationFrame(() => setTimeout(resolve, 0));
+				});
+			}
+		} finally {
+			for (const obj of hidden) obj.visible = true;
+		}
+	}
 	render() {
 		const scene = this.engine.scene;
 		if (!scene) return;
+		this.webgl.info.reset();
 		this.governResolution();
 		this.syncDebugLines();
 		this.syncSelectionOutline();
@@ -1574,10 +1711,11 @@ var Renderer3D = class {
 		const threeLight = sunLight ? sunLight._ensureObject3D() : null;
 		const followsCamera = !!threeLight && sunLight.shadowFollowsCamera === true;
 		this.environment.applySunLight(threeLight, followsCamera ? camWorld : null);
-		if (this.compiledScene !== scene) {
+		if (this.compiledScene !== scene && !this.deferCompile) {
 			this.compiledScene = scene;
 			this.webgl.compile(this.threeScene, activeCamera);
 		}
+		this.warmCamera = activeCamera;
 		const w = this.canvas.clientWidth || this.canvas.width;
 		const h = this.canvas.clientHeight || this.canvas.height;
 		const size = this.webgl.getSize(sizeScratch);
@@ -1645,7 +1783,10 @@ var Renderer3D = class {
 			this.bloomBlurTarget = null;
 		}
 		if (!this.bloomTarget) {
-			this.bloomTarget = new WebGLRenderTarget(w, h, { type: HalfFloatType });
+			this.bloomTarget = new WebGLRenderTarget(w, h, {
+				type: HalfFloatType,
+				samples: 4
+			});
 			this.bloomBrightTarget = new WebGLRenderTarget(hw, hh, { type: HalfFloatType });
 			this.bloomBlurTarget = new WebGLRenderTarget(hw, hh, { type: HalfFloatType });
 		}
@@ -1882,8 +2023,8 @@ var Renderer3D = class {
 		return null;
 	}
 	/**
-	* GPU counters for the LAST rendered frame, straight from three's
-	* per-frame-maintained `renderer.info` (render pass + GPU memory).
+	* GPU counters for the last rendered frame — EVERY pass of it, summed (see
+	* the `info.reset()` in `render`), plus GPU memory.
 	*/
 	stats() {
 		const info = this.webgl.info;
@@ -1894,6 +2035,24 @@ var Renderer3D = class {
 			textures: info.memory.textures
 		};
 	}
+	/**
+	* Where the last rendered frame was seen FROM.
+	*
+	* Paired with {@link cameraBasis} this is the view on screen — a third-person
+	* rig, a cutscene camera and the editor's free-fly all answer here, which is
+	* what a mode switch needs to carry across so the cut does not read as a
+	* page load.
+	*/
+	lastCameraPosition() {
+		const cam = this.lastCamera;
+		if (!cam) return null;
+		cam.getWorldPosition(basisPos);
+		return {
+			x: basisPos.x,
+			y: basisPos.y,
+			z: basisPos.z
+		};
+	}
 	/** The last rendered camera's world-space basis (for screen-plane dragging). */
 	cameraBasis() {
 		const cam = this.lastCamera;
@@ -1949,12 +2108,16 @@ var Renderer3D = class {
 		this.webgl.dispose();
 	}
 };
+/** Slices the warm-up compile is broken into — enough for a bar to move, few
+* enough that walking the scene per slice stays negligible. */
+const WARMUP_SLICES = 12;
 const sizeScratch = new Vector2();
 const lookScratch = new Vector3();
 const projScratch = new Vector3();
 const sunDirScratch = new Vector3();
 const sunTargetScratch = new Vector3();
 const basisQuat = new Quaternion();
+const basisPos = new Vector3();
 /** Reused camera world-position scratch (shadow-follow focus + underwater test). */
 const camPosScratch = new Vector3();
 /** Reused click-pick scratches (no per-pick allocation). */
@@ -1968,6 +2131,14 @@ var create_game_exports = /* @__PURE__ */ __exportAll({ createGame3D: () => crea
 * (engine attached for onReady) → physics (auto) → input → renderer → start.
 */
 async function createGame3D(opts) {
+	const report = async (fraction, label) => {
+		if (!opts.onProgress) return;
+		opts.onProgress(fraction, label);
+		if (typeof requestAnimationFrame !== "function") return;
+		await new Promise((resolve) => {
+			requestAnimationFrame(() => setTimeout(resolve, 0));
+		});
+	};
 	registerNodes3D();
 	if (opts.gameplay ?? true) registerGameplayBehaviors();
 	for (const [name, ctor] of Object.entries(opts.behaviors ?? {})) registerBehavior(name, ctor, { replace: true });
@@ -1976,13 +2147,16 @@ async function createGame3D(opts) {
 		fixedHz: opts.fixedHz,
 		...opts._scheduler ? { scheduler: opts._scheduler } : {}
 	});
-	const scene = loadScene(cloneSceneJson(opts.scene), {
+	const sourceJson = cloneSceneJson(opts.scene);
+	const scene = loadScene(cloneSceneJson(sourceJson), {
 		resolveScene: opts.resolveScene,
 		engine
 	});
 	engine.setScene(scene);
+	await report(.06, "scene");
 	let physics = null;
 	if (opts.physics === true || (opts.physics ?? "auto") === "auto" && hasBody(scene.root)) physics = await enablePhysics3D(engine);
+	await report(.1, "physics");
 	const cleanups = [];
 	const keyboard = opts.keyboard ?? (typeof window !== "undefined" ? window : false);
 	if (keyboard) engine.input.attachKeyboard(keyboard);
@@ -2016,22 +2190,79 @@ async function createGame3D(opts) {
 		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {},
 		...opts.adaptiveResolution !== void 0 ? { adaptiveResolution: opts.adaptiveResolution } : {}
 	});
-	if (opts.debug ?? false) {
+	await report(.14, "renderer");
+	const wantDebug = opts.debug ?? false;
+	const wantEditor = opts.editor ?? wantDebug;
+	const editorSwitch = wantEditor === true ? {} : wantEditor ? wantEditor : null;
+	const editorAction = {
+		label: "✎ edit this scene",
+		run: async () => {
+			if (!editorSwitch) return;
+			const camera = poseFromRenderer(renderer);
+			const open = editorSwitch.open ?? openBundledEditor;
+			const reboot = async (working) => {
+				await createGame3D({
+					...opts,
+					scene: working
+				});
+			};
+			await crossFade(async () => {
+				disposeGame();
+				try {
+					await open({
+						scene: sourceJson,
+						...camera ? { camera } : {},
+						play: reboot,
+						exit: () => reboot(sourceJson),
+						...editorSwitch.save ? { save: editorSwitch.save } : {},
+						...editorSwitch.library ? { library: editorSwitch.library === true ? devServerLibrary() : editorSwitch.library } : {}
+					});
+				} catch (error) {
+					console.error("[incanto] could not open the editor:", error);
+					await reboot(sourceJson);
+				}
+			}, "opening the editor…");
+		}
+	};
+	if (wantDebug) {
 		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?.() ?? {},
+				...editorSwitch ? { actions: [editorAction] } : {},
 				...opts._debugDoc ? { doc: opts._debugDoc } : {}
 			});
 			if (overlay) cleanups.push(() => overlay.dispose());
 		}
 	}
 	engine.start();
+	await report(.16, "shaders");
+	try {
+		renderer.deferFirstCompile?.();
+		const nowMs = globalThis.performance?.now?.() ?? 0;
+		engine.tick(nowMs);
+		engine.tick(nowMs + 16);
+		await renderer.warmUp?.((f) => {
+			opts.onProgress?.(.16 + f * .82, "shaders");
+		});
+	} catch {}
+	await report(1, "ready");
+	function disposeGame() {
+		teardown([
+			physics ? ["physics", () => physics?.dispose()] : null,
+			["app cleanups", () => {
+				for (const cleanup of cleanups) cleanup();
+			}],
+			["engine", () => engine.dispose()],
+			["renderer", () => renderer.dispose()]
+		]);
+	}
 	return {
 		engine,
 		scene,
+		sourceJson,
 		renderer,
 		physics,
 		stats() {
@@ -2044,12 +2275,8 @@ async function createGame3D(opts) {
 				...renderer.stats?.()
 			};
 		},
-		dispose() {
-			renderer.dispose();
-			physics?.dispose();
-			for (const cleanup of cleanups) cleanup();
-			engine.dispose();
-		}
+		openEditor: editorSwitch ? editorAction.run : null,
+		dispose: disposeGame
 	};
 }
 function cloneSceneJson(json) {

package/dist/debug-draw-BM3DsvtT.js

@@ -0,0 +1,18 @@
+//#region src/core/debug-draw.ts
+const sources = /* @__PURE__ */ new Set();
+/** @internal physics runtimes self-register on enable. */
+function registerDebugSource(source) {
+	sources.add(source);
+	return () => sources.delete(source);
+}
+/**
+* @internal renderers pull their OWN engine's sources for their dimension.
+*
+* `engine` is optional only so a caller with nothing to scope by still works;
+* every renderer passes one, and should.
+*/
+function debugSources(dimension, engine) {
+	return [...sources].filter((s) => s.dimension === dimension && (engine === void 0 || s.engine === engine));
+}
+//#endregion
+export { registerDebugSource as n, debugSources as t };