@volter/game-editor 0.5.65

package/catalog/project-source/src/lib/static-batch/mutation-watch.ts

@@ -0,0 +1,149 @@
+/**
+ * THE TRIPWIRE for the one rule `<Frozen>` cannot enforce: its children must
+ * be MOUNT-STATIC.
+ *
+ * A freeze draws the batched products and hides the originals. React still
+ * owns those originals, so nothing stops a game from moving one, re-colouring
+ * it, or un-hiding it — and nothing HAPPENS when it does. The mesh is
+ * invisible; the picture comes from the product; the edit is simply lost. That
+ * is the worst possible failure shape: silent, and indistinguishable from the
+ * mechanic being wrong. An author who animates a door under a `<Frozen>` will
+ * spend an afternoon in the wrong file.
+ *
+ * The contract used to live in a docblock. A docblock describes intent; only a
+ * measurement describes status. So the hidden originals are SAMPLED — the
+ * cheapest reading that catches all three drifts:
+ *   - `matrixWorld`, hashed: it moved, was scaled, or was re-parented;
+ *   - `material.version`, which three bumps on `needsUpdate`: it was re-styled;
+ *   - `visible`, restored to `true` by the game: it thinks it is showing.
+ *
+ * ── COST, AND WHY IT IS A TIMER ─────────────────────────────────────────────
+ * ~1 Hz, and only under {@link devBuildEnabled}. A per-frame check would be a
+ * real cost added by a feature whose entire job is removing cost; a `Proxy` or
+ * accessor trap over every node would change the objects the game is holding.
+ * A second of latency on a diagnostic nobody is waiting for is free, and 4,000
+ * hashes once a second is a rounding error against one frame of the draw calls
+ * this replaced.
+ *
+ * It fires ONCE. The first drift is the finding; a mechanic that runs every
+ * frame would otherwise fill the console with the same line, and the watch
+ * stops itself rather than becoming the noise it exists to prevent.
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * OWNER: the handle {@link watchFrozenMutations} returns, which owns exactly
+ * one interval. SHARERS: none — `Frozen.tsx` holds it and nothing else sees
+ * it. TEARDOWN: that handle's `stop()`, the ONE path that clears the interval,
+ * called from the wrapper's own effect cleanup and by the watch itself after
+ * it warns. Idempotent.
+ */
+
+import { devBuildEnabled } from '@volter/game-runtime/runtime/dev-build';
+import type * as THREE from 'three';
+import type { FrozenBatch } from './freeze';
+
+/** Samples per second. See the module note for why this is a timer at all. */
+export const MUTATION_SAMPLE_MS = 1000;
+
+interface Sample {
+  matrix: number;
+  materialVersions: string;
+  visible: boolean;
+}
+
+/** A cheap order-sensitive fold of the 16 world-matrix elements. Collisions
+ *  are possible in principle and irrelevant in practice: this compares a value
+ *  against ITS OWN previous value, not against another node's. */
+function hashMatrix(mesh: THREE.Object3D): number {
+  const elements = mesh.matrixWorld.elements;
+  let hash = 0;
+  for (let i = 0; i < 16; i++) hash = (hash * 31 + (elements[i] ?? 0)) % 1e12;
+  return hash;
+}
+
+function sample(mesh: THREE.Mesh): Sample {
+  const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+  return {
+    matrix: hashMatrix(mesh),
+    materialVersions: materials.map((material) => material?.version ?? -1).join(','),
+    visible: mesh.visible,
+  };
+}
+
+/** What changed, in the words of the thing that changed it. */
+function drift(before: Sample, after: Sample): string | null {
+  if (after.visible !== before.visible) return 'was made visible again';
+  if (after.matrix !== before.matrix) return 'moved (its world matrix changed)';
+  if (after.materialVersions !== before.materialVersions) return 'had its material changed';
+  return null;
+}
+
+export interface FrozenMutationWatch {
+  /** See the ownership note — the ONE path that ends the watch. Idempotent. */
+  stop(): void;
+}
+
+function warnOnConsole(message: string): void {
+  // biome-ignore lint/suspicious/noConsole: console is this tripwire's vgai-status channel.
+  console.warn(message);
+}
+
+/**
+ * Watch a freeze's hidden originals for the mutations the contract forbids,
+ * and say so once. A no-op outside a dev context, and a no-op when the freeze
+ * hid nothing.
+ */
+export function watchFrozenMutations(
+  batch: FrozenBatch,
+  options: {
+    /** Injectable so the tripwire is provable without a console. */
+    readonly warn?: (message: string) => void;
+    /** Injectable so a test can step time instead of waiting a second. */
+    readonly schedule?: (tick: () => void) => () => void;
+    /** Overrides the dev gate — a headless test passes `true`. */
+    readonly dev?: boolean;
+  } = {},
+): FrozenMutationWatch {
+  const warn = options.warn ?? warnOnConsole;
+  if (!devBuildEnabled(options.dev) || batch.sources.length === 0) {
+    return { stop: () => {} };
+  }
+
+  const baseline = batch.sources.map((source) => sample(source.mesh));
+  let stopped = false;
+  let release: (() => void) | null = null;
+
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    release?.();
+    release = null;
+  };
+
+  const tick = (): void => {
+    if (stopped) return;
+    for (let i = 0; i < batch.sources.length; i++) {
+      const source = batch.sources[i];
+      const before = baseline[i];
+      if (!source || !before) continue;
+      const change = drift(before, sample(source.mesh));
+      if (!change) continue;
+      const node = source.mesh.name || '(unnamed)';
+      warn(
+        `[static-batch] "${node}" ${change} while frozen under <Frozen name="${batch.name}"> — ` +
+          'the change will never be visible, because the picture comes from the batched copy ' +
+          'and the original is hidden. Everything under a <Frozen> must be mount-static: move ' +
+          'this node OUT of the wrapper, or mark its subtree userData={{ staticBatch: false }}.',
+      );
+      stop();
+      return;
+    }
+  };
+
+  if (options.schedule) {
+    release = options.schedule(tick);
+  } else {
+    const timer = setInterval(tick, MUTATION_SAMPLE_MS);
+    release = () => clearInterval(timer);
+  }
+  return { stop };
+}

package/catalog/project-source/src/lib/static-batch/shadow-cache.ts

@@ -0,0 +1,171 @@
+/** Reuse directional shadow maps only while every caster is declared mount-static. */
+
+import type * as THREE from 'three';
+import { activeFrozenBatches, type FrozenBatch } from './freeze';
+
+export interface FrozenDirectionalShadowController {
+  update(): void;
+  dispose(): void;
+}
+
+function belongsTo(node: THREE.Object3D, ancestor: THREE.Object3D): boolean {
+  for (let cursor: THREE.Object3D | null = node; cursor !== null; cursor = cursor.parent) {
+    if (cursor === ancestor) return true;
+  }
+  return false;
+}
+
+function matrixChanged(
+  node: THREE.Object3D,
+  snapshots: Map<THREE.Object3D, THREE.Matrix4>,
+): boolean {
+  node.updateWorldMatrix(true, false);
+  const previous = snapshots.get(node);
+  if (previous?.equals(node.matrixWorld)) return false;
+  if (previous === undefined) snapshots.set(node, node.matrixWorld.clone());
+  else previous.copy(node.matrixWorld);
+  return true;
+}
+
+function projectionChanged(
+  camera: THREE.Camera,
+  snapshots: Map<THREE.Camera, THREE.Matrix4>,
+): boolean {
+  const projectable = camera as THREE.Camera & { updateProjectionMatrix?: () => void };
+  projectable.updateProjectionMatrix?.();
+  const previous = snapshots.get(camera);
+  if (previous?.equals(camera.projectionMatrix)) return false;
+  if (previous === undefined) snapshots.set(camera, camera.projectionMatrix.clone());
+  else previous.copy(camera.projectionMatrix);
+  return true;
+}
+
+function collectDirectionalShadowLights(
+  root: THREE.Object3D,
+  lights: Set<THREE.DirectionalLight>,
+): void {
+  root.traverseVisible((node) => {
+    const light = node as THREE.DirectionalLight;
+    if (light.isDirectionalLight && light.castShadow) lights.add(light);
+  });
+}
+
+function inspectOutsideFrozen(
+  node: THREE.Object3D,
+  frozenRoots: ReadonlySet<THREE.Object3D>,
+  lights: Set<THREE.DirectionalLight>,
+): boolean {
+  if (!node.visible || frozenRoots.has(node)) return false;
+  const light = node as THREE.DirectionalLight;
+  if (light.isDirectionalLight && light.castShadow) lights.add(light);
+  let caster = (node as THREE.Mesh).isMesh === true && (node as THREE.Mesh).castShadow;
+  for (const child of node.children) {
+    caster = inspectOutsideFrozen(child, frozenRoots, lights) || caster;
+  }
+  return caster;
+}
+
+function sceneBatches(scene: THREE.Object3D): readonly FrozenBatch[] {
+  return activeFrozenBatches().filter((batch) => belongsTo(batch.root, scene));
+}
+
+interface ShadowControllerState {
+  readonly objectMatrices: Map<THREE.Object3D, THREE.Matrix4>;
+  readonly cameraProjections: Map<THREE.Camera, THREE.Matrix4>;
+  readonly controlledLights: Set<THREE.DirectionalLight>;
+  readonly frozenLights: Set<THREE.DirectionalLight>;
+  previousBatches: Set<FrozenBatch>;
+  hadOutsideCaster: boolean;
+}
+
+function batchesChanged(batches: readonly FrozenBatch[], previous: ReadonlySet<FrozenBatch>) {
+  return batches.length !== previous.size || batches.some((batch) => !previous.has(batch));
+}
+
+function updateLight(
+  light: THREE.DirectionalLight,
+  external: boolean,
+  staticInputChanged: boolean,
+  state: ShadowControllerState,
+): void {
+  state.controlledLights.add(light);
+  if (external) {
+    light.shadow.autoUpdate = true;
+    light.shadow.needsUpdate = true;
+    return;
+  }
+  // Snapshot every input on the first invalidation. A short-circuit expression here would
+  // discover one previously unseen input per frame and redraw the same initial map four times.
+  const lightMoved = matrixChanged(light, state.objectMatrices);
+  const targetMoved = matrixChanged(light.target, state.objectMatrices);
+  const projectionMoved = projectionChanged(light.shadow.camera, state.cameraProjections);
+  light.shadow.autoUpdate = false;
+  if (staticInputChanged || lightMoved || targetMoved || projectionMoved) {
+    light.shadow.needsUpdate = true;
+  }
+}
+
+function updateController(scene: THREE.Object3D, state: ShadowControllerState): void {
+  const batches = sceneBatches(scene);
+  const roots = new Set(batches.map((batch) => batch.root));
+  const batchSetChanged = batchesChanged(batches, state.previousBatches);
+  state.previousBatches = new Set(batches);
+
+  if (batchSetChanged) {
+    state.frozenLights.clear();
+    for (const root of roots) collectDirectionalShadowLights(root, state.frozenLights);
+  }
+  const nextLights = new Set(state.frozenLights);
+  const outsideCaster = inspectOutsideFrozen(scene, roots, nextLights);
+  const external = batches.length === 0 || outsideCaster;
+  let staticInputChanged = batchSetChanged || external !== state.hadOutsideCaster;
+  state.hadOutsideCaster = external;
+  for (const root of roots) {
+    staticInputChanged = matrixChanged(root, state.objectMatrices) || staticInputChanged;
+  }
+  for (const light of nextLights) updateLight(light, external, staticInputChanged, state);
+
+  for (const light of state.controlledLights) {
+    if (nextLights.has(light)) continue;
+    light.shadow.autoUpdate = true;
+    light.shadow.needsUpdate = true;
+    state.controlledLights.delete(light);
+  }
+}
+
+/**
+ * Three redraws every directional shadow map every frame by default. A mounted `Frozen` subtree
+ * promises that its descendants do not change, so a scene whose ENTIRE caster set is covered by
+ * those declarations can reuse its depth map until a wrapper, light, target, or shadow camera
+ * changes. A caster anywhere outside a Frozen root immediately restores Three's ordinary
+ * per-frame path; reactive content is never guessed to be static.
+ */
+export function createFrozenDirectionalShadowController(
+  scene: THREE.Object3D,
+): FrozenDirectionalShadowController {
+  const state: ShadowControllerState = {
+    objectMatrices: new Map(),
+    cameraProjections: new Map(),
+    controlledLights: new Set(),
+    frozenLights: new Set(),
+    previousBatches: new Set(),
+    hadOutsideCaster: true,
+  };
+
+  return {
+    update(): void {
+      updateController(scene, state);
+    },
+    dispose(): void {
+      for (const light of state.controlledLights) {
+        light.shadow.autoUpdate = true;
+        light.shadow.needsUpdate = true;
+      }
+      state.controlledLights.clear();
+      state.frozenLights.clear();
+      state.objectMatrices.clear();
+      state.cameraProjections.clear();
+      state.previousBatches.clear();
+    },
+  };
+}

package/catalog/project-source/src/tools/bake-module.tool.ts

@@ -0,0 +1,139 @@
+import { defineTool } from '@volter/editor-sdk/tools/registry';
+import { z } from 'zod';
+import {
+  assertRenderableGeometry,
+  buildFromModule,
+  computeMeshStats,
+  EMPTY_GEOMETRY_ERROR,
+  EXPORT_NOT_CALLABLE_ERROR,
+  MODULE_NOT_FOUND_ERROR,
+  NOT_AN_OBJECT3D_ERROR,
+  PATH_ESCAPES_PROJECT_ERROR,
+} from '../contributions/module-source';
+import { bakeObject3DSource } from '../lib/bake/object3d-bake';
+import { disposeObject3D } from '../lib/bake/object3d-lifecycle';
+
+// The module-loading step and its typed errors live in `module-source.ts`
+// so `project.bake.preview` refuses an identical module for an identical reason.
+export {
+  EMPTY_GEOMETRY_ERROR,
+  EXPORT_NOT_CALLABLE_ERROR,
+  MODULE_NOT_FOUND_ERROR,
+  NOT_AN_OBJECT3D_ERROR,
+  PATH_ESCAPES_PROJECT_ERROR,
+};
+
+export const BlenderBuildInputSchema = z.object({
+  modulePath: z
+    .string()
+    .min(1)
+    .describe(
+      'Project-relative (or absolute, inside the project) path to a TypeScript module that ' +
+        'exports a builder function returning a native THREE.Object3D — typically assembled with ' +
+        'the blender kit (`lib/mesh`).',
+    ),
+  exportName: z
+    .string()
+    .min(1)
+    .default('default')
+    .describe("Name of the module export to call. Defaults to the module's default export."),
+  name: z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-_]{0,63}$/)
+    .describe('Stable lowercase asset name used for the generated GLB file.'),
+  dryRun: z
+    .boolean()
+    .default(false)
+    .describe('Build and validate the module output without writing project files.'),
+});
+
+const OutputFileSchema = z.object({
+  path: z.string(),
+  bytes: z.number(),
+  mediaType: z.string().optional(),
+  role: z.enum(['asset', 'provenance', 'other']).optional(),
+});
+
+export const BlenderBuildResultSchema = z.object({
+  model: z.string(),
+  provenanceOperationId: z.string().optional(),
+  vertexCount: z.number(),
+  triangleCount: z.number(),
+  meshCount: z.number(),
+  skinnedMeshCount: z.number(),
+  boneCount: z.number(),
+  animatedNodeCount: z.number(),
+  clips: z.array(z.string()),
+  files: z.array(OutputFileSchema),
+  totalBytes: z.number(),
+  dryRun: z.boolean(),
+});
+
+export const tool = defineTool({
+  name: 'project.bake.module',
+  summary: 'Bake a project-authored Object3D module into a GLB asset.',
+  description:
+    'Dynamically imports a project TypeScript module (a project module reference: `modulePath` + ' +
+    '`exportName`), calls its exported builder to get a native THREE.Object3D — typically assembled ' +
+    'with the blender kit (`lib/mesh`) — validates the geometry, and atomically writes an ' +
+    'ordinary model. This is the agent/MCP-callable front door onto any project-owned ' +
+    'Three.js source builder, mirroring the turntable tool’s `--module`/`--export` mechanism.',
+  input: BlenderBuildInputSchema,
+  result: BlenderBuildResultSchema,
+  errors: [
+    MODULE_NOT_FOUND_ERROR,
+    EXPORT_NOT_CALLABLE_ERROR,
+    NOT_AN_OBJECT3D_ERROR,
+    EMPTY_GEOMETRY_ERROR,
+    PATH_ESCAPES_PROJECT_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  longRunning: true,
+  permission: {
+    risk: 'write',
+    summary: 'Writes a generated GLB under public/ unless dryRun is set.',
+  },
+  async impl(input, ctx) {
+    const projectRoot = ctx.projectRoot;
+    if (!projectRoot) throw new Error('project.bake.module requires a project root.');
+    const build = await buildFromModule(
+      projectRoot,
+      input.modulePath,
+      input.exportName,
+      ctx.loadProjectModule,
+    );
+    const root = build.root;
+    const stats = computeMeshStats(root);
+    assertRenderableGeometry(stats, input.modulePath, input.exportName);
+    return bakeObject3DSource({
+      ctx,
+      name: input.name,
+      dryRun: input.dryRun,
+      // `Object3D.animations` is three's OWN carrier for the clips that belong
+      // to a model — it is where `GLTFLoader` puts them, what `Object3D.copy`
+      // carries across a clone, and what `useAnimations(scene.animations)`
+      // reads. A model module that builds a rig and its actions therefore
+      // returns them the ecosystem's way, with nothing new to declare; before
+      // this line the module lane passed no animations at all and every clip a
+      // builder authored was silently dropped from the GLB. (A build-result
+      // export's separate `animations` list is written onto the root by
+      // `buildFromModule`, so this reads one carrier for both shapes.)
+      build: () => ({
+        root,
+        animations: root.animations,
+        // The BUILDER's own teardown when it returned one — a rig holds mixers
+        // and actions the generic graph walk cannot see.
+        dispose: build.dispose ?? (() => disposeObject3D(root)),
+      }),
+      validation: {
+        requireSkinned: false,
+        forbidSkinned: false,
+        minimumAnimatedNodes: 0,
+      },
+      inspectSource: () => stats,
+    });
+  },
+});