@vgai/engine 0.5.5 → 0.5.7

package/dist/asset-formats/material.d.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+export declare const MaterialDescriptorSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        standard: "standard";
+        physical: "physical";
+        basic: "basic";
+        toon: "toon";
+    }>;
+    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.$strict>;
+export type MaterialDescriptor = z.infer<typeof MaterialDescriptorSchema>;
+/** .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<{
+            standard: "standard";
+            physical: "physical";
+            basic: "basic";
+            toon: "toon";
+        }>;
+        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.$strict>;
+}, z.core.$strip>;
+export type MaterialFile = z.infer<typeof MaterialFileSchema>;
+//# sourceMappingURL=material.d.ts.map

package/dist/asset-formats/material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material.d.ts","sourceRoot":"","sources":["../../src/asset-formats/material.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwFxB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAEpC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,iEAAiE;AACjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMsB,CAAC;AAEtD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/asset-formats/material.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+const MaterialDescriptorObjectSchema = z
+    .object({
+    type: z.enum(['standard', 'physical', 'basic', 'toon']).describe('Material shading model'),
+    color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
+    metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
+    roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
+    map: z.string().optional().describe('Path to albedo/diffuse texture image'),
+    normalMap: z.string().optional().describe('Path to normal map texture image'),
+    emissive: z.string().optional().describe('Emissive color as CSS hex string'),
+    emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
+    emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
+    aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
+    lightMap: z
+        .string()
+        .optional()
+        .describe("Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material."),
+    lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
+    roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
+    metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
+    opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
+    transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
+    side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
+    flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
+    // Physical material feature groups (physical only, all optional)
+    clearcoat: z
+        .object({
+        clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
+        clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
+        clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
+        clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
+    })
+        .optional()
+        .describe('Clearcoat layer (physical only)'),
+    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'),
+})
+    .strict();
+export const MaterialDescriptorSchema = MaterialDescriptorObjectSchema.describe('Material appearance properties');
+/** .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: MaterialDescriptorSchema.describe('Material definition'),
+})
+    .describe('Shared material asset file (.mat.json)');

package/dist/asset-formats/mesh.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const MeshDescriptorSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        box: "box";
+        capsule: "capsule";
+        sphere: "sphere";
+        plane: "plane";
+        cylinder: "cylinder";
+        gltf: "gltf";
+        splat: "splat";
+    }>;
+    args: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    src: z.ZodOptional<z.ZodString>;
+    node: z.ZodOptional<z.ZodString>;
+    instances: z.ZodOptional<z.ZodString>;
+    lod: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        distance: z.ZodNumber;
+        node: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strict>;
+export type MeshDescriptor = z.infer<typeof MeshDescriptorSchema>;
+//# sourceMappingURL=mesh.d.ts.map

package/dist/asset-formats/mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.d.ts","sourceRoot":"","sources":["../../src/asset-formats/mesh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoExB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;kBAoBM,CAAC;AAExC,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/asset-formats/mesh.js

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

package/dist/asset-formats/parse.d.ts

@@ -0,0 +1,20 @@
+import { AssetParseError } from '../asset-parse-error';
+import type { InstancesFile } from './instances';
+import type { MaterialFile } from './material';
+export { AssetParseError };
+/**
+ * Parse a `.mat.json` shared material asset (T4.6). There is no version-range
+ * gate for this format — `MaterialFileSchema`'s `version` field is RESERVED
+ * (see `schema-consumption-map.ts`).
+ *
+ * Formerly `@engine/scene/parse`'s `parseMaterialFile`; moved here when WO-8
+ * deleted the `.vscn` scene format that module was named for.
+ */
+export declare function parseMaterialFile(json: unknown, filePath?: string): MaterialFile;
+/**
+ * Parse a `.instances.json` instance-transform asset (F3). Mirrors
+ * `parseMaterialFile` exactly — no version-range gate (the format is a bare
+ * tuple array, no `version` field).
+ */
+export declare function parseInstancesFile(json: unknown, filePath?: string): InstancesFile;
+//# sourceMappingURL=parse.d.ts.map

package/dist/asset-formats/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/asset-formats/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAMhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAMlF"}

package/dist/asset-formats/parse.js

@@ -0,0 +1,34 @@
+import { AssetParseError } from '../asset-parse-error';
+import { InstancesFileSchema } from './instances';
+import { MaterialFileSchema } from './material';
+// The error class itself is format-neutral and lives in
+// `engine/src/asset-parse-error.ts` (the input-map loader raises it too).
+// Re-exported here so callers have one import for parse + error.
+export { AssetParseError };
+/**
+ * Parse a `.mat.json` shared material asset (T4.6). There is no version-range
+ * gate for this format — `MaterialFileSchema`'s `version` field is RESERVED
+ * (see `schema-consumption-map.ts`).
+ *
+ * Formerly `@engine/scene/parse`'s `parseMaterialFile`; moved here when WO-8
+ * deleted the `.vscn` scene format that module was named for.
+ */
+export function parseMaterialFile(json, filePath) {
+    const result = MaterialFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new AssetParseError(result.error.issues, filePath);
+    }
+    return result.data;
+}
+/**
+ * Parse a `.instances.json` instance-transform asset (F3). Mirrors
+ * `parseMaterialFile` exactly — no version-range gate (the format is a bare
+ * tuple array, no `version` field).
+ */
+export function parseInstancesFile(json, filePath) {
+    const result = InstancesFileSchema.safeParse(json);
+    if (!result.success) {
+        throw new AssetParseError(result.error.issues, filePath);
+    }
+    return result.data;
+}