@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/schema/material.d.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+export declare const SceneMaterialSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        custom: "custom";
+        standard: "standard";
+        physical: "physical";
+        basic: "basic";
+        toon: "toon";
+    }>;
+    def: z.ZodOptional<z.ZodString>;
+    uniforms: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodNumber>]>>>;
+    color: z.ZodOptional<z.ZodString>;
+    metalness: z.ZodOptional<z.ZodNumber>;
+    roughness: z.ZodOptional<z.ZodNumber>;
+    map: z.ZodOptional<z.ZodString>;
+    normalMap: z.ZodOptional<z.ZodString>;
+    emissive: z.ZodOptional<z.ZodString>;
+    emissiveIntensity: z.ZodOptional<z.ZodNumber>;
+    emissiveMap: z.ZodOptional<z.ZodString>;
+    aoMap: z.ZodOptional<z.ZodString>;
+    lightMap: z.ZodOptional<z.ZodString>;
+    lightMapIntensity: z.ZodOptional<z.ZodNumber>;
+    roughnessMap: z.ZodOptional<z.ZodString>;
+    metalnessMap: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    transparent: z.ZodOptional<z.ZodBoolean>;
+    side: z.ZodOptional<z.ZodEnum<{
+        front: "front";
+        back: "back";
+        double: "double";
+    }>>;
+    flatShading: z.ZodOptional<z.ZodBoolean>;
+    clearcoat: z.ZodOptional<z.ZodObject<{
+        clearcoat: z.ZodNumber;
+        clearcoatRoughness: z.ZodOptional<z.ZodNumber>;
+        clearcoatMap: z.ZodOptional<z.ZodString>;
+        clearcoatRoughnessMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    transmission: z.ZodOptional<z.ZodObject<{
+        transmission: z.ZodNumber;
+        ior: z.ZodOptional<z.ZodNumber>;
+        thickness: z.ZodOptional<z.ZodNumber>;
+        attenuationColor: z.ZodOptional<z.ZodString>;
+        attenuationDistance: z.ZodOptional<z.ZodNumber>;
+        transmissionMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sheen: z.ZodOptional<z.ZodObject<{
+        sheen: z.ZodNumber;
+        sheenColor: z.ZodOptional<z.ZodString>;
+        sheenRoughness: z.ZodOptional<z.ZodNumber>;
+        sheenColorMap: z.ZodOptional<z.ZodString>;
+        sheenRoughnessMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    iridescence: z.ZodOptional<z.ZodObject<{
+        iridescence: z.ZodNumber;
+        iridescenceIOR: z.ZodOptional<z.ZodNumber>;
+        iridescenceThicknessRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        iridescenceMap: z.ZodOptional<z.ZodString>;
+        iridescenceThicknessMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    displacementMap: z.ZodOptional<z.ZodString>;
+    displacementScale: z.ZodOptional<z.ZodNumber>;
+    displacementBias: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Partial schema for prefab instance overrides (type not required). */
+export declare const SceneMaterialOverrideSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        custom: "custom";
+        standard: "standard";
+        physical: "physical";
+        basic: "basic";
+        toon: "toon";
+    }>>;
+    def: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    uniforms: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodNumber>]>>>>;
+    color: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    metalness: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    roughness: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    map: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    normalMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    emissive: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    emissiveIntensity: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    emissiveMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    aoMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    lightMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    lightMapIntensity: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    roughnessMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    metalnessMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    opacity: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    transparent: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    side: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+        front: "front";
+        back: "back";
+        double: "double";
+    }>>>;
+    flatShading: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    clearcoat: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        clearcoat: z.ZodNumber;
+        clearcoatRoughness: z.ZodOptional<z.ZodNumber>;
+        clearcoatMap: z.ZodOptional<z.ZodString>;
+        clearcoatRoughnessMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    transmission: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        transmission: z.ZodNumber;
+        ior: z.ZodOptional<z.ZodNumber>;
+        thickness: z.ZodOptional<z.ZodNumber>;
+        attenuationColor: z.ZodOptional<z.ZodString>;
+        attenuationDistance: z.ZodOptional<z.ZodNumber>;
+        transmissionMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    sheen: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        sheen: z.ZodNumber;
+        sheenColor: z.ZodOptional<z.ZodString>;
+        sheenRoughness: z.ZodOptional<z.ZodNumber>;
+        sheenColorMap: z.ZodOptional<z.ZodString>;
+        sheenRoughnessMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    iridescence: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        iridescence: z.ZodNumber;
+        iridescenceIOR: z.ZodOptional<z.ZodNumber>;
+        iridescenceThicknessRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        iridescenceMap: z.ZodOptional<z.ZodString>;
+        iridescenceThicknessMap: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    displacementMap: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    displacementScale: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    displacementBias: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type SceneMaterial = z.infer<typeof SceneMaterialSchema>;
+/** .mat.json file format for shared/reusable material assets. */
+export declare const MaterialFileSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    name: z.ZodString;
+    material: z.ZodObject<{
+        type: z.ZodEnum<{
+            custom: "custom";
+            standard: "standard";
+            physical: "physical";
+            basic: "basic";
+            toon: "toon";
+        }>;
+        def: z.ZodOptional<z.ZodString>;
+        uniforms: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodNumber>]>>>;
+        color: z.ZodOptional<z.ZodString>;
+        metalness: z.ZodOptional<z.ZodNumber>;
+        roughness: z.ZodOptional<z.ZodNumber>;
+        map: z.ZodOptional<z.ZodString>;
+        normalMap: z.ZodOptional<z.ZodString>;
+        emissive: z.ZodOptional<z.ZodString>;
+        emissiveIntensity: z.ZodOptional<z.ZodNumber>;
+        emissiveMap: z.ZodOptional<z.ZodString>;
+        aoMap: z.ZodOptional<z.ZodString>;
+        lightMap: z.ZodOptional<z.ZodString>;
+        lightMapIntensity: z.ZodOptional<z.ZodNumber>;
+        roughnessMap: z.ZodOptional<z.ZodString>;
+        metalnessMap: z.ZodOptional<z.ZodString>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        transparent: z.ZodOptional<z.ZodBoolean>;
+        side: z.ZodOptional<z.ZodEnum<{
+            front: "front";
+            back: "back";
+            double: "double";
+        }>>;
+        flatShading: z.ZodOptional<z.ZodBoolean>;
+        clearcoat: z.ZodOptional<z.ZodObject<{
+            clearcoat: z.ZodNumber;
+            clearcoatRoughness: z.ZodOptional<z.ZodNumber>;
+            clearcoatMap: z.ZodOptional<z.ZodString>;
+            clearcoatRoughnessMap: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        transmission: z.ZodOptional<z.ZodObject<{
+            transmission: z.ZodNumber;
+            ior: z.ZodOptional<z.ZodNumber>;
+            thickness: z.ZodOptional<z.ZodNumber>;
+            attenuationColor: z.ZodOptional<z.ZodString>;
+            attenuationDistance: z.ZodOptional<z.ZodNumber>;
+            transmissionMap: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sheen: z.ZodOptional<z.ZodObject<{
+            sheen: z.ZodNumber;
+            sheenColor: z.ZodOptional<z.ZodString>;
+            sheenRoughness: z.ZodOptional<z.ZodNumber>;
+            sheenColorMap: z.ZodOptional<z.ZodString>;
+            sheenRoughnessMap: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        iridescence: z.ZodOptional<z.ZodObject<{
+            iridescence: z.ZodNumber;
+            iridescenceIOR: z.ZodOptional<z.ZodNumber>;
+            iridescenceThicknessRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            iridescenceMap: z.ZodOptional<z.ZodString>;
+            iridescenceThicknessMap: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        displacementMap: z.ZodOptional<z.ZodString>;
+        displacementScale: z.ZodOptional<z.ZodNumber>;
+        displacementBias: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MaterialFile = z.infer<typeof MaterialFileSchema>;
+//# sourceMappingURL=material.d.ts.map

package/dist/scene/schema/material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/material.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8Fa,CAAC;AAE9C,wEAAwE;AACxE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgC,CAAC;AAEzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,iEAAiE;AACjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMsB,CAAC;AAEtD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/scene/schema/material.js

@@ -0,0 +1,99 @@
+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();
+/** .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)');

package/dist/scene/schema/mesh.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+export declare const SceneMeshSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        capsule: "capsule";
+        box: "box";
+        sphere: "sphere";
+        plane: "plane";
+        cylinder: "cylinder";
+        gltf: "gltf";
+    }>;
+    args: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    src: z.ZodOptional<z.ZodString>;
+    node: z.ZodOptional<z.ZodString>;
+    instances: z.ZodOptional<z.ZodString>;
+    instancer: z.ZodOptional<z.ZodString>;
+    instancerParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>>>;
+    generator: z.ZodOptional<z.ZodString>;
+    generatorParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>>>;
+    lod: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        distance: z.ZodNumber;
+        node: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Partial schema for prefab instance overrides (type not required). */
+export declare const SceneMeshOverrideSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        capsule: "capsule";
+        box: "box";
+        sphere: "sphere";
+        plane: "plane";
+        cylinder: "cylinder";
+        gltf: "gltf";
+    }>>;
+    args: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodNumber>>>;
+    src: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    node: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    instances: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    instancer: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    instancerParams: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>>>>;
+    generator: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    generatorParams: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>>>>;
+    lod: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        distance: z.ZodNumber;
+        node: z.ZodString;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type SceneMesh = z.infer<typeof SceneMeshSchema>;
+//# sourceMappingURL=mesh.d.ts.map

package/dist/scene/schema/mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../../../src/scene/schema/mesh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkFxB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;iBAoBW,CAAC;AAExC,wEAAwE;AACxE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;iBAA0B,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/scene/schema/mesh.js

@@ -0,0 +1,82 @@
+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();