@forgeax/engine-gltf 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-gltf",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -38,21 +38,21 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-animation": "0.1.23",
-    "@forgeax/engine-geometry": "0.1.23",
-    "@forgeax/engine-import": "0.1.23",
-    "@forgeax/engine-math": "0.1.23",
-    "@forgeax/engine-pack": "0.1.23",
-    "@forgeax/engine-scene": "0.1.23",
-    "@forgeax/engine-types": "0.1.23",
+    "@forgeax/engine-animation": "0.1.24",
+    "@forgeax/engine-geometry": "0.1.24",
+    "@forgeax/engine-import": "0.1.24",
+    "@forgeax/engine-math": "0.1.24",
+    "@forgeax/engine-pack": "0.1.24",
+    "@forgeax/engine-scene": "0.1.24",
+    "@forgeax/engine-types": "0.1.24",
     "@webgpu/types": "^0.1.71",
     "meshoptimizer": "^0.20.0"
   },
   "devDependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.23",
-    "@forgeax/engine-picking": "0.1.23",
-    "@forgeax/engine-render": "0.1.23",
-    "@forgeax/engine-runtime": "0.1.23",
+    "@forgeax/engine-assets-runtime": "0.1.24",
+    "@forgeax/engine-picking": "0.1.24",
+    "@forgeax/engine-render": "0.1.24",
+    "@forgeax/engine-runtime": "0.1.24",
     "@types/node": "^20.14.0"
   },
   "forgeax": {

package/src/__tests__/bridge-material-values.unit.test.ts

@@ -1,4 +1,4 @@
-import type { Handle } from '@forgeax/engine-types';
+import type { AssetGuid, Handle } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { toMaterialAsset } from '../bridge.js';
 import type { GltfMaterialIr } from '../parse-gltf.js';
@@ -149,4 +149,87 @@ describe('glTF material bridge values', () => {
       },
     });
   });
+
+  it('owns a complete five-extension Standard root and admits only authored physical textures', () => {
+    const material = toMaterialAsset(
+      {
+        name: 'physical-root',
+        baseColorFactor: [0.8, 0.7, 0.6, 1],
+        metallicFactor: 0.1,
+        roughnessFactor: 0.35,
+        clearcoatFactor: 0.75,
+        clearcoatRoughnessFactor: 0.2,
+        clearcoatNormalTexture: { texture: 0 },
+        anisotropyStrength: 0.5,
+        anisotropyRotation: 0.25,
+        anisotropyTexture: { texture: 1 },
+        sheenColorFactor: [0.2, 0.1, 0.05],
+        sheenRoughnessFactor: 0.3,
+        sheenColorTexture: { texture: 2 },
+        iridescenceFactor: 0.6,
+        iridescenceIor: 1.4,
+        iridescenceThicknessMinimum: 120,
+        iridescenceThicknessMaximum: 380,
+        iridescenceTexture: { texture: 3 },
+        specularFactor: 0.8,
+        specularColorFactor: [0.9, 0.85, 0.75],
+        specularColorTexture: { texture: 4 },
+      } as unknown as GltfMaterialIr,
+      {
+        standardRootGuid: 'standard-root' as unknown as AssetGuid,
+        textureHandles: new Map([
+          [0, 100],
+          [1, 101],
+          [2, 102],
+          [3, 103],
+          [4, 104],
+        ]) as unknown as ReadonlyMap<number, Handle<'TextureAsset', 'shared'>>,
+      },
+    );
+
+    expect(material.parent).toBeUndefined();
+    const names = new Set((material.parameters ?? []).map((parameter) => parameter.name));
+    for (const name of [
+      'clearcoat',
+      'clearcoatRoughness',
+      'clearcoatNormalTexture',
+      'anisotropyStrength',
+      'anisotropyRotation',
+      'anisotropyTexture',
+      'sheenColor',
+      'sheenRoughness',
+      'sheenColorTexture',
+      'iridescence',
+      'iridescenceIor',
+      'iridescenceThicknessMinimum',
+      'iridescenceThicknessMaximum',
+      'iridescenceTexture',
+      'specular',
+      'specularColor',
+      'specularColorTexture',
+    ]) {
+      expect(names.has(name)).toBe(true);
+    }
+    for (const name of [
+      'clearcoatTexture',
+      'clearcoatRoughnessTexture',
+      'sheenRoughnessTexture',
+      'iridescenceThicknessTexture',
+      'specularTexture',
+    ]) {
+      expect(names.has(name)).toBe(false);
+    }
+    expect(material.values).toMatchObject({
+      clearcoat: 0.75,
+      anisotropyStrength: 0.5,
+      sheenColor: [0.2, 0.1, 0.05],
+      iridescenceIor: 1.4,
+      specularColor: [0.9, 0.85, 0.75],
+      clearcoatNormalTexture: { texture: 100 },
+      anisotropyTexture: { texture: 101 },
+      sheenColorTexture: { texture: 102 },
+      iridescenceTexture: { texture: 103 },
+      specularColorTexture: { texture: 104 },
+    });
+  });
 });

package/src/__tests__/bridge-skin-stride.unit.test.ts

@@ -102,6 +102,28 @@ describe('meshIrToMeshAsset pure-unskinned path (AC-04 / AC-08 / OOS-9)', () =>
 });
 
 describe('glTF bridge uses geometry-owned packing', () => {
+  it('persists a generated tangent frame when source TANGENT is absent', () => {
+    const asset = meshIrToMeshAsset([
+      {
+        meshIndex: 0,
+        materialIndex: null,
+        positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+        normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+        texcoord0: new Float32Array([0, 0, 1, 0, 0, 1]),
+        indices: new Uint16Array([0, 1, 2]),
+      },
+    ]);
+
+    const tangent = asset.attributes.tangent;
+    expect(tangent).toBeInstanceOf(Float32Array);
+    if (!(tangent instanceof Float32Array)) throw new Error('generated tangent stream missing');
+    expect(tangent?.length).toBe(12);
+    expect(tangent?.[0]).toBeCloseTo(1, 5);
+    expect(tangent?.[1]).toBeCloseTo(0, 5);
+    expect(tangent?.[2]).toBeCloseTo(0, 5);
+    expect(Math.abs(tangent?.[3] ?? 0)).toBeCloseTo(1, 5);
+  });
+
   it('does not own a parallel 12F/18F stride or uv count calculation', () => {
     const asset = meshIrToMeshAsset([makeUnskinnedPrim(0, 4)]);
     expect(asset.vertices.length / 12).toBe(4);

package/src/__tests__/gltf-error-derived-views.test-d.ts

@@ -15,6 +15,7 @@ import {
   type GltfInstancingCountMismatchDetail,
   type GltfLodInvalidDetail,
   type GltfMalformedHeaderDetail,
+  type GltfMaterialPhysicalInvalidDetail,
   type GltfMaterialTransmissionInvalidDetail,
   type GltfMeshBridgeInvalidDetail,
   type GltfMeshoptDecodeFailedDetail,
@@ -55,6 +56,7 @@ type ExpectedDetails = {
   readonly 'gltf-mesh-bridge-invalid': GltfMeshBridgeInvalidDetail;
   readonly 'gltf-lod-invalid': GltfLodInvalidDetail;
   readonly 'gltf-material-transmission-invalid': GltfMaterialTransmissionInvalidDetail;
+  readonly 'gltf-material-physical-invalid': GltfMaterialPhysicalInvalidDetail;
 };
 
 type ExpectedCodes = keyof ExpectedDetails;
@@ -117,6 +119,8 @@ function exhaustive(error: GltfError): string {
       return error.detail.reason;
     case 'gltf-material-transmission-invalid':
       return `${error.detail.extension}:${error.detail.field}:${error.detail.reason}`;
+    case 'gltf-material-physical-invalid':
+      return `${error.detail.extension}:${error.detail.field}:${error.detail.reason}`;
   }
   return error;
 }

package/src/__tests__/gltf-error-migration.test.ts

@@ -17,7 +17,7 @@ import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 
 const REPO_ROOT = resolve(import.meta.dirname ?? '.', '..', '..', '..', '..');
-const TYPES_INDEX = resolve(REPO_ROOT, 'packages', 'types', 'src', 'index.ts');
+const TYPES_INDEX = resolve(REPO_ROOT, 'packages', 'types', 'src', 'core-contracts.ts');
 const GLTF_ERRORS = resolve(REPO_ROOT, 'packages', 'gltf', 'src', 'errors.ts');
 
 function grepCount(pattern: string, file: string): number {
@@ -125,12 +125,12 @@ function grepCountImportGltfErrorFromTypes(): number {
 }
 
 describe('M1 GltfErrorCode migration grep gate (AC-28)', () => {
-  it("(a) types/src/index.ts contains zero 'gltf-' string literals", () => {
+  it("(a) types/src/core-contracts.ts contains zero 'gltf-' string literals", () => {
     const count = grepCount("'gltf-", TYPES_INDEX);
     expect(count).toBe(0);
   });
 
-  it('(b) types/src/index.ts contains zero export type GltfError* exports', () => {
+  it('(b) types/src/core-contracts.ts contains zero export type GltfError* exports', () => {
     const count = grepCount('export type GltfError', TYPES_INDEX);
     expect(count).toBe(0);
   });

package/src/__tests__/gltf.unit.test.ts

@@ -278,7 +278,9 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
     'gltf-version-unsupported',
     'gltf-buffer-out-of-bounds',
     'gltf-extension-unsupported',
+    'gltf-lod-invalid',
     'gltf-material-transmission-invalid',
+    'gltf-material-physical-invalid',
     'gltf-accessor-type-mismatch',
     'gltf-texture-load-failed',
     'gltf-meta-missing',
@@ -300,7 +302,8 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
   ];
 
   function classifyByExhaustiveSwitch(err: GltfError): string {
-    switch (err.code) {
+    const code = err.code;
+    switch (code) {
       case 'gltf-malformed-header':
         return 'malformed';
       case 'gltf-version-unsupported':
@@ -313,6 +316,8 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         return 'lod';
       case 'gltf-material-transmission-invalid':
         return 'material-transmission-invalid';
+      case 'gltf-material-physical-invalid':
+        return 'material-physical-invalid';
       case 'gltf-accessor-type-mismatch':
         return 'accessor';
       case 'gltf-texture-load-failed':
@@ -350,6 +355,7 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
       case 'gltf-mesh-bridge-invalid':
         return 'mesh-bridge-invalid';
     }
+    throw new Error(`unhandled glTF error code: ${code}`);
   }
 
   function buildErrSample(code: GltfErrorCode): GltfError {
@@ -371,6 +377,13 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
           reason: 'range',
           actual: 2,
         });
+      case 'gltf-material-physical-invalid':
+        return gltfErr(code, {
+          extension: 'KHR_materials_clearcoat',
+          field: 'clearcoatFactor',
+          reason: 'range',
+          actual: 2,
+        });
       case 'gltf-accessor-type-mismatch':
         return gltfErr(code, { accessorIndex: 0, reason: 'sparse' });
       case 'gltf-texture-load-failed':
@@ -452,6 +465,7 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
       case 'gltf-mesh-bridge-invalid':
         return gltfErr(code, { reason: 'empty-input', primitiveCount: 0 });
     }
+    throw new Error(`unhandled glTF error code: ${code}`);
   }
 
   describe('errors.test.ts', () => {
@@ -460,8 +474,8 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
     });
 
     describe('GltfErrorCode roster', () => {
-      it('GLTF_ERROR_HINTS exposes exactly 24 keys', () => {
-        expect(Object.keys(GLTF_ERROR_HINTS).length).toBe(24);
+      it('GLTF_ERROR_HINTS exposes exactly 25 keys', () => {
+        expect(Object.keys(GLTF_ERROR_HINTS).length).toBe(25);
       });
 
       it.each(ALL_CODES)('hint for %s is a non-empty string', (code) => {
@@ -1934,6 +1948,25 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         expect(map.get(0)).toBe('srgb');
       });
 
+      it('physical extension texture slots keep their glTF color domains', () => {
+        const map = deriveTextureColorSpace({
+          imageCount: 4,
+          textures: [{ source: 0 }, { source: 1 }, { source: 2 }, { source: 3 }],
+          materials: [
+            {
+              sheenColorTexture: 0,
+              specularColorTexture: 1,
+              anisotropyTexture: 2,
+              thicknessTexture: 3,
+            },
+          ],
+        });
+        expect(map.get(0)).toBe('srgb');
+        expect(map.get(1)).toBe('srgb');
+        expect(map.get(2)).toBe('linear');
+        expect(map.get(3)).toBe('linear');
+      });
+
       it('occlusionTexture image classifies as linear', () => {
         const map = deriveTextureColorSpace({
           imageCount: 1,
@@ -2023,12 +2056,20 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         stderrSpy.mockRestore();
       });
 
-      it('v1 allowlist contains EXT_mesh_gpu_instancing (literal)', () => {
+      it('public allowlist contains every currently supported extension (literal)', () => {
         expect(EXTENSION_ALLOWLIST).toEqual([
           'EXT_mesh_gpu_instancing',
           'EXT_meshopt_compression',
-          'MSFT_lod',
-          'MSFT_screencoverage',
+          'KHR_lights_punctual',
+          'KHR_texture_transform',
+          'KHR_materials_transmission',
+          'KHR_materials_ior',
+          'KHR_materials_volume',
+          'KHR_materials_clearcoat',
+          'KHR_materials_anisotropy',
+          'KHR_materials_sheen',
+          'KHR_materials_iridescence',
+          'KHR_materials_specular',
         ]);
       });
 
@@ -2095,6 +2136,11 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         'KHR_materials_transmission',
         'KHR_materials_ior',
         'KHR_materials_volume',
+        'KHR_materials_clearcoat',
+        'KHR_materials_anisotropy',
+        'KHR_materials_sheen',
+        'KHR_materials_iridescence',
+        'KHR_materials_specular',
       ])('%s in extensionsRequired routes ok (supported)', (extension) => {
         const result = checkExtensions({ extensionsRequired: [extension] });
         expect(result.ok).toBe(true);

package/src/__tests__/material-pack-refs.integration.test.ts

@@ -67,4 +67,57 @@ describe('glTF material Pack refs', () => {
       'sampler-6',
     ]);
   });
+
+  it('keeps the five physical extension texture edges in producer slot order', () => {
+    const material = {
+      name: 'PhysicalPackMaterial',
+      baseColorFactor: [1, 1, 1, 1],
+      metallicFactor: 0,
+      roughnessFactor: 0.5,
+      clearcoatNormalTexture: { texture: 0, sampler: 0 },
+      anisotropyTexture: { texture: 1, sampler: 1 },
+      sheenColorTexture: { texture: 2, sampler: 2 },
+      iridescenceTexture: { texture: 3, sampler: 3 },
+      specularColorTexture: { texture: 4, sampler: 4 },
+    } as unknown as GltfMaterialIr;
+    const doc = {
+      textures: [
+        { source: 0, sampler: 0 },
+        { source: 1, sampler: 1 },
+        { source: 2, sampler: 2 },
+        { source: 3, sampler: 3 },
+        { source: 4, sampler: 4 },
+      ],
+    } as unknown as GltfDoc;
+    const refs = materialRefsForPack(
+      material,
+      doc,
+      new Map([
+        [0, 'clearcoat-normal-texture'],
+        [1, 'anisotropy-texture'],
+        [2, 'sheen-color-texture'],
+        [3, 'iridescence-texture'],
+        [4, 'specular-color-texture'],
+      ]),
+      new Map([
+        [0, 'clearcoat-normal-sampler'],
+        [1, 'anisotropy-sampler'],
+        [2, 'sheen-color-sampler'],
+        [3, 'iridescence-sampler'],
+        [4, 'specular-color-sampler'],
+      ]),
+    );
+    expect(refs.map((ref) => ref.guid)).toEqual([
+      'clearcoat-normal-texture',
+      'clearcoat-normal-sampler',
+      'anisotropy-texture',
+      'anisotropy-sampler',
+      'sheen-color-texture',
+      'sheen-color-sampler',
+      'iridescence-texture',
+      'iridescence-sampler',
+      'specular-color-texture',
+      'specular-color-sampler',
+    ]);
+  });
 });

package/src/__tests__/parse-gltf.unit.test.ts

@@ -162,6 +162,35 @@ describe('glTF transmission material IR', () => {
   });
 });
 
+describe('glTF specular material IR', () => {
+  it('projects specularTexture through the alpha channel', () => {
+    const result = parseMaterialIr(
+      {
+        extensions: {
+          KHR_materials_specular: {
+            specularFactor: 0.75,
+            specularTexture: { index: 0 },
+            specularColorFactor: [0.8, 0.7, 0.6],
+            specularColorTexture: { index: 1 },
+          },
+        },
+      },
+      [{ source: 0 }, { source: 1 }],
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toMatchObject({
+      specularFactor: 0.75,
+      specularChannel: 3,
+      specularTexture: { texture: 0 },
+      specularColorFactor: [0.8, 0.7, 0.6],
+      specularColorChannel: [0, 1, 2],
+      specularColorTexture: { texture: 1 },
+    });
+  });
+});
+
 describe('glTF required extension admission', () => {
   it.each([
     'KHR_materials_transmission',
@@ -183,7 +212,6 @@ describe('glTF required extension admission', () => {
     expect(result.value.diagnostics.unsupportedExtensions).toEqual([]);
   });
 });
-
 describe('glTF COLOR_0 importer carrier', () => {
   it('publishes normalized VEC3 FLOAT colors as importer-owned RGBA', async () => {
     const fixture = JSON.parse(

package/src/__tests__/physical-clearcoat.unit.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import { validateMaterialTangentInputs } from '../bridge.js';
+import { checkExtensions } from '../check-extensions.js';
+import { parseMaterial } from '../material/parse-material.js';
+
+describe('KHR_materials_clearcoat projection', () => {
+  it('projects factor, R/G textures, coat normal RG, scale, and transform facts', () => {
+    const result = parseMaterial(
+      {
+        extensions: {
+          KHR_materials_clearcoat: {
+            clearcoatFactor: 0.75,
+            clearcoatTexture: {
+              index: 0,
+              texCoord: 2,
+              extensions: { KHR_texture_transform: { offset: [0.25, 0.5] } },
+            },
+            clearcoatRoughnessFactor: 0.25,
+            clearcoatRoughnessTexture: { index: 1, texCoord: 3 },
+            clearcoatNormalTexture: { index: 2, texCoord: 4, scale: 0.5 },
+          },
+        },
+      } as never,
+      [{ source: 0 }, { source: 1 }, { source: 2 }],
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatchObject({
+        clearcoatFactor: 0.75,
+        clearcoatChannel: 0,
+        clearcoatRoughnessFactor: 0.25,
+        clearcoatRoughnessChannel: 1,
+        clearcoatNormalTexture: { texture: 2, texCoord: 4, scale: 0.5 },
+        clearcoatNormalChannel: [0, 1],
+      });
+      expect((result.value as unknown as Record<string, unknown>).clearcoatTexture).toMatchObject({
+        texture: 0,
+        texCoord: 2,
+        transform: { offset: [0.25, 0.5] },
+      });
+    }
+  });
+
+  it('admits the clearcoat extension as a required extension', () => {
+    const result = checkExtensions({ extensionsRequired: ['KHR_materials_clearcoat'] });
+    expect(result.ok).toBe(true);
+  });
+
+  it('reports tangent admission with material, mesh, layer, UV, and attributes', () => {
+    const result = validateMaterialTangentInputs(
+      {
+        name: 'coat',
+        baseColorFactor: [1, 1, 1, 1],
+        metallicFactor: 0,
+        roughnessFactor: 0.5,
+        clearcoatNormalTexture: { texture: 0 },
+      } as never,
+      {
+        name: 'mesh',
+        positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+        texcoord0: new Float32Array([0, 0, 0, 0, 0, 0]),
+        materialIndex: 0,
+        meshIndex: 0,
+        indices: new Uint32Array([0, 1, 2]),
+      },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('material-tangent-required');
+      expect(result.error.detail).toMatchObject({
+        material: 'coat',
+        mesh: 'mesh',
+        layer: 'clearcoat',
+        uv: 'TEXCOORD_0',
+        attributes: ['NORMAL', 'TEXCOORD_0', 'TANGENT'],
+      });
+    }
+  });
+
+  it('requires a tangent frame for scalar-only anisotropy', () => {
+    const result = validateMaterialTangentInputs(
+      {
+        name: 'anisotropic-scalar',
+        baseColorFactor: [1, 1, 1, 1],
+        metallicFactor: 0,
+        roughnessFactor: 0.5,
+        anisotropyStrength: 0.4,
+        anisotropyRotation: 0,
+      } as never,
+      {
+        name: 'mesh-without-frame',
+        positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+        materialIndex: 0,
+        meshIndex: 0,
+        indices: new Uint32Array([0, 1, 2]),
+      },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('material-tangent-required');
+      expect(result.error.detail).toMatchObject({
+        material: 'anisotropic-scalar',
+        mesh: 'mesh-without-frame',
+        layer: 'anisotropy',
+        uv: 'TEXCOORD_0',
+        attributes: ['NORMAL', 'TEXCOORD_0', 'TANGENT'],
+      });
+    }
+  });
+});