@forgeax/engine-gltf 0.1.7 → 0.1.20

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

@@ -278,6 +278,7 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
     'gltf-version-unsupported',
     'gltf-buffer-out-of-bounds',
     'gltf-extension-unsupported',
+    'gltf-material-transmission-invalid',
     'gltf-accessor-type-mismatch',
     'gltf-texture-load-failed',
     'gltf-meta-missing',
@@ -308,6 +309,8 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         return 'oob';
       case 'gltf-extension-unsupported':
         return 'ext';
+      case 'gltf-material-transmission-invalid':
+        return 'material-transmission-invalid';
       case 'gltf-accessor-type-mismatch':
         return 'accessor';
       case 'gltf-texture-load-failed':
@@ -357,6 +360,13 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         return gltfErr(code, { accessor: 0, byteOffset: 0, byteLength: 0, bufferIndex: 0 });
       case 'gltf-extension-unsupported':
         return gltfErr(code, { extension: 'KHR_x', source: 'extensionsRequired' });
+      case 'gltf-material-transmission-invalid':
+        return gltfErr(code, {
+          extension: 'KHR_materials_transmission',
+          field: 'transmissionFactor',
+          reason: 'range',
+          actual: 2,
+        });
       case 'gltf-accessor-type-mismatch':
         return gltfErr(code, { accessorIndex: 0, reason: 'sparse' });
       case 'gltf-texture-load-failed':
@@ -446,8 +456,8 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
     });
 
     describe('GltfErrorCode roster', () => {
-      it('GLTF_ERROR_HINTS exposes exactly 22 keys', () => {
-        expect(Object.keys(GLTF_ERROR_HINTS).length).toBe(22);
+      it('GLTF_ERROR_HINTS exposes exactly 23 keys', () => {
+        expect(Object.keys(GLTF_ERROR_HINTS).length).toBe(23);
       });
 
       it.each(ALL_CODES)('hint for %s is a non-empty string', (code) => {
@@ -1219,12 +1229,11 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
 
   const MOCK_TEXTURE: TextureAsset = {
     kind: 'texture',
-    width: 1,
-    height: 1,
+    shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
     format: 'rgba8unorm-srgb',
     data: new Uint8Array([0, 0, 0, 0]),
     colorSpace: 'srgb',
-    mipmap: true,
+    mips: { kind: 'generate' },
   };
 
   function buildSelfContainedGltfWithDataUriImage(): Uint8Array {
@@ -1371,12 +1380,11 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
 
   const EXT_MOCK_TEXTURE: TextureAsset = {
     kind: 'texture',
-    width: 1,
-    height: 1,
+    shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
     format: 'rgba8unorm-srgb',
     data: new Uint8Array([200, 100, 50, 255]),
     colorSpace: 'srgb',
-    mipmap: true,
+    mips: { kind: 'generate' },
   };
 
   interface SiblingCall {
@@ -1481,12 +1489,11 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
 
   const GLB_MOCK_TEXTURE: TextureAsset = {
     kind: 'texture',
-    width: 1,
-    height: 1,
+    shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
     format: 'rgba8unorm-srgb',
     data: new Uint8Array([255, 128, 64, 255]),
     colorSpace: 'srgb',
-    mipmap: true,
+    mips: { kind: 'generate' },
   };
 
   interface GlbDecodeCall {
@@ -2016,7 +2023,7 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         expect(EXTENSION_ALLOWLIST).toEqual(['EXT_mesh_gpu_instancing', 'EXT_meshopt_compression']);
       });
 
-      it('(a) rejects extensionsRequired entries outside the allowlist', () => {
+      it('(a) rejects unsupported extensionsRequired entries', () => {
         const result = checkExtensions({
           extensionsRequired: ['KHR_materials_pbrSpecularGlossiness'],
         });
@@ -2029,7 +2036,9 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
       });
 
       it('(b) accepts extensionsUsed (not required) into diagnostics list with no stderr', () => {
-        const result = checkExtensions({ extensionsUsed: ['KHR_materials_pbrSpecularGlossiness'] });
+        const result = checkExtensions({
+          extensionsUsed: ['KHR_materials_pbrSpecularGlossiness', 'KHR_materials_transmission'],
+        });
         expect(result.ok).toBe(true);
         if (!result.ok) return;
         expect(result.value.unsupportedUsed).toEqual(['KHR_materials_pbrSpecularGlossiness']);
@@ -2073,6 +2082,18 @@ function unwrapReimport(result: ReturnType<typeof reimportReuseMeta>) {
         expect(stderrSpy).not.toHaveBeenCalled();
       });
 
+      it.each([
+        'KHR_materials_transmission',
+        'KHR_materials_ior',
+        'KHR_materials_volume',
+      ])('%s in extensionsRequired routes ok (supported)', (extension) => {
+        const result = checkExtensions({ extensionsRequired: [extension] });
+        expect(result.ok).toBe(true);
+        if (!result.ok) return;
+        expect(result.value.unsupportedUsed).toEqual([]);
+        expect(stderrSpy).not.toHaveBeenCalled();
+      });
+
       it('EXT_mesh_gpu_instancing in extensionsUsed (not required) routes ok with no warn', () => {
         const result = checkExtensions({ extensionsUsed: ['EXT_mesh_gpu_instancing'] });
         expect(result.ok).toBe(true);

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

@@ -14,6 +14,8 @@ describe('glTF material Pack refs', () => {
       normalTexture: { texture: 2, sampler: 2 },
       occlusionTexture: { texture: 3, sampler: 3 },
       emissiveTexture: { texture: 4, sampler: 4 },
+      transmissionTexture: { texture: 5, sampler: 5 },
+      thicknessTexture: { texture: 6, sampler: 6 },
     } as unknown as GltfMaterialIr;
     const doc = {
       textures: [
@@ -22,6 +24,8 @@ describe('glTF material Pack refs', () => {
         { source: 2, sampler: 2 },
         { source: 3, sampler: 3 },
         { source: 4, sampler: 4 },
+        { source: 5, sampler: 5 },
+        { source: 6, sampler: 6 },
       ],
     } as unknown as GltfDoc;
     const refs = materialRefsForPack(
@@ -33,6 +37,8 @@ describe('glTF material Pack refs', () => {
         [2, 'texture-2'],
         [3, 'texture-3'],
         [4, 'texture-4'],
+        [5, 'texture-5'],
+        [6, 'texture-6'],
       ]),
       new Map([
         [0, 'sampler-0'],
@@ -40,6 +46,8 @@ describe('glTF material Pack refs', () => {
         [2, 'sampler-2'],
         [3, 'sampler-3'],
         [4, 'sampler-4'],
+        [5, 'sampler-5'],
+        [6, 'sampler-6'],
       ]),
     );
     expect(refs.map((ref) => ref.guid)).toEqual([
@@ -53,6 +61,10 @@ describe('glTF material Pack refs', () => {
       'sampler-3',
       'texture-4',
       'sampler-4',
+      'texture-5',
+      'sampler-5',
+      'texture-6',
+      'sampler-6',
     ]);
   });
 });

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

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import { dataUriBase64Payload, decodeBase64 } from '../data-uri.js';
+import { parseMaterial as parseMaterialIr } from '../material/parse-material.js';
 import { parseGltf } from '../parse-gltf.js';
 
 const noopLoader = async (_uri: string) => new ArrayBuffer(0);
@@ -41,6 +42,126 @@ describe('glTF MASK alpha cutoff parsing', () => {
   });
 });
 
+describe('glTF transmission material IR', () => {
+  it('rejects BLEND materials with effective transmission as a structured error', () => {
+    const result = parseMaterialIr(
+      {
+        alphaMode: 'BLEND',
+        extensions: { KHR_materials_transmission: { transmissionFactor: 1 } },
+      },
+      [],
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('gltf-material-transmission-invalid');
+    expect(result.error.detail).toEqual({
+      extension: 'KHR_materials_transmission',
+      field: 'alphaMode',
+      reason: 'blend',
+      actual: 'BLEND',
+    });
+  });
+
+  it('projects transmission, IOR, volume, channel, and texture transform facts', async () => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        extensionsUsed: ['KHR_materials_transmission', 'KHR_materials_ior', 'KHR_materials_volume'],
+        materials: [
+          {
+            pbrMetallicRoughness: {
+              baseColorTexture: {
+                index: 0,
+                texCoord: 1,
+                extensions: {
+                  KHR_texture_transform: {
+                    offset: [0.25, 0.5],
+                    rotation: 0.25,
+                    scale: [2, 3],
+                  },
+                },
+              },
+            },
+            extensions: {
+              KHR_materials_transmission: {
+                transmissionFactor: 0.75,
+                transmissionTexture: { index: 1, texCoord: 2 },
+              },
+              KHR_materials_ior: { ior: 1.33 },
+              KHR_materials_volume: {
+                thicknessFactor: 0.04,
+                thicknessTexture: { index: 2, texCoord: 3 },
+                attenuationColor: [0.2, 0.4, 0.8],
+                attenuationDistance: Number.POSITIVE_INFINITY,
+              },
+            },
+          },
+        ],
+        textures: [
+          { sampler: 7, source: 0 },
+          { sampler: 8, source: 1 },
+          { sampler: 9, source: 2 },
+        ],
+      },
+      noopLoader,
+      '/material-transmission.gltf',
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.materials[0]).toMatchObject({
+      transmissionFactor: 0.75,
+      transmissionTexture: { texture: 1, sampler: 8, texCoord: 2 },
+      ior: 1.33,
+      thicknessFactor: 0.04,
+      thicknessTexture: { texture: 2, sampler: 9, texCoord: 3 },
+      attenuationColor: [0.2, 0.4, 0.8],
+    });
+    expect(result.value.materials[0]).not.toHaveProperty('attenuationDistance');
+    expect(result.value.materials[0]?.baseColorTexture).toMatchObject({
+      transform: { offset: [0.25, 0.5], rotation: 0.25, scale: [2, 3] },
+    });
+  });
+
+  it('rejects an IOR at the non-positive boundary', async () => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        extensionsUsed: ['KHR_materials_ior'],
+        materials: [{ extensions: { KHR_materials_ior: { ior: 0 } } }],
+      },
+      noopLoader,
+      '/material-invalid-ior.gltf',
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('gltf-material-transmission-invalid');
+    expect(result.error.detail).toMatchObject({ extension: 'KHR_materials_ior', field: 'ior' });
+  });
+
+  it('accepts all transmission material required extensions through the parse path', async () => {
+    const result = await parseGltf(
+      {
+        asset: { version: '2.0' },
+        extensionsUsed: ['KHR_materials_transmission', 'KHR_materials_ior', 'KHR_materials_volume'],
+        extensionsRequired: [
+          'KHR_materials_transmission',
+          'KHR_materials_ior',
+          'KHR_materials_volume',
+        ],
+      },
+      noopLoader,
+      '/material-required-transmission.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__/transmission-pack-carrier.integration.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { toMaterialAsset } from '../bridge.js';
+import { parseGltf, toAssetPack } from '../parse-gltf.js';
+
+const noopLoader = async (_uri: string) => new ArrayBuffer(0);
+
+describe('glTF transmission carrier route', () => {
+  it('keeps required transmission extensions through parse, pack identity, and Standard bridge', async () => {
+    const source = {
+      asset: { version: '2.0' },
+      extensionsRequired: [
+        'KHR_materials_transmission',
+        'KHR_materials_ior',
+        'KHR_materials_volume',
+      ],
+      extensionsUsed: ['KHR_materials_transmission', 'KHR_materials_ior', 'KHR_materials_volume'],
+      materials: [
+        {
+          name: 'TransmissionSphere',
+          pbrMetallicRoughness: {
+            baseColorFactor: [0.76, 0.9, 1, 1],
+            metallicFactor: 0,
+            roughnessFactor: 0.06,
+          },
+          extensions: {
+            KHR_materials_transmission: { transmissionFactor: 1 },
+            KHR_materials_ior: { ior: 1.45 },
+            KHR_materials_volume: {
+              thicknessFactor: 0.12,
+              attenuationColor: [0.9, 0.97, 1],
+              attenuationDistance: 3,
+            },
+          },
+        },
+      ],
+    };
+
+    const parsed = await parseGltf(source, noopLoader, 'carrier/transmission.gltf');
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+
+    const material = parsed.value.materials[0];
+    if (material === undefined) throw new Error('transmission carrier did not parse a material');
+    expect(material).toMatchObject({
+      name: 'TransmissionSphere',
+      transmissionFactor: 1,
+      ior: 1.45,
+      thicknessFactor: 0.12,
+      attenuationColor: [0.9, 0.97, 1],
+      attenuationDistance: 3,
+    });
+
+    const pack = toAssetPack(parsed.value, undefined, 'transmission.gltf');
+    expect(pack.ok).toBe(true);
+    if (!pack.ok) return;
+    expect(pack.value.subAssets).toEqual([
+      expect.objectContaining({
+        kind: 'material',
+        name: 'TransmissionSphere',
+        sourceKey: 'material:TransmissionSphere',
+      }),
+    ]);
+
+    const bridged = toMaterialAsset(material);
+    const pass = bridged.passes?.[0];
+    if (pass === undefined) throw new Error('transmission bridge did not emit a Forward pass');
+    if (pass.renderState === undefined)
+      throw new Error('transmission bridge pass has no render state');
+    expect(pass.program.module).toBe('forgeax::default-standard-pbr');
+    expect(pass.renderState.queue).toBe(2000);
+    expect(bridged.values).toMatchObject({
+      baseColor: [0.76, 0.9, 1, 1],
+      metallic: 0,
+      roughness: 0.06,
+      transmission: 1,
+      ior: 1.45,
+      thickness: 0.12,
+      attenuationColor: [0.9, 0.97, 1],
+      attenuationDistance: 3,
+    });
+  });
+});

package/src/bridge.ts

@@ -776,7 +776,9 @@ type MaterialTextureSlot =
   | 'metallicRoughnessTexture'
   | 'normalTexture'
   | 'occlusionTexture'
-  | 'emissiveTexture';
+  | 'emissiveTexture'
+  | 'transmissionTexture'
+  | 'thicknessTexture';
 
 function textureValue(
   info: GltfTextureInfoIr | number | undefined,
@@ -830,6 +832,8 @@ export function validateMaterialUvSets(
     ['normalTexture', mat.normalTexture],
     ['occlusionTexture', mat.occlusionTexture],
     ['emissiveTexture', mat.emissiveTexture],
+    ['transmissionTexture', mat.transmissionTexture],
+    ['thicknessTexture', mat.thicknessTexture],
   ];
   for (const [slot, rawBinding] of slots) {
     const binding = textureInfo(rawBinding);
@@ -867,6 +871,8 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
     ['normalTexture', mat.normalTexture],
     ['occlusionTexture', mat.occlusionTexture],
     ['emissiveTexture', mat.emissiveTexture],
+    ['transmissionTexture', mat.transmissionTexture],
+    ['thicknessTexture', mat.thicknessTexture],
   ];
   for (const [slot, info] of textureSlots) {
     const value = textureValue(info, slot, ctx);
@@ -875,6 +881,11 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
   if (mat.occlusionTexture !== undefined && values.occlusionStrength === undefined) {
     values.occlusionStrength = 1;
   }
+  if (mat.transmissionFactor !== undefined) values.transmission = mat.transmissionFactor;
+  if (mat.ior !== undefined) values.ior = mat.ior;
+  if (mat.thicknessFactor !== undefined) values.thickness = mat.thicknessFactor;
+  if (mat.attenuationColor !== undefined) values.attenuationColor = mat.attenuationColor;
+  if (mat.attenuationDistance !== undefined) values.attenuationDistance = mat.attenuationDistance;
 
   const module = ctx?.skinned === true ? 'forgeax::pbr-skin' : 'forgeax::default-standard-pbr';
 

package/src/check-extensions.ts

@@ -1,13 +1,15 @@
 // check-extensions.ts - KHR / vendor extension gate.
 //
-// v1 required-extension support contains EXT_mesh_gpu_instancing,
-// KHR_lights_punctual, and KHR_texture_transform. The exported legacy list remains the original mesh
-// extension list for callers that display the v1 mesh-only surface.
+// Required-extension support contains EXT_mesh_gpu_instancing,
+// EXT_meshopt_compression, KHR_lights_punctual, KHR_texture_transform, and
+// the KHR material transmission/IOR/volume extensions. The exported legacy
+// list remains the original mesh extension list for callers that display the
+// v1 mesh-only surface.
 // (feat-20260518-gltf-instancing-and-name-component plan-strategy section
 // 2 D-1 / D-3). Any extension listed in `extensionsRequired[]` outside
-// this allowlist triggers `gltf-extension-unsupported` (hard fail).
+// the supported extension set triggers `gltf-extension-unsupported` (hard fail).
 // Extensions listed in `extensionsUsed[]` (but not required and not in
-// allowlist) are recorded in `importSettings.diagnostics
+// supported extension set) are recorded in `importSettings.diagnostics
 // .unsupportedExtensions` so AI users can observe them downstream — and
 // nothing else: `extensionsUsed` is purely informational per the glTF spec
 // (only `extensionsRequired` is binding), and exporters routinely
@@ -16,12 +18,12 @@
 // diagnostics list is the single channel (no `console.error`).
 //
 // Future expansion (KHR_materials_unlit, ...) extends
-// `EXTENSION_ALLOWLIST` in place; each addition lands under its own feat-*
+// `SUPPORTED_EXTENSIONS` in place; each addition lands under its own feat-*
 // loop with breaking-change registry entry.
 
 import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
 
-/** Hard-coded v1 allowlist (plan-strategy decision section 2 D-1 / D-3). */
+/** Legacy v1 mesh-only list kept for callers that display that surface. */
 export const EXTENSION_ALLOWLIST: readonly string[] = [
   'EXT_mesh_gpu_instancing',
   'EXT_meshopt_compression',
@@ -30,10 +32,13 @@ const SUPPORTED_EXTENSIONS: readonly string[] = [
   ...EXTENSION_ALLOWLIST,
   'KHR_lights_punctual',
   'KHR_texture_transform',
+  'KHR_materials_transmission',
+  'KHR_materials_ior',
+  'KHR_materials_volume',
 ];
 
 export interface ExtensionsCheckResult {
-  /** Names listed in extensionsUsed but not in the allowlist. */
+  /** Names listed in extensionsUsed but not in the supported extension set. */
   readonly unsupportedUsed: readonly string[];
 }
 
@@ -43,7 +48,7 @@ export interface GltfExtensionsJson {
 }
 
 /**
- * Validate the glTF JSON's extension declarations against the v1 allowlist.
+ * Validate the glTF JSON's extension declarations against the supported set.
  *
  * Returns:
  *   - `Result.err(gltf-extension-unsupported)` for the FIRST entry of

package/src/errors.ts

@@ -60,6 +60,13 @@ export interface GltfExtensionUnsupportedDetail {
   readonly source: 'extensionsRequired' | 'extensionsUsed';
 }
 
+export interface GltfMaterialTransmissionInvalidDetail {
+  readonly extension: 'KHR_materials_transmission' | 'KHR_materials_ior' | 'KHR_materials_volume';
+  readonly field: string;
+  readonly reason: 'type' | 'range' | 'non-finite' | 'blend';
+  readonly actual?: unknown;
+}
+
 /** `gltf-accessor-type-mismatch` payload: 4-member closed reason discriminator. */
 export interface GltfAccessorTypeMismatchDetail {
   readonly accessorIndex: number;
@@ -256,6 +263,10 @@ const gltfErrorPolicy = {
     expected: 'extension listed in v1 allowlist (see EXTENSION_ALLOWLIST in @forgeax/engine-gltf)',
     hint: 'see feat-future-gltf-extensions-allowlist; remove this extension or wait for the allowlist to expand',
   },
+  'gltf-material-transmission-invalid': {
+    expected: 'KHR transmission, IOR, and volume values are finite and within their glTF ranges',
+    hint: 'repair the named glTF material extension value and re-import the source',
+  },
   'gltf-accessor-type-mismatch': {
     expected: 'dense fixed-stride accessor with supported componentType',
     hint: 'sparse: see feat-future-gltf-sparse-accessor; morph: see feat-future-gltf-morph; interleaved: see feat-future-gltf-mesh-multi-section',
@@ -364,6 +375,7 @@ interface DetailFor {
   readonly 'gltf-color-accessor-unsupported': GltfColorAccessorUnsupportedDetail;
   readonly 'gltf-color-accessor-malformed': GltfColorAccessorMalformedDetail;
   readonly 'gltf-mesh-bridge-invalid': GltfMeshBridgeInvalidDetail;
+  readonly 'gltf-material-transmission-invalid': GltfMaterialTransmissionInvalidDetail;
 }
 
 /**

package/src/gltf-importer.ts

@@ -412,6 +412,8 @@ export function materialRefsForPack(
   pushRefsForSlot(mat.normalTexture, 'normalTexture');
   pushRefsForSlot(mat.occlusionTexture, 'occlusionTexture');
   pushRefsForSlot(mat.emissiveTexture, 'emissiveTexture');
+  pushRefsForSlot(mat.transmissionTexture, 'transmissionTexture');
+  pushRefsForSlot(mat.thicknessTexture, 'thicknessTexture');
   return refs;
 }
 
@@ -439,6 +441,8 @@ function rewriteMaterialAssetRefs(
       | 'normalTexture'
       | 'occlusionTexture'
       | 'emissiveTexture'
+      | 'transmissionTexture'
+      | 'thicknessTexture'
     ),
     GltfTextureInfoIr | number | undefined,
   ][] = [
@@ -447,6 +451,8 @@ function rewriteMaterialAssetRefs(
     ['normalTexture', mat.normalTexture],
     ['occlusionTexture', mat.occlusionTexture],
     ['emissiveTexture', mat.emissiveTexture],
+    ['transmissionTexture', mat.transmissionTexture],
+    ['thicknessTexture', mat.thicknessTexture],
   ];
   let cursor = 0;
   for (const [slot, rawBinding] of slots) {

package/src/index.ts

@@ -65,6 +65,7 @@ export type {
   GltfImageMimeUnsupportedDetail,
   GltfInstancingCountMismatchDetail,
   GltfMalformedHeaderDetail,
+  GltfMaterialTransmissionInvalidDetail,
   GltfMetaMissingDetail,
   GltfMorphInvalidDetail,
   GltfMorphUnsupportedDetail,