@vgai/engine 0.2.0

package/src/scene/schema/material.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+
+export const SceneMaterialSchema = 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'),
+
+    // 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)'),
+
+    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)'),
+
+    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'),
+  })
+  .describe('Material appearance properties');
+
+/** Partial schema for prefab instance overrides (type not required). */
+export const SceneMaterialOverrideSchema = SceneMaterialSchema.partial();
+
+export type SceneMaterial = z.infer<typeof SceneMaterialSchema>;
+
+/** .mat.json file format for shared/reusable material assets. */
+export const MaterialFileSchema = z
+  .object({
+    version: z.number().describe('File format version'),
+    name: z.string().describe('Human-readable material name'),
+    material: SceneMaterialSchema.describe('Material definition'),
+  })
+  .describe('Shared material asset file (.mat.json)');
+
+export type MaterialFile = z.infer<typeof MaterialFileSchema>;

package/src/scene/schema/mesh.ts

@@ -0,0 +1,108 @@
+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.',
+    ),
+});
+
+export const SceneMeshSchema = SceneMeshBase.refine((m) => m.type !== 'gltf' || m.src != null, {
+  message: "GLTF mesh 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)), {
+    message:
+      "Mesh 'lod' cannot combine with 'node'/'instances'/'instancer' — LOD is the multi-level " +
+      'form of a node ref',
+  })
+  .describe('Mesh geometry definition');
+
+/** Partial schema for prefab instance overrides (type not required). */
+export const SceneMeshOverrideSchema = SceneMeshBase.partial();
+
+export type SceneMesh = z.infer<typeof SceneMeshSchema>;

package/src/scene/schema/particles.ts

@@ -0,0 +1,398 @@
+import { z } from 'zod';
+import { Vec3Schema } from './tuples';
+
+// --- Value Generators (mirrors quarks.core FunctionJSON) ---
+
+const ConstantValueSchema = z.object({
+  type: z.literal('ConstantValue'),
+  value: z.number(),
+});
+
+const IntervalValueSchema = z.object({
+  type: z.literal('IntervalValue'),
+  a: z.number(),
+  b: z.number(),
+});
+
+const BezierSchema = z.object({
+  p0: z.number(),
+  p1: z.number(),
+  p2: z.number(),
+  p3: z.number(),
+});
+
+const PiecewiseBezierSchema = z.object({
+  type: z.literal('PiecewiseBezier'),
+  functions: z.array(
+    z.object({
+      function: BezierSchema,
+      start: z.number(),
+    }),
+  ),
+});
+
+export const ValueGeneratorSchema = z
+  .discriminatedUnion('type', [ConstantValueSchema, IntervalValueSchema, PiecewiseBezierSchema])
+  .describe('Numeric value: constant, random interval, or bezier curve');
+
+export type ValueGeneratorJSON = z.infer<typeof ValueGeneratorSchema>;
+
+// --- Color Generators (mirrors quarks.core ColorGenerator JSON) ---
+
+const ColorRGBA = z.object({
+  r: z.number(),
+  g: z.number(),
+  b: z.number(),
+  a: z.number(),
+});
+
+const ColorRGB = z.object({
+  r: z.number(),
+  g: z.number(),
+  b: z.number(),
+});
+
+/** ContinuousLinearFunction JSON format used by Gradient internally */
+const CLinearColorSchema = z.object({
+  type: z.literal('CLinearFunction'),
+  subType: z.literal('Color'),
+  keys: z.array(z.object({ value: ColorRGB, pos: z.number() })),
+});
+
+const CLinearNumberSchema = z.object({
+  type: z.literal('CLinearFunction'),
+  subType: z.literal('Number'),
+  keys: z.array(z.object({ value: z.number(), pos: z.number() })),
+});
+
+const ConstantColorSchema = z.object({
+  type: z.literal('ConstantColor'),
+  color: ColorRGBA,
+});
+
+const ColorRangeSchema = z.object({
+  type: z.literal('ColorRange'),
+  a: ColorRGBA,
+  b: ColorRGBA,
+});
+
+const GradientSchema = z.object({
+  type: z.literal('Gradient'),
+  color: CLinearColorSchema,
+  alpha: CLinearNumberSchema,
+});
+
+const RandomColorBetweenGradientSchema = z.object({
+  type: z.literal('RandomColorBetweenGradient'),
+  gradient1: GradientSchema,
+  gradient2: GradientSchema,
+});
+
+export const ColorGeneratorSchema = z
+  .discriminatedUnion('type', [
+    ConstantColorSchema,
+    ColorRangeSchema,
+    GradientSchema,
+    RandomColorBetweenGradientSchema,
+  ])
+  .describe('Color generator: constant, range, gradient, or random between gradients');
+
+export type ColorGeneratorJSON = z.infer<typeof ColorGeneratorSchema>;
+
+// --- Emitter Shapes (mirrors quarks.core shape constructor params) ---
+
+const PointEmitterSchema = z.object({ type: z.literal('point') });
+
+const SphereEmitterSchema = z.object({
+  type: z.literal('sphere'),
+  radius: z.number().optional().describe('Sphere radius'),
+  arc: z.number().optional().describe('Arc angle in radians (2π = full sphere)'),
+  thickness: z.number().optional().describe('Shell thickness 0–1 (1 = solid, 0 = surface only)'),
+});
+
+const HemisphereEmitterSchema = z.object({
+  type: z.literal('hemisphere'),
+  radius: z.number().optional().describe('Hemisphere radius'),
+  arc: z.number().optional().describe('Arc angle in radians'),
+  thickness: z.number().optional().describe('Shell thickness 0–1'),
+});
+
+const ConeEmitterSchema = z.object({
+  type: z.literal('cone'),
+  radius: z.number().optional().describe('Cone base radius'),
+  arc: z.number().optional().describe('Arc angle in radians'),
+  thickness: z.number().optional().describe('Shell thickness 0–1'),
+  angle: z.number().optional().describe('Cone opening angle in radians'),
+});
+
+const CircleEmitterSchema = z.object({
+  type: z.literal('circle'),
+  radius: z.number().optional().describe('Circle radius'),
+  arc: z.number().optional().describe('Arc angle in radians'),
+  thickness: z.number().optional().describe('Ring thickness 0–1'),
+});
+
+const DonutEmitterSchema = z.object({
+  type: z.literal('donut'),
+  radius: z.number().optional().describe('Donut major radius'),
+  arc: z.number().optional().describe('Arc angle in radians'),
+  thickness: z.number().optional().describe('Ring thickness 0–1'),
+  donutRadius: z.number().optional().describe('Donut tube (minor) radius'),
+});
+
+const RectangleEmitterSchema = z.object({
+  type: z.literal('rectangle'),
+  width: z.number().optional().describe('Rectangle width'),
+  height: z.number().optional().describe('Rectangle height'),
+  thickness: z.number().optional().describe('Extrusion depth 0–1'),
+});
+
+const GridEmitterSchema = z.object({
+  type: z.literal('grid'),
+  width: z.number().optional().describe('Grid total width'),
+  height: z.number().optional().describe('Grid total height'),
+  column: z.number().int().optional().describe('Number of columns'),
+  row: z.number().int().optional().describe('Number of rows'),
+});
+
+export const EmitterShapeSchema = z
+  .discriminatedUnion('type', [
+    PointEmitterSchema,
+    SphereEmitterSchema,
+    HemisphereEmitterSchema,
+    ConeEmitterSchema,
+    CircleEmitterSchema,
+    DonutEmitterSchema,
+    RectangleEmitterSchema,
+    GridEmitterSchema,
+  ])
+  .describe('Particle emitter shape');
+
+export type EmitterShapeJSON = z.infer<typeof EmitterShapeSchema>;
+
+// --- Behaviors (mirrors quarks.core behavior toJSON) ---
+
+const ApplyForceBehaviorSchema = z.object({
+  type: z.literal('ApplyForce'),
+  direction: Vec3Schema.describe('Force direction vector'),
+  magnitude: ValueGeneratorSchema.describe('Force magnitude'),
+});
+
+const ColorOverLifeBehaviorSchema = z.object({
+  type: z.literal('ColorOverLife'),
+  color: ColorGeneratorSchema.describe('Color curve over particle lifetime'),
+});
+
+const SizeOverLifeBehaviorSchema = z.object({
+  type: z.literal('SizeOverLife'),
+  size: ValueGeneratorSchema.describe('Size curve over particle lifetime'),
+});
+
+const SpeedOverLifeBehaviorSchema = z.object({
+  type: z.literal('SpeedOverLife'),
+  speed: ValueGeneratorSchema.describe('Speed multiplier curve over lifetime'),
+});
+
+const RotationOverLifeBehaviorSchema = z.object({
+  type: z.literal('RotationOverLife'),
+  angularVelocity: ValueGeneratorSchema.describe('Angular velocity in radians/sec'),
+});
+
+const ForceOverLifeBehaviorSchema = z.object({
+  type: z.literal('ForceOverLife'),
+  x: ValueGeneratorSchema.describe('Force along X axis over lifetime'),
+  y: ValueGeneratorSchema.describe('Force along Y axis over lifetime'),
+  z: ValueGeneratorSchema.describe('Force along Z axis over lifetime'),
+});
+
+const OrbitOverLifeBehaviorSchema = z.object({
+  type: z.literal('OrbitOverLife'),
+  orbitSpeed: ValueGeneratorSchema.describe('Orbit speed over lifetime'),
+  axis: Vec3Schema.optional().describe('Orbit axis. Defaults to [0, 1, 0]'),
+});
+
+const NoiseBehaviorSchema = z.object({
+  type: z.literal('Noise'),
+  frequency: ValueGeneratorSchema.describe('Noise frequency'),
+  power: ValueGeneratorSchema.describe('Noise amplitude'),
+  positionAmount: ValueGeneratorSchema.optional().describe('Position displacement amount'),
+  rotationAmount: ValueGeneratorSchema.optional().describe('Rotation displacement amount'),
+});
+
+const TurbulenceFieldBehaviorSchema = z.object({
+  type: z.literal('TurbulenceField'),
+  scale: Vec3Schema.describe('Turbulence field scale'),
+  octaves: z.number().int().describe('Noise octave count'),
+  velocityMultiplier: Vec3Schema.describe('Velocity multiplier per axis'),
+  timeScale: Vec3Schema.describe('Time scale per axis'),
+});
+
+const FrameOverLifeBehaviorSchema = z.object({
+  type: z.literal('FrameOverLife'),
+  frame: ValueGeneratorSchema.describe('Sprite sheet frame index over lifetime'),
+});
+
+const LimitSpeedOverLifeBehaviorSchema = z.object({
+  type: z.literal('LimitSpeedOverLife'),
+  speed: ValueGeneratorSchema.describe('Maximum speed over lifetime'),
+  dampen: z.number().describe('Damping factor when speed exceeds limit (0–1)'),
+});
+
+const ChangeEmitDirectionBehaviorSchema = z.object({
+  type: z.literal('ChangeEmitDirection'),
+  angle: ValueGeneratorSchema.describe('Angle deviation from original emit direction'),
+});
+
+const GravityForceBehaviorSchema = z.object({
+  type: z.literal('GravityForce'),
+  center: Vec3Schema.describe('Gravity center point'),
+  magnitude: z.number().describe('Gravity force strength'),
+});
+
+const WidthOverLengthBehaviorSchema = z.object({
+  type: z.literal('WidthOverLength'),
+  width: ValueGeneratorSchema.describe('Trail width over trail length'),
+});
+
+export const BehaviorSchema = z
+  .discriminatedUnion('type', [
+    ApplyForceBehaviorSchema,
+    ColorOverLifeBehaviorSchema,
+    SizeOverLifeBehaviorSchema,
+    SpeedOverLifeBehaviorSchema,
+    RotationOverLifeBehaviorSchema,
+    ForceOverLifeBehaviorSchema,
+    OrbitOverLifeBehaviorSchema,
+    NoiseBehaviorSchema,
+    TurbulenceFieldBehaviorSchema,
+    FrameOverLifeBehaviorSchema,
+    LimitSpeedOverLifeBehaviorSchema,
+    ChangeEmitDirectionBehaviorSchema,
+    GravityForceBehaviorSchema,
+    WidthOverLengthBehaviorSchema,
+  ])
+  .describe('Particle behavior applied over lifetime');
+
+export type BehaviorJSON = z.infer<typeof BehaviorSchema>;
+
+// --- Render Mode ---
+
+export const RenderModeSchema = z
+  .enum([
+    'billboard',
+    'stretchedBillboard',
+    'mesh',
+    'trail',
+    'horizontalBillboard',
+    'verticalBillboard',
+  ])
+  .describe('How particles are rendered');
+
+// --- Particle Material (our format — asset paths, not Three.js UUIDs) ---
+
+const ParticleMaterialSchema = z
+  .object({
+    type: z.enum(['basic', 'standard']).optional().describe('Particle material shading model'),
+    color: z.string().optional().describe('Particle color as CSS hex string'),
+    map: z.string().optional().describe('Path to particle sprite texture'),
+    blending: z
+      .enum(['normal', 'additive'])
+      .optional()
+      .describe('Blending mode (additive for glowing/fire effects)'),
+    transparent: z.boolean().optional().describe('Enable transparency'),
+    depthWrite: z
+      .boolean()
+      .optional()
+      .describe('Write to depth buffer (disable for additive effects)'),
+    side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
+  })
+  .describe('Particle material settings');
+
+// --- Burst ---
+
+const BurstSchema = z
+  .object({
+    time: z.number().describe('Time offset in seconds within the emission cycle'),
+    count: ValueGeneratorSchema.describe('Number of particles to emit'),
+    cycle: z.number().optional().describe('Burst repeat interval in seconds'),
+    interval: z.number().optional().describe('Delay between burst repetitions'),
+    probability: z.number().optional().describe('Chance of burst firing (0–1)'),
+  })
+  .describe('Timed particle burst');
+
+// --- Top-level SceneParticles ---
+
+export const SceneParticlesSchema = z
+  .object({
+    // Lifecycle
+    autoDestroy: z
+      .boolean()
+      .optional()
+      .describe('Destroy the particle system when all particles have died'),
+    looping: z.boolean().optional().describe('Continuously emit particles'),
+    prewarm: z
+      .boolean()
+      .optional()
+      .describe('Simulate one full cycle on start so particles appear immediately'),
+    duration: z.number().optional().describe('Total emission duration in seconds'),
+
+    // Shape
+    shape: EmitterShapeSchema.optional().describe(
+      'Emitter shape that defines where particles spawn',
+    ),
+
+    // Per-particle initial values
+    startLife: ValueGeneratorSchema.optional().describe('Initial particle lifetime in seconds'),
+    startSpeed: ValueGeneratorSchema.optional().describe('Initial particle speed'),
+    startSize: ValueGeneratorSchema.optional().describe('Initial particle size'),
+    startRotation: ValueGeneratorSchema.optional().describe('Initial particle rotation in radians'),
+    startColor: ColorGeneratorSchema.optional().describe('Initial particle color'),
+    startLength: ValueGeneratorSchema.optional().describe(
+      'Initial trail length (trail render mode only)',
+    ),
+    startTileIndex: ValueGeneratorSchema.optional().describe('Initial sprite sheet tile index'),
+
+    // Emission
+    emissionOverTime: ValueGeneratorSchema.optional().describe('Particles emitted per second'),
+    emissionOverDistance: ValueGeneratorSchema.optional().describe(
+      'Particles emitted per unit of emitter movement',
+    ),
+    emissionBursts: z.array(BurstSchema).optional().describe('Timed burst emissions'),
+
+    // Behaviors
+    behaviors: z
+      .array(BehaviorSchema)
+      .optional()
+      .describe('Behaviors applied to particles over their lifetime'),
+
+    // Rendering
+    renderMode: RenderModeSchema.optional().describe(
+      'How particles are rendered (billboard, trail, mesh, etc.)',
+    ),
+    worldSpace: z
+      .boolean()
+      .optional()
+      .describe('Simulate particles in world space instead of local space'),
+    renderOrder: z
+      .number()
+      .optional()
+      .describe('Render order for sorting (higher = rendered later)'),
+    uTileCount: z.number().int().optional().describe('Horizontal tile count in sprite sheet'),
+    vTileCount: z.number().int().optional().describe('Vertical tile count in sprite sheet'),
+    blendTiles: z
+      .boolean()
+      .optional()
+      .describe('Blend between sprite sheet tiles for smooth animation'),
+    softParticles: z.boolean().optional().describe('Enable soft particle depth fading'),
+    softFarFade: z.number().optional().describe('Far fade distance for soft particles'),
+    softNearFade: z.number().optional().describe('Near fade distance for soft particles'),
+
+    // Material
+    material: ParticleMaterialSchema.describe('Particle material settings'),
+  })
+  .describe('Particle system configuration');
+
+/** Partial schema for prefab instance overrides. */
+export const SceneParticlesOverrideSchema = SceneParticlesSchema.partial();
+
+export type SceneParticles = z.infer<typeof SceneParticlesSchema>;

package/src/scene/schema/physics.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { SceneColliderOverrideSchema, SceneColliderSchema } from './collider';
+
+export const ScenePhysicsSchema = z
+  .object({
+    bodyType: z
+      .enum(['dynamic', 'fixed', 'kinematic'])
+      .describe(
+        'Physics body type: dynamic (simulated), fixed (immovable), kinematic (script-driven). ' +
+          'T1.1/R1c: ANY physics body (dynamic, fixed, OR kinematic) nested under an ancestor ' +
+          'entity that itself has a "dynamic" or "kinematic" body is unsupported (loud load ' +
+          'error) — Rapier has no parent/child body relationship, so a moving ancestor cannot ' +
+          "carry a nested body of ANY type with it; the child's Object3D would stay pinned to " +
+          "its own (non-moving) body's pose while the ancestor moves out from under it. " +
+          'Nesting under a "fixed"/static or physics-less transformed ancestor is fine.',
+      ),
+    mass: z
+      .number()
+      .optional()
+      .describe('Explicit mass override. If omitted, computed from collider density and volume'),
+    collider: SceneColliderSchema.describe(
+      'Collider shape attached to this body. T1.1/T1.2: the Rapier body is created at this ' +
+        "entity's COMPOSED WORLD transform (parent chain × own local transform) — Rapier has " +
+        "no concept of a parent Object3D, so nested entities' transforms are baked in at spawn " +
+        'time, not read live thereafter.',
+    ),
+  })
+  .describe('Physics rigid body configuration');
+
+/** Partial override — uses SceneColliderOverrideSchema for deep partial on collider. */
+export const ScenePhysicsOverrideSchema = z.object({
+  bodyType: z
+    .enum(['dynamic', 'fixed', 'kinematic'])
+    .optional()
+    .describe(
+      'Physics body type: dynamic (simulated), fixed (immovable), kinematic (script-driven). ' +
+        'A body of ANY type nested under a "dynamic"/"kinematic"-bodied ancestor throws a loud ' +
+        'load error (T1.1/R1c) — see ScenePhysicsSchema.bodyType.',
+    ),
+  mass: z
+    .number()
+    .optional()
+    .describe('Explicit mass override. If omitted, computed from collider density and volume'),
+  collider: SceneColliderOverrideSchema.optional().describe(
+    'Partial collider overrides merged with prefab',
+  ),
+});
+
+export type ScenePhysics = z.infer<typeof ScenePhysicsSchema>;