@vgai/engine 0.2.0

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

@@ -0,0 +1,299 @@
+import { z } from 'zod';
+import { type SceneEntity, SceneEntitySchema } from './entity';
+import { SceneEnvironmentSchema } from './environment';
+import { UIRootSchema } from './ui';
+
+export const SceneFileSchema = z
+  .object({
+    version: z.number().describe('Scene file format version'),
+    name: z.string().describe('Scene display name'),
+    environment: SceneEnvironmentSchema.optional().describe('Scene-level environment settings'),
+    entities: z.array(SceneEntitySchema).describe('Top-level entities in the scene'),
+    // UI roots (HUD/menus) attached to the scene graph as data. Optional and
+    // additive — pre-UI scenes (no `ui` field) load unchanged (A4 versioning).
+    ui: z
+      .array(UIRootSchema)
+      .optional()
+      .describe('React UI roots (canvases) attached to the scene graph (A1)'),
+  })
+  .describe('Scene file (.vscn.json)');
+
+export type SceneFile = z.infer<typeof SceneFileSchema>;
+
+export const PrefabFileSchema = z
+  .object({
+    version: z.number().describe('Prefab file format version'),
+    name: z.string().describe('Prefab display name'),
+    root: SceneEntitySchema.describe('Root entity of the prefab'),
+  })
+  .describe('Prefab file (.prefab.json)');
+
+export type PrefabFile = z.infer<typeof PrefabFileSchema>;
+
+/**
+ * Shallow-merge a section, but deep-merge specific named nested sub-objects
+ * within it (e.g. `physics.collider`, `material.clearcoat`). A partial
+ * instance override of a nested sub-object would otherwise wholesale-replace
+ * it and drop the prefab's other fields in that sub-object (e.g. an instance
+ * overriding one collider field would silently lose the prefab's `type`).
+ */
+function mergeSectionDeepNested<T extends Record<string, unknown>>(
+  prefabSection: T | undefined,
+  instanceSection: T | undefined,
+  nestedKeys: readonly (keyof T)[],
+): T | undefined {
+  if (instanceSection === undefined) return prefabSection;
+  if (prefabSection === undefined) return instanceSection;
+  const merged: Record<string, unknown> = { ...prefabSection, ...instanceSection };
+  for (const key of nestedKeys) {
+    const p = prefabSection[key];
+    const i = instanceSection[key];
+    if (
+      i !== undefined &&
+      p !== undefined &&
+      typeof i === 'object' &&
+      typeof p === 'object' &&
+      !Array.isArray(i) &&
+      !Array.isArray(p)
+    ) {
+      merged[key as string] = { ...(p as object), ...(i as object) };
+    }
+  }
+  return merged as T;
+}
+
+/**
+ * Sections whose nested sub-object needs deep merging (T1.10) — see the
+ * `mergePrefabInstance` docstring for the reasoning behind each.
+ */
+const DEEP_NESTED_SECTIONS = [
+  { key: 'physics', nestedKeys: ['collider'] },
+  { key: 'material', nestedKeys: ['clearcoat', 'transmission', 'sheen', 'iridescence'] },
+  { key: 'shadow', nestedKeys: ['camera'] },
+] as const;
+
+/**
+ * Re-validate a merged entity through `SceneEntitySchema` (T1.10). This is
+ * the gate that catches a prefab's inline `material` combined with an
+ * instance's `materialRef` (or vice versa) — each half is individually valid,
+ * so only the MERGED entity can trip the material/materialRef
+ * mutual-exclusion refine. Throws naming the offending prefab path + instance
+ * so a bad scene file points straight at the offender.
+ */
+function validateMergedEntity(merged: SceneEntity, instance: SceneEntity): SceneEntity {
+  const validated = SceneEntitySchema.safeParse(merged);
+  if (validated.success) return validated.data;
+  const issues = validated.error.issues.map((issue) => issue.message).join('; ');
+  const prefabPath = instance.prefab ?? '<unknown prefab>';
+  throw new Error(
+    `Prefab merge produced an invalid entity — prefab "${prefabPath}", instance "${instance.name}": ${issues}`,
+  );
+}
+
+/**
+ * Merge a prefab root definition with an instance's overrides.
+ *
+ * Per-field merge rules (exactly as implemented below):
+ *
+ * - transform: instance wins entirely if set, else the prefab root's transform
+ *   (placement is per-instance; transforms are not blended field-by-field).
+ * - name: instance always wins.
+ * - id: instance wins if set (each instance has its own id); else prefab's.
+ * - prefab: stripped from the result so spawnEntity recursion terminates.
+ *
+ * - Sections — `mesh`, `light`, `camera`, `animation`, `audio`, `particles`,
+ *   `spline`, `render`: SHALLOW merge per section. If the instance sets the
+ *   section, its top-level fields override the prefab root's same-named
+ *   fields ({ ...prefabSection, ...instanceSection }); fields the instance
+ *   omits fall through to the prefab. Nested objects are replaced, not
+ *   deep-merged. If only the prefab has the section it is kept as-is.
+ *   (CB4: `spline` is included here; CB5: see metadata below; T1.10: `render`
+ *   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
+ *   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
+ *   authors may legitimately want fully replaced; discriminated unions can't
+ *   be safely field-merged across different variants). Left as wholesale
+ *   per-section replace; flagged here rather than silently "fixed" with a
+ *   guess. Revisit if this causes real authoring pain.
+ *
+ * - `material`: shallow merge at the top level, PLUS deep-merge of the four
+ *   nested physical-material feature groups (`clearcoat`, `transmission`,
+ *   `sheen`, `iridescence`) so an instance overriding e.g. `clearcoat.clearcoat`
+ *   preserves the prefab's `clearcoat.clearcoatRoughness` (T1.10 — previously
+ *   these nested groups were wholesale-replaced like any other shallow field).
+ *
+ * - `physics`: shallow merge at the top level (`bodyType`, `mass`), PLUS
+ *   deep-merge of the nested `collider` object so a partial instance collider
+ *   override (e.g. just `isSensor`) preserves the prefab's `type` and other
+ *   collider fields instead of dropping them (T1.10 AC).
+ *
+ * - `shadow`: shallow merge at the top level, PLUS deep-merge of the nested
+ *   `camera` (shadow-camera frustum bounds) object, for the same reason as
+ *   `physics.collider` (T1.10 audit — same defect, same fix).
+ *
+ * - components: DEEP merge, keyed by component name. The union of component
+ *   names is taken; for each, instance fields override prefab fields
+ *   ({ ...prefabComp, ...instanceComp }).
+ *
+ * - joints: REPLACE — if the instance sets joints, its array wins wholesale
+ *   (arrays are not field-mergeable); else the prefab's joints are kept.
+ * - children: APPEND — prefab children first, then instance-only children.
+ *
+ * - Instance-level metadata `visible`, `materialRef`, `tags`, `locked`,
+ *   `navigation`, `pivot`: instance wins if explicitly set, otherwise the
+ *   prefab root's value is inherited. (CB5: spline + these metadata fields are
+ *   now instance-wins; previously dropped.)
+ *
+ * - Re-validation (T1.10): the merged entity is re-parsed through
+ *   `SceneEntitySchema` before being returned. This is what makes the
+ *   material/materialRef mutual-exclusion refine fire on the MERGED result —
+ *   previously a prefab's inline `material` plus an instance's `materialRef`
+ *   (or vice versa) silently combined into an entity carrying both, bypassing
+ *   the refine entirely (it only ever saw the pre-merge, individually-valid
+ *   halves). A merge that produces an invalid entity now throws, naming the
+ *   offending prefab path + instance name.
+ */
+export function mergePrefabInstance(prefabRoot: SceneEntity, instance: SceneEntity): SceneEntity {
+  const merged: SceneEntity = {
+    ...prefabRoot,
+    name: instance.name,
+  };
+
+  // Handle optional fields explicitly to satisfy exactOptionalPropertyTypes
+  const resolvedTransform = instance.transform ?? prefabRoot.transform;
+  if (resolvedTransform) merged.transform = resolvedTransform;
+  if (instance.id) merged.id = instance.id;
+
+  // Strip prefab field so spawnEntity won't recurse infinitely
+  delete merged.prefab;
+
+  applyInstanceMetadata(merged, prefabRoot, instance);
+  applyDeepNestedSections(merged, prefabRoot, instance);
+  applyShallowSections(merged, prefabRoot, instance);
+
+  const components = mergeComponents(prefabRoot, instance);
+  if (components !== undefined) merged.components = components;
+
+  // Joints: instance wins (array, not shallow-mergeable)
+  if (instance.joints !== undefined) {
+    merged.joints = instance.joints;
+  }
+
+  const children = mergeChildren(prefabRoot, instance);
+  if (children !== undefined) merged.children = children;
+
+  // Re-validate the merged result (T1.10) — see `validateMergedEntity` above.
+  return validateMergedEntity(merged, instance);
+}
+
+/**
+ * Visibility + instance-level metadata (`materialRef`, `tags`, `locked`,
+ * `navigation`, `pivot`): instance wins if explicitly set, otherwise the
+ * prefab root's value (already present on `merged` via the initial spread in
+ * `mergePrefabInstance`) is kept.
+ */
+function applyInstanceMetadata(
+  merged: SceneEntity,
+  prefabRoot: SceneEntity,
+  instance: SceneEntity,
+): void {
+  if (instance.visible !== undefined) merged.visible = instance.visible;
+  if (instance.materialRef !== undefined) merged.materialRef = instance.materialRef;
+  if (instance.tags !== undefined) merged.tags = instance.tags;
+  if (instance.locked !== undefined) merged.locked = instance.locked;
+  if (instance.navigation !== undefined) merged.navigation = instance.navigation;
+
+  if (instance.pivot !== undefined) {
+    merged.pivot = instance.pivot;
+  } else if (prefabRoot.pivot !== undefined) {
+    merged.pivot = prefabRoot.pivot;
+  }
+}
+
+/**
+ * Sections whose nested sub-object needs deep (not shallow) merging — see the
+ * `mergePrefabInstance` docstring for the reasoning behind each.
+ */
+function applyDeepNestedSections(
+  merged: SceneEntity,
+  prefabRoot: SceneEntity,
+  instance: SceneEntity,
+): void {
+  for (const { key, nestedKeys } of DEEP_NESTED_SECTIONS) {
+    const result = mergeSectionDeepNested(
+      // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+      (prefabRoot as any)[key],
+      // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+      (instance as any)[key],
+      nestedKeys,
+    );
+    // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+    if (result !== undefined) (merged as any)[key] = result;
+  }
+}
+
+/** Sections shallow-merged whole (material/physics/shadow handled separately above). */
+const SHALLOW_SECTIONS = [
+  'mesh',
+  'light',
+  'camera',
+  'animation',
+  'audio',
+  'particles',
+  'spline',
+  'render',
+] as const;
+
+/**
+ * Shallow merge per remaining section — instance fields override within the
+ * section ({ ...prefabSection, ...instanceSection }); if only the prefab has
+ * the section it is kept as-is.
+ */
+function applyShallowSections(
+  merged: SceneEntity,
+  prefabRoot: SceneEntity,
+  instance: SceneEntity,
+): void {
+  for (const key of SHALLOW_SECTIONS) {
+    if (instance[key] === undefined) continue;
+    // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+    (merged as any)[key] =
+      prefabRoot[key] !== undefined
+        ? // biome-ignore lint/suspicious/noExplicitAny: TS can't correlate indexed access across a union of keys
+          { ...(prefabRoot as any)[key], ...(instance as any)[key] }
+        : instance[key];
+  }
+}
+
+/** Deep merge `components`, keyed by component name (instance fields win per-component). */
+function mergeComponents(
+  prefabRoot: SceneEntity,
+  instance: SceneEntity,
+):
+  | Record<string, Record<string, number | string | boolean | number[] | string[] | boolean[]>>
+  | undefined {
+  if (!instance.components && !prefabRoot.components) return undefined;
+  const base = prefabRoot.components ?? {};
+  const over = instance.components ?? {};
+  const result: Record<
+    string,
+    Record<string, number | string | boolean | number[] | string[] | boolean[]>
+  > = {};
+  for (const comp of new Set([...Object.keys(base), ...Object.keys(over)])) {
+    result[comp] = { ...base[comp], ...over[comp] };
+  }
+  return result;
+}
+
+/** Children: prefab children first, then instance-only children appended. */
+function mergeChildren(prefabRoot: SceneEntity, instance: SceneEntity): SceneEntity[] | undefined {
+  const prefabChildren = prefabRoot.children ?? [];
+  const instanceChildren = instance.children ?? [];
+  if (prefabChildren.length === 0 && instanceChildren.length === 0) return undefined;
+  return [...prefabChildren, ...instanceChildren];
+}

package/src/scene/schema/shadow.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+export const SceneShadowSchema = z
+  .object({
+    enabled: z.boolean().describe('Whether this light casts shadows'),
+    mapSize: z.number().optional().describe('Shadow map resolution in pixels (e.g. 1024, 2048)'),
+    camera: z
+      .object({
+        left: z.number().optional().describe('Left bound of shadow camera frustum'),
+        right: z.number().optional().describe('Right bound of shadow camera frustum'),
+        top: z.number().optional().describe('Top bound of shadow camera frustum'),
+        bottom: z.number().optional().describe('Bottom bound of shadow camera frustum'),
+      })
+      .optional()
+      .describe('Shadow camera frustum bounds (directional lights)'),
+    radius: z.number().optional().describe('Shadow map blur radius for soft shadows'),
+    bias: z.number().optional().describe('Shadow bias to reduce shadow acne artifacts'),
+  })
+  .describe('Shadow casting configuration');
+
+/** Partial schema for prefab instance overrides (enabled not required). */
+export const SceneShadowOverrideSchema = SceneShadowSchema.partial();
+
+export type SceneShadow = z.infer<typeof SceneShadowSchema>;

package/src/scene/schema/spline.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { Vec3Schema } from './tuples';
+
+export const SceneSplineSchema = z.object({
+  curveType: z
+    .enum(['centripetal', 'chordal', 'catmullrom'])
+    .describe('CatmullRomCurve3 parameterization type. Matches Three.js curveType parameter'),
+  points: z.array(Vec3Schema).min(2).describe('Control point positions in local space'),
+  closed: z.boolean().optional().describe('Whether the spline forms a closed loop'),
+  tension: z
+    .number()
+    .optional()
+    .describe(
+      'Curve tension (default 0.5). Only used when curveType is catmullrom; ignored for centripetal and chordal',
+    ),
+  resolution: z.number().optional().describe('Number of line segments for rendering the curve'),
+});
+
+export type SceneSpline = z.infer<typeof SceneSplineSchema>;
+
+export const SceneSplineOverrideSchema = SceneSplineSchema.partial();

package/src/scene/schema/tuples.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const Vec3Schema = z
+  .tuple([z.number(), z.number(), z.number()])
+  .describe('3D vector as [x, y, z]');
+export const QuatSchema = z
+  .tuple([z.number(), z.number(), z.number(), z.number()])
+  .describe('Quaternion as [x, y, z, w]');
+
+export type Vec3 = z.infer<typeof Vec3Schema>;
+export type Quat = z.infer<typeof QuatSchema>;
+
+export const TransformSchema = z
+  .object({
+    position: Vec3Schema.optional().describe('World-space position [x, y, z]'),
+    rotation: QuatSchema.optional().describe('Rotation quaternion [x, y, z, w]'),
+    scale: Vec3Schema.optional().describe('Scale factor per axis [x, y, z]. Defaults to [1, 1, 1]'),
+  })
+  .describe('Local transform relative to parent entity');
+
+export type SceneTransform = z.infer<typeof TransformSchema>;