@vgai/engine 0.5.21 → 0.5.23

package/src/render/ibl-override-material.ts

@@ -0,0 +1,170 @@
+/**
+ * Replace Three's image-based-lighting functions on a `MeshStandardMaterial`,
+ * per fragment, without forking three.
+ *
+ * A local-probe system cannot express itself as `material.envMap`: one envMap
+ * per object picks ONE environment for the whole draw, and the decisive work —
+ * which probe volume contains this fragment, how it fades at the boundary,
+ * what happens where volumes overlap — is per-fragment and can differ across a
+ * single `InstancedMesh`. Every such system therefore does the same three
+ * things to three's own program, and this module is that shared mechanism:
+ *
+ *   1. take `ShaderChunk.envmap_physical_pars_fragment` and rename its two
+ *      entry points, so the caller's replacement can still call them as its
+ *      fallback ({@link baseIblFunctions});
+ *   2. publish the fragment's world position as a varying, spliced into
+ *      `<worldpos_vertex>` under `USE_ENVMAP` ({@link IBL_WORLD_POSITION});
+ *   3. swap the fragment chunk for the caller's own GLSL and extend the
+ *      program cache key so the variant is not shared with an unpatched
+ *      material ({@link overrideMaterialIbl}).
+ *
+ * What the caller keeps is exactly what makes its system ITS system: the
+ * lighting model in the GLSL body, the uniforms behind it, and how probes are
+ * discovered, scheduled and captured. This module decides none of that — it
+ * hands back three's own shader object and gets out of the way.
+ *
+ * Consumers today: the `reflections` capability's native probe system, and
+ * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * deliberately different renderers over this one splice.
+ */
+import { type Mesh, type MeshStandardMaterial, ShaderChunk } from 'three';
+
+/** The shader object three hands to `onBeforeCompile`. */
+export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
+
+/**
+ * The `varying vec3` the vertex splice publishes and the fragment body reads.
+ *
+ * It is ONE name across every consumer on purpose: the splice that declares it
+ * lives here, so a per-consumer name would be a string two files have to agree
+ * on with nothing checking that they do.
+ */
+export const IBL_WORLD_POSITION = 'vgaiIblWorldPosition';
+
+/**
+ * Three's own IBL chunk with `getIBLIrradiance`/`getIBLRadiance` renamed to
+ * `getBaseIBLIrradiance`/`getBaseIBLRadiance`.
+ *
+ * A replacement chunk defines the original names itself; calling the renamed
+ * pair is how it falls back to the scene environment where no probe applies.
+ */
+export function baseIblFunctions(): string {
+  return ShaderChunk.envmap_physical_pars_fragment
+    .replaceAll('getIBLIrradiance', 'getBaseIBLIrradiance')
+    .replaceAll('getIBLRadiance', 'getBaseIBLRadiance');
+}
+
+/**
+ * Every material a mesh draws with that {@link overrideMaterialIbl} accepts.
+ *
+ * `isMeshStandardMaterial` is true for `MeshPhysicalMaterial` too, which is the
+ * intent: both compile the physical IBL chunk this module replaces.
+ */
+export function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[] {
+  const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+  return materials.filter((material): material is MeshStandardMaterial =>
+    Boolean((material as MeshStandardMaterial).isMeshStandardMaterial),
+  );
+}
+
+export interface IblOverrideOptions {
+  /**
+   * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at
+   * COMPILE time, not at install time, so a caller whose probe count is still
+   * settling does not have to reinstall to change it.
+   */
+  readonly fragment: () => string;
+  /**
+   * Appended to the material's own `customProgramCacheKey`, after a `|`. Must
+   * distinguish every shape of {@link IblOverrideOptions.fragment} the caller
+   * can produce — a probe COUNT belongs in here, because it changes the
+   * declared uniform array sizes.
+   */
+  readonly cacheKey: () => string;
+  /**
+   * Runs at the end of `onBeforeCompile`, with the shader three is compiling.
+   * Seed uniforms here: this is the only moment the caller is handed the
+   * object whose `uniforms` map the program will read.
+   */
+  readonly onCompile?: (shader: IblOverrideShader) => void;
+}
+
+export interface IblOverride {
+  readonly material: MeshStandardMaterial;
+  /**
+   * The shader three compiled this material with, or null before the first
+   * compile and after {@link IblOverride.restore}. Uniform writes go through
+   * `shader.uniforms`.
+   */
+  readonly shader: IblOverrideShader | null;
+  /** Put the material's own `onBeforeCompile`/`customProgramCacheKey` back. */
+  restore(): void;
+}
+
+/**
+ * Install the override. The returned handle is the only way to reach the
+ * compiled shader or to undo the patch; the material is otherwise untouched
+ * (in particular this never assigns `envMap`, which stays the caller's).
+ *
+ * The caller's own `onBeforeCompile` runs FIRST and its result is what gets
+ * spliced, so an override composes over a material that already had one.
+ */
+export function overrideMaterialIbl(
+  material: MeshStandardMaterial,
+  options: IblOverrideOptions,
+): IblOverride {
+  const previousCompile = material.onBeforeCompile;
+  const previousCacheKey = material.customProgramCacheKey;
+  let compiled: IblOverrideShader | null = null;
+
+  material.onBeforeCompile = (shader, renderer) => {
+    previousCompile.call(material, shader, renderer);
+    requireChunk(shader.vertexShader, '#include <worldpos_vertex>');
+    requireChunk(shader.fragmentShader, '#include <envmap_physical_pars_fragment>');
+    shader.vertexShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.vertexShader.replace(
+      '#include <worldpos_vertex>',
+      `#include <worldpos_vertex>
+#if defined(USE_ENVMAP)
+  ${IBL_WORLD_POSITION} = worldPosition.xyz;
+#endif`,
+    )}`;
+    shader.fragmentShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.fragmentShader.replace(
+      '#include <envmap_physical_pars_fragment>',
+      options.fragment(),
+    )}`;
+    compiled = shader;
+    options.onCompile?.(shader);
+  };
+  material.customProgramCacheKey = () => `${previousCacheKey.call(material)}|${options.cacheKey()}`;
+  material.needsUpdate = true;
+
+  return {
+    material,
+    get shader() {
+      return compiled;
+    },
+    restore() {
+      material.onBeforeCompile = previousCompile;
+      material.customProgramCacheKey = previousCacheKey;
+      material.needsUpdate = true;
+      compiled = null;
+    },
+  };
+}
+
+/**
+ * A missing chunk is a NAMED error rather than a silent no-op.
+ *
+ * `String.replace` with no match returns the string unchanged, which would
+ * leave the varying declared and never assigned — a shader that links and
+ * renders the wrong thing. The only way to reach this today is a preceding
+ * `onBeforeCompile` in the same chain having already replaced the chunk (two
+ * IBL overrides stacked on one material), and that is worth a message naming
+ * the chunk instead of a black frame.
+ */
+function requireChunk(source: string, chunk: string): void {
+  if (source.includes(chunk)) return;
+  throw new Error(
+    `overrideMaterialIbl needs three's ${chunk} shader chunk, and this material's program no longer contains it.`,
+  );
+}

package/src/render/light-camera-factory.ts

@@ -1,12 +1,10 @@
 /**
- * Shared light + camera factory (T1.13 — DEFAULTS truth).
+ * Shared light + camera factory — the ONE place light/camera fallbacks are
+ * decided, and it decides them by READING `DEFAULTS.light`/`DEFAULTS.camera`.
  *
- * `createLight`/`createCamera` used to be duplicated verbatim between the
- * runtime loader (`scene-loader.ts`) and the editor preview
- * (`entity-factory.ts`) — both hardcoded the same fallback literals (color
- * '#ffffff', fov 60, near 0.1, far 1000, etc.) that happened to agree with
- * `DEFAULTS.light`/`DEFAULTS.camera` by luck rather than by reading them. Any
- * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
+ * A second copy hardcoding the same literals (color '#ffffff', fov 60, near
+ * 0.1, far 1000) would agree by luck rather than by construction, and any
+ * edit to either copy — or to `DEFAULTS` — would silently diverge.
  *
  * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
  * from a `LightDescriptor`/`CameraDescriptor` descriptor, reading its fallbacks from
@@ -22,10 +20,9 @@ import * as THREE from 'three';
 // `three/addons/*` alias (package.json `exports`: `"./addons/*":
 // "./examples/jsm/*"` — the identical file as
 // `three/examples/jsm/lights/RectAreaLightUniformsLib.js`) because a literal
-// `/examples/` specifier trips `engine-host-no-game-imports.test.ts`'s
-// game/editor-example guard (a same-substring false positive against this
-// repo's OWN `packages/editor/template/src/examples/` convention, unrelated
-// to three.js's addon folder naming).
+// `/examples/` specifier trips this repo's game/editor-example import guard —
+// a same-substring false positive against our own `src/examples/` convention,
+// unrelated to three.js's addon folder naming.
 import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
 import type { CameraDescriptor } from '../asset-formats/camera';
 import type { LightDescriptor } from '../asset-formats/light';

package/src/render/material-factory.ts

@@ -65,7 +65,7 @@ export function createMaterial(mat?: MaterialDescriptor): THREE.Material {
   // R1c — every fallback below reads DEFAULTS.material.* instead of
   // duplicating its value as a bare literal, so DEFAULTS stays the single
   // source of truth for what an omitted field renders as (see
-  // defaults-out-of-scope-consistency.test.ts / material-factory.test.ts's
+  // `material-factory.test.ts`'s
   // "omitted-field" locks, which fail if either copy drifts from the other).
   const dMat = DEFAULTS.material;
   const sideValue = mat.side ?? dMat.side;

package/src/render/render-batch-system.ts

@@ -13,21 +13,29 @@ import { staticBatchSignature } from './structural-signature';
  * N logical objects → 1 draw call, ~0 CPU/frame. This is the classic "static
  * batching" technique (cf. Unity/PlayCanvas static batch groups).
  *
- * Strategy 1 (keep identity, don't merge). Moving entities (boids-style, all-frame churn) are a separate
- * concern — see render/auto-batcher.ts (dynamic).
+ * Strategy 1 (keep identity, don't merge). Moving entities (boids-style,
+ * all-frame churn) are a separate concern, and the engine does not answer it:
+ * a game's production answer is the `static-batch` capability's `<Frozen>`
+ * (see the scope note below).
  *
  * Eligibility (anything failing stays an ordinary draw — degrade, don't break):
  *   - plain THREE.Mesh (not Instanced/Skinned/Batched)
  *   - single, opaque material (transparency needs per-object sorting)
  *   - group of ≥2 sharing (geometry, material, shadow flags)
- *   - not explicitly opted out (`entity.render.autoBatch === false`)
+ *   - (there is no per-entity opt-out setting: this docblock used to name
+ *     `entity.render.autoBatch === false`, a render-feature field NO CODE HERE
+ *     OR ANYWHERE EVER READ. The field was deleted with R-2's coverage fix;
+ *     opting a subtree out is the `static-batch` capability's `<Frozen>`
+ *     declaration, per the scope note below.)
  *   - STATIC members (no physics/components/animation) → detached; MOVING members →
  *     kept in-graph hidden + dirty-synced each frame. A bucket may split into both.
  *
  * Scope / limitations (v1):
- *   - NOT WIRED: nothing in the engine calls build() — the rendering-scale
- *     example's render lab is the only driver (via the hosted-module map), and
- *     no adapter batches automatically. That is settled, not pending: a game's
+ *   - NOT WIRED: nothing in the engine calls build(), and nothing constructs
+ *     this class. The only remaining reference is the hosted editor's
+ *     project-script module map (`editor/src/browser-project-scripts.ts`),
+ *     which loads the module so a project script MAY drive it; the example
+ *     that used to is gone. That is settled, not pending: a game's
  *     production answer is the `static-batch` capability's `<Frozen>`, a
  *     DECLARED mount-static subtree in the game's own TSX, and `dev/static-
  *     batch-advisor.ts` is what routes an author to it by measurement. Full-

package/src/render/render-features.ts

@@ -2,12 +2,23 @@ import { z } from 'zod';
 
 /**
  * The render-feature registry — single source of truth for every togglable render
- * setting. The scene schema (`SceneEnvironment.rendering`, `SceneEntity.render`),
- * the cascade resolver (`resolveRenderSettings`), the editor UI, and the stats
- * overlay are all derived from this list, so "everything togglable" stays
- * consistent by construction (same posture as the component/material/instancer
- * registries). Adding a feature here gives it a schema field + cascade entry for
- * free..
+ * setting. The render-env schema (`asset-formats/render-env.ts`) and the cascade
+ * resolver (`resolveRenderSettings`) are both derived from this list, so
+ * "everything togglable" stays consistent by construction (same posture as the
+ * component/material/instancer registries).
+ *
+ * EVERY ENTRY HERE MUST HAVE A RUNTIME READER of its resolved value, and that is
+ * now enforced: `schema-reader-coverage.test.ts` derives its walk from this
+ * array, so adding a feature adds a described schema path that fails coverage
+ * until `schema-consumption-map.ts` names the file that reads it.
+ *
+ * Three entries were deleted when that enforcement first ran, having reached it
+ * with no reader at all: `autoBatch` (its only mention was a COMMENT in
+ * `render-batch-system.ts`, a class whose own header says nothing calls it),
+ * `lod`, and `backend` (which offered a `webgpu` option while
+ * `setup-renderer.ts` unconditionally constructs a `THREE.WebGLRenderer`). A
+ * toggle that changes nothing is worse than a missing one — it tells an author
+ * the engine has a dial it does not have.
  */
 
 export type RenderFeatureValue = boolean | number | string;
@@ -37,16 +48,6 @@ export interface RenderFeature {
 }
 
 export const RENDER_FEATURES: readonly RenderFeature[] = [
-  {
-    key: 'autoBatch',
-    label: 'Auto-batching',
-    description:
-      'Automatically batch entities sharing geometry+material into one draw call (InstancedMesh/BatchedMesh) while keeping each Object3D as the handle. The headline perf win; opt out per-entity for custom-shader/skinned meshes.',
-    kind: 'toggle',
-    default: true,
-    apply: 'live',
-    perEntity: true,
-  },
   {
     key: 'frustumCulling',
     label: 'Frustum culling',
@@ -56,15 +57,6 @@ export const RENDER_FEATURES: readonly RenderFeature[] = [
     apply: 'live',
     perEntity: true,
   },
-  {
-    key: 'lod',
-    label: 'Level of detail',
-    description: 'Distance-based geometry swap (LOD) for eligible entities.',
-    kind: 'toggle',
-    default: true,
-    apply: 'live',
-    perEntity: true,
-  },
   {
     key: 'shadows',
     label: 'Shadows',
@@ -103,16 +95,6 @@ export const RENDER_FEATURES: readonly RenderFeature[] = [
     apply: 'reload',
     perEntity: false,
   },
-  {
-    key: 'backend',
-    label: 'Renderer backend',
-    description: 'GPU backend: auto picks WebGPU when available, else WebGL2. Applies on reload.',
-    kind: 'enum',
-    default: 'auto',
-    apply: 'reload',
-    perEntity: false,
-    options: ['auto', 'webgl', 'webgpu'],
-  },
 ];
 
 /** Map for O(1) lookup by key. */