@vgai/engine 0.5.42 → 0.5.45

package/dist/react/use-data.d.ts

@@ -48,7 +48,7 @@ export declare function useData<T>(handle: DataHandle<T>): T;
  * runtime state belongs in your game's own store, never written back into
  * data files. Outside a running editor there is no `/__editor` server, so
  * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
+ * route anyway — builds strip `src/contributions/` and `src/tools/` entirely, §4).
  *
  * The body is PARSED VALUES, never serialized text: the dev server's fold
  * (`packages/editor/server/data-file-serialize.ts`) owns key order and the

package/dist/react/use-data.js

@@ -50,7 +50,7 @@ export function useData(handle) {
  * runtime state belongs in your game's own store, never written back into
  * data files. Outside a running editor there is no `/__editor` server, so
  * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
+ * route anyway — builds strip `src/contributions/` and `src/tools/` entirely, §4).
  *
  * The body is PARSED VALUES, never serialized text: the dev server's fold
  * (`packages/editor/server/data-file-serialize.ts`) owns key order and the

package/dist/render/matcap-texture.d.ts

@@ -0,0 +1,5 @@
+import * as THREE from 'three';
+export declare function drawNeutralMatcap(size?: number): HTMLCanvasElement;
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export declare function createNeutralMatcapTexture(size?: number): THREE.CanvasTexture;
+//# sourceMappingURL=matcap-texture.d.ts.map

package/dist/render/matcap-texture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcap-texture.d.ts","sourceRoot":"","sources":["../../src/render/matcap-texture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA8B/B,wBAAgB,iBAAiB,CAAC,IAAI,SAAO,GAAG,iBAAiB,CAkDhE;AAED,2EAA2E;AAC3E,wBAAgB,0BAA0B,CAAC,IAAI,SAAO,GAAG,KAAK,CAAC,aAAa,CAQ3E"}

package/dist/render/matcap-texture.js

@@ -0,0 +1,82 @@
+import * as THREE from 'three';
+/**
+ * The neutral matcap sphere, DRAWN rather than shipped.
+ *
+ * A matcap is just a picture of a lit sphere sampled by view-space normal, so
+ * there is nothing to vendor: the same three numbers a shader would use
+ * (key, fill, rim) evaluated once per texel produce the image. Keeping it
+ * procedural means the diagnostic look has no binary asset, no license, no
+ * provenance row, and no way to go missing from a build.
+ *
+ * The look is deliberately CLAY: one warm key from the upper left, a cool
+ * fill from the lower right, a tight rim, and a broad soft highlight — the
+ * neutral sculpting material whose whole job is to let form read without
+ * colour, texture or authored lighting getting a vote.
+ */
+const SIZE = 256;
+/** sRGB transfer curve — the canvas holds display-referred bytes. */
+function encode(value) {
+    const c = Math.min(1, Math.max(0, value));
+    return c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+function normalize(x, y, z) {
+    const length = Math.hypot(x, y, z) || 1;
+    return [x / length, y / length, z / length];
+}
+export function drawNeutralMatcap(size = SIZE) {
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const context = canvas.getContext('2d');
+    if (!context)
+        return canvas;
+    const image = context.createImageData(size, size);
+    const key = normalize(-0.45, 0.62, 0.64);
+    const fill = normalize(0.65, -0.35, 0.5);
+    // View direction is +Z for a matcap: the sphere is drawn facing the camera.
+    const half = normalize(key[0], key[1], key[2] + 1);
+    const base = [0.7, 0.69, 0.68];
+    const fillColor = [0.34, 0.4, 0.52];
+    const rimColor = [0.85, 0.88, 1];
+    for (let py = 0; py < size; py++) {
+        for (let px = 0; px < size; px++) {
+            const nx = (px + 0.5) / size / 0.5 - 1;
+            const ny = 1 - (py + 0.5) / size / 0.5;
+            const r2 = nx * nx + ny * ny;
+            // Outside the unit disc a matcap is never sampled by a facing surface,
+            // but bilinear filtering reaches one texel past the silhouette. Clamp
+            // to the rim normal so the edge stays the rim colour instead of
+            // bleeding whatever happened to be there.
+            const clamped = r2 > 1;
+            const scale = clamped ? 1 / Math.sqrt(r2) : 1;
+            const x = nx * scale;
+            const y = ny * scale;
+            const z = clamped ? 0 : Math.sqrt(Math.max(0, 1 - r2));
+            const diffuse = Math.max(0, x * key[0] + y * key[1] + z * key[2]);
+            const fillTerm = Math.max(0, x * fill[0] + y * fill[1] + z * fill[2]);
+            const specular = Math.max(0, x * half[0] + y * half[1] + z * half[2]) ** 42 * 0.5;
+            const rim = (1 - z) ** 3.2 * 0.4;
+            const offset = (py * size + px) * 4;
+            for (let channel = 0; channel < 3; channel++) {
+                const lit = base[channel] * (0.16 + 0.8 * diffuse) +
+                    fillColor[channel] * 0.3 * fillTerm +
+                    rimColor[channel] * rim +
+                    specular;
+                image.data[offset + channel] = Math.round(encode(lit) * 255);
+            }
+            image.data[offset + 3] = 255;
+        }
+    }
+    context.putImageData(image, 0, 0);
+    return canvas;
+}
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export function createNeutralMatcapTexture(size = SIZE) {
+    const texture = new THREE.CanvasTexture(drawNeutralMatcap(size));
+    texture.colorSpace = THREE.SRGBColorSpace;
+    texture.minFilter = THREE.LinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.generateMipmaps = false;
+    texture.needsUpdate = true;
+    return texture;
+}

package/dist/render/soft-particle-depth.d.ts

@@ -1,6 +1,6 @@
 /**
- * Scene DEPTH for three.quarks' soft particles — the pass that makes
- * `ParticlesDescriptor.softParticles` a real effect instead of a footgun.
+ * Opaque scene DEPTH for native consumers, including three.quarks soft particles and translated
+ * Godot `hint_depth_texture` shader uniforms.
  *
  * ## What three.quarks needs, and what it does when nobody supplies it
  *
@@ -61,12 +61,10 @@
  * with the armed particle renderers and every transparent surface hidden and a
  * colour-write-disabled override material in place.
  *
- * That cost is paid ONLY while something is armed. {@link armSoftParticleDepth}
- * is called from `particles-factory.ts`'s `registerParticleSystem` when the
- * system it is registering asked for `softParticles`; with the registry empty
- * {@link SoftParticleDepthPass.render} returns before it touches the scene, so a
- * world with no soft particles pays one `Set.size` read per frame and nothing
- * else. Armed, per frame per camera it costs: one scene traverse (to find the
+ * That cost is paid ONLY while something is armed. Soft particles enter through
+ * {@link armSoftParticleDepth}; translated depth-texture shader programs enter through
+ * {@link armSceneDepthTexture}. With both registries empty {@link SoftParticleDepthPass.render}
+ * returns before it touches the scene. Armed, per frame per camera it costs: one scene traverse (to find the
  * transparent surfaces to hide), one extra geometry-only scene draw with shadow
  * updates suppressed, and a drawing-buffer-sized depth target
  * (`UnsignedIntType` depth + an unread RGBA8 colour attachment ≈ 8
@@ -97,6 +95,10 @@
  */
 import * as THREE from 'three';
 import type { BatchedRenderer } from 'three.quarks';
+/** Any native material/program that samples Godot's opaque-pass depth texture. */
+export interface SceneDepthTextureConsumer {
+    setDepthTexture(texture: THREE.Texture): void;
+}
 /**
  * A 1x1 texture whose red channel is 1.0 — "the depth buffer says nothing is in
  * front of anything".
@@ -120,6 +122,10 @@ export declare function armSoftParticleDepth(renderer: BatchedRenderer): void;
  * depth nobody is refreshing.
  */
 export declare function disarmSoftParticleDepth(renderer: BatchedRenderer): void;
+/** Retain one consumer of the same opaque scene-depth image Godot exposes as hint_depth_texture. */
+export declare function armSceneDepthTexture(consumer: SceneDepthTextureConsumer): void;
+/** Release one retained Godot depth-texture consumer without leaving a disposed target bound. */
+export declare function disarmSceneDepthTexture(consumer: SceneDepthTextureConsumer): void;
 /** Test/diagnostic read of the registry — how many renderers a pass would consider. */
 export declare function armedSoftParticleRendererCount(): number;
 /** The subset of `THREE.WebGLRenderer` this pass drives, so a host can supply its own. */

package/dist/render/soft-particle-depth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAepD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA0CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA0GnE"}
+{"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAapD,kFAAkF;AAClF,MAAM,WAAW,yBAAyB;IACxC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;CAC/C;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAG9E;AAED,iGAAiG;AACjG,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAQjF;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA0CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CAiHnE"}

package/dist/render/soft-particle-depth.js

@@ -1,6 +1,6 @@
 /**
- * Scene DEPTH for three.quarks' soft particles — the pass that makes
- * `ParticlesDescriptor.softParticles` a real effect instead of a footgun.
+ * Opaque scene DEPTH for native consumers, including three.quarks soft particles and translated
+ * Godot `hint_depth_texture` shader uniforms.
  *
  * ## What three.quarks needs, and what it does when nobody supplies it
  *
@@ -61,12 +61,10 @@
  * with the armed particle renderers and every transparent surface hidden and a
  * colour-write-disabled override material in place.
  *
- * That cost is paid ONLY while something is armed. {@link armSoftParticleDepth}
- * is called from `particles-factory.ts`'s `registerParticleSystem` when the
- * system it is registering asked for `softParticles`; with the registry empty
- * {@link SoftParticleDepthPass.render} returns before it touches the scene, so a
- * world with no soft particles pays one `Set.size` read per frame and nothing
- * else. Armed, per frame per camera it costs: one scene traverse (to find the
+ * That cost is paid ONLY while something is armed. Soft particles enter through
+ * {@link armSoftParticleDepth}; translated depth-texture shader programs enter through
+ * {@link armSceneDepthTexture}. With both registries empty {@link SoftParticleDepthPass.render}
+ * returns before it touches the scene. Armed, per frame per camera it costs: one scene traverse (to find the
  * transparent surfaces to hide), one extra geometry-only scene draw with shadow
  * updates suppressed, and a drawing-buffer-sized depth target
  * (`UnsignedIntType` depth + an unread RGBA8 colour attachment ≈ 8
@@ -106,6 +104,7 @@ import * as THREE from 'three';
  * renderers actually parented under the scene it is rendering.
  */
 const armed = new Map();
+const depthTextureConsumers = new Map();
 let farDepth;
 /**
  * A 1x1 texture whose red channel is 1.0 — "the depth buffer says nothing is in
@@ -148,6 +147,22 @@ export function disarmSoftParticleDepth(renderer) {
         return;
     renderer.setDepthTexture(farDepthTexture());
 }
+/** Retain one consumer of the same opaque scene-depth image Godot exposes as hint_depth_texture. */
+export function armSceneDepthTexture(consumer) {
+    depthTextureConsumers.set(consumer, (depthTextureConsumers.get(consumer) ?? 0) + 1);
+    consumer.setDepthTexture(farDepthTexture());
+}
+/** Release one retained Godot depth-texture consumer without leaving a disposed target bound. */
+export function disarmSceneDepthTexture(consumer) {
+    const remaining = (depthTextureConsumers.get(consumer) ?? 0) - 1;
+    if (remaining > 0) {
+        depthTextureConsumers.set(consumer, remaining);
+        return;
+    }
+    if (!depthTextureConsumers.delete(consumer))
+        return;
+    consumer.setDepthTexture(farDepthTexture());
+}
 /** Test/diagnostic read of the registry — how many renderers a pass would consider. */
 export function armedSoftParticleRendererCount() {
     return armed.size;
@@ -210,14 +225,14 @@ export function createSoftParticleDepthPass() {
     };
     return {
         render(renderer, scene, camera) {
-            if (armed.size === 0)
+            if (armed.size === 0 && depthTextureConsumers.size === 0)
                 return;
             const consumers = [];
             for (const candidate of armed.keys()) {
                 if (isUnder(candidate, scene))
                     consumers.push(candidate);
             }
-            if (consumers.length === 0)
+            if (consumers.length === 0 && depthTextureConsumers.size === 0)
                 return;
             // See REQUIRED_RENDERER_MEMBERS: a renderer that cannot swap render
             // targets cannot run a prepass, and the frame is worth more than the
@@ -227,9 +242,9 @@ export function createSoftParticleDepthPass() {
                 if (!warnedIncapable) {
                     warnedIncapable = true;
                     // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to throwing out of the frame
-                    console.warn(`soft-particle depth prepass skipped: this renderer implements none of ${missing.join(', ')}. ` +
-                        `${String(consumers.length)} particle batch(es) keep the inert far-depth default, so they ` +
-                        'draw unfaded — the same pixels as a batch that never declared a proximity fade. A real ' +
+                    console.warn(`opaque scene-depth prepass skipped: this renderer is missing ${missing.join(', ')}. ` +
+                        `${String(consumers.length)} particle batch(es) and ${String(depthTextureConsumers.size)} ` +
+                        'shader consumer(s) keep the inert far-depth default. A real ' +
                         'WebGLRenderer has these; a design-time settle stand-in does not.');
                 }
                 return;
@@ -284,14 +299,22 @@ export function createSoftParticleDepthPass() {
                     object.visible = true;
                 hidden.length = 0;
             }
+            const renderedDepth = rt.depthTexture;
+            if (renderedDepth === null) {
+                throw new Error('opaque scene-depth prepass lost its authored depth texture.');
+            }
             for (const consumer of consumers)
-                consumer.setDepthTexture(rt.depthTexture);
+                consumer.setDepthTexture(renderedDepth);
+            for (const consumer of depthTextureConsumers.keys())
+                consumer.setDepthTexture(renderedDepth);
         },
         dispose() {
             // Every consumer this pass fed now points at a texture that is about to
             // go away. Hand them the inert default back rather than a disposed one.
             for (const candidate of armed.keys())
                 candidate.setDepthTexture(farDepthTexture());
+            for (const consumer of depthTextureConsumers.keys())
+                consumer.setDepthTexture(farDepthTexture());
             target?.dispose();
             target = null;
             override.dispose();

package/dist/render/viewport-shading.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from 'three';
 /** Temporary developer-facing shading modes. These never become scene data. */
-export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'matcap' | 'normals' | 'overdraw';
 /**
  * Applies a render-only material view and restores every native material in a
  * `finally` block. Gameplay and authoring therefore always observe the real
@@ -9,6 +9,16 @@ export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'no
 export declare class ViewportShadingRenderer {
     private readonly _derived;
     private readonly _normals;
+    /**
+     * The clay/sculpt look. Built on FIRST USE, not at construction: the matcap
+     * sphere is drawn into a 2D canvas, and every ViewportShadingRenderer that
+     * only ever draws `solid` would otherwise pay for a texture nobody samples.
+     * `toneMapped: false` for the same reason the overdraw material sets it —
+     * a diagnostic look must read exactly as authored, not as the document's
+     * exposure and tone curve happen to grade it.
+     */
+    private _matcap;
+    private _matcapTexture;
     private readonly _overdraw;
     render(scene: THREE.Scene, mode: ViewportShadingMode, draw: () => void, include?: (mesh: THREE.Mesh) => boolean): void;
     dispose(): void;

package/dist/render/viewport-shading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewport-shading.d.ts","sourceRoot":"","sources":["../../src/render/viewport-shading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAqBpG;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CASvB;IAEH,MAAM,CACJ,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAoB,GAClD,IAAI;IA0BP,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,YAAY;CA6CrB"}
+{"version":3,"file":"viewport-shading.d.ts","sourceRoot":"","sources":["../../src/render/viewport-shading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,MAAM,GACN,OAAO,GACP,WAAW,GACX,QAAQ,GACR,SAAS,GACT,UAAU,CAAC;AAqBf;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CASvB;IAEH,MAAM,CACJ,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAoB,GAClD,IAAI;IA0BP,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,YAAY;CAuDrB"}

package/dist/render/viewport-shading.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { createNeutralMatcapTexture } from './matcap-texture';
 function materialColor(material) {
     const color = material.color;
     return color?.clone() ?? new THREE.Color(0xbec7d1);
@@ -14,6 +15,16 @@ function textureOf(material, key) {
 export class ViewportShadingRenderer {
     _derived = new Map();
     _normals = new THREE.MeshNormalMaterial();
+    /**
+     * The clay/sculpt look. Built on FIRST USE, not at construction: the matcap
+     * sphere is drawn into a 2D canvas, and every ViewportShadingRenderer that
+     * only ever draws `solid` would otherwise pay for a texture nobody samples.
+     * `toneMapped: false` for the same reason the overdraw material sets it —
+     * a diagnostic look must read exactly as authored, not as the document's
+     * exposure and tone curve happen to grade it.
+     */
+    _matcap = null;
+    _matcapTexture = null;
     _overdraw = new THREE.MeshBasicMaterial({
         color: 0xffffff,
         transparent: true,
@@ -56,12 +67,26 @@ export class ViewportShadingRenderer {
         this._derived.clear();
         this._normals.dispose();
         this._overdraw.dispose();
+        this._matcap?.dispose();
+        this._matcapTexture?.dispose();
+        this._matcap = null;
+        this._matcapTexture = null;
     }
     _materialFor(material, mode) {
         if (mode === 'normals')
             return this._normals;
         if (mode === 'overdraw')
             return this._overdraw;
+        if (mode === 'matcap') {
+            if (!this._matcap) {
+                this._matcapTexture = createNeutralMatcapTexture();
+                this._matcap = new THREE.MeshMatcapMaterial({
+                    matcap: this._matcapTexture,
+                    toneMapped: false,
+                });
+            }
+            return this._matcap;
+        }
         let pair = this._derived.get(material);
         if (!pair) {
             const common = {

package/dist/runtime/create-runtime.js

@@ -112,14 +112,15 @@ export async function createGameRuntime(config) {
 // Universal root host
 // ---------------------------------------------------------------------------
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
- *  roots: a headless mount never calls a render-phase method on
- *  `host.renderer` at all, so
- *  this only needs to satisfy the handful of calls THIS file itself makes
+ *  roots: draw submission is inert while native scene/component evaluation
+ *  still runs. This satisfies Fiber's custom-renderer gate and the calls
  *  (`setPixelRatio`/`setClearColor`/`setSize` at mount, `dispose`/
  *  `forceContextLoss` at teardown) — never a real GL call. Node conformance
  *  tests only; never used when `headless` is left `false`/absent. */
-function createHeadlessRendererStub() {
+function createHeadlessRendererStub(canvas) {
     return {
+        domElement: canvas,
+        render() { },
         setPixelRatio() { },
         setClearColor() { },
         setSize() { },
@@ -174,7 +175,7 @@ function disposeMountedRoot(entry, container) {
 async function mountOneThreeRoot(spec, ctx) {
     const { game, canvas, w, h, dpr, isBottom, headless, assets, antialias } = ctx;
     const renderer = headless
-        ? createHeadlessRendererStub()
+        ? createHeadlessRendererStub(canvas)
         : createHostRenderer(canvas, w, h, 
         // The manifest's `rendering.antialias` reaches the WebGL context here and NOWHERE else:
         // `createHostRenderer` passes it straight to the constructor, and the sample count is

package/dist/runtime/mount-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount-manifest.d.ts","sourceRoot":"","sources":["../../src/runtime/mount-manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mount-manifest.d.ts","sourceRoot":"","sources":["../../src/runtime/mount-manifest.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAqB,KAAK,WAAW,EAAsB,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAE,KAAK,uBAAuB,EAA2B,MAAM,gBAAgB,CAAC;AAGvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CAClE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,qBAAqB;IAC3D,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;CACtC;AAED,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;AAM5E,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;6DACyD;IACzD,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC;;qEAEiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC;IACpE;8EAC0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;gEAC4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EACjB;QACE,QAAQ,CAAC,GAAG,CAAC,EAAE;YAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;QACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;KACvD,GACD,SAAS,CAAC;IACd;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;IACvD;;;kFAG8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CAC5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAC;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACvD,GAAG,MAAM,GAAG,SAAS,CAIrB;AAkBD,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAyCjD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CAGlE;AAiID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuFzF"}

package/dist/runtime/mount-manifest.js

@@ -76,6 +76,15 @@ function hasRealWindow() {
 function looksAlreadyResolved(value) {
     if (typeof value !== 'object' || value === null)
         return false;
+    // The loader's own output field is the surest mark: a raw manifest never
+    // carries it (the schema is strict). Without this, a RESOLVED manifest
+    // with `roots: []` — a models project, nothing to play — fell through to
+    // `loadGameManifest`, whose strict parse refused THIS key ("Unrecognized
+    // key: deferredConfigurationKinds") instead of saying "no roots"
+    // (blind lantern round 21, 2026-09-06, sent there by the never-played nag).
+    if (Array.isArray(value.deferredConfigurationKinds)) {
+        return true;
+    }
     const roots = value.roots;
     if (!Array.isArray(roots) || roots.length === 0)
         return false;
@@ -97,7 +106,7 @@ function looksAlreadyResolved(value) {
 export function resolveManifest(raw) {
     if (looksAlreadyResolved(raw))
         return raw;
-    return loadGameManifest(raw);
+    return loadGameManifest(raw, { configurationKinds: 'defer' });
 }
 // ---------------------------------------------------------------------------
 // Per-kind entry -> adapter resolution (mirrors `resolveRootBinding`'s
@@ -265,7 +274,7 @@ export async function mountManifestRoots(opts) {
         // `manifest/load.ts`) is `{ room, module } | undefined`; its mere presence
         // is the "this project declares a room" signal, independent of
         // whether/when the game actually joins it.
-        if (manifest.server) {
+        if (manifest.configurations.some((configuration) => configuration.kind === 'process')) {
             debugRegistry.setRoomDeclared(true);
         }
         // Defect 5 fix: `maybeInstallDebugBridge` adds `window` listeners and

package/dist/settings/schema.d.ts

@@ -0,0 +1,99 @@
+/**
+ * THE SETTINGS DOCUMENT — the Zod truth for the two shared settings layers
+ * (ARCHITECTURE-CORE §Editor chrome, "Settings have four layers with named
+ * homes"):
+ *
+ *   ~/.vgai/settings.json     the USER layer — one person, every project
+ *   <project>/.vgai/settings.json   the PROJECT layer — one project, committed,
+ *                             every person who opens it
+ *
+ * Both files carry the same shape; the project layer overrides the user layer
+ * key by key (`mergeEditorSettings`). Neither layer holds authored content —
+ * an unreadable file is reported by name and falls back to defaults, never
+ * migrated. The generated JSON Schema (`npm run generate-schema` →
+ * `packages/engine/schemas/vgai-settings.schema.json`) is what an editor
+ * autocompletes against when a person edits either file by hand.
+ *
+ * Every field here has a runtime reader in the editor's settings store
+ * consumers (`theme-preference.ts`, `workspace-regions.ts`,
+ * `keymap-presets.ts`, `workspace-presets.ts`, `device-preview.ts`); a field
+ * with no reader does not get declared (CLAUDE.md, "Do not author schema
+ * fields that have no runtime reader").
+ */
+import { z } from 'zod';
+export declare const ChromeRegionsSettingsSchema: z.ZodObject<{
+    tabs: z.ZodOptional<z.ZodEnum<{
+        hidden: "hidden";
+        shown: "shown";
+    }>>;
+    header: z.ZodOptional<z.ZodEnum<{
+        hidden: "hidden";
+        shown: "shown";
+    }>>;
+    shelf: z.ZodOptional<z.ZodEnum<{
+        hidden: "hidden";
+        shown: "shown";
+    }>>;
+    inspector: z.ZodOptional<z.ZodEnum<{
+        properties: "properties";
+        column: "column";
+    }>>;
+    drawer: z.ZodOptional<z.ZodEnum<{
+        hidden: "hidden";
+        shown: "shown";
+    }>>;
+}, z.core.$strict>;
+export declare const EditorSettingsSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    appearance: z.ZodOptional<z.ZodObject<{
+        palette: z.ZodOptional<z.ZodString>;
+        material: z.ZodOptional<z.ZodString>;
+        regions: z.ZodOptional<z.ZodObject<{
+            tabs: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                shown: "shown";
+            }>>;
+            header: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                shown: "shown";
+            }>>;
+            shelf: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                shown: "shown";
+            }>>;
+            inspector: z.ZodOptional<z.ZodEnum<{
+                properties: "properties";
+                column: "column";
+            }>>;
+            drawer: z.ZodOptional<z.ZodEnum<{
+                hidden: "hidden";
+                shown: "shown";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    keymap: z.ZodOptional<z.ZodString>;
+    workspace: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    devicePreview: z.ZodOptional<z.ZodObject<{
+        preset: z.ZodOptional<z.ZodString>;
+        touch: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type EditorSettings = z.infer<typeof EditorSettingsSchema>;
+export type ChromeRegionsSettings = z.infer<typeof ChromeRegionsSettingsSchema>;
+/** Which layer a file is; the file paths are the server's. */
+export type SettingsLayer = 'user' | 'project';
+/** Deep-merge plain objects; anything else (primitives, arrays, null)
+ *  replaces. `merge(user, project)` is the effective document. */
+export declare function mergeEditorSettings(base: EditorSettings, over: EditorSettings): EditorSettings;
+/** Validate a raw document. The result carries the parsed settings or the
+ *  issues, spelled for a person who has the file open. */
+export declare function parseEditorSettings(raw: unknown): {
+    settings: EditorSettings;
+    issues: [];
+} | {
+    settings: null;
+    issues: string[];
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/settings/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/settings/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;kBAY0B,CAAC;AAEnE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA6CsD,CAAC;AAExF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAM/C;kEACkE;AAClE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAY9F;AAED;0DAC0D;AAC1D,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,GACX;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,EAAE,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CASjF"}