@forgeax/engine-gltf 0.1.21 → 0.1.24

package/src/bridge.ts

@@ -19,7 +19,7 @@
 // (B3) child world pos accumulates parent transform
 // (B6) camera detection via GltfNodeIr.camera field (not legacy nodes[1] heuristic)
 
-import { packInterleavedVertexAttributes } from '@forgeax/engine-geometry';
+import { computeTangentVec4, packInterleavedVertexAttributes } from '@forgeax/engine-geometry';
 import type { Mat4 } from '@forgeax/engine-math';
 import { box3, mat4, quat, vec3 } from '@forgeax/engine-math';
 import { AssetGuid as AssetGuidCodec } from '@forgeax/engine-pack/guid';
@@ -40,6 +40,13 @@ import type {
   Submesh,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import {
+  STANDARD_LAYER_PARAMETER_GROUPS,
+  STANDARD_MATERIAL_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_PARAMETER_NAMES,
+  STANDARD_TRANSMISSION_PARAMETER_NAMES,
+  standardMaterialParameters,
+} from '@forgeax/engine-types';
 import { createMaterialError, err, type GltfError, gltfErr, ok } from './errors.js';
 import type {
   GltfDoc,
@@ -216,6 +223,21 @@ export function meshIrToMeshAsset(
     const materialSlot = slotFor(mesh.materialIndex);
     const primVertexCount = mesh.positions.length / 3;
     const primIndexCount = mesh.indices === undefined ? 0 : mesh.indices.length;
+    // A tangent admission check may already have computed a valid frame for a
+    // physical glTF material. Persist that producer result into the canonical
+    // MeshAsset instead of silently replacing it with the historical identity
+    // tangent. Non-physical meshes keep the identity fallback when the source
+    // lacks the inputs required by the tangent producer.
+    let generatedTangents: Float32Array | undefined;
+    if (mesh.tangents === undefined && mesh.normals !== undefined && mesh.texcoord0 !== undefined) {
+      const generated = computeTangentVec4(
+        mesh.positions,
+        mesh.normals,
+        mesh.texcoord0,
+        mesh.indices,
+      );
+      if (generated.ok) generatedTangents = generated.value;
+    }
     if (mesh.colors0 !== undefined && mesh.colors0.length !== primVertexCount * 4) {
       return err(
         gltfErr('gltf-mesh-bridge-invalid', {
@@ -247,12 +269,13 @@ export function meshIrToMeshAsset(
         uvsCat[(vertexCursor + i) * 2 + 0] = mesh.texcoord0[t + 0] as number;
         uvsCat[(vertexCursor + i) * 2 + 1] = mesh.texcoord0[t + 1] as number;
       }
-      if (mesh.tangents !== undefined) {
+      const sourceTangents = mesh.tangents ?? generatedTangents;
+      if (sourceTangents !== undefined) {
         const g = i * 4;
-        tangentsCat[(vertexCursor + i) * 4 + 0] = mesh.tangents[g + 0] as number;
-        tangentsCat[(vertexCursor + i) * 4 + 1] = mesh.tangents[g + 1] as number;
-        tangentsCat[(vertexCursor + i) * 4 + 2] = mesh.tangents[g + 2] as number;
-        tangentsCat[(vertexCursor + i) * 4 + 3] = mesh.tangents[g + 3] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 0] = sourceTangents[g + 0] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 1] = sourceTangents[g + 1] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 2] = sourceTangents[g + 2] as number;
+        tangentsCat[(vertexCursor + i) * 4 + 3] = sourceTangents[g + 3] as number;
       } else {
         tangentsCat[(vertexCursor + i) * 4 + 0] = 1;
         tangentsCat[(vertexCursor + i) * 4 + 3] = 1;
@@ -541,7 +564,7 @@ export function gltfDocToSceneAsset(doc: GltfDoc, ctx: GltfBridgeContext): Scene
 
   // bug-20260613: SceneAsset entities also emit ChildOf when a glTF node has a
   // parent (line 547 below). Runtime propagateTransforms then derives
-  // Transform.world via `parent.world * compose(child.local TRS)`. If we
+  // GlobalTransform.world via `parent.world * compose(child.local TRS)`. If we
   // wrote the *world* TRS into Transform here, every child node would get
   // baked twice -- once at importer time and again at propagate time --
   // collapsing the skin so vertices fly to (parent.world)^2 space and the
@@ -778,7 +801,17 @@ type MaterialTextureSlot =
   | 'occlusionTexture'
   | 'emissiveTexture'
   | 'transmissionTexture'
-  | 'thicknessTexture';
+  | 'thicknessTexture'
+  | 'clearcoatTexture'
+  | 'clearcoatRoughnessTexture'
+  | 'clearcoatNormalTexture'
+  | 'anisotropyTexture'
+  | 'sheenColorTexture'
+  | 'sheenRoughnessTexture'
+  | 'iridescenceTexture'
+  | 'iridescenceThicknessTexture'
+  | 'specularTexture'
+  | 'specularColorTexture';
 
 function textureValue(
   info: GltfTextureInfoIr | number | undefined,
@@ -811,6 +844,12 @@ function textureValue(
       return { ...value, normalScale: normal.scale };
     }
   }
+  if (slot === 'clearcoatNormalTexture') {
+    const normal = info as GltfMaterialIr['clearcoatNormalTexture'];
+    if (typeof normal === 'object' && normal?.scale !== undefined) {
+      return { ...value, normalScale: normal.scale };
+    }
+  }
   if (slot === 'occlusionTexture') {
     const occlusion = info as GltfMaterialIr['occlusionTexture'];
     if (typeof occlusion === 'object' && occlusion?.strength !== undefined) {
@@ -820,6 +859,102 @@ function textureValue(
   return value;
 }
 
+/**
+ * Select the exact Standard root contract emitted by the glTF producer.
+ * Numeric/base fields come from the shared schema; physical texture slots are
+ * admitted only when the source actually declares them.  A parent root is
+ * retained for the legacy base-only path, while an extended glTF material
+ * becomes its own root so its extension declarations own cook/ABI identity.
+ */
+function standardRootParameterNames(mat: GltfMaterialIr): {
+  readonly names: ReadonlySet<string>;
+  readonly extended: boolean;
+} {
+  const names = new Set(
+    STANDARD_MATERIAL_PARAM_SCHEMA.filter(
+      (entry) =>
+        !STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) &&
+        !STANDARD_TRANSMISSION_PARAMETER_NAMES.has(entry.name),
+    ).map((entry) => entry.name),
+  );
+  // IOR is consumed for the base dielectric F0 fallback even when the
+  // transmission/volume extension is absent.
+  names.add('ior');
+
+  const addLayer = (layer: keyof typeof STANDARD_LAYER_PARAMETER_GROUPS): void => {
+    for (const name of STANDARD_LAYER_PARAMETER_GROUPS[layer]) names.add(name);
+  };
+  const addTexture = (name: string, info: GltfTextureInfoIr | number | undefined): void => {
+    if (info !== undefined) names.add(name);
+  };
+
+  const clearcoat =
+    mat.clearcoatFactor !== undefined ||
+    mat.clearcoatRoughnessFactor !== undefined ||
+    mat.clearcoatNormalTexture !== undefined ||
+    mat.clearcoatTexture !== undefined ||
+    mat.clearcoatRoughnessTexture !== undefined;
+  const anisotropy =
+    mat.anisotropyStrength !== undefined ||
+    mat.anisotropyRotation !== undefined ||
+    mat.anisotropyTexture !== undefined;
+  const sheen =
+    mat.sheenColorFactor !== undefined ||
+    mat.sheenRoughnessFactor !== undefined ||
+    mat.sheenColorTexture !== undefined ||
+    mat.sheenRoughnessTexture !== undefined;
+  const iridescence =
+    mat.iridescenceFactor !== undefined ||
+    mat.iridescenceIor !== undefined ||
+    mat.iridescenceThicknessMinimum !== undefined ||
+    mat.iridescenceThicknessMaximum !== undefined ||
+    mat.iridescenceTexture !== undefined ||
+    mat.iridescenceThicknessTexture !== undefined;
+  if (clearcoat) addLayer('clearcoat');
+  if (anisotropy) addLayer('anisotropy');
+  if (sheen) addLayer('sheen');
+  if (iridescence) addLayer('iridescence');
+  if (clearcoat && mat.clearcoatNormalTexture !== undefined) names.add('clearcoatNormalScale');
+
+  addTexture('clearcoatTexture', mat.clearcoatTexture);
+  addTexture('clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture);
+  addTexture('clearcoatNormalTexture', mat.clearcoatNormalTexture);
+  addTexture('anisotropyTexture', mat.anisotropyTexture);
+  addTexture('sheenColorTexture', mat.sheenColorTexture);
+  addTexture('sheenRoughnessTexture', mat.sheenRoughnessTexture);
+  addTexture('iridescenceTexture', mat.iridescenceTexture);
+  addTexture('iridescenceThicknessTexture', mat.iridescenceThicknessTexture);
+  addTexture('specularTexture', mat.specularTexture);
+  addTexture('specularColorTexture', mat.specularColorTexture);
+
+  const transmission =
+    mat.transmissionFactor !== undefined ||
+    mat.transmissionTexture !== undefined ||
+    mat.ior !== undefined ||
+    mat.thicknessFactor !== undefined ||
+    mat.thicknessTexture !== undefined ||
+    mat.attenuationColor !== undefined ||
+    mat.attenuationDistance !== undefined;
+  if (transmission) {
+    // Transmission/volume keeps its existing paired backdrop ABI.  The
+    // producer may leave either value at its neutral fallback, but the pair
+    // remains part of the pre-existing transmission root contract.
+    for (const name of STANDARD_TRANSMISSION_PARAMETER_NAMES) names.add(name);
+  }
+
+  return {
+    names,
+    extended:
+      clearcoat ||
+      anisotropy ||
+      sheen ||
+      iridescence ||
+      transmission ||
+      mat.specularTexture !== undefined ||
+      mat.specularColorTexture !== undefined,
+  };
+}
+
 export function validateMaterialUvSets(
   mat: GltfMaterialIr,
   primitive: string,
@@ -834,6 +969,16 @@ export function validateMaterialUvSets(
     ['emissiveTexture', mat.emissiveTexture],
     ['transmissionTexture', mat.transmissionTexture],
     ['thicknessTexture', mat.thicknessTexture],
+    ['clearcoatTexture', mat.clearcoatTexture],
+    ['clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture],
+    ['clearcoatNormalTexture', mat.clearcoatNormalTexture],
+    ['anisotropyTexture', mat.anisotropyTexture],
+    ['sheenColorTexture', mat.sheenColorTexture],
+    ['sheenRoughnessTexture', mat.sheenRoughnessTexture],
+    ['iridescenceTexture', mat.iridescenceTexture],
+    ['iridescenceThicknessTexture', mat.iridescenceThicknessTexture],
+    ['specularTexture', mat.specularTexture],
+    ['specularColorTexture', mat.specularColorTexture],
   ];
   for (const [slot, rawBinding] of slots) {
     const binding = textureInfo(rawBinding);
@@ -854,8 +999,67 @@ export function validateMaterialUvSets(
   return ok(undefined);
 }
 
+export function validateMaterialTangentInputs(
+  mat: GltfMaterialIr,
+  mesh: GltfMeshIr,
+  layer = 'clearcoat',
+): Result<void, MaterialError> {
+  // Anisotropy changes the base GGX lobe even when it has no texture map, so
+  // its tangent direction is part of the scalar layer contract.  Select UV 0
+  // for the scalar-only form; a mapped form keeps the map's explicit UV set.
+  const anisotropyDeclared =
+    mat.anisotropyStrength !== undefined ||
+    mat.anisotropyRotation !== undefined ||
+    mat.anisotropyTexture !== undefined;
+  const tangentSlot = anisotropyDeclared
+    ? { layer: 'anisotropy', info: mat.anisotropyTexture }
+    : mat.clearcoatNormalTexture !== undefined
+      ? { layer: 'clearcoat', info: mat.clearcoatNormalTexture }
+      : undefined;
+  if (tangentSlot === undefined) return ok(undefined);
+  const selected = textureInfo(tangentSlot.info);
+  const uvSet = selected?.texCoord ?? 0;
+  const uv = mesh[`texcoord${uvSet === 0 ? '0' : uvSet}` as keyof GltfMeshIr];
+  const attributes = ['NORMAL', `TEXCOORD_${uvSet}`, 'TANGENT'];
+  const fail = (reason: string): Result<void, MaterialError> =>
+    err(
+      createMaterialError('material-tangent-required', {
+        code: 'material-tangent-required',
+        material: mat.name ?? '<unnamed>',
+        mesh: mesh.name ?? '<unnamed>',
+        layer: tangentSlot.layer ?? layer,
+        uv: `TEXCOORD_${uvSet}`,
+        attributes,
+        reason,
+      }),
+    );
+  if (mesh.tangents !== undefined) {
+    if (
+      mesh.tangents.length !== (mesh.positions.length / 3) * 4 ||
+      mesh.tangents.some((value) => !Number.isFinite(value))
+    ) {
+      return fail('imported TANGENT must be finite vec4 per vertex');
+    }
+    return ok(undefined);
+  }
+  if (mesh.normals === undefined) return fail('NORMAL is required to generate tangent');
+  if (!(uv instanceof Float32Array))
+    return fail('the selected UV set is required to generate tangent');
+  const generated = computeTangentVec4(mesh.positions, mesh.normals, uv, mesh.indices);
+  if (!generated.ok) {
+    const detail = generated.error.detail;
+    const reason =
+      detail !== undefined && 'reason' in detail
+        ? String(detail.reason)
+        : 'tangent producer rejected topology';
+    return fail(reason);
+  }
+  return ok(undefined);
+}
+
 /** Convert a parsed GltfMaterialIr into a standard-root derived MaterialAsset. */
 export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext): MaterialAsset {
+  const rootContract = standardRootParameterNames(mat);
   const values: Record<string, NonNullable<MaterialAsset['values']>[string]> = {
     baseColor: mat.baseColorFactor,
     metallic: mat.metallicFactor,
@@ -873,6 +1077,16 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
     ['emissiveTexture', mat.emissiveTexture],
     ['transmissionTexture', mat.transmissionTexture],
     ['thicknessTexture', mat.thicknessTexture],
+    ['clearcoatTexture', mat.clearcoatTexture],
+    ['clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture],
+    ['clearcoatNormalTexture', mat.clearcoatNormalTexture],
+    ['anisotropyTexture', mat.anisotropyTexture],
+    ['sheenColorTexture', mat.sheenColorTexture],
+    ['sheenRoughnessTexture', mat.sheenRoughnessTexture],
+    ['iridescenceTexture', mat.iridescenceTexture],
+    ['iridescenceThicknessTexture', mat.iridescenceThicknessTexture],
+    ['specularTexture', mat.specularTexture],
+    ['specularColorTexture', mat.specularColorTexture],
   ];
   for (const [slot, info] of textureSlots) {
     const value = textureValue(info, slot, ctx);
@@ -881,11 +1095,37 @@ 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;
+  if (rootContract.extended && rootContract.names.has('transmission')) {
+    values.transmission = mat.transmissionFactor ?? 0;
+    values.ior = mat.ior ?? 1.5;
+    values.thickness = mat.thicknessFactor ?? 0;
+    values.attenuationColor = mat.attenuationColor ?? [1, 1, 1];
+    if (mat.attenuationDistance !== undefined) values.attenuationDistance = mat.attenuationDistance;
+  }
+  if (rootContract.names.has('clearcoat')) {
+    values.clearcoat = mat.clearcoatFactor ?? 0;
+    values.clearcoatRoughness = mat.clearcoatRoughnessFactor ?? 0;
+  }
+  const clearcoatNormal = textureInfo(mat.clearcoatNormalTexture) as
+    | (GltfTextureInfoIr & { readonly scale?: number })
+    | undefined;
+  if (clearcoatNormal?.scale !== undefined) values.clearcoatNormalScale = clearcoatNormal.scale;
+  if (rootContract.names.has('anisotropyStrength')) {
+    values.anisotropyStrength = mat.anisotropyStrength ?? 0;
+    values.anisotropyRotation = mat.anisotropyRotation ?? 0;
+  }
+  if (rootContract.names.has('sheenColor')) {
+    values.sheenColor = mat.sheenColorFactor ?? [0, 0, 0];
+    values.sheenRoughness = mat.sheenRoughnessFactor ?? 0;
+  }
+  if (rootContract.names.has('iridescence')) {
+    values.iridescence = mat.iridescenceFactor ?? 0;
+    values.iridescenceIor = mat.iridescenceIor ?? 1.3;
+    values.iridescenceThicknessMinimum = mat.iridescenceThicknessMinimum ?? 100;
+    values.iridescenceThicknessMaximum = mat.iridescenceThicknessMaximum ?? 400;
+  }
+  if (mat.specularFactor !== undefined) values.specular = mat.specularFactor;
+  if (mat.specularColorFactor !== undefined) values.specularColor = mat.specularColorFactor;
 
   const module = ctx?.skinned === true ? 'forgeax::pbr-skin' : 'forgeax::default-standard-pbr';
 
@@ -932,8 +1172,13 @@ export function toMaterialAsset(mat: GltfMaterialIr, ctx?: MaterialBridgeContext
   return {
     kind: 'material',
     colorSpace: 'linear',
-    ...(ctx?.standardRootGuid === undefined ? {} : { parent: ctx.standardRootGuid }),
+    ...(!rootContract.extended && ctx?.standardRootGuid !== undefined
+      ? { parent: ctx.standardRootGuid }
+      : {}),
     passes: [pass],
+    ...(ctx?.standardRootGuid !== undefined && !rootContract.extended
+      ? {}
+      : { parameters: standardMaterialParameters(rootContract.names) }),
     values,
   };
 }

package/src/check-extensions.ts

@@ -2,9 +2,10 @@
 //
 // 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.
+// the KHR material transmission/IOR/volume/clearcoat/anisotropy/sheen/
+// iridescence/specular extensions. The exported list is the public supported
+// extension surface consumed by both the required-extension gate and callers
+// that need to discover support.
 // (feat-20260518-gltf-instancing-and-name-component plan-strategy section
 // 2 D-1 / D-3). Any extension listed in `extensionsRequired[]` outside
 // the supported extension set triggers `gltf-extension-unsupported` (hard fail).
@@ -18,23 +19,30 @@
 // diagnostics list is the single channel (no `console.error`).
 //
 // Future expansion (KHR_materials_unlit, ...) extends
-// `SUPPORTED_EXTENSIONS` in place; each addition lands under its own feat-*
+// `EXTENSION_ALLOWLIST` 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';
 
-/** Legacy v1 mesh-only list kept for callers that display that surface. */
+/** Public supported extension list used by the required/used declaration gate. */
 export const EXTENSION_ALLOWLIST: readonly string[] = [
   'EXT_mesh_gpu_instancing',
   'EXT_meshopt_compression',
-];
-const SUPPORTED_EXTENSIONS: readonly string[] = [
-  ...EXTENSION_ALLOWLIST,
   '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',
+];
+const SUPPORTED_EXTENSIONS: readonly string[] = [
+  ...EXTENSION_ALLOWLIST,
+  'MSFT_lod',
+  'MSFT_screencoverage',
 ];
 
 export interface ExtensionsCheckResult {

package/src/errors.ts

@@ -60,6 +60,12 @@ export interface GltfExtensionUnsupportedDetail {
   readonly source: 'extensionsRequired' | 'extensionsUsed';
 }
 
+export interface GltfLodInvalidDetail {
+  readonly rootNode: number;
+  readonly ids: readonly number[];
+  readonly reason: 'missing-node' | 'duplicate-node' | 'not-integer' | 'coverage';
+}
+
 export interface GltfMaterialTransmissionInvalidDetail {
   readonly extension: 'KHR_materials_transmission' | 'KHR_materials_ior' | 'KHR_materials_volume';
   readonly field: string;
@@ -67,6 +73,18 @@ export interface GltfMaterialTransmissionInvalidDetail {
   readonly actual?: unknown;
 }
 
+export interface GltfMaterialPhysicalInvalidDetail {
+  readonly extension:
+    | 'KHR_materials_clearcoat'
+    | 'KHR_materials_anisotropy'
+    | 'KHR_materials_sheen'
+    | 'KHR_materials_iridescence'
+    | 'KHR_materials_specular';
+  readonly field: string;
+  readonly reason: 'type' | 'range' | 'non-finite';
+  readonly actual?: unknown;
+}
+
 /** `gltf-accessor-type-mismatch` payload: 4-member closed reason discriminator. */
 export interface GltfAccessorTypeMismatchDetail {
   readonly accessorIndex: number;
@@ -260,13 +278,23 @@ const gltfErrorPolicy = {
     hint: 'rebuild .gltf with valid bufferViews; check accessor index; ensure accessor.byteOffset + EFFECTIVE_STRIDE * (count - 1) + element_size <= bufferView.byteLength',
   },
   'gltf-extension-unsupported': {
-    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',
+    expected:
+      'extension listed in the supported allowlist (see EXTENSION_ALLOWLIST in @forgeax/engine-gltf)',
+    hint: 'remove the unsupported required extension or use a supported glTF extension; extensionsUsed-only entries remain diagnostic',
+  },
+  'gltf-lod-invalid': {
+    expected: 'MSFT_lod ids to reference unique existing node indices with valid coverage',
+    hint: 'repair the MSFT_lod node relation or remove it from extensionsRequired before re-importing',
   },
   '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-material-physical-invalid': {
+    expected:
+      'KHR clearcoat, anisotropy, sheen, iridescence, and specular values are finite and within their glTF ranges',
+    hint: 'repair the named physical 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',
@@ -357,6 +385,7 @@ interface DetailFor {
   readonly 'gltf-version-unsupported': GltfVersionUnsupportedDetail;
   readonly 'gltf-buffer-out-of-bounds': GltfBufferOutOfBoundsDetail;
   readonly 'gltf-extension-unsupported': GltfExtensionUnsupportedDetail;
+  readonly 'gltf-lod-invalid': GltfLodInvalidDetail;
   readonly 'gltf-accessor-type-mismatch': GltfAccessorTypeMismatchDetail;
   readonly 'gltf-texture-load-failed': GltfTextureLoadFailedDetail;
   readonly 'gltf-meta-missing': GltfMetaMissingDetail;
@@ -376,6 +405,7 @@ interface DetailFor {
   readonly 'gltf-color-accessor-malformed': GltfColorAccessorMalformedDetail;
   readonly 'gltf-mesh-bridge-invalid': GltfMeshBridgeInvalidDetail;
   readonly 'gltf-material-transmission-invalid': GltfMaterialTransmissionInvalidDetail;
+  readonly 'gltf-material-physical-invalid': GltfMaterialPhysicalInvalidDetail;
 }
 
 /**

package/src/gltf-importer.ts

@@ -32,6 +32,7 @@
 // gap as `import-produced-no-assets`. A texture sub-asset that fails byte
 // extraction surfaces as `gltf-image-extract-failed` (D-6).
 
+import { deriveDefaultLodScreenCoverages } from '@forgeax/engine-import';
 import { packMeshBinV4 } from '@forgeax/engine-import/mesh-bin';
 import { AssetGuid as AssetGuidCodec } from '@forgeax/engine-pack/guid';
 import type {
@@ -58,6 +59,7 @@ import {
   gltfDocToSceneAsset,
   meshIrToMeshAsset,
   toMaterialAsset,
+  validateMaterialTangentInputs,
   validateMaterialUvSets,
 } from './bridge.js';
 import { gltfErr } from './errors.js';
@@ -414,6 +416,16 @@ export function materialRefsForPack(
   pushRefsForSlot(mat.emissiveTexture, 'emissiveTexture');
   pushRefsForSlot(mat.transmissionTexture, 'transmissionTexture');
   pushRefsForSlot(mat.thicknessTexture, 'thicknessTexture');
+  pushRefsForSlot(mat.clearcoatTexture, 'clearcoatTexture');
+  pushRefsForSlot(mat.clearcoatRoughnessTexture, 'clearcoatRoughnessTexture');
+  pushRefsForSlot(mat.clearcoatNormalTexture, 'clearcoatNormalTexture');
+  pushRefsForSlot(mat.anisotropyTexture, 'anisotropyTexture');
+  pushRefsForSlot(mat.sheenColorTexture, 'sheenColorTexture');
+  pushRefsForSlot(mat.sheenRoughnessTexture, 'sheenRoughnessTexture');
+  pushRefsForSlot(mat.iridescenceTexture, 'iridescenceTexture');
+  pushRefsForSlot(mat.iridescenceThicknessTexture, 'iridescenceThicknessTexture');
+  pushRefsForSlot(mat.specularTexture, 'specularTexture');
+  pushRefsForSlot(mat.specularColorTexture, 'specularColorTexture');
   return refs;
 }
 
@@ -443,6 +455,16 @@ function rewriteMaterialAssetRefs(
       | 'emissiveTexture'
       | 'transmissionTexture'
       | 'thicknessTexture'
+      | 'clearcoatTexture'
+      | 'clearcoatRoughnessTexture'
+      | 'clearcoatNormalTexture'
+      | 'anisotropyTexture'
+      | 'sheenColorTexture'
+      | 'sheenRoughnessTexture'
+      | 'iridescenceTexture'
+      | 'iridescenceThicknessTexture'
+      | 'specularTexture'
+      | 'specularColorTexture'
     ),
     GltfTextureInfoIr | number | undefined,
   ][] = [
@@ -453,6 +475,16 @@ function rewriteMaterialAssetRefs(
     ['emissiveTexture', mat.emissiveTexture],
     ['transmissionTexture', mat.transmissionTexture],
     ['thicknessTexture', mat.thicknessTexture],
+    ['clearcoatTexture', mat.clearcoatTexture],
+    ['clearcoatRoughnessTexture', mat.clearcoatRoughnessTexture],
+    ['clearcoatNormalTexture', mat.clearcoatNormalTexture],
+    ['anisotropyTexture', mat.anisotropyTexture],
+    ['sheenColorTexture', mat.sheenColorTexture],
+    ['sheenRoughnessTexture', mat.sheenRoughnessTexture],
+    ['iridescenceTexture', mat.iridescenceTexture],
+    ['iridescenceThicknessTexture', mat.iridescenceThicknessTexture],
+    ['specularTexture', mat.specularTexture],
+    ['specularColorTexture', mat.specularColorTexture],
   ];
   let cursor = 0;
   for (const [slot, rawBinding] of slots) {
@@ -591,7 +623,83 @@ async function importGltf(
           }),
         };
       }
-      const meshPayload = stabilizeMeshMaterialSlots(bridged.value, ctx, sub.guid, sub.sourceKey);
+      const stabilizedMesh = stabilizeMeshMaterialSlots(
+        bridged.value,
+        ctx,
+        sub.guid,
+        sub.sourceKey,
+      );
+      const lodGroup =
+        doc.lod?.groups?.find(
+          (group) => doc.nodes[group.rootNode]?.meshIndex === sub.sourceIndex,
+        ) ??
+        (doc.lod?.rootNode !== undefined &&
+        doc.nodes[doc.lod.rootNode]?.meshIndex === sub.sourceIndex
+          ? doc.lod
+          : undefined);
+      const rootMeshIndex = lodGroup === undefined ? undefined : sub.sourceIndex;
+      if (lodGroup !== undefined) {
+        const referencedMeshIndices = [
+          sub.sourceIndex,
+          ...lodGroup.lodNodeIds.map((nodeIndex) => doc.nodes[nodeIndex]?.meshIndex),
+        ];
+        const missingMeshIndex = referencedMeshIndices.find(
+          (meshIndex) =>
+            !Number.isInteger(meshIndex) ||
+            meshIndex === null ||
+            meshIndex === undefined ||
+            maps.meshGuidByIndex.get(meshIndex as number) === undefined,
+        );
+        if (missingMeshIndex !== undefined) {
+          return {
+            ok: false,
+            error: new ImportError({
+              code: 'import-internal-error',
+              expected: 'every MSFT_lod node to resolve a cooked mesh sub-asset',
+              actual: String(missingMeshIndex),
+              hint: 'repair the referenced glTF mesh primitives and re-run the importer',
+              detail: {
+                reason: `MSFT_lod group for mesh ${sub.sourceIndex} references an unprojected mesh`,
+              },
+            }),
+          };
+        }
+      }
+      const authoredLods =
+        sub.sourceKey === undefined ? undefined : ctx.sourceOverrides?.[sub.sourceKey]?.lods;
+      const lodEntries = Array.isArray(authoredLods) ? authoredLods : [];
+      const lodLevels =
+        rootMeshIndex === sub.sourceIndex && lodGroup !== undefined
+          ? lodGroup.lodNodeIds.flatMap((nodeIndex, index) => {
+              const meshIndex = doc.nodes[nodeIndex]?.meshIndex;
+              const guid =
+                meshIndex === undefined || meshIndex === null
+                  ? undefined
+                  : maps.meshGuidByIndex.get(meshIndex);
+              if (guid === undefined) return [];
+              const authored = lodEntries[index];
+              const authoredCoverage =
+                authored !== null && typeof authored === 'object'
+                  ? (authored as { readonly screenCoverage?: unknown }).screenCoverage
+                  : undefined;
+              const coverage =
+                typeof authoredCoverage === 'number'
+                  ? authoredCoverage
+                  : (lodGroup.screenCoverages[index] ??
+                    deriveDefaultLodScreenCoverages(lodGroup.lodNodeIds.length + 1)[index]);
+              const parsed = AssetGuidCodec.parse(guid);
+              return parsed.ok && coverage !== undefined
+                ? [{ mesh: parsed.value, screenCoverage: coverage, guid }]
+                : [];
+            })
+          : [];
+      const meshPayload: MeshAsset =
+        lodLevels.length === 0
+          ? stabilizedMesh
+          : {
+              ...stabilizedMesh,
+              lods: lodLevels.map(({ mesh, screenCoverage }) => ({ mesh, screenCoverage })),
+            };
       const materialRefs: AssetRef[] = [];
       const seenMaterialGuids = new Set<string>();
       for (let slotIndex = 0; slotIndex < meshPayload.materialSlots.length; slotIndex++) {
@@ -606,6 +714,15 @@ async function importGltf(
           });
         }
       }
+      for (const [lodIndex, level] of lodLevels.entries()) {
+        if (!seenMaterialGuids.has(level.guid.toLowerCase())) {
+          seenMaterialGuids.add(level.guid.toLowerCase());
+          materialRefs.push({
+            guid: level.guid,
+            sourceField: { fieldName: 'lods', arrayIndex: lodIndex },
+          });
+        }
+      }
       out.push({
         guid: sub.guid,
         kind: 'mesh',
@@ -664,6 +781,10 @@ async function importGltf(
         if (!uvResult.ok) {
           throw Object.assign(new Error(uvResult.error.message), uvResult.error);
         }
+        const tangentResult = validateMaterialTangentInputs(mat, meshIr);
+        if (!tangentResult.ok) {
+          throw Object.assign(new Error(tangentResult.error.message), tangentResult.error);
+        }
       }
       const matAsset = toMaterialAsset(mat, {
         textureHandles: maps.textureHandles,