@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/scene/scene-loader.ts

@@ -14,18 +14,17 @@ import {
   assetCacheSizes,
   clearAssetCaches as clearSharedAssetCaches,
   loadGLTF,
+  loadSplat,
   resolveGltfNode,
 } from './asset-loaders';
 import { applyImportCorrection, getAssetMeta, loadRegistry } from './asset-registry';
 import { computeColliderWorldDimensions, computeColliderWorldOffset } from './collider-dimensions';
 import { applyComponents, type ComponentRegistry } from './component-registry';
 import { DEFAULTS } from './defaults';
-import './geometries';
-import './instancers';
-import { buildInstancedMesh, buildInstancedMeshFromTuples } from './instance-registry';
+import { buildInstancedMeshFromTuples } from './instance-mesh';
 import { createCamera, createLight } from './light-camera-factory';
 import { createGeometry, createMaterial } from './material-factory';
-import './materials';
+import { setMeshShadowEnabled } from './mesh-shadow';
 import { parseInstancesFile, parseMaterialFile, parsePrefabFile, parseSceneFile } from './parse';
 import { createParticleSystemFromData } from './particles-factory';
 import {
@@ -78,9 +77,8 @@ export function clearAssetCaches(): void {
 /**
  * F7 — per-frame LOD tick. THREE.LOD only swaps its active level when
  * `.update(camera)` runs, so every `THREE.LOD` in the scene graph (built by
- * the `mesh.lod` spawn branch above) needs this called once a frame. Mirrors
- * `tickCustomMaterials`'s traverse-and-tick shape; wired into the runtime's
- * `preRender` system in `vgai-scene-game-adapter.ts`.
+ * the `mesh.lod` spawn branch above) needs this called once a frame. Wired
+ * into the runtime's `preRender` system in `vgai-scene-game-adapter.ts`.
  */
 export function updateSceneLODs(scene: THREE.Scene, camera: THREE.Camera): void {
   scene.traverse((o) => {
@@ -96,12 +94,14 @@ export function updateSceneLODs(scene: THREE.Scene, camera: THREE.Camera): void
 export function __assetCacheSizesForTest(): {
   textures: number;
   gltf: number;
+  splat: number;
   env: number;
 } {
   const sizes = assetCacheSizes();
   return {
     textures: sizes.textures,
     gltf: sizes.gltf,
+    splat: sizes.splat,
     env: envTextureCache.size,
   };
 }
@@ -222,6 +222,13 @@ export interface SceneInstance {
    * `instantiateScene` return site, so this is populated identically for both.
    */
   entities: ReadonlyMap<string, THREE.Object3D>;
+  /** Number of native Gaussian-splat Object3Ds owned by this scene. The render
+   *  host uses this to install exactly one SparkRenderer for the scene. */
+  splatCount: number;
+}
+
+interface DisposableSplat extends THREE.Object3D {
+  dispose(): void;
 }
 
 /**
@@ -405,6 +412,7 @@ async function instantiateScene(
 ): Promise<SceneInstance> {
   const tickFns: ((dt: number) => void)[] = [];
   const mixers: THREE.AnimationMixer[] = [];
+  const splats: DisposableSplat[] = [];
 
   // Ensure asset registry is loaded before spawning entities
   await loadRegistry();
@@ -462,7 +470,7 @@ async function instantiateScene(
   const idMap = new Map<string, THREE.Object3D>();
 
   for (const entityDef of data.entities) {
-    const obj = await spawnEntity(entityDef, ctx, tickFns, mixers, idMap);
+    const obj = await spawnEntity(entityDef, ctx, tickFns, mixers, splats, idMap);
     ctx.scene.add(obj);
   }
 
@@ -516,6 +524,7 @@ async function instantiateScene(
     cameras,
     environment: data.environment,
     entities: idMap,
+    splatCount: splats.length,
     update(dt: number) {
       for (const fn of tickFns) fn(dt);
     },
@@ -523,6 +532,8 @@ async function instantiateScene(
       for (const mixer of mixers) mixer.stopAllAction();
       tickFns.length = 0;
       mixers.length = 0;
+      for (const splat of splats) splat.dispose();
+      splats.length = 0;
     },
   };
 }
@@ -532,6 +543,7 @@ async function spawnEntity(
   ctx: SceneLoadContext,
   tickFns: ((dt: number) => void)[],
   mixers: THREE.AnimationMixer[],
+  splats: DisposableSplat[],
   idMap?: Map<string, THREE.Object3D>,
   ancestorCtx: AncestorPhysicsContext = ROOT_ANCESTOR_CONTEXT,
   audioTracker?: AudioTracker,
@@ -578,7 +590,7 @@ async function spawnEntity(
   if (def.prefab) {
     const prefabDef = await loadPrefabFile(def.prefab, ctx);
     const merged = mergePrefabInstance(prefabDef.root, def);
-    return spawnEntity(merged, ctx, tickFns, mixers, idMap, ancestorCtx, audioTracker);
+    return spawnEntity(merged, ctx, tickFns, mixers, splats, idMap, ancestorCtx, audioTracker);
   }
 
   // Transform
@@ -664,6 +676,11 @@ async function spawnEntity(
       // Apply import correction from asset registry
       applyImportCorrection(content, getAssetMeta(def.mesh.src)?.importCorrection);
 
+      // A glTF entity is a hierarchy, not one Mesh. Propagate the same
+      // authored shadow contract primitive entities already honor to every
+      // Mesh/SkinnedMesh descendant before wrapping the content.
+      setMeshShadowEnabled(content, def.shadow?.enabled);
+
       // Wrap in a group so entity transform and import correction are separated.
       // `content` carries import correction; wrapper carries entity transform.
       const wrapper = new THREE.Group();
@@ -700,6 +717,16 @@ async function spawnEntity(
           }
         }
       }
+    } else if (def.mesh.type === 'splat' && def.mesh.src) {
+      const wrapper = new THREE.Group();
+      // A headless game still needs the authored entity, transform, components,
+      // and hierarchy for bots/CI; only the visual payload is GPU-bound.
+      if (ctx.renderer) {
+        const content = await loadSplat(def.mesh.src);
+        splats.push(content);
+        wrapper.add(content);
+      }
+      object3d = wrapper;
     } else {
       const geometry = createGeometry(def.mesh);
       const resolvedMat = await resolveMaterial(def, ctx);
@@ -710,13 +737,6 @@ async function spawnEntity(
         // .instances.json and build one InstancedMesh from its tuples.
         const tuples = await loadInstancesFile(def.mesh.instances, ctx);
         mesh = buildInstancedMeshFromTuples(geometry, material, tuples);
-      } else if (def.mesh.instancer) {
-        mesh = buildInstancedMesh(
-          geometry,
-          material,
-          def.mesh.instancer,
-          def.mesh.instancerParams ?? {},
-        );
       } else {
         mesh = new THREE.Mesh(geometry, material);
       }
@@ -930,6 +950,7 @@ async function spawnEntity(
         ctx,
         tickFns,
         mixers,
+        splats,
         idMap,
         childAncestorCtx,
         audioTracker,
@@ -1391,12 +1412,14 @@ export async function spawnPrefab(
   };
   const tickFns: ((dt: number) => void)[] = [];
   const mixers: THREE.AnimationMixer[] = [];
+  const splats: DisposableSplat[] = [];
   const audioTracker: AudioTracker = { audios: [], disposed: { value: false } };
   const object3D = await spawnEntity(
     instance,
     ctx,
     tickFns,
     mixers,
+    splats,
     undefined,
     ROOT_ANCESTOR_CONTEXT,
     audioTracker,
@@ -1494,8 +1517,10 @@ export async function spawnPrefab(
 
       ctx.scene.remove(object3D);
       for (const mixer of mixers) mixer.stopAllAction();
+      for (const splat of splats) splat.dispose();
       tickFns.length = 0;
       mixers.length = 0;
+      splats.length = 0;
     },
   };
 }

package/src/scene/schema/instances.ts

@@ -3,8 +3,7 @@ import { z } from 'zod';
 /**
  * `.instances.json` — a declarative, authored-data instance-transform asset
  * (F3, docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Referenced by `mesh.instances`
- * as the data counterpart to `mesh.instancer` (a code-registered generator):
- * a bare array of 10-number tuples, one per instance, each
+ * as a bare array of 10-number tuples, one per instance, each
  * `[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ]`. The
  * scene loader fetches+parses this file and renders it as one
  * `THREE.InstancedMesh` (one draw call) — bulk transform data is referenced

package/src/scene/schema/material.ts

@@ -1,105 +1,94 @@
 import { z } from 'zod';
 
-const SceneMaterialObjectSchema = z.object({
-  type: z
-    .enum(['standard', 'physical', 'basic', 'toon', 'custom'])
-    .describe('Material shading model. "custom" resolves `def` against the material registry'),
-  def: z
-    .string()
-    .optional()
-    .describe('Registered custom-material name (required when type is "custom")'),
-  uniforms: z
-    .record(z.string(), z.union([z.number(), z.string(), z.boolean(), z.array(z.number())]))
-    .optional()
-    .describe('Authored uniform values for a custom material, keyed by uniform name'),
-  color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
-  metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
-  roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
-  map: z.string().optional().describe('Path to albedo/diffuse texture image'),
-  normalMap: z.string().optional().describe('Path to normal map texture image'),
-  emissive: z.string().optional().describe('Emissive color as CSS hex string'),
-  emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
-  emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
-  aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
-  lightMap: z
-    .string()
-    .optional()
-    .describe(
-      "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
-    ),
-  lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
-  roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
-  metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
-  opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
-  transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
-  side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
-  flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
+const SceneMaterialObjectSchema = z
+  .object({
+    type: z.enum(['standard', 'physical', 'basic', 'toon']).describe('Material shading model'),
+    color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
+    metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
+    roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
+    map: z.string().optional().describe('Path to albedo/diffuse texture image'),
+    normalMap: z.string().optional().describe('Path to normal map texture image'),
+    emissive: z.string().optional().describe('Emissive color as CSS hex string'),
+    emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
+    emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
+    aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
+    lightMap: z
+      .string()
+      .optional()
+      .describe(
+        "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
+      ),
+    lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
+    roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
+    metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
+    opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
+    transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
+    side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
+    flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
 
-  // Physical material feature groups (physical only, all optional)
-  clearcoat: z
-    .object({
-      clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
-      clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
-      clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
-      clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
-    })
-    .optional()
-    .describe('Clearcoat layer (physical only)'),
+    // Physical material feature groups (physical only, all optional)
+    clearcoat: z
+      .object({
+        clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
+        clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
+        clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
+        clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
+      })
+      .optional()
+      .describe('Clearcoat layer (physical only)'),
 
-  transmission: z
-    .object({
-      transmission: z.number().describe('Transmission intensity 0–1 (glass, liquid)'),
-      ior: z.number().optional().describe('Index of refraction (default 1.5)'),
-      thickness: z.number().optional().describe('Volume thickness for refraction'),
-      attenuationColor: z.string().optional().describe('Color absorbed over distance'),
-      attenuationDistance: z
-        .number()
-        .optional()
-        .describe('Distance at which attenuation color takes full effect'),
-      transmissionMap: z.string().optional().describe('Path to transmission map'),
-    })
-    .optional()
-    .describe('Light transmission (physical only)'),
+    transmission: z
+      .object({
+        transmission: z.number().describe('Transmission intensity 0–1 (glass, liquid)'),
+        ior: z.number().optional().describe('Index of refraction (default 1.5)'),
+        thickness: z.number().optional().describe('Volume thickness for refraction'),
+        attenuationColor: z.string().optional().describe('Color absorbed over distance'),
+        attenuationDistance: z
+          .number()
+          .optional()
+          .describe('Distance at which attenuation color takes full effect'),
+        transmissionMap: z.string().optional().describe('Path to transmission map'),
+      })
+      .optional()
+      .describe('Light transmission (physical only)'),
 
-  sheen: z
-    .object({
-      sheen: z.number().describe('Sheen intensity 0–1 (fabric, velvet)'),
-      sheenColor: z.string().optional().describe('Sheen tint color'),
-      sheenRoughness: z.number().optional().describe('Sheen roughness 0–1'),
-      sheenColorMap: z.string().optional().describe('Path to sheen color map'),
-      sheenRoughnessMap: z.string().optional().describe('Path to sheen roughness map'),
-    })
-    .optional()
-    .describe('Sheen layer (physical only)'),
+    sheen: z
+      .object({
+        sheen: z.number().describe('Sheen intensity 0–1 (fabric, velvet)'),
+        sheenColor: z.string().optional().describe('Sheen tint color'),
+        sheenRoughness: z.number().optional().describe('Sheen roughness 0–1'),
+        sheenColorMap: z.string().optional().describe('Path to sheen color map'),
+        sheenRoughnessMap: z.string().optional().describe('Path to sheen roughness map'),
+      })
+      .optional()
+      .describe('Sheen layer (physical only)'),
 
-  iridescence: z
-    .object({
-      iridescence: z.number().describe('Iridescence intensity 0–1 (soap bubbles, oil slick)'),
-      iridescenceIOR: z.number().optional().describe('Thin-film IOR (default 1.3)'),
-      iridescenceThicknessRange: z
-        .tuple([z.number(), z.number()])
-        .optional()
-        .describe('Min/max thin-film thickness in nm'),
-      iridescenceMap: z.string().optional().describe('Path to iridescence intensity map'),
-      iridescenceThicknessMap: z.string().optional().describe('Path to iridescence thickness map'),
-    })
-    .optional()
-    .describe('Iridescence thin-film (physical only)'),
+    iridescence: z
+      .object({
+        iridescence: z.number().describe('Iridescence intensity 0–1 (soap bubbles, oil slick)'),
+        iridescenceIOR: z.number().optional().describe('Thin-film IOR (default 1.3)'),
+        iridescenceThicknessRange: z
+          .tuple([z.number(), z.number()])
+          .optional()
+          .describe('Min/max thin-film thickness in nm'),
+        iridescenceMap: z.string().optional().describe('Path to iridescence intensity map'),
+        iridescenceThicknessMap: z
+          .string()
+          .optional()
+          .describe('Path to iridescence thickness map'),
+      })
+      .optional()
+      .describe('Iridescence thin-film (physical only)'),
 
-  displacementMap: z.string().optional().describe('Path to displacement/height map'),
-  displacementScale: z.number().optional().describe('Displacement height multiplier'),
-  displacementBias: z.number().optional().describe('Displacement offset'),
-});
+    displacementMap: z.string().optional().describe('Path to displacement/height map'),
+    displacementScale: z.number().optional().describe('Displacement height multiplier'),
+    displacementBias: z.number().optional().describe('Displacement offset'),
+  })
+  .strict();
 
-export const SceneMaterialSchema = SceneMaterialObjectSchema.superRefine((material, ctx) => {
-  if (material.type === 'custom' && !material.def?.trim()) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['def'],
-      message: 'Custom material requires a non-empty registered definition name',
-    });
-  }
-}).describe('Material appearance properties');
+export const SceneMaterialSchema = SceneMaterialObjectSchema.describe(
+  'Material appearance properties',
+);
 
 /** Partial schema for prefab instance overrides (type not required). */
 export const SceneMaterialOverrideSchema = SceneMaterialObjectSchema.partial();

package/src/scene/schema/mesh.ts

@@ -1,104 +1,90 @@
 import { z } from 'zod';
 
-const SceneMeshBase = z.object({
-  type: z
-    .enum(['box', 'sphere', 'plane', 'cylinder', 'capsule', 'gltf'])
-    .describe('Mesh primitive type, or "gltf" for an external 3D model'),
-  args: z
-    .array(z.number())
-    .optional()
-    .describe(
-      'Geometry constructor args — box: [w,h,d], sphere: [radius], cylinder: [rTop,rBot,h], capsule: [radius,length], plane: [w,h]',
-    ),
-  src: z.string().optional().describe('Path to GLTF/GLB model file. Required when type is "gltf"'),
-  node: z
-    .string()
-    .optional()
-    .describe(
-      'Name (or path) of a single node inside the referenced glTF (resolved via ' +
-        "getObjectByName) to instantiate as this entity's geometry, instead of the whole " +
-        'file. The geometry stays SHARED from the cached glTF — nothing is copied out. ' +
-        'Only meaningful with type: "gltf". CONSTRAINT: a skinned/animated node cannot be ' +
-        'lifted out of its armature — if the named node is a SkinnedMesh (or contains one), ' +
-        'resolving it throws (degrade loudly, not silently).',
-    ),
-  instances: z
-    .string()
-    .optional()
-    .describe(
-      'Path to an instance-transform asset (.instances.json: an array of ' +
-        '[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples). Renders one ' +
-        'THREE.InstancedMesh (one draw call). Bulk transform data is referenced as an asset, ' +
-        'never inlined — keeps vscn thin.',
-    ),
-  instancer: z
-    .string()
-    .optional()
-    .describe(
-      'Registered instancer name. When set, the mesh renders as a single THREE.InstancedMesh ' +
-        '(one draw call) with code-generated per-instance transforms instead of one THREE.Mesh',
-    ),
-  instancerParams: z
-    .record(z.string(), z.union([z.number(), z.string(), z.boolean()]))
-    .optional()
-    .describe('Params for the instancer (e.g. count, spacing), keyed by name'),
-  generator: z
-    .string()
-    .optional()
-    .describe(
-      'Registered geometry-generator name (e.g. "Terrain"). When set, the mesh geometry is ' +
-        'produced procedurally in code instead of from `type`/`args`. Pairs with a "trimesh" ' +
-        'collider for matching physics.',
-    ),
-  generatorParams: z
-    .record(z.string(), z.union([z.number(), z.string(), z.boolean()]))
-    .optional()
-    .describe('Params for the geometry generator (e.g. width, segments, amplitude)'),
-  lod: z
-    .array(
-      z.object({
-        distance: z
-          .number()
-          .describe(
-            'Camera distance in world units at/beyond which this level shows (THREE.LOD ' +
-              'threshold). Use 0 for the closest/highest-detail level.',
-          ),
-        node: z
-          .string()
-          .describe(
-            'Name of a node inside the referenced glTF (mesh.src) to show at this distance — ' +
-              'resolved via getObjectByName, geometry shared (F4-style). A skinned node throws ' +
-              '(atomic-subtree rule).',
-          ),
-      }),
-    )
-    .optional()
-    .describe(
-      'Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance ' +
-        '(THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when ' +
-        'off, only the closest level renders. Cannot combine with node/instances/instancer.',
-    ),
-});
+const SceneMeshBase = z
+  .object({
+    type: z
+      .enum(['box', 'sphere', 'plane', 'cylinder', 'capsule', 'gltf', 'splat'])
+      .describe(
+        'Renderable type: a built-in mesh primitive, "gltf" for an external 3D model, or "splat" for a native Gaussian-splat asset',
+      ),
+    args: z
+      .array(z.number())
+      .optional()
+      .describe(
+        'Geometry constructor args — box: [w,h,d], sphere: [radius], cylinder: [rTop,rBot,h], capsule: [radius,length], plane: [w,h,widthSegments,heightSegments]',
+      ),
+    src: z
+      .string()
+      .optional()
+      .describe(
+        'Path to the external render asset. Required for "gltf" (GLTF/GLB) and "splat" (SPZ)',
+      ),
+    node: z
+      .string()
+      .optional()
+      .describe(
+        'Name (or path) of a single node inside the referenced glTF (resolved via ' +
+          "getObjectByName) to instantiate as this entity's geometry, instead of the whole " +
+          'file. The geometry stays SHARED from the cached glTF — nothing is copied out. ' +
+          'Only meaningful with type: "gltf". CONSTRAINT: a skinned/animated node cannot be ' +
+          'lifted out of its armature — if the named node is a SkinnedMesh (or contains one), ' +
+          'resolving it throws (degrade loudly, not silently).',
+      ),
+    instances: z
+      .string()
+      .optional()
+      .describe(
+        'Path to an instance-transform asset (.instances.json: an array of ' +
+          '[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples). Renders one ' +
+          'THREE.InstancedMesh (one draw call). Bulk transform data is referenced as an asset, ' +
+          'never inlined — keeps vscn thin.',
+      ),
+    lod: z
+      .array(
+        z.object({
+          distance: z
+            .number()
+            .describe(
+              'Camera distance in world units at/beyond which this level shows (THREE.LOD ' +
+                'threshold). Use 0 for the closest/highest-detail level.',
+            ),
+          node: z
+            .string()
+            .describe(
+              'Name of a node inside the referenced glTF (mesh.src) to show at this distance — ' +
+                'resolved via getObjectByName, geometry shared (F4-style). A skinned node throws ' +
+                '(atomic-subtree rule).',
+            ),
+        }),
+      )
+      .optional()
+      .describe(
+        'Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance ' +
+          '(THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when ' +
+          'off, only the closest level renders. Cannot combine with node/instances.',
+      ),
+  })
+  .strict();
 
-export const SceneMeshSchema = SceneMeshBase.refine((m) => m.type !== 'gltf' || m.src != null, {
-  message: "GLTF mesh requires 'src' field",
-})
+export const SceneMeshSchema = SceneMeshBase.refine(
+  (m) => (m.type !== 'gltf' && m.type !== 'splat') || m.src != null,
+  {
+    message: "External render asset requires 'src' field",
+  },
+)
   .refine((m) => m.node == null || m.type === 'gltf', {
     message:
       "Mesh 'node' is only meaningful with type: 'gltf' (names a sub-node of the referenced glTF)",
   })
-  .refine((m) => !(m.instances && m.instancer), {
-    message:
-      "Mesh cannot set both 'instances' (authored) and 'instancer' (code-registered) — " +
-      'pick one canonical instancing source per mesh',
-  })
   .refine((m) => m.lod == null || m.type === 'gltf', {
     message: "Mesh 'lod' is only meaningful with type: 'gltf'",
   })
-  .refine((m) => !(m.lod && (m.node || m.instances || m.instancer)), {
+  .refine((m) => m.instances == null || m.type !== 'splat', {
+    message: "Mesh 'instances' is not supported with type: 'splat'",
+  })
+  .refine((m) => !(m.lod && (m.node || m.instances)), {
     message:
-      "Mesh 'lod' cannot combine with 'node'/'instances'/'instancer' — LOD is the multi-level " +
-      'form of a node ref',
+      "Mesh 'lod' cannot combine with 'node'/'instances' — LOD is the multi-level form of a node ref",
   })
   .describe('Mesh geometry definition');
 

package/src/scene/schema/scene-file.ts

@@ -105,8 +105,7 @@ function validateMergedEntity(merged: SceneEntity, instance: SceneEntity): Scene
  *   is now included — an instance's per-entity render overrides are honored
  *   and merged the same way as `mesh`/`material`.)
  *
- *   NOTE (T1.10 audit): `mesh.instancerParams`/`mesh.generatorParams` and
- *   `animation.parameters`/`animation.clipAliases` are keyed dict maps nested
+ *   NOTE (T1.10 audit): `animation.parameters`/`animation.clipAliases` are keyed dict maps nested
  *   one level down, and `particles` nests discriminated-union shapes/behaviors
  *   arrays. These have the same "shallow replace" defect as `material`/
  *   `physics` did, but no single well-defined field-merge semantics (dict keys