@forgeax/engine-gltf 0.1.21 → 0.1.24

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

@@ -162,6 +162,56 @@ 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',
+    'KHR_materials_ior',
+    'KHR_materials_volume',
+  ])('accepts %s through the parse path', async (extension) => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        extensionsUsed: [extension],
+        extensionsRequired: [extension],
+      },
+      noopLoader,
+      `/required-${extension}.gltf`,
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    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'],
+      });
+    }
+  });
+});

package/src/__tests__/physical-material-import.integration.test.ts

@@ -0,0 +1,239 @@
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import {
+  ImporterRegistry,
+  type ImportRunnerFs,
+  type RunImportMeta,
+  runImport,
+} from '@forgeax/engine-import';
+import type { TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { gltfImporter } from '../gltf-importer.js';
+
+const SOURCE = 'physical-material.gltf';
+const TINY_PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC';
+
+const MATERIAL_GUID = '019f0000-0000-7000-8000-000000000100';
+const TEXTURE_GUIDS = [
+  '019f0000-0000-7000-8000-000000000101',
+  '019f0000-0000-7000-8000-000000000102',
+  '019f0000-0000-7000-8000-000000000103',
+  '019f0000-0000-7000-8000-000000000104',
+  '019f0000-0000-7000-8000-000000000105',
+] as const;
+const SAMPLER_GUIDS = [
+  '019f0000-0000-7000-8000-000000000106',
+  '019f0000-0000-7000-8000-000000000107',
+  '019f0000-0000-7000-8000-000000000108',
+  '019f0000-0000-7000-8000-000000000109',
+  '019f0000-0000-7000-8000-00000000010a',
+] as const;
+
+function dataUri(): string {
+  return `data:image/png;base64,${TINY_PNG_BASE64}`;
+}
+
+function sourceBytes(): Uint8Array {
+  const textures = TEXTURE_GUIDS.map((_guid, index) => ({ source: index, sampler: index }));
+  return new TextEncoder().encode(
+    JSON.stringify({
+      asset: { version: '2.0' },
+      extensionsUsed: [
+        'KHR_materials_clearcoat',
+        'KHR_materials_anisotropy',
+        'KHR_materials_sheen',
+        'KHR_materials_iridescence',
+        'KHR_materials_specular',
+      ],
+      materials: [
+        {
+          name: 'PhysicalSurface',
+          pbrMetallicRoughness: {
+            baseColorFactor: [0.8, 0.7, 0.6, 1],
+            metallicFactor: 0.1,
+            roughnessFactor: 0.35,
+          },
+          extensions: {
+            KHR_materials_clearcoat: {
+              clearcoatFactor: 0.75,
+              clearcoatRoughnessFactor: 0.2,
+              clearcoatNormalTexture: { index: 0 },
+            },
+            KHR_materials_anisotropy: {
+              anisotropyStrength: 0.5,
+              anisotropyRotation: 0.25,
+              anisotropyTexture: { index: 1 },
+            },
+            KHR_materials_sheen: {
+              sheenColorFactor: [0.2, 0.1, 0.05],
+              sheenRoughnessFactor: 0.3,
+              sheenColorTexture: { index: 2 },
+            },
+            KHR_materials_iridescence: {
+              iridescenceFactor: 0.6,
+              iridescenceIor: 1.4,
+              iridescenceThicknessMinimum: 120,
+              iridescenceThicknessMaximum: 380,
+              iridescenceTexture: { index: 3 },
+            },
+            KHR_materials_specular: {
+              specularFactor: 0.8,
+              specularColorFactor: [0.9, 0.85, 0.75],
+              specularColorTexture: { index: 4 },
+            },
+          },
+        },
+      ],
+      textures,
+      samplers: [{}, {}, {}, {}, {}],
+      images: TEXTURE_GUIDS.map(() => ({ uri: dataUri(), mimeType: 'image/png' })),
+      scenes: [],
+      nodes: [],
+      meshes: [],
+    }),
+  );
+}
+
+function meta(): RunImportMeta {
+  return {
+    importer: 'gltf',
+    source: SOURCE,
+    subAssets: [
+      {
+        guid: MATERIAL_GUID,
+        sourceIndex: 0,
+        sourceKey: 'material/physical-surface',
+        kind: 'material',
+      },
+      ...TEXTURE_GUIDS.map((guid, sourceIndex) => ({
+        guid,
+        sourceIndex,
+        sourceKey: `texture/${sourceIndex}`,
+        kind: 'texture' as const,
+      })),
+      ...SAMPLER_GUIDS.map((guid, sourceIndex) => ({
+        guid,
+        sourceIndex,
+        sourceKey: `sampler/${sourceIndex}`,
+        kind: 'sampler' as const,
+      })),
+    ],
+  };
+}
+
+function decodeBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function fs(): ImportRunnerFs {
+  return {
+    readSource: async (sourcePath) =>
+      sourcePath === SOURCE
+        ? { ok: true, value: sourceBytes() }
+        : { ok: false, error: new Error(`unexpected source path ${sourcePath}`) },
+    decodeImage: async (_bytes, _mimeType, settings) => {
+      const colorSpace = settings.colorSpace === 'srgb' ? 'srgb' : 'linear';
+      const texture: TextureAsset = {
+        kind: 'texture',
+        shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
+        format: colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm',
+        data: new Uint8Array([128, 96, 64, 255]),
+        colorSpace,
+        mips: { kind: 'generate' },
+      };
+      return {
+        ok: true,
+        value: {
+          texture,
+          bytes: decodeBase64(TINY_PNG_BASE64),
+          mediaType: 'image/png',
+          assetCodec: { name: 'rgba8', version: '1' },
+        },
+      };
+    },
+  };
+}
+
+describe('glTF physical material importer route', () => {
+  it('carries all five KHR layers from importer through pack and runtime material parsing', async () => {
+    const importers = new ImporterRegistry();
+    importers.register(gltfImporter);
+
+    const result = await runImport(meta(), importers, fs());
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value)
+      throw new Error('physical import did not publish a pack');
+
+    expect(result.value.pack.assets).toHaveLength(11);
+    expect(result.value.cookProducts).toHaveLength(11);
+    expect(result.value.cookProducts.every((product) => product.receipt !== undefined)).toBe(true);
+
+    const material = result.value.pack.assets.find((asset) => asset.guid === MATERIAL_GUID);
+    if (material === undefined) throw new Error('physical material pack row missing');
+    expect(material.refs).toEqual([
+      TEXTURE_GUIDS[0],
+      SAMPLER_GUIDS[0],
+      TEXTURE_GUIDS[1],
+      SAMPLER_GUIDS[1],
+      TEXTURE_GUIDS[2],
+      SAMPLER_GUIDS[2],
+      TEXTURE_GUIDS[3],
+      SAMPLER_GUIDS[3],
+      TEXTURE_GUIDS[4],
+      SAMPLER_GUIDS[4],
+    ]);
+
+    const payload = material.payload;
+    const parameterNames = new Set(
+      (payload.parameters as readonly { name: string }[]).map((parameter) => parameter.name),
+    );
+    for (const name of [
+      'clearcoat',
+      'anisotropyStrength',
+      'sheenColor',
+      'iridescence',
+      'specular',
+      'clearcoatNormalTexture',
+      'anisotropyTexture',
+      'sheenColorTexture',
+      'iridescenceTexture',
+      'specularColorTexture',
+    ]) {
+      expect(parameterNames.has(name)).toBe(true);
+    }
+
+    const runtime = new AssetRegistry({
+      findMaterialArtifact: () => ({ ok: false, error: new Error('shader registry not wired') }),
+    } as never);
+    const parsed = runtime.parseAndReturnAsset({
+      kind: material.kind,
+      payload,
+      refs: [...material.refs],
+    });
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.value.asset.kind).toBe('material');
+    const values = (parsed.value.asset as { values?: Record<string, unknown> }).values ?? {};
+    expect(values.clearcoatNormalTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[0],
+      sampler: SAMPLER_GUIDS[0],
+    });
+    expect(values.anisotropyTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[1],
+      sampler: SAMPLER_GUIDS[1],
+    });
+    expect(values.sheenColorTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[2],
+      sampler: SAMPLER_GUIDS[2],
+    });
+    expect(values.iridescenceTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[3],
+      sampler: SAMPLER_GUIDS[3],
+    });
+    expect(values.specularColorTexture).toMatchObject({
+      texture: TEXTURE_GUIDS[4],
+      sampler: SAMPLER_GUIDS[4],
+    });
+  });
+});

package/src/__tests__/source-key-producer.integration.test.ts

@@ -86,7 +86,9 @@ describe('glTF producer source-key boundary', () => {
     expect(result.ok).toBe(false);
     if (result.ok) return;
     expect(result.error.code).toBe('duplicate-source-key');
-    expect(result.error.detail.sourceIndices).toEqual([0, 1]);
+    expect((result.error.detail as { sourceIndices: readonly number[] }).sourceIndices).toEqual([
+      0, 1,
+    ]);
   });
 
   it('applies the same preflight to duplicate material names', () => {
@@ -95,7 +97,9 @@ describe('glTF producer source-key boundary', () => {
     expect(result.ok).toBe(false);
     if (result.ok) return;
     expect(result.error.code).toBe('duplicate-source-key');
-    expect(result.error.detail.sourceIndices).toEqual([0, 1]);
+    expect((result.error.detail as { sourceIndices: readonly number[] }).sourceIndices).toEqual([
+      0, 1,
+    ]);
   });
 
   it('publishes producer-valid output when semantic identity is unique', () => {