@forgeax/engine-gltf 0.1.21 → 0.1.24

package/dist/cli-gltf.mjs

@@ -3,8 +3,9 @@ import { realpath, stat, readFile, writeFile, readdir } from 'fs/promises';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { parseArgs } from 'util';
-import { reconcileMeshMaterialSlotTopology, err, MESH_MATERIAL_SLOT_SOURCE_OVERRIDE_PAYLOAD_SCHEMA, ok, ImportError, IMPORT_ERROR_HINTS } from '@forgeax/engine-types';
+import { err, reconcileMeshMaterialSlotTopology, MESH_MATERIAL_SLOT_SOURCE_OVERRIDE_PAYLOAD_SCHEMA, ok, ImportError, IMPORT_ERROR_HINTS } from '@forgeax/engine-types';
 import { vec3, quat, mat4 } from '@forgeax/engine-math';
+import { deriveDefaultLodScreenCoverages, reconcileMeshLodMeta } from '@forgeax/engine-import';
 import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 
@@ -24,13 +25,21 @@ var 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"
@@ -394,15 +403,22 @@ function decodeColorAccessor(input, flags = {}) {
 // src/check-extensions.ts
 var EXTENSION_ALLOWLIST = [
   "EXT_mesh_gpu_instancing",
-  "EXT_meshopt_compression"
-];
-var SUPPORTED_EXTENSIONS = [
-  ...EXTENSION_ALLOWLIST,
+  "EXT_meshopt_compression",
   "KHR_lights_punctual",
   "KHR_texture_transform",
   "KHR_materials_transmission",
   "KHR_materials_ior",
-  "KHR_materials_volume"
+  "KHR_materials_volume",
+  "KHR_materials_clearcoat",
+  "KHR_materials_anisotropy",
+  "KHR_materials_sheen",
+  "KHR_materials_iridescence",
+  "KHR_materials_specular"
+];
+var SUPPORTED_EXTENSIONS = [
+  ...EXTENSION_ALLOWLIST,
+  "MSFT_lod",
+  "MSFT_screencoverage"
 ];
 function checkExtensions(json) {
   const required = json.extensionsRequired ?? [];
@@ -454,6 +470,103 @@ function decodeBase64(b64) {
   return out;
 }
 
+// src/lod/parse-lod.ts
+function parseGltfLodExtension(json) {
+  const doc = json;
+  const nodes = doc.nodes ?? [];
+  const rawCoverage = doc.extensions?.MSFT_screencoverage?.scales;
+  const groups = [];
+  for (let rootNode = 0; rootNode < nodes.length; rootNode += 1) {
+    if (nodes[rootNode]?.extensions?.MSFT_lod === void 0) continue;
+    const idsRaw = nodes[rootNode]?.extensions?.MSFT_lod?.ids;
+    if (!Array.isArray(idsRaw)) {
+      return err(gltfErr("gltf-lod-invalid", { rootNode, ids: [], reason: "not-integer" }));
+    }
+    const ids = idsRaw.filter((value) => typeof value === "number");
+    if (ids.length !== idsRaw.length || ids.some((id) => !Number.isInteger(id) || id < 0 || id >= nodes.length)) {
+      return err(gltfErr("gltf-lod-invalid", { rootNode, ids, reason: "missing-node" }));
+    }
+    if (new Set(ids).size !== ids.length || ids.includes(rootNode)) {
+      return err(gltfErr("gltf-lod-invalid", { rootNode, ids, reason: "duplicate-node" }));
+    }
+    const hasMesh = (node) => {
+      if (typeof node?.mesh !== "number" || !Number.isInteger(node.mesh) || node.mesh < 0) {
+        return false;
+      }
+      const mesh = doc.meshes?.[node.mesh];
+      return mesh !== void 0 && Array.isArray(mesh.primitives) && mesh.primitives.length > 0;
+    };
+    if (!hasMesh(nodes[rootNode]) || ids.some((id) => !hasMesh(nodes[id]))) {
+      return err(gltfErr("gltf-lod-invalid", { rootNode, ids, reason: "missing-node" }));
+    }
+    const nodeCoverage = nodes[rootNode]?.extras?.MSFT_screencoverage;
+    const coverage = normalizeScreenCoverages(
+      nodeCoverage === void 0 ? rawCoverage : nodeCoverage,
+      ids.length,
+      nodeCoverage !== void 0
+    );
+    if (coverage === "invalid") {
+      return err(gltfErr("gltf-lod-invalid", { rootNode, ids, reason: "coverage" }));
+    }
+    groups.push({
+      rootNode,
+      lodNodeIds: ids,
+      screenCoverages: coverage ?? []
+    });
+  }
+  const first = groups[0];
+  if (first === void 0) {
+    if (doc.extensionsRequired?.some((extension) => extension === "MSFT_lod")) {
+      return err(gltfErr("gltf-lod-invalid", { rootNode: 0, ids: [], reason: "missing-node" }));
+    }
+    return ok({ rootNode: 0, lodNodeIds: [], screenCoverages: [], groups: [] });
+  }
+  return ok({
+    rootNode: first.rootNode,
+    lodNodeIds: first.lodNodeIds,
+    screenCoverages: first.screenCoverages,
+    groups
+  });
+}
+function normalizeScreenCoverages(raw, lodCount, officialNodeForm) {
+  if (raw === void 0) return void 0;
+  if (!Array.isArray(raw)) return "invalid";
+  if (raw.some(
+    (value) => typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1
+  )) {
+    return "invalid";
+  }
+  const expectedLengths = officialNodeForm ? [lodCount + 1] : [lodCount, lodCount + 1];
+  if (!expectedLengths.includes(raw.length)) return "invalid";
+  const values = raw.slice(0, lodCount);
+  for (let index = 1; index < values.length; index += 1) {
+    if (values[index] >= values[index - 1]) return "invalid";
+  }
+  return values;
+}
+function projectGltfLodMeta(input) {
+  const defaults = deriveDefaultLodScreenCoverages(input.levels.length + 1);
+  const previous = (input.previous ?? []).map((level) => ({
+    sourceKey: level.sourceKey,
+    meshGuid: level.guid,
+    ...level.screenCoverage === void 0 ? {} : { screenCoverage: level.screenCoverage }
+  }));
+  const next = input.levels.map((level, index) => ({
+    sourceKey: level.sourceKey,
+    meshGuid: level.guid,
+    screenCoverage: level.screenCoverage ?? defaults[index] ?? 0
+  }));
+  const reconciled = reconcileMeshLodMeta(previous, next);
+  if (!reconciled.ok) return err({ code: reconciled.error.code, reason: reconciled.error.reason });
+  return ok({
+    lods: reconciled.value.lods.map((level) => ({
+      sourceKey: level.sourceKey,
+      meshGuid: level.meshGuid,
+      screenCoverage: level.screenCoverage
+    }))
+  });
+}
+
 // src/material/parse-material.ts
 function tuple2(values) {
   if (values === void 0 || values.length < 2) return void 0;
@@ -498,6 +611,11 @@ function parseMaterial(matJson, textures) {
   const transmission = matJson.extensions?.KHR_materials_transmission;
   const ior = matJson.extensions?.KHR_materials_ior;
   const volume = matJson.extensions?.KHR_materials_volume;
+  const clearcoat = matJson.extensions?.KHR_materials_clearcoat;
+  const anisotropy = matJson.extensions?.KHR_materials_anisotropy;
+  const sheen = matJson.extensions?.KHR_materials_sheen;
+  const iridescence = matJson.extensions?.KHR_materials_iridescence;
+  const specular = matJson.extensions?.KHR_materials_specular;
   const attenuationColor = tuple3(volume?.attenuationColor);
   const invalid = (extension, field, reason, actual) => err(
     gltfErr("gltf-material-transmission-invalid", {
@@ -507,6 +625,14 @@ function parseMaterial(matJson, textures) {
       ...actual === void 0 ? {} : { actual }
     })
   );
+  const physicalInvalid = (extension, field, reason, actual) => err(
+    gltfErr("gltf-material-physical-invalid", {
+      extension,
+      field,
+      reason,
+      ...actual === void 0 ? {} : { actual }
+    })
+  );
   if (transmission?.transmissionFactor !== void 0 && (typeof transmission.transmissionFactor !== "number" || !Number.isFinite(transmission.transmissionFactor))) {
     return invalid(
       "KHR_materials_transmission",
@@ -557,6 +683,98 @@ function parseMaterial(matJson, textures) {
   if (alphaMode === "BLEND" && (transmission?.transmissionFactor ?? 0) > 0) {
     return invalid("KHR_materials_transmission", "alphaMode", "blend", alphaMode);
   }
+  if (clearcoat?.clearcoatFactor !== void 0 && (typeof clearcoat.clearcoatFactor !== "number" || !Number.isFinite(clearcoat.clearcoatFactor))) {
+    return physicalInvalid(
+      "KHR_materials_clearcoat",
+      "clearcoatFactor",
+      "non-finite",
+      clearcoat.clearcoatFactor
+    );
+  }
+  if (clearcoat?.clearcoatFactor !== void 0 && (clearcoat.clearcoatFactor < 0 || clearcoat.clearcoatFactor > 1)) {
+    return physicalInvalid(
+      "KHR_materials_clearcoat",
+      "clearcoatFactor",
+      "range",
+      clearcoat.clearcoatFactor
+    );
+  }
+  if (clearcoat?.clearcoatRoughnessFactor !== void 0 && (typeof clearcoat.clearcoatRoughnessFactor !== "number" || !Number.isFinite(clearcoat.clearcoatRoughnessFactor))) {
+    return physicalInvalid(
+      "KHR_materials_clearcoat",
+      "clearcoatRoughnessFactor",
+      "non-finite",
+      clearcoat.clearcoatRoughnessFactor
+    );
+  }
+  if (clearcoat?.clearcoatRoughnessFactor !== void 0 && (clearcoat.clearcoatRoughnessFactor < 0 || clearcoat.clearcoatRoughnessFactor > 1)) {
+    return physicalInvalid(
+      "KHR_materials_clearcoat",
+      "clearcoatRoughnessFactor",
+      "range",
+      clearcoat.clearcoatRoughnessFactor
+    );
+  }
+  if (clearcoat?.clearcoatNormalTexture?.scale !== void 0 && (typeof clearcoat.clearcoatNormalTexture.scale !== "number" || !Number.isFinite(clearcoat.clearcoatNormalTexture.scale) || clearcoat.clearcoatNormalTexture.scale < 0)) {
+    return physicalInvalid(
+      "KHR_materials_clearcoat",
+      "clearcoatNormalTexture.scale",
+      "range",
+      clearcoat.clearcoatNormalTexture.scale
+    );
+  }
+  const validateUnit = (extension, field, value) => {
+    if (value === void 0) return void 0;
+    if (typeof value !== "number" || !Number.isFinite(value))
+      return physicalInvalid(extension, field, "non-finite", value);
+    if (value < 0 || value > 1) return physicalInvalid(extension, field, "range", value);
+    return void 0;
+  };
+  const validateFinite = (extension, field, value, minimum) => {
+    if (value === void 0) return void 0;
+    if (typeof value !== "number" || !Number.isFinite(value))
+      return physicalInvalid(extension, field, "non-finite", value);
+    if (minimum !== void 0 && value < minimum)
+      return physicalInvalid(extension, field, "range", value);
+    return void 0;
+  };
+  const validateColor = (extension, field, value) => {
+    if (value === void 0) return void 0;
+    if (value.length < 3 || value.slice(0, 3).some((channel) => typeof channel !== "number" || !Number.isFinite(channel))) {
+      return physicalInvalid(extension, field, "type", value);
+    }
+    if (value.slice(0, 3).some((channel) => channel < 0 || channel > 1)) {
+      return physicalInvalid(extension, field, "range", value);
+    }
+    return void 0;
+  };
+  const physicalChecks = [
+    validateUnit("KHR_materials_anisotropy", "anisotropyStrength", anisotropy?.anisotropyStrength),
+    validateFinite(
+      "KHR_materials_anisotropy",
+      "anisotropyRotation",
+      anisotropy?.anisotropyRotation
+    ),
+    validateUnit("KHR_materials_sheen", "sheenRoughnessFactor", sheen?.sheenRoughnessFactor),
+    validateColor("KHR_materials_sheen", "sheenColorFactor", sheen?.sheenColorFactor),
+    validateUnit("KHR_materials_iridescence", "iridescenceFactor", iridescence?.iridescenceFactor),
+    validateFinite("KHR_materials_iridescence", "iridescenceIor", iridescence?.iridescenceIor, 1),
+    validateFinite(
+      "KHR_materials_iridescence",
+      "iridescenceThicknessMinimum",
+      iridescence?.iridescenceThicknessMinimum,
+      0
+    ),
+    validateFinite(
+      "KHR_materials_iridescence",
+      "iridescenceThicknessMaximum",
+      iridescence?.iridescenceThicknessMaximum,
+      0
+    ),
+    validateUnit("KHR_materials_specular", "specularFactor", specular?.specularFactor),
+    validateColor("KHR_materials_specular", "specularColorFactor", specular?.specularColorFactor)
+  ];
+  for (const check of physicalChecks) if (check !== void 0) return check;
   return ok({
     ...matJson.name === void 0 ? {} : { name: matJson.name },
     baseColorFactor: baseColor4,
@@ -593,6 +811,65 @@ function parseMaterial(matJson, textures) {
       ...attenuationColor === void 0 ? {} : { attenuationColor },
       ...finiteOrUndefined(volume.attenuationDistance) === void 0 ? {} : { attenuationDistance: volume.attenuationDistance }
     },
+    ...clearcoat === void 0 ? {} : {
+      clearcoatFactor: clearcoat.clearcoatFactor ?? 0,
+      clearcoatChannel: 0,
+      clearcoatRoughnessFactor: clearcoat.clearcoatRoughnessFactor ?? 0,
+      clearcoatRoughnessChannel: 1,
+      clearcoatNormalChannel: [0, 1],
+      ...clearcoat.clearcoatTexture === void 0 ? {} : { clearcoatTexture: parseTextureInfo(clearcoat.clearcoatTexture, textures) },
+      ...clearcoat.clearcoatRoughnessTexture === void 0 ? {} : {
+        clearcoatRoughnessTexture: parseTextureInfo(
+          clearcoat.clearcoatRoughnessTexture,
+          textures
+        )
+      },
+      ...clearcoat.clearcoatNormalTexture === void 0 ? {} : {
+        clearcoatNormalTexture: {
+          ...parseTextureInfo(clearcoat.clearcoatNormalTexture, textures),
+          ...clearcoat.clearcoatNormalTexture.scale === void 0 ? {} : { scale: clearcoat.clearcoatNormalTexture.scale }
+        }
+      }
+    },
+    ...anisotropy === void 0 ? {} : {
+      anisotropyStrength: anisotropy.anisotropyStrength ?? 0,
+      anisotropyRotation: anisotropy.anisotropyRotation ?? 0,
+      anisotropyChannel: [0, 1, 2],
+      ...anisotropy.anisotropyTexture === void 0 ? {} : { anisotropyTexture: parseTextureInfo(anisotropy.anisotropyTexture, textures) }
+    },
+    ...sheen === void 0 ? {} : {
+      sheenColorFactor: tuple3(sheen.sheenColorFactor) ?? [0, 0, 0],
+      sheenColorChannel: [0, 1, 2],
+      sheenRoughnessFactor: sheen.sheenRoughnessFactor ?? 0,
+      sheenRoughnessChannel: 3,
+      ...sheen.sheenColorTexture === void 0 ? {} : { sheenColorTexture: parseTextureInfo(sheen.sheenColorTexture, textures) },
+      ...sheen.sheenRoughnessTexture === void 0 ? {} : { sheenRoughnessTexture: parseTextureInfo(sheen.sheenRoughnessTexture, textures) }
+    },
+    ...iridescence === void 0 ? {} : {
+      iridescenceFactor: iridescence.iridescenceFactor ?? 0,
+      iridescenceIor: iridescence.iridescenceIor ?? 1.3,
+      iridescenceThicknessMinimum: iridescence.iridescenceThicknessMinimum ?? 100,
+      iridescenceThicknessMaximum: iridescence.iridescenceThicknessMaximum ?? 400,
+      iridescenceChannel: 0,
+      iridescenceThicknessChannel: 1,
+      ...iridescence.iridescenceTexture === void 0 ? {} : { iridescenceTexture: parseTextureInfo(iridescence.iridescenceTexture, textures) },
+      ...iridescence.iridescenceThicknessTexture === void 0 ? {} : {
+        iridescenceThicknessTexture: parseTextureInfo(
+          iridescence.iridescenceThicknessTexture,
+          textures
+        )
+      }
+    },
+    ...specular === void 0 ? {} : {
+      specularFactor: specular.specularFactor ?? 1,
+      specularChannel: 3,
+      specularColorFactor: tuple3(specular.specularColorFactor) ?? [1, 1, 1],
+      specularColorChannel: [0, 1, 2],
+      ...specular.specularTexture === void 0 ? {} : { specularTexture: parseTextureInfo(specular.specularTexture, textures) },
+      ...specular.specularColorTexture === void 0 ? {} : {
+        specularColorTexture: parseTextureInfo(specular.specularColorTexture, textures)
+      }
+    },
     ...alphaMode === void 0 ? {} : { alphaMode },
     ...alphaCutoff === void 0 ? {} : { alphaCutoff },
     ...matJson.doubleSided === true ? { doubleSided: true } : {},
@@ -1479,6 +1756,8 @@ async function parseGltfWithBin(json, ctx) {
   const extResult = checkExtensions(json);
   if (!extResult.ok) return err(extResult.error);
   const unsupportedExtensions = extResult.value.unsupportedUsed;
+  const lodResult = parseGltfLodExtension(json);
+  if (!lodResult.ok) return err(lodResult.error);
   const lightsResult = parsePunctualLights(json, ctx.filePath);
   if (!lightsResult.ok) return err(lightsResult.error);
   const meshesJson = json.meshes ?? [];
@@ -2019,7 +2298,8 @@ async function parseGltfWithBin(json, ctx) {
       matrixTrsCoexistNodes: diagnostics.matrixTrsCoexistNodes
     },
     meshPrimitiveCount,
-    lights: lightsResult.value
+    lights: lightsResult.value,
+    ...lodResult.value.lodNodeIds.length === 0 ? {} : { lod: lodResult.value }
   });
 }
 async function parseGltfForImporter(json, externalLoader, filePath, options = {}) {
@@ -2158,6 +2438,74 @@ function toAssetPack(doc, existingMeta, source) {
   const sourceOverrides = {
     ...existingMeta?.sourceOverrides ?? {}
   };
+  const lodGroups = doc.lod === void 0 ? [] : doc.lod.groups.length > 0 ? doc.lod.groups : [doc.lod];
+  for (const lodGroup of lodGroups) {
+    if (lodGroup.lodNodeIds.length === 0) continue;
+    const rootMeshIndex = doc.nodes[lodGroup.rootNode]?.meshIndex;
+    const referencedMeshIndices = [
+      rootMeshIndex,
+      ...lodGroup.lodNodeIds.map((nodeIndex) => doc.nodes[nodeIndex]?.meshIndex)
+    ];
+    if (referencedMeshIndices.some(
+      (meshIndex) => !Number.isInteger(meshIndex) || meshIndex === null || meshIndex === void 0 || !seenMeshIndices.has(meshIndex)
+    )) {
+      return err(
+        gltfErr("gltf-lod-invalid", {
+          rootNode: lodGroup.rootNode,
+          ids: lodGroup.lodNodeIds,
+          reason: "missing-node"
+        })
+      );
+    }
+    const rootOutput = rootMeshIndex === void 0 || rootMeshIndex === null ? void 0 : subAssetByKindIndex.get(`mesh:${rootMeshIndex}`);
+    const levels = lodGroup.lodNodeIds.map((nodeIndex, index) => {
+      const meshIndex = doc.nodes[nodeIndex]?.meshIndex;
+      const output = meshIndex === void 0 || meshIndex === null ? void 0 : subAssetByKindIndex.get(`mesh:${meshIndex}`);
+      return {
+        sourceKey: output?.sourceKey ?? `mesh:${meshIndex ?? nodeIndex}`,
+        meshGuid: output?.guid ?? "",
+        ...lodGroup.screenCoverages[index] === void 0 ? {} : { screenCoverage: lodGroup.screenCoverages[index] }
+      };
+    });
+    if (rootOutput?.sourceKey !== void 0 && levels.every((level) => level.meshGuid !== "")) {
+      const previousLodMeta = (() => {
+        const raw = existingMeta?.sourceOverrides?.[rootOutput.sourceKey]?.lods;
+        if (!Array.isArray(raw)) return void 0;
+        return raw.flatMap((entry) => {
+          if (entry === null || typeof entry !== "object") return [];
+          const value = entry;
+          return typeof value.sourceKey === "string" && typeof value.meshGuid === "string" ? [
+            {
+              sourceKey: value.sourceKey,
+              guid: value.meshGuid,
+              ...typeof value.screenCoverage === "number" ? { screenCoverage: value.screenCoverage } : {}
+            }
+          ] : [];
+        });
+      })();
+      const projected = projectGltfLodMeta({
+        rootSourceKey: rootOutput.sourceKey,
+        levels: levels.map((level) => ({
+          sourceKey: level.sourceKey,
+          guid: level.meshGuid,
+          ...level.screenCoverage === void 0 ? {} : { screenCoverage: level.screenCoverage }
+        })),
+        ...previousLodMeta === void 0 ? {} : { previous: previousLodMeta }
+      });
+      if (!projected.ok)
+        return err(
+          gltfErr("gltf-lod-invalid", {
+            rootNode: lodGroup.rootNode,
+            ids: lodGroup.lodNodeIds,
+            reason: "coverage"
+          })
+        );
+      sourceOverrides[rootOutput.sourceKey] = {
+        ...sourceOverrides[rootOutput.sourceKey] ?? {},
+        lods: projected.value.lods
+      };
+    }
+  }
   for (const meshIndex of seenMeshIndices) {
     const meshOutput = subAssetByKindIndex.get(`mesh:${meshIndex}`);
     if (meshOutput?.sourceKey === void 0) continue;
@@ -2252,13 +2600,13 @@ function serializeMetaJson(meta) {
 }
 
 // src/cli-gltf.ts
-function emitError(ctx, err2) {
+function emitError(ctx, err3) {
   const payload = {
-    code: err2.code,
-    expected: err2.expected,
-    hint: err2.hint
+    code: err3.code,
+    expected: err3.expected,
+    hint: err3.hint
   };
-  if (err2.detail !== void 0) payload.detail = err2.detail;
+  if (err3.detail !== void 0) payload.detail = err3.detail;
   ctx.stderrWrite(JSON.stringify(payload));
   return 1;
 }