@volter/threejs-runtime 0.5.65

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

@@ -0,0 +1,260 @@
+import * as THREE from 'three';
+import { getUserData } from '../ecs/user-data';
+import type { ResolvedRenderSettings } from './render-settings';
+import { staticBatchSignature } from './structural-signature';
+
+/**
+ * Runtime STATIC render-batching (the framework-level transparent perf delivery).
+ *
+ * Scans a loaded scene graph for STATIC meshes sharing geometry+material and draws
+ * each group through ONE InstancedMesh. The originals are DETACHED from the render
+ * tree (so the renderer never walks them — zero per-frame cost), but retained here
+ * as the logical handles: re-attached on teardown, and resolvable via raycast().
+ * 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, 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)
+ *   - (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(), and nothing constructs
+ *     this class. The only remaining reference is the hosted editor's
+ *     project-script module map (`editor/src/served-bundle-runtime-modules.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-
+ *     auto inference over a scene nobody declared static is what this class
+ *     would need to become, and it was rejected (issue #1503).
+ *   - build() is a one-shot scan of the scene handed to it. Entities spawned
+ *     AFTER build do not join a batch; call build() again to re-scan. Removing a batched
+ *     source leaves a stale instance until rebuild. (Static scenery is load-time stable.)
+ *   - The batch culls as ONE unit (no per-instance frustum culling yet — Tier-2).
+ */
+
+interface Group {
+  instanced: THREE.InstancedMesh;
+  sources: THREE.Mesh[]; // instanceId → source (raycast mapping + restore on teardown)
+  dynamic: boolean; // true = sources kept in the graph & re-synced each frame (movers)
+  cache?: Float32Array; // dynamic only: last-synced matrixWorld elements (16/source)
+}
+
+// Structural signature — groups meshes that are VALUE-identical, not object-identical.
+// The engine scene-loader instantiates a fresh geometry+material per entity (no dedup),
+// so keying on .uuid would never batch a real scene; a TSX/R3F world writing inline
+// `<meshStandardMaterial>` elements has exactly the same property. That key lives in
+// `render/structural-signature.ts` — ONE owner, shared with the `static-batch`
+// capability's `<Frozen>`, so the two cannot drift into disagreeing about what
+// "the same draw" means. `staticBatchSignature` is this file's original key, moved.
+const SIG = staticBatchSignature;
+
+/** Match Three.js renderer visibility: a hidden ancestor hides the whole subtree. */
+function isEffectivelyVisible(obj: THREE.Object3D): boolean {
+  let cur: THREE.Object3D | null = obj;
+  while (cur) {
+    if (!cur.visible) return false;
+    cur = cur.parent;
+  }
+  return true;
+}
+
+function isBatchCandidate(object: THREE.Object3D, batchRoot: THREE.Group): object is THREE.Mesh {
+  const mesh = object as THREE.Mesh;
+  if (!mesh.isMesh) return false;
+  if ((mesh as THREE.InstancedMesh).isInstancedMesh) return false;
+  if ((mesh as THREE.SkinnedMesh).isSkinnedMesh) return false;
+  if ((mesh as unknown as THREE.BatchedMesh).isBatchedMesh) return false;
+  if (!isEffectivelyVisible(mesh)) return false;
+  if (!mesh.geometry || !mesh.material || Array.isArray(mesh.material)) return false;
+  if ((mesh.material as THREE.Material).transparent) return false;
+  return batchRoot !== mesh.parent;
+}
+
+/**
+ * Static-batching eligibility: only objects that won't move are safe to freeze
+ * and instance. An object (or an ancestor) carrying its own animation mixer is
+ * a likely mover → left as an ordinary draw. Plain scenery is eligible. This is
+ * the safe, transparent default; a future dynamic-batch path (markMoved-driven)
+ * can include movers.
+ */
+function isLikelyStatic(obj: THREE.Object3D): boolean {
+  let cur: THREE.Object3D | null = obj;
+  while (cur) {
+    if (getUserData(cur, '_animMixer')) return false;
+    cur = cur.parent;
+  }
+  return true;
+}
+
+export class RenderBatchSystem {
+  private root = new THREE.Group();
+  private groups: Group[] = [];
+  private dynamicGroups: Group[] = []; // subset needing per-frame sync
+  // Original parent of each detached (static) source, to re-attach on teardown.
+  private parentOf = new WeakMap<THREE.Mesh, THREE.Object3D>();
+  // instanceId mapping for raycast: which group + slot an InstancedMesh belongs to.
+  private membersOf = new WeakMap<THREE.InstancedMesh, THREE.Mesh[]>();
+
+  constructor(
+    private scene: THREE.Scene,
+    private settings: ResolvedRenderSettings,
+  ) {
+    this.root.name = 'RenderBatchSystem';
+    this.root.matrixAutoUpdate = false; // instances carry world matrices directly
+  }
+
+  /** Scan the scene and build instanced groups. Idempotent (rebuilds). */
+  build(): void {
+    this.teardown();
+    this.scene.add(this.root);
+    this.scene.updateMatrixWorld(true);
+
+    // collect eligible candidates, grouped by (geometry, material)
+    const buckets = new Map<string, THREE.Mesh[]>();
+    this.scene.traverse((obj) => {
+      if (!isBatchCandidate(obj, this.root)) return;
+      const key = SIG(obj);
+      const arr = buckets.get(key) ?? [];
+      arr.push(obj);
+      buckets.set(key, arr);
+    });
+
+    // Each signature bucket is partitioned into STATIC (detached, zero-cost) and
+    // DYNAMIC (kept in-place, dirty-synced) members, each ≥2 forming its own batch.
+    for (const bucket of buckets.values()) {
+      const staticMembers: THREE.Mesh[] = [];
+      const dynamicMembers: THREE.Mesh[] = [];
+      for (const m of bucket) (isLikelyStatic(m) ? staticMembers : dynamicMembers).push(m);
+      if (staticMembers.length >= 2) this.makeGroup(staticMembers, false);
+      if (dynamicMembers.length >= 2) this.makeGroup(dynamicMembers, true);
+    }
+  }
+
+  private makeGroup(sources: THREE.Mesh[], dynamic: boolean): void {
+    const frustum = this.settings['frustumCulling'] !== false;
+    const tmp = new THREE.Matrix4();
+    const proto = sources[0]!;
+    const inst = new THREE.InstancedMesh(
+      proto.geometry,
+      proto.material as THREE.Material,
+      sources.length,
+    );
+    inst.frustumCulled = frustum && !dynamic; // moving batches can leave the padded sphere
+    // Inherit shadow flags from the prototype so batched objects still cast/receive
+    // shadows (otherwise detaching the sources would silently drop them from shadows).
+    inst.castShadow = proto.castShadow;
+    inst.receiveShadow = proto.receiveShadow;
+    const cache = dynamic ? new Float32Array(sources.length * 16) : undefined;
+    for (let i = 0; i < sources.length; i++) {
+      const s = sources[i]!;
+      tmp.copy(s.matrixWorld);
+      inst.setMatrixAt(i, tmp);
+      if (dynamic) {
+        // keep the source in the graph (physics/animation still updates its matrixWorld),
+        // just hide its own draw; we copy its world matrix into the instance each frame.
+        cache!.set(tmp.elements, i * 16);
+        s.visible = false;
+      } else if (s.parent) {
+        // static: detach entirely so the renderer never walks it (zero per-frame cost)
+        this.parentOf.set(s, s.parent);
+        s.parent.remove(s);
+      }
+    }
+    inst.instanceMatrix.needsUpdate = true;
+    if (frustum && !dynamic) inst.computeBoundingSphere();
+    this.membersOf.set(inst, sources);
+    this.root.add(inst);
+    const group: Group = cache
+      ? { instanced: inst, sources, dynamic, cache }
+      : { instanced: inst, sources, dynamic };
+    this.groups.push(group);
+    if (dynamic) this.dynamicGroups.push(group);
+  }
+
+  /**
+   * Per-frame sync for DYNAMIC groups only (static are detached & immutable → free).
+   * Called in the preRender phase. Refreshes world matrices once (the engine's movers
+   * set matrixWorldNeedsUpdate via physics/animation), then re-writes only the instances
+   * whose source moved (element-wise cache compare). No-op when there are no movers.
+   */
+  update(): void {
+    if (this.dynamicGroups.length === 0) return;
+    this.scene.updateMatrixWorld(false); // refresh moved subtrees (force=false → cheap)
+    for (const g of this.dynamicGroups) {
+      const cache = g.cache!;
+      let dirty = false;
+      for (let i = 0; i < g.sources.length; i++) {
+        const el = g.sources[i]!.matrixWorld.elements;
+        const off = i * 16;
+        let changed = false;
+        for (let k = 0; k < 16; k++) {
+          if (el[k] !== cache[off + k]) {
+            changed = true;
+            break;
+          }
+        }
+        if (!changed) continue;
+        g.instanced.setMatrixAt(i, g.sources[i]!.matrixWorld);
+        cache.set(el, off);
+        dirty = true;
+      }
+      if (dirty) g.instanced.instanceMatrix.needsUpdate = true;
+    }
+  }
+
+  /**
+   * Raycast against the batched instances, mapping a hit back to the logical source
+   * Object3D (so editor/gameplay picking still resolves a detached entity).
+   */
+  raycast(raycaster: THREE.Raycaster): THREE.Mesh | null {
+    const hits = raycaster.intersectObject(this.root, true);
+    for (const h of hits) {
+      const members = this.membersOf.get(h.object as THREE.InstancedMesh);
+      if (members && h.instanceId != null) return members[h.instanceId] ?? null;
+    }
+    return null;
+  }
+
+  /** Number of draw calls the batcher contributes (1 per group). */
+  get drawCalls(): number {
+    return this.groups.length;
+  }
+
+  /** How many source meshes were collapsed into instances. */
+  get batchedCount(): number {
+    return this.groups.reduce((n, g) => n + g.sources.length, 0);
+  }
+
+  teardown(): void {
+    for (const g of this.groups) {
+      for (const s of g.sources) {
+        if (g.dynamic)
+          s.visible = true; // dynamic sources stayed in-graph, hidden
+        else {
+          const parent = this.parentOf.get(s); // static sources were detached — re-attach
+          if (parent) parent.add(s);
+        }
+      }
+      g.instanced.dispose();
+      this.root.remove(g.instanced);
+    }
+    this.groups = [];
+    this.dynamicGroups = [];
+    if (this.root.parent) this.root.parent.remove(this.root);
+  }
+}

package/src/render/render-features.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+
+/**
+ * The render-feature registry — single source of truth for every togglable render
+ * 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;
+
+export interface RenderFeature {
+  /** Stable key used in schema, cascade, and UI. */
+  key: string;
+  /** Editor display label. */
+  label: string;
+  /** Schema `.describe()` text (powers JSON Schema / inspector docs). */
+  description: string;
+  /** Control shape. */
+  kind: 'toggle' | 'number' | 'enum';
+  /** Engine default — the "fast by default" baseline. */
+  default: RenderFeatureValue;
+  /**
+   * `live` re-applies on change; `reload` needs a renderer re-init (e.g. backend,
+   * antialias). The editor badges `reload` features and re-inits the viewport.
+   */
+  apply: 'live' | 'reload';
+  /** Whether this feature may be overridden per-entity (the entity cascade layer). */
+  perEntity: boolean;
+  /** Allowed values for `enum` kind. */
+  options?: readonly string[];
+  /** [min, max] for `number` kind. */
+  range?: readonly [number, number];
+}
+
+export const RENDER_FEATURES: readonly RenderFeature[] = [
+  {
+    key: 'frustumCulling',
+    label: 'Frustum culling',
+    description: 'Per-instance frustum culling for batched content.',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: true,
+  },
+  {
+    key: 'shadows',
+    label: 'Shadows',
+    description: 'Enable the shadow map. Per-entity cast/receive still applies.',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: true,
+  },
+  {
+    key: 'postProcessing',
+    label: 'Post-processing',
+    description:
+      'Master switch for the post-processing stack (individual effects nest beneath it).',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: false,
+  },
+  {
+    key: 'resolutionScale',
+    label: 'Resolution scale',
+    description: 'Device-pixel-ratio multiplier (1.0 = native). The cheapest perf dial.',
+    kind: 'number',
+    default: 1,
+    apply: 'live',
+    perEntity: false,
+    range: [0.25, 2],
+  },
+  {
+    key: 'antialias',
+    label: 'Antialiasing',
+    description: 'MSAA via renderer construction. Applies on reload (renderer re-init).',
+    kind: 'toggle',
+    default: true,
+    apply: 'reload',
+    perEntity: false,
+  },
+];
+
+/** Map for O(1) lookup by key. */
+export const RENDER_FEATURE_BY_KEY: ReadonlyMap<string, RenderFeature> = new Map(
+  RENDER_FEATURES.map((f) => [f.key, f]),
+);
+
+/**
+ * Build a Zod object for the render settings, derived from the registry so the
+ * schema can never drift from the feature list. All fields optional — absence
+ * means "inherit" in the cascade. `perEntityOnly` builds the per-entity override
+ * schema (only features whose `perEntity` is true).
+ */
+export function buildRenderingZod(opts: { perEntityOnly?: boolean } = {}): z.ZodTypeAny {
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const f of RENDER_FEATURES) {
+    if (opts.perEntityOnly && !f.perEntity) continue;
+    let base: z.ZodTypeAny;
+    if (f.kind === 'toggle') base = z.boolean();
+    else if (f.kind === 'number') base = z.number();
+    else base = z.enum(f.options as [string, ...string[]]);
+    shape[f.key] = base.optional().describe(f.description);
+  }
+  return z
+    .object(shape)
+    .describe(
+      opts.perEntityOnly
+        ? 'Per-entity render overrides (omit a field to inherit from the scene/engine default)'
+        : 'Scene render settings (omit a field to inherit the engine default)',
+    );
+}

package/src/render/render-settings.ts

@@ -0,0 +1,71 @@
+import { RENDER_FEATURES, type RenderFeatureValue } from './render-features';
+
+/**
+ * Cascade resolution for render settings: engine default → scene → entity, with
+ * tri-state inherit (an absent value inherits from the next level up)..
+ */
+
+/** A partial override map (scene-level or entity-level). Absent key = inherit. */
+export type RenderScope = Partial<Record<string, RenderFeatureValue>>;
+
+/** Fully-resolved settings: every registry key present. */
+export type ResolvedRenderSettings = Record<string, RenderFeatureValue>;
+
+/**
+ * Resolve effective settings. `entity` overrides only apply to features whose
+ * `perEntity` flag is set; non-per-entity features resolve across engine→scene
+ * only. `??` walks up the chain on `undefined` (inherit) but lets an explicit
+ * `false`/`0` override (they are not nullish).
+ */
+export function resolveRenderSettings(
+  scene?: RenderScope,
+  entity?: RenderScope,
+): ResolvedRenderSettings {
+  const out: ResolvedRenderSettings = {};
+  for (const f of RENDER_FEATURES) {
+    const entityVal = f.perEntity ? entity?.[f.key] : undefined;
+    out[f.key] = entityVal ?? scene?.[f.key] ?? f.default;
+  }
+  return out;
+}
+
+/**
+ * A small observable holding the live scene-level resolved settings. Live
+ * features re-apply when a value changes (subscribers are notified with the
+ * changed key). This is the seam a future player-facing graphics menu would
+ * drive — for now it backs the editor toggles + the runtime systems.
+ */
+export class RenderSettings {
+  private values: ResolvedRenderSettings;
+  private listeners = new Set<(key: string, value: RenderFeatureValue) => void>();
+
+  constructor(scene?: RenderScope) {
+    this.values = resolveRenderSettings(scene);
+  }
+
+  get(key: string): RenderFeatureValue {
+    return this.values[key]!;
+  }
+
+  /** Set a scene-level value; notifies subscribers if it changed. */
+  set(key: string, value: RenderFeatureValue): void {
+    if (this.values[key] === value) return;
+    this.values[key] = value;
+    for (const fn of this.listeners) fn(key, value);
+  }
+
+  /** Resolve the effective value for an entity (entity override → scene → default). */
+  forEntity(key: string, entity?: RenderScope): RenderFeatureValue {
+    const f = entity?.[key];
+    return f ?? this.values[key]!;
+  }
+
+  subscribe(fn: (key: string, value: RenderFeatureValue) => void): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  snapshot(): ResolvedRenderSettings {
+    return { ...this.values };
+  }
+}