@vgai/engine 0.2.0

package/src/scene/scene-query.ts

@@ -0,0 +1,63 @@
+import type * as THREE from 'three';
+import { getUserData } from './user-data';
+
+/**
+ * Runtime queries over a loaded THREE scene graph (P1.6d).
+ *
+ * The scene's `tags` schema field is documented as "for runtime queries" but,
+ * until now, no query existed. These helpers walk a THREE.Object3D graph and
+ * read entity metadata off `userData`, so gameplay code can find objects by tag,
+ * name, or attached component without bookkeeping its own indexes.
+ *
+ * Canonical metadata locations (in priority order):
+ *   - tags:       `userData['tags']` (string[])     — falls back to `userData['entity'].tags`
+ *   - name:       `Object3D.name`
+ *   - components: `userData['components']` (record or string[]) — falls back to
+ *                 `userData['entity'].components` (record keyed by component name)
+ */
+
+function getTags(obj: THREE.Object3D): string[] {
+  const direct = getUserData(obj, 'tags');
+  if (Array.isArray(direct)) return direct;
+  const fromDef = getUserData(obj, 'entity')?.tags;
+  return Array.isArray(fromDef) ? fromDef : [];
+}
+
+function getComponentNames(obj: THREE.Object3D): string[] {
+  const direct = getUserData(obj, 'components');
+  if (Array.isArray(direct)) return direct;
+  if (direct && typeof direct === 'object') return Object.keys(direct);
+  const fromDef = getUserData(obj, 'entity')?.components;
+  if (fromDef && typeof fromDef === 'object') return Object.keys(fromDef);
+  return [];
+}
+
+/** All objects in the graph carrying the given tag (depth-first, document order). */
+export function queryByTag(root: THREE.Object3D, tag: string): THREE.Object3D[] {
+  const matches: THREE.Object3D[] = [];
+  root.traverse((obj) => {
+    if (getTags(obj).includes(tag)) matches.push(obj);
+  });
+  return matches;
+}
+
+/** All objects in the graph with the given name (depth-first, document order). */
+export function queryByName(root: THREE.Object3D, name: string): THREE.Object3D[] {
+  const matches: THREE.Object3D[] = [];
+  root.traverse((obj) => {
+    if (obj.name === name) matches.push(obj);
+  });
+  return matches;
+}
+
+/**
+ * All objects in the graph that have the named component attached
+ * (depth-first, document order).
+ */
+export function queryByComponent(root: THREE.Object3D, componentName: string): THREE.Object3D[] {
+  const matches: THREE.Object3D[] = [];
+  root.traverse((obj) => {
+    if (getComponentNames(obj).includes(componentName)) matches.push(obj);
+  });
+  return matches;
+}

package/src/scene/scene-types.ts

@@ -0,0 +1,34 @@
+/**
+ * Scene file types — derived from Zod schemas (single source of truth).
+ *
+ * Raw types for the .vscn.json file format. Both the editor and the runtime
+ * loader work with these directly, applying DEFAULTS (./defaults.ts) for omitted
+ * fields — DEFAULTS is the single source of truth for default values.
+ */
+
+export type {
+  InstancesFile,
+  MaterialFile,
+  PrefabFile,
+  SceneAnimation,
+  SceneAudio,
+  SceneCamera,
+  SceneCollider,
+  SceneEntity,
+  SceneEnvironment,
+  SceneFile,
+  SceneJoint,
+  SceneLight,
+  SceneMaterial,
+  SceneMesh,
+  SceneNavigation,
+  SceneParticles,
+  ScenePhysics,
+  ScenePhysicsSettings,
+  ScenePostProcessing,
+  SceneSpline,
+  SceneToneMapping,
+  UIRoot,
+} from './schema';
+
+export { mergePrefabInstance } from './schema';

package/src/scene/scene-version.ts

@@ -0,0 +1,40 @@
+/**
+ * The scene/prefab file format `version` range this engine checkout can
+ * load (T2.3/D3 §1.E, docs/ENGINE-UPGRADE-DESIGN.md). `[min, max]` — today
+ * `[1, 1]`: every shipped `.vscn.json`/`.prefab.json` is version 1, and no
+ * migration machinery exists yet (a future format bump widens `max`, and a
+ * future engine that drops support for `1` would raise `min`).
+ *
+ * Deliberately NOT in `./schema/` (that directory's byte contents are
+ * pinned by `packages/engine/schemas/engine-capabilities.json`'s
+ * `schemaDirHash`, refreshed only by `scripts/capabilities-hash.ts` — this
+ * slice does not run that script). This is also why the check below is a
+ * POST-Zod-parse function here in `scene/`, not a Zod refinement inside
+ * `SceneFileSchema`/`PrefabFileSchema`: the generated `vscn.schema.json`/
+ * `prefab.schema.json` stay byte-identical (the `version` field itself is
+ * still just `z.number()`).
+ */
+export const SUPPORTED_SCENE_VERSION_RANGE: readonly [number, number] = [1, 1];
+
+/**
+ * Throw if `version` falls outside `SUPPORTED_SCENE_VERSION_RANGE`; silently
+ * accept in-range versions. `fileKind` only changes the error message's noun
+ * (`.vscn.json` and `.prefab.json` share this single version axis — verified
+ * both schemas declare their own `version: z.number()` field, not a shared
+ * ref, but the same counter/semantics per docs/ENGINE-UPGRADE-DESIGN.md).
+ */
+export function checkSceneVersionInRange(
+  version: number,
+  fileKind: 'scene' | 'prefab' = 'scene',
+): void {
+  const [min, max] = SUPPORTED_SCENE_VERSION_RANGE;
+  if (version >= min && version <= max) return;
+  const cause =
+    version > max
+      ? `the engine checkout is older than this ${fileKind}`
+      : `this ${fileKind} predates the oldest supported format version`;
+  throw new Error(
+    `${fileKind} version ${version} is outside the supported range [${min}, ${max}] — ` +
+      `${cause}; see docs/ENGINE-UPGRADE-DESIGN.md`,
+  );
+}

package/src/scene/schema/animation.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+// Reuse the UI track easing vocabulary (S1) so there is ONE easing enum across
+// the codebase — see F5 (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Do NOT reuse
+// UIKeyframeSchema itself: its `value` is `z.union([z.number(), z.string()])`,
+// and property-track values MUST be numbers only (no expression/string-logic
+// values — in-scene scripting is banned, G1).
+import { UIEasingSchema } from './ui';
+
+/** Validated at runtime against AnimGraph parameter definitions. */
+const AnimParameterOverridesSchema = z.record(z.string(), z.union([z.number(), z.boolean()]));
+
+// ---------------------------------------------------------------------------
+// F5 — Declarative property tracks (deterministic timeline).
+//
+// A track is DATA: a pure function of time (keyframes + named easing), never
+// behavior. `target` is a FIXED allowlist, not an arbitrary property path —
+// this is the guardrail that keeps the format from becoming an in-scene
+// scripting surface (G1, docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Anything
+// state-dependent ("move WHEN the player steps on it") stays a GameComponent,
+// which may start/stop/seek a track — it never grows conditionals here.
+// ---------------------------------------------------------------------------
+
+export const PropertyTrackTargetSchema = z
+  .enum([
+    'position.x',
+    'position.y',
+    'position.z',
+    'rotation.x',
+    'rotation.y',
+    'rotation.z',
+    'scale.x',
+    'scale.y',
+    'scale.z',
+    'material.opacity',
+    'light.intensity',
+  ])
+  .describe(
+    'The Object3D property this track drives. A FIXED allowlist, not an arbitrary property ' +
+      'path — an open path would let scene data address/mutate arbitrary runtime state, which ' +
+      'is in-scene scripting (banned, G1). Add new targets here deliberately, one at a time.',
+  );
+export type PropertyTrackTarget = z.infer<typeof PropertyTrackTargetSchema>;
+
+export const PropertyTrackKeyframeSchema = z
+  .object({
+    time: z.number().describe('Seconds from track start'),
+    value: z
+      .number()
+      .describe(
+        'Numeric value at this time — numbers only; no expressions/strings (in-scene scripting is banned)',
+      ),
+    easing: UIEasingSchema.optional().describe(
+      'Easing of the segment after this keyframe (reuses the UI track easing vocabulary)',
+    ),
+  })
+  .describe('A single keyframe (time + numeric value + optional easing) on a property track');
+export type PropertyTrackKeyframe = z.infer<typeof PropertyTrackKeyframeSchema>;
+
+export const PropertyTrackSchema = z
+  .object({
+    target: PropertyTrackTargetSchema,
+    keyframes: z.array(PropertyTrackKeyframeSchema).describe('Ordered by time'),
+    loop: z.boolean().optional().describe('Whether the track repeats after reaching `duration`'),
+    duration: z.number().describe('Track length in seconds'),
+  })
+  .describe('A deterministic keyframed timeline driving one allowlisted property');
+export type PropertyTrack = z.infer<typeof PropertyTrackSchema>;
+
+export const SceneAnimationSchema = z
+  .object({
+    animGraph: z.string().optional().describe('Path to .animgraph.json state machine file'),
+    parameters: AnimParameterOverridesSchema.optional().describe(
+      'Initial parameter values for the animation graph',
+    ),
+    autoplay: z
+      .string()
+      .optional()
+      .describe('Clip name to play automatically on load (when no animGraph is set)'),
+    loop: z.boolean().optional().describe('Whether the autoplay clip should loop'),
+    clipAliases: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe('Map raw GLTF clip names to clean names used by the animation graph'),
+    tracks: z
+      .array(PropertyTrackSchema)
+      .optional()
+      .describe(
+        'Deterministic keyframed property timelines (data, not behavior — pure function of ' +
+          'time; state-dependent motion stays a GameComponent). Runs in the animation phase, ' +
+          'honors pause/timeScale.',
+      ),
+  })
+  .describe('Animation playback configuration');
+
+export type SceneAnimation = z.infer<typeof SceneAnimationSchema>;

package/src/scene/schema/audio.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+export const SceneAudioSchema = z
+  .object({
+    src: z.string().optional().describe('Path to audio file (WAV, MP3, OGG)'),
+    spatial: z.boolean().optional().describe('Enable 3D spatial audio (positional sound)'),
+    volume: z.number().optional().describe('Playback volume 0–1'),
+    refDistance: z
+      .number()
+      .optional()
+      .describe('Distance at which volume starts to attenuate (spatial only)'),
+    rolloffFactor: z
+      .number()
+      .optional()
+      .describe('How quickly volume attenuates with distance (spatial only)'),
+    maxDistance: z
+      .number()
+      .optional()
+      .describe('Maximum distance at which sound is audible (spatial only)'),
+    loop: z.boolean().optional().describe('Whether the audio should loop'),
+    autoplay: z.boolean().optional().describe('Start playing automatically when the scene loads'),
+  })
+  .describe('Audio source configuration');
+
+export type SceneAudio = z.infer<typeof SceneAudioSchema>;

package/src/scene/schema/camera.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const SceneCameraSchema = z
+  .object({
+    type: z.enum(['perspective', 'orthographic']).describe('Camera projection type'),
+    fov: z.number().optional().describe('Vertical field of view in degrees (perspective only)'),
+    near: z.number().optional().describe('Near clipping plane distance'),
+    far: z.number().optional().describe('Far clipping plane distance'),
+    orthoSize: z
+      .number()
+      .optional()
+      .describe('Half-height of the orthographic frustum (orthographic only)'),
+    width: z.number().optional().describe('Render width in pixels. Defaults to viewport width'),
+    height: z.number().optional().describe('Render height in pixels. Defaults to viewport height'),
+  })
+  .describe('Camera configuration');
+
+/** Partial schema for prefab instance overrides (type not required). */
+export const SceneCameraOverrideSchema = SceneCameraSchema.partial();
+
+export type SceneCamera = z.infer<typeof SceneCameraSchema>;

package/src/scene/schema/collider.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { Vec3Schema } from './tuples';
+
+export const SceneColliderSchema = z
+  .object({
+    type: z
+      .enum(['cuboid', 'ball', 'capsule', 'trimesh'])
+      .describe(
+        "Collider shape type. T1.2: every shape scales with the entity's composed world scale " +
+          "(self × ancestors) — for trimesh this means the entity's own mesh geometry vertices " +
+          'are pre-scaled per-axis before building the Rapier trimesh, so it matches whatever ' +
+          "size ends up on screen; it does not require the collider's own dimension fields.",
+      ),
+    halfExtents: Vec3Schema.optional().describe(
+      "Half-size [x, y, z] for cuboid colliders, in the ENTITY'S OWN LOCAL units. T1.2: " +
+        "scales with the entity — the actual Rapier collider is this value times the entity's " +
+        'composed world scale (self × every transformed ancestor), per axis, baked in once at ' +
+        "load time (Rapier has no live notion of an Object3D's scale).",
+    ),
+    radius: z
+      .number()
+      .optional()
+      .describe(
+        "Radius for ball and capsule colliders, in the ENTITY'S OWN LOCAL units. T1.2: scales " +
+          "with the entity's composed world scale, which MUST be uniform on the collider's round " +
+          'axes (ball: all of x/y/z; capsule: x and z) — a non-uniform scale there throws a loud ' +
+          'load error (Rapier balls/capsules cannot represent an ellipse).',
+      ),
+    halfHeight: z
+      .number()
+      .optional()
+      .describe(
+        "Half-height for capsule colliders, in the entity's own local units, along the capsule's " +
+          "axis (Y). T1.2: scales by the entity's composed world scale on that axis.",
+      ),
+    friction: z.number().optional().describe('Surface friction coefficient'),
+    restitution: z
+      .number()
+      .optional()
+      .describe('Bounciness coefficient (0 = no bounce, 1 = perfect bounce)'),
+    density: z
+      .number()
+      .optional()
+      .describe('Mass density. Used to compute mass from collider volume'),
+    offset: Vec3Schema.optional().describe(
+      "Translation offset relative to body origin, in the ENTITY'S OWN LOCAL units. T1.2/R1c: " +
+        "scales with the entity's composed world scale (self × every transformed ancestor), " +
+        'per axis, the same way halfExtents/radius/halfHeight do — an unscaled offset would ' +
+        "silently drift away from the entity's visual anchor point under any non-1 scale.",
+    ),
+    isSensor: z
+      .boolean()
+      .optional()
+      .describe('When true, detects overlaps without physical blocking (trigger volume)'),
+    collisionGroups: z
+      .number()
+      .optional()
+      .describe('Bitmask: collision layers this collider belongs to (max 16 bits)'),
+    collisionFilter: z
+      .number()
+      .optional()
+      .describe('Bitmask: collision layers this collider interacts with (max 16 bits)'),
+  })
+  .describe('Physics collider shape and properties');
+
+/** Partial schema for prefab instance overrides (type not required). */
+export const SceneColliderOverrideSchema = SceneColliderSchema.partial();
+
+export type SceneCollider = z.infer<typeof SceneColliderSchema>;

package/src/scene/schema/entity-ref.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+
+/**
+ * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) — a first-class, reusable
+ * reference from one entity to another, for a `GameComponent`'s own static
+ * Zod schema (e.g. `target: EntityRefSchema` — "this button opens THAT
+ * door"). A branded string: on disk (and through generic component-data
+ * validation) it is a plain string id, but a component field typed
+ * `EntityRef` is compile-time distinct from an arbitrary `string` field, so a
+ * bare label can't be assigned where a ref is expected.
+ *
+ * Resolution is a runtime concern, not a schema one: `scene-loader.ts`'s
+ * `resolveEntityRefs` (the post-spawn pass, modeled on `joint.target`'s
+ * existing resolution) rewrites the field from the authored string id to the
+ * live `THREE.Object3D` — through the SAME `idMap` `createSceneJoints`
+ * already uses, no new registry (G3) — before the referencing component's
+ * `init()` runs.
+ */
+export const EntityRefSchema = z
+  .string()
+  .brand<'EntityRef'>()
+  .describe(
+    'A reference to another entity by its authored id. On disk it is a plain string id; the ' +
+      'scene loader resolves it to the live THREE.Object3D (WorldNode-as-truth) before the ' +
+      "referencing component's init() runs. A ref to a missing id is a loud load error.",
+  );
+
+export type EntityRef = z.infer<typeof EntityRefSchema>;
+
+/**
+ * Identity registry of the `EntityRefSchema` object (there is exactly one —
+ * this module's export), used by {@link isEntityRefSchema}.
+ *
+ * Why identity rather than a Zod "type name" check: zod 4's `.brand()` is a
+ * type-only cast (see zod's own source — `inst.brand = () => inst`), not a
+ * distinct wrapper class runtime code could switch on. A branded schema is,
+ * at runtime, just the underlying `ZodString` (here, after `.describe()`
+ * clones it once more — see zod's `check()`/`clone()`). So "is this an
+ * EntityRef field" can only be answered by reference identity against the
+ * one schema object every ref field is declared with — which is exactly
+ * what we want anyway: a look-alike `z.string()` field must NOT count.
+ */
+const ENTITY_REF_SCHEMAS = new WeakSet<object>();
+ENTITY_REF_SCHEMAS.add(EntityRefSchema);
+
+/**
+ * Just enough of zod 4's internal `_def` shape to unwrap wrapper schemas.
+ * Typed against `z.core.$ZodType` (the base/"core" schema type, NOT the
+ * fuller "classic" `z.ZodType`) because that's what a `z.ZodObject`'s
+ * `.shape` values are typed as (`ZodRawShape = core.$ZodShape`) — the type
+ * every field schema `resolveEntityRefs` (`scene-loader.ts`) actually walks
+ * arrives as.
+ */
+interface UnwrappableDef {
+  innerType?: z.core.$ZodType;
+}
+
+/**
+ * Is `schema` an {@link EntityRefSchema} field — including when wrapped by
+ * `.optional()`, `.default(...)`, or `.nullable()` (the common ways a
+ * component author would declare an optional ref)? Unwraps those via zod 4's
+ * internal `_def.innerType` (there is no public reflection API for this —
+ * `packages/editor/src/components/inspectors/zod-fields.ts` uses the same
+ * mechanism to introspect component schemas for the inspector) down to the
+ * core schema, then checks it against the registered `EntityRefSchema`
+ * instance by reference.
+ */
+export function isEntityRefSchema(schema: z.core.$ZodType): boolean {
+  let cur: z.core.$ZodType | undefined = schema;
+  while (cur) {
+    if (ENTITY_REF_SCHEMAS.has(cur)) return true;
+    const inner: z.core.$ZodType | undefined = (cur as unknown as { _def?: UnwrappableDef })._def
+      ?.innerType;
+    if (!inner) return false;
+    cur = inner;
+  }
+  return false;
+}

package/src/scene/schema/entity.ts

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import { buildRenderingZod } from '../../render/render-features';
+import { SceneAnimationSchema } from './animation';
+import { SceneAudioSchema } from './audio';
+import { SceneCameraOverrideSchema, SceneCameraSchema } from './camera';
+import { SceneJointSchema } from './joint';
+import { SceneLightOverrideSchema, SceneLightSchema } from './light';
+import { SceneMaterialOverrideSchema, SceneMaterialSchema } from './material';
+import { SceneMeshOverrideSchema, SceneMeshSchema } from './mesh';
+import { SceneParticlesOverrideSchema, SceneParticlesSchema } from './particles';
+import { ScenePhysicsOverrideSchema, ScenePhysicsSchema } from './physics';
+import { SceneShadowOverrideSchema, SceneShadowSchema } from './shadow';
+import { SceneSplineOverrideSchema, SceneSplineSchema } from './spline';
+import { TransformSchema, Vec3Schema } from './tuples';
+
+/**
+ * User-defined ECS component data. Validated at runtime against ComponentRegistry.
+ *
+ * Scalars (number/string/boolean) plus homogeneous arrays of those scalars so
+ * that vec3 (number[3]) and other array fields produced by the schema-driven
+ * inspector round-trip through parse/validate. The component's own static Zod
+ * schema (GameComponent.schema) does the precise per-field validation at load.
+ *
+ * F6 (`docs/VSCN-STRUCTURAL-GAPS-DESIGN.md`) entity refs (`EntityRefSchema`,
+ * `./entity-ref.ts`) are branded strings — structurally still a `string` on
+ * disk and through this coarse, per-component-agnostic schema, so they
+ * already parse via the `z.string()` branch below without a dedicated union
+ * member. (Deliberately not added as an explicit branch: this record's VALUE
+ * schema is the one place in the file with no `.describe()` calls anywhere in
+ * it — see `schema-consumption-map.ts`'s `entity.components` entry — and
+ * `EntityRefSchema` carries one, which would flip `entity.components` from a
+ * plain leaf into a `subtree: true` entry for no behavioral gain: the
+ * precise, per-field validation of a ref — and the brand — comes from the
+ * referencing component's OWN static schema in `applyComponents`, not from
+ * this generic envelope.)
+ */
+const ComponentScalarSchema = z.union([z.number(), z.string(), z.boolean()]);
+const ComponentValueSchema = z.union([
+  ComponentScalarSchema,
+  z.array(z.number()),
+  z.array(z.string()),
+  z.array(z.boolean()),
+]);
+const ComponentDataSchema = z.record(z.string(), ComponentValueSchema);
+const ComponentsSchema = z.record(z.string(), ComponentDataSchema);
+
+const NavigationRoleSchema = z
+  .object({
+    role: z
+      .enum(['walkable', 'obstacle'])
+      .describe('Whether this entity is walkable surface or an obstacle'),
+  })
+  .describe('Navigation mesh role');
+
+// Fields shared by both standalone and prefab instance entities
+const SharedEntityFields = {
+  id: z.string().optional().describe('Unique entity ID. Auto-generated if omitted'),
+  name: z.string().describe('Human-readable entity name (shown in hierarchy panel)'),
+  visible: z.boolean().optional().describe('Whether the entity and its children are rendered'),
+  locked: z.boolean().optional().describe('Prevent selection and editing in the scene editor'),
+  tags: z.array(z.string()).optional().describe('Arbitrary string tags for runtime queries'),
+  prefab: z.string().optional().describe('Path to .prefab.json file to instantiate'),
+  materialRef: z
+    .string()
+    .optional()
+    .describe('Path to shared .mat.json material asset. Mutually exclusive with inline material'),
+  transform: TransformSchema.optional().describe('Local transform relative to parent'),
+  pivot: Vec3Schema.optional().describe(
+    'Local-space pivot point for rotation/scale. [0,0,0] = geometry center',
+  ),
+  navigation: NavigationRoleSchema.optional().describe('Navigation mesh role for this entity'),
+  render: buildRenderingZod({ perEntityOnly: true })
+    .optional()
+    .describe(
+      'Per-entity render overrides (e.g. autoBatch:false to keep a custom-shader entity out of batching). Omit to inherit from the scene/engine default.',
+    ),
+  components: ComponentsSchema.optional().describe(
+    'User-defined ECS component data (validated against component registry)',
+  ),
+};
+
+// Standalone entities: full section validation (type fields required)
+const StandaloneEntityBase = z.object({
+  ...SharedEntityFields,
+  mesh: SceneMeshSchema.optional().describe('Mesh geometry'),
+  material: SceneMaterialSchema.optional().describe('Material appearance'),
+  light: SceneLightSchema.optional().describe('Light source'),
+  shadow: SceneShadowSchema.optional().describe('Shadow configuration'),
+  physics: ScenePhysicsSchema.optional().describe('Physics rigid body'),
+  camera: SceneCameraSchema.optional().describe('Camera'),
+  audio: SceneAudioSchema.optional().describe('Audio source'),
+  animation: SceneAnimationSchema.optional().describe('Animation configuration'),
+  particles: SceneParticlesSchema.optional().describe('Particle system'),
+  spline: SceneSplineSchema.optional().describe('Spline path'),
+  joints: z
+    .array(SceneJointSchema)
+    .optional()
+    .describe('Physics joints connecting to other bodies'),
+});
+
+// Prefab instance entities: section overrides are partial (merged with prefab root at load time)
+const PrefabInstanceBase = z.object({
+  ...SharedEntityFields,
+  prefab: z.string().describe('Path to .prefab.json file to instantiate'),
+  mesh: SceneMeshOverrideSchema.optional().describe('Mesh overrides merged with prefab'),
+  material: SceneMaterialOverrideSchema.optional().describe(
+    'Material overrides merged with prefab',
+  ),
+  light: SceneLightOverrideSchema.optional().describe('Light overrides merged with prefab'),
+  shadow: SceneShadowOverrideSchema.optional().describe('Shadow overrides merged with prefab'),
+  physics: ScenePhysicsOverrideSchema.optional().describe('Physics overrides merged with prefab'),
+  camera: SceneCameraOverrideSchema.optional().describe('Camera overrides merged with prefab'),
+  audio: SceneAudioSchema.optional().describe('Audio source'),
+  animation: SceneAnimationSchema.optional().describe('Animation configuration'),
+  particles: SceneParticlesOverrideSchema.optional().describe(
+    'Particle overrides merged with prefab',
+  ),
+  spline: SceneSplineOverrideSchema.optional().describe('Spline overrides merged with prefab'),
+  joints: z
+    .array(SceneJointSchema)
+    .optional()
+    .describe('Physics joints connecting to other bodies'),
+});
+
+/**
+ * SceneEntity type — the strict form used by all consumer code.
+ * Section types have required discriminant fields (type, bodyType, etc.).
+ *
+ * Prefab instances in scene files may have partial sections, but they are
+ * always completed by mergePrefabInstance() before being consumed.
+ */
+export type SceneEntity = z.infer<typeof StandaloneEntityBase> & {
+  children?: SceneEntity[] | undefined;
+};
+
+/**
+ * Validation schema for scene entity JSON.
+ *
+ * Standalone entities are validated strictly (section discriminants required).
+ * Prefab instances accept partial section overrides — these are merged with
+ * the prefab root at load time via mergePrefabInstance().
+ *
+ * Typed as SceneEntity (strict) because prefab instances always go through
+ * mergePrefabInstance() before any code reads their section data.
+ */
+export const SceneEntitySchema: z.ZodType<SceneEntity> = z.lazy(() =>
+  z
+    .union([
+      StandaloneEntityBase.extend({
+        children: z.array(SceneEntitySchema).optional().describe('Child entities'),
+      }),
+      PrefabInstanceBase.extend({
+        children: z.array(SceneEntitySchema).optional().describe('Child entities'),
+      }),
+    ])
+    // P1.6a: `material` (inline) and `materialRef` (shared .mat.json asset) are
+    // mutually exclusive — allowing both lets one silently win at load time.
+    // Reject up front instead of trapping the author.
+    .superRefine((entity, ctx) => {
+      if (entity.material !== undefined && entity.materialRef !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'An entity cannot set both `material` (inline) and `materialRef` (shared .mat.json asset). Choose one.',
+          path: ['material'],
+        });
+      }
+    }),
+) as z.ZodType<SceneEntity>;