@forgeax/engine-gltf 0.0.0-dev.8d955ade1c79

package/src/parse-animation.ts

@@ -0,0 +1,286 @@
+// parse-animation.ts - glTF animation parser (feat-20260523-skin-skeleton-animation M0).
+//
+// Implements parseAnimation(): parses glTF `animations[]` array into
+// GltfAnimationClipRecord[] with duration, channels, and sampler data.
+// Used by parseGltfWithBin to populate GltfDoc.
+//
+// Decision anchors:
+//   - plan-strategy D-1 (AnimationClip independent asset)
+//   - requirements AC-07 (AnimationClip shape), AC-09 (CUBICSPLINE/morph fail-fast)
+//   - requirements AC-10 (IR extension)
+//   - charter P3 (fail-fast on unsupported interpolation/morph targets)
+
+import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
+import type { AnimationTargetIdValue } from '@forgeax/engine-types';
+import { decodeF32Accessor } from './accessor/decode-accessor.js';
+import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
+import { buildNodeParentMap, resolveNamedNodePath } from './node-path.js';
+
+/** Supported interpolation modes (CUBICSPLINE is deferred to OOS-skin-cubicspline). */
+type Interpolation = 'LINEAR' | 'STEP';
+
+interface ChannelJson {
+  readonly sampler: number;
+  readonly target: {
+    readonly node?: number;
+    readonly path: string;
+  };
+}
+
+interface SamplerJson {
+  readonly input: number;
+  readonly output: number;
+  readonly interpolation?: string;
+}
+
+interface AnimationJson {
+  readonly name?: string;
+  readonly channels: readonly ChannelJson[];
+  readonly samplers: readonly SamplerJson[];
+}
+
+const ANIMATION_ACCESSOR_TYPES = ['SCALAR', 'VEC2', 'VEC3', 'VEC4'] as const;
+
+interface AccessorJson {
+  readonly bufferView?: number;
+  readonly componentType: number;
+  readonly type: string;
+  readonly count: number;
+  readonly byteOffset?: number;
+}
+
+interface BufferViewJson {
+  readonly buffer: number;
+  readonly byteOffset?: number;
+  readonly byteLength: number;
+}
+
+export interface GltfAnimationChannelRecord {
+  readonly targetId: AnimationTargetIdValue;
+  readonly targetNodeIndex: number;
+  /** 'translation' | 'rotation' | 'scale' | 'weights'. */
+  readonly property: 'translation' | 'rotation' | 'scale' | 'weights';
+  /** Sampler driving this channel. */
+  readonly sampler: GltfAnimationSamplerRecord;
+}
+
+export interface GltfAnimationSamplerRecord {
+  /** Keyframe timestamp array (ascending). */
+  readonly input: Float32Array;
+  /** Keyframe value array per element size. */
+  readonly output: Float32Array;
+  /** 'LINEAR' | 'STEP'. */
+  readonly interpolation: Interpolation;
+}
+
+export interface GltfAnimationClipRecord {
+  /** Producer-authored animation name, when the source provides one. */
+  readonly name?: string;
+  /** Clip duration = max(sampler.input[last]). */
+  readonly duration: number;
+  /** Per-joint-property channels. */
+  readonly channels: readonly GltfAnimationChannelRecord[];
+}
+
+/**
+ * Parse glTF animations[] array into GltfAnimationClipRecord[].
+ *
+ * Only LINEAR and STEP interpolation are supported. CUBICSPLINE triggers
+ * fail-fast with 'gltf-animation-cubicspline-unsupported'. Channels targeting
+ * morph weights preserve their element-major sampler output for playback.
+ */
+export function parseAnimation(
+  animationsJson: readonly AnimationJson[] | undefined,
+  nodesJson: readonly { readonly name?: string; readonly children?: readonly number[] }[],
+  accessors: readonly AccessorJson[],
+  bufferViews: readonly BufferViewJson[],
+  buffers: readonly Uint8Array[],
+): Result<readonly GltfAnimationClipRecord[], GltfError> {
+  if (animationsJson === undefined || animationsJson.length === 0) {
+    return ok([]);
+  }
+
+  const clips: GltfAnimationClipRecord[] = [];
+  const parentOf = buildNodeParentMap(nodesJson);
+  const nodeByPath = new Map<string, number>();
+  const pathById = new Map<AnimationTargetIdValue, string>();
+
+  for (let animIdx = 0; animIdx < animationsJson.length; animIdx++) {
+    const anim = animationsJson[animIdx];
+    if (anim === undefined) continue;
+
+    // Decode samplers first (shared across channels).
+    const decodedSamplers: GltfAnimationSamplerRecord[] = [];
+    for (let sampIdx = 0; sampIdx < anim.samplers.length; sampIdx++) {
+      const sampler = anim.samplers[sampIdx];
+      if (sampler === undefined) continue;
+
+      const interpolation = (sampler.interpolation ?? 'LINEAR') as string;
+      if (interpolation === 'CUBICSPLINE') {
+        return err(
+          gltfErr('gltf-animation-cubicspline-unsupported', {
+            animationIndex: animIdx,
+            samplerIndex: sampIdx,
+          }),
+        );
+      }
+      if (interpolation !== 'LINEAR' && interpolation !== 'STEP') {
+        return err(
+          gltfErr('gltf-animation-cubicspline-unsupported', {
+            animationIndex: animIdx,
+            samplerIndex: sampIdx,
+          }),
+        );
+      }
+
+      const inputAcc = accessors[sampler.input];
+      if (inputAcc === undefined) {
+        return err(
+          gltfErr('gltf-buffer-out-of-bounds', {
+            accessor: sampler.input,
+            byteOffset: 0,
+            byteLength: 0,
+            bufferIndex: 0,
+          }),
+        );
+      }
+      const inputResult = decodeF32Accessor(
+        sampler.input,
+        inputAcc,
+        ANIMATION_ACCESSOR_TYPES,
+        bufferViews,
+        buffers,
+      );
+      if (!inputResult.ok) return err(inputResult.error);
+
+      const outputAcc = accessors[sampler.output];
+      if (outputAcc === undefined) {
+        return err(
+          gltfErr('gltf-buffer-out-of-bounds', {
+            accessor: sampler.output,
+            byteOffset: 0,
+            byteLength: 0,
+            bufferIndex: 0,
+          }),
+        );
+      }
+      const outputResult = decodeF32Accessor(
+        sampler.output,
+        outputAcc,
+        ANIMATION_ACCESSOR_TYPES,
+        bufferViews,
+        buffers,
+      );
+      if (!outputResult.ok) return err(outputResult.error);
+
+      decodedSamplers.push({
+        input: inputResult.value,
+        output: outputResult.value,
+        interpolation: interpolation as Interpolation,
+      });
+    }
+
+    // Decode channels.
+    const channels: GltfAnimationChannelRecord[] = [];
+    for (let chIdx = 0; chIdx < anim.channels.length; chIdx++) {
+      const ch = anim.channels[chIdx];
+      if (ch === undefined) continue;
+
+      const samplerRecord = decodedSamplers[ch.sampler];
+      if (samplerRecord === undefined) {
+        return err(
+          gltfErr('gltf-buffer-out-of-bounds', {
+            accessor: ch.sampler,
+            byteOffset: 0,
+            byteLength: 0,
+            bufferIndex: 0,
+          }),
+        );
+      }
+
+      const targetNodeIdx = ch.target.node;
+      const path =
+        targetNodeIdx === undefined
+          ? { ok: false as const, reason: 'name-missing' as const, nodeIndex: -1 }
+          : resolveNamedNodePath(nodesJson, parentOf, targetNodeIdx);
+      if (!path.ok) {
+        return err(
+          gltfErr('gltf-animation-target-invalid', {
+            reason: path.reason,
+            animationIndex: animIdx,
+            channelIndex: chIdx,
+            nodeIndex: path.nodeIndex,
+          }),
+        );
+      }
+      if (
+        ch.target.path !== 'weights' &&
+        ch.target.path !== 'translation' &&
+        ch.target.path !== 'rotation' &&
+        ch.target.path !== 'scale'
+      ) {
+        return err(
+          gltfErr('gltf-morph-unsupported', {
+            animationIndex: animIdx,
+            channelIndex: chIdx,
+            nodeIndex: ch.target.node ?? -1,
+          }),
+        );
+      }
+      const pathKey = JSON.stringify(path.value);
+      const previousNode = nodeByPath.get(pathKey);
+      if (previousNode !== undefined && previousNode !== targetNodeIdx) {
+        return err(
+          gltfErr('gltf-animation-target-invalid', {
+            reason: 'path-duplicate',
+            animationIndex: animIdx,
+            channelIndex: chIdx,
+            nodeIndex: targetNodeIdx as number,
+          }),
+        );
+      }
+      nodeByPath.set(pathKey, targetNodeIdx as number);
+      const targetId = deriveAnimationTargetId(path.value);
+      const previousPath = pathById.get(targetId);
+      if (previousPath !== undefined && previousPath !== pathKey) {
+        return err(
+          gltfErr('gltf-animation-target-invalid', {
+            reason: 'id-collision',
+            animationIndex: animIdx,
+            channelIndex: chIdx,
+            nodeIndex: targetNodeIdx as number,
+          }),
+        );
+      }
+      pathById.set(targetId, pathKey);
+
+      channels.push({
+        targetId,
+        targetNodeIndex: targetNodeIdx as number,
+        property: ch.target.path,
+        sampler: samplerRecord,
+      });
+    }
+
+    // Compute duration = max(sampler.input[last]) across all channels.
+    let duration = 0;
+    for (const ch of channels) {
+      const input = ch.sampler.input;
+      if (input.length > 0) {
+        const last = input[input.length - 1];
+        if (last !== undefined && last > duration) {
+          duration = last;
+        }
+      }
+    }
+
+    const name = anim.name?.trim();
+    clips.push({
+      ...(name === undefined || name.length === 0 ? {} : { name }),
+      duration,
+      channels,
+    });
+  }
+
+  return ok(clips);
+}

package/src/parse-glb-chunks.ts

@@ -0,0 +1,167 @@
+// parse-glb-chunks.ts - GLB 2.0 binary container parser (w8).
+//
+// Pure function: ArrayBuffer in, Result<{version, length, jsonChunk, binChunk?}, GltfError> out.
+// No fs, no fetch, no global state. Caller owns I/O.
+//
+// GLB 2.0 layout (Khronos KHR glTF-2.0 GLB section):
+//
+//   header (12 bytes, little-endian uint32 each):
+//     magic   = 0x46546C67  ('glTF')
+//     version = 2
+//     length  = total byte length of the GLB container (header + chunks)
+//
+//   chunk (variable):
+//     chunkLength (uint32 LE)
+//     chunkType   (uint32 LE)
+//        0x4E4F534A = 'JSON' - exactly one, must be the first chunk
+//        0x004E4942 = 'BIN'  - at most one, must be the second chunk
+//     chunkData (chunkLength bytes; padded so chunkLength is a multiple of 4)
+//
+// `parseGltfHeader` (asset.version check) lives in parse-gltf-header.ts and
+// is re-exported here so call sites can grab both binary and JSON gates from
+// a single entry without walking module paths.
+
+import { err, type GltfError, gltfErr, ok, type Result } from './errors.js';
+import { parseGltfHeader } from './parse-gltf-header.js';
+
+export type { GltfHeaderJson } from './parse-gltf-header.js';
+export { parseGltfHeader };
+
+const GLB_HEADER_SIZE = 12;
+const GLB_MAGIC = 0x46546c67;
+const CHUNK_HEADER_SIZE = 8;
+const CHUNK_TYPE_JSON = 0x4e4f534a;
+const CHUNK_TYPE_BIN = 0x004e4942;
+
+/** Result payload of {@link parseGlbChunks}. */
+export interface GlbChunks {
+  readonly version: number;
+  readonly length: number;
+  readonly jsonChunk: Uint8Array;
+  readonly binChunk?: Uint8Array;
+}
+
+/**
+ * Split a GLB 2.0 binary container into its `JSON` chunk and optional
+ * `BIN` chunk. Returns the declared `version` and `length` for the caller
+ * to surface in diagnostics.
+ *
+ * Failure path returns one of:
+ *   - `gltf-malformed-header` (magic / chunk shape / declared length / missing JSON)
+ *   - `gltf-version-unsupported` (version != 2)
+ *
+ * The function is pure: no fs / network access; the caller passes the
+ * already-loaded ArrayBuffer.
+ */
+export function parseGlbChunks(
+  buffer: ArrayBuffer,
+  filePath: string,
+): Result<GlbChunks, GltfError> {
+  if (buffer.byteLength < GLB_HEADER_SIZE) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 0,
+      }),
+    );
+  }
+  const view = new DataView(buffer);
+  const magic = view.getUint32(0, true);
+  if (magic !== GLB_MAGIC) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 0,
+        magic,
+      }),
+    );
+  }
+  const version = view.getUint32(4, true);
+  if (version !== 2) {
+    return err(
+      gltfErr('gltf-version-unsupported', {
+        filePath,
+        actualVersion: String(version),
+      }),
+    );
+  }
+  const declaredLength = view.getUint32(8, true);
+  if (declaredLength !== buffer.byteLength) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 8,
+      }),
+    );
+  }
+
+  // First chunk MUST be JSON.
+  let offset = GLB_HEADER_SIZE;
+  if (offset + CHUNK_HEADER_SIZE > buffer.byteLength) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: offset,
+      }),
+    );
+  }
+  const jsonChunkLength = view.getUint32(offset, true);
+  const jsonChunkType = view.getUint32(offset + 4, true);
+  if (jsonChunkType !== CHUNK_TYPE_JSON) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: offset + 4,
+      }),
+    );
+  }
+  if (offset + CHUNK_HEADER_SIZE + jsonChunkLength > buffer.byteLength) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: offset,
+      }),
+    );
+  }
+  const jsonChunk = new Uint8Array(buffer, offset + CHUNK_HEADER_SIZE, jsonChunkLength);
+  offset += CHUNK_HEADER_SIZE + jsonChunkLength;
+
+  // Optional BIN chunk follows JSON.
+  let binChunk: Uint8Array | undefined;
+  if (offset < buffer.byteLength) {
+    if (offset + CHUNK_HEADER_SIZE > buffer.byteLength) {
+      return err(
+        gltfErr('gltf-malformed-header', {
+          filePath,
+          byteOffset: offset,
+        }),
+      );
+    }
+    const binChunkLength = view.getUint32(offset, true);
+    const binChunkType = view.getUint32(offset + 4, true);
+    if (binChunkType !== CHUNK_TYPE_BIN) {
+      return err(
+        gltfErr('gltf-malformed-header', {
+          filePath,
+          byteOffset: offset + 4,
+        }),
+      );
+    }
+    if (offset + CHUNK_HEADER_SIZE + binChunkLength > buffer.byteLength) {
+      return err(
+        gltfErr('gltf-malformed-header', {
+          filePath,
+          byteOffset: offset,
+        }),
+      );
+    }
+    binChunk = new Uint8Array(buffer, offset + CHUNK_HEADER_SIZE, binChunkLength);
+  }
+
+  return ok({
+    version,
+    length: declaredLength,
+    jsonChunk,
+    ...(binChunk === undefined ? {} : { binChunk }),
+  });
+}

package/src/parse-glb.ts

@@ -0,0 +1,16 @@
+// parse-glb.ts - GLB-entry re-export shell (w17 + w19).
+//
+// `parseGlb` itself lives in parse-gltf.ts (so it shares a single module
+// closure with `parseGltf` + `toAssetPack` and avoids circular imports).
+// This file is the named entry point listed in plan-tasks.json target
+// files; it re-exports the surface so the package layout matches the
+// component map in plan-strategy section 3.1 / gltf_pkg.Pure.
+//
+// w19 adds the `parseGlbFromFile` file-entry shell which performs the
+// sidecar `<source>.meta.json` stat pre-step (plan-strategy section 2.8
+// path a) before delegating to the pure `parseGlb` core. The file-entry
+// wrapper now lives in `node-file-entry.ts` and ships under the
+// `@forgeax/engine-gltf/node` sub-entry (browser-bundle hygiene).
+
+export type { ExternalLoader, GltfDoc } from './parse-gltf.js';
+export { parseGlb } from './parse-gltf.js';

package/src/parse-gltf-header.ts

@@ -0,0 +1,58 @@
+// parse-gltf-header.ts - asset.version check for the parsed glTF JSON
+// document (w8). Pure function, no I/O.
+//
+// glTF 2.0 spec section 3.1: every glTF JSON document MUST carry an
+// `asset.version` literal. v1 / v3 are not parsed by this importer
+// (v3 does not exist; v1 is a different format). This step is the gate
+// before any deeper structural traversal.
+//
+// Producers route through `gltfErr` (errors.ts SSOT) so `expected` and
+// `hint` fields stay aligned with the GLTF_ERROR_HINTS table.
+
+import type { GltfError } from './errors.js';
+import { err, gltfErr, ok, type Result } from './errors.js';
+
+/** Minimal JSON shape touched by the version gate. */
+export interface GltfHeaderJson {
+  readonly asset?: { readonly version?: string };
+}
+
+/**
+ * Validate the top-level `asset.version` field of a parsed glTF document.
+ *
+ * On success the JSON object is echoed back unchanged (caller already owns
+ * the parsed representation). On failure, the closed `GltfErrorCode`
+ * surface narrows to either `gltf-malformed-header` (asset block missing)
+ * or `gltf-version-unsupported` (version != "2.0").
+ */
+export function parseGltfHeader(
+  json: unknown,
+  filePath: string,
+): Result<GltfHeaderJson, GltfError> {
+  if (json === null || typeof json !== 'object' || !('asset' in json)) {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 0,
+      }),
+    );
+  }
+  const asset = (json as GltfHeaderJson).asset;
+  if (!asset || typeof asset !== 'object' || typeof asset.version !== 'string') {
+    return err(
+      gltfErr('gltf-malformed-header', {
+        filePath,
+        byteOffset: 0,
+      }),
+    );
+  }
+  if (asset.version !== '2.0') {
+    return err(
+      gltfErr('gltf-version-unsupported', {
+        filePath,
+        actualVersion: asset.version,
+      }),
+    );
+  }
+  return ok(json as GltfHeaderJson);
+}