@forgeax/engine-gltf 0.1.20 → 0.1.23

package/src/lod/parse-lod.ts

@@ -0,0 +1,129 @@
+import { err, gltfErr, ok, type Result } from '../errors.js';
+
+export interface GltfLodRelation {
+  readonly rootNode: number;
+  readonly lodNodeIds: readonly number[];
+  readonly screenCoverages: readonly number[];
+  /** All node-level MSFT_lod groups, retained for multi-root scenes. */
+  readonly groups: readonly GltfLodGroup[];
+}
+
+export interface GltfLodGroup {
+  readonly rootNode: number;
+  readonly lodNodeIds: readonly number[];
+  readonly screenCoverages: readonly number[];
+}
+
+interface RawNode {
+  readonly mesh?: unknown;
+  readonly extensions?: { readonly MSFT_lod?: { readonly ids?: unknown } };
+  readonly extras?: { readonly MSFT_screencoverage?: unknown };
+}
+
+interface RawMesh {
+  readonly primitives?: unknown;
+}
+
+interface RawGltf {
+  readonly extensionsRequired?: readonly unknown[];
+  readonly meshes?: readonly RawMesh[];
+  readonly nodes?: readonly RawNode[];
+  readonly extensions?: { readonly MSFT_screencoverage?: { readonly scales?: unknown } };
+}
+
+export function parseGltfLodExtension(
+  json: unknown,
+): Result<GltfLodRelation, ReturnType<typeof gltfErr<'gltf-lod-invalid'>>> {
+  const doc = json as RawGltf;
+  const nodes = doc.nodes ?? [];
+  const rawCoverage = doc.extensions?.MSFT_screencoverage?.scales;
+  const groups: GltfLodGroup[] = [];
+  for (let rootNode = 0; rootNode < nodes.length; rootNode += 1) {
+    if (nodes[rootNode]?.extensions?.MSFT_lod === undefined) 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): value is number => 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: RawNode | undefined): boolean => {
+      if (typeof node?.mesh !== 'number' || !Number.isInteger(node.mesh) || node.mesh < 0) {
+        return false;
+      }
+      const mesh = doc.meshes?.[node.mesh];
+      // An extension relation is publishable only when its target mesh has at
+      // least one primitive. The parser normally receives the source mesh
+      // table, so an empty table/primitive list is a source-contract failure;
+      // treating it as a valid relation would let toAssetPack silently drop
+      // the LOD level later.
+      return mesh !== undefined && 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 === undefined ? rawCoverage : nodeCoverage,
+      ids.length,
+      nodeCoverage !== undefined,
+    );
+    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 === undefined) {
+    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,
+  });
+}
+
+/**
+ * Normalize the official node `extras.MSFT_screencoverage` form and the
+ * historical ForgeaX document-extension adapter form. The official array
+ * includes one terminal threshold for the discard range, while MeshAsset
+ * stores only the thresholds that select lower geometry levels.
+ */
+function normalizeScreenCoverages(
+  raw: unknown,
+  lodCount: number,
+  officialNodeForm: boolean,
+): readonly number[] | undefined | 'invalid' {
+  if (raw === undefined) return undefined;
+  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) as number[];
+  for (let index = 1; index < values.length; index += 1) {
+    if ((values[index] as number) >= (values[index - 1] as number)) return 'invalid';
+  }
+  return values;
+}

package/src/lod/project-meta.ts

@@ -0,0 +1,48 @@
+import { deriveDefaultLodScreenCoverages, reconcileMeshLodMeta } from '@forgeax/engine-import';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export interface GltfLodMetaLevel {
+  readonly sourceKey: string;
+  readonly guid: string;
+  readonly screenCoverage?: number;
+}
+
+export interface GltfLodMetaCandidate {
+  readonly rootSourceKey: string;
+  readonly levels: readonly GltfLodMetaLevel[];
+  readonly previous?: readonly GltfLodMetaLevel[] | undefined;
+}
+
+export interface GltfLodMetaOutput {
+  readonly sourceKey: string;
+  readonly meshGuid: string;
+  readonly screenCoverage: number;
+}
+
+export function projectGltfLodMeta(
+  input: GltfLodMetaCandidate,
+): Result<
+  { readonly lods: readonly GltfLodMetaOutput[] },
+  { readonly code: string; readonly reason: string }
+> {
+  const defaults = deriveDefaultLodScreenCoverages(input.levels.length + 1);
+  const previous = (input.previous ?? []).map((level) => ({
+    sourceKey: level.sourceKey,
+    meshGuid: level.guid,
+    ...(level.screenCoverage === undefined ? {} : { 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,
+    })),
+  });
+}

package/src/parse-gltf.ts

@@ -19,6 +19,8 @@ import { decodeColorAccessor } from './accessor/decode-color.js';
 import { checkExtensions, type GltfExtensionsJson } from './check-extensions.js';
 import { Base64DecodeError, dataUriBase64Payload, decodeBase64 } from './data-uri.js';
 import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
+import { type GltfLodRelation, parseGltfLodExtension } from './lod/parse-lod.js';
+import { projectGltfLodMeta } from './lod/project-meta.js';
 import {
   type GltfImageIr,
   type GltfMaterialIr,
@@ -341,6 +343,7 @@ export interface GltfDoc {
    * fixtures; producers from parseGltf / parseGlb always populate it.
    */
   readonly meshPrimitiveCount?: ReadonlyMap<number, number>;
+  readonly lod?: GltfLodRelation;
 }
 
 interface BuffersJson {
@@ -363,6 +366,7 @@ interface RootGltfJson extends GltfExtensionsJson {
     readonly rotation?: readonly number[];
     readonly scale?: readonly number[];
     readonly weights?: readonly number[];
+    readonly extras?: { readonly MSFT_screencoverage?: readonly number[] };
     readonly extensions?: {
       readonly KHR_lights_punctual?: {
         readonly light?: number;
@@ -374,6 +378,7 @@ interface RootGltfJson extends GltfExtensionsJson {
           readonly SCALE?: number;
         };
       };
+      readonly MSFT_lod?: { readonly ids?: readonly number[] };
     };
   }>;
   readonly extensions?: {
@@ -389,6 +394,7 @@ interface RootGltfJson extends GltfExtensionsJson {
         };
       }>;
     };
+    readonly MSFT_screencoverage?: { readonly scales?: readonly number[] };
   };
   readonly skins?: ReadonlyArray<{
     readonly name?: string;
@@ -565,6 +571,8 @@ async function parseGltfWithBin(
   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);
 
@@ -1183,6 +1191,7 @@ async function parseGltfWithBin(
     },
     meshPrimitiveCount,
     lights: lightsResult.value,
+    ...(lodResult.value.lodNodeIds.length === 0 ? {} : { lod: lodResult.value }),
   });
 }
 
@@ -1293,7 +1302,7 @@ export interface GltfAssetPack {
   readonly subAssets: readonly GltfSubAssetEntry[];
 }
 
-export type GltfAssetPackResult = Result<GltfAssetPack, GltfSourceKeyError>;
+export type GltfAssetPackResult = Result<GltfAssetPack, GltfSourceKeyError | GltfError>;
 
 /**
  * Project a parsed `GltfDoc` into the disk-shape `<source>.meta.json` plus
@@ -1407,6 +1416,93 @@ export function toAssetPack(
   const sourceOverrides: Record<string, Readonly<Record<string, unknown>>> = {
     ...(existingMeta?.sourceOverrides ?? {}),
   };
+  const lodGroups =
+    doc.lod === undefined ? [] : 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 === undefined ||
+          !seenMeshIndices.has(meshIndex as number),
+      )
+    ) {
+      return err(
+        gltfErr('gltf-lod-invalid', {
+          rootNode: lodGroup.rootNode,
+          ids: lodGroup.lodNodeIds,
+          reason: 'missing-node',
+        }),
+      );
+    }
+    const rootOutput =
+      rootMeshIndex === undefined || rootMeshIndex === null
+        ? undefined
+        : subAssetByKindIndex.get(`mesh:${rootMeshIndex}`);
+    const levels = lodGroup.lodNodeIds.map((nodeIndex, index) => {
+      const meshIndex = doc.nodes[nodeIndex]?.meshIndex;
+      const output =
+        meshIndex === undefined || meshIndex === null
+          ? undefined
+          : subAssetByKindIndex.get(`mesh:${meshIndex}`);
+      return {
+        sourceKey: output?.sourceKey ?? `mesh:${meshIndex ?? nodeIndex}`,
+        meshGuid: output?.guid ?? '',
+        ...(lodGroup.screenCoverages[index] === undefined
+          ? {}
+          : { screenCoverage: lodGroup.screenCoverages[index] }),
+      };
+    });
+    if (rootOutput?.sourceKey !== undefined && levels.every((level) => level.meshGuid !== '')) {
+      const previousLodMeta = (() => {
+        const raw = existingMeta?.sourceOverrides?.[rootOutput.sourceKey]?.lods;
+        if (!Array.isArray(raw)) return undefined;
+        return raw.flatMap((entry) => {
+          if (entry === null || typeof entry !== 'object') return [];
+          const value = entry as Record<string, unknown>;
+          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 === undefined ? {} : { screenCoverage: level.screenCoverage }),
+        })),
+        ...(previousLodMeta === undefined ? {} : { 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 === undefined) continue;

package/src/reimport-reuse-meta.ts

@@ -49,7 +49,9 @@ export interface GltfMetaJson {
   readonly importer: 'gltf';
   readonly source: string;
   readonly subAssets: readonly GltfSubAssetEntry[];
-  readonly sourceOverrides?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly sourceOverrides?:
+    | Readonly<Record<string, Readonly<Record<string, unknown>>>>
+    | undefined;
   readonly sourceOverrideDescriptors?: readonly import('@forgeax/engine-types').SourceOverrideDescriptor[];
   readonly importSettings: {
     readonly defaultSceneIndex: number;