@forgeax/engine-fbx 0.1.2

package/src/fbx-importer.ts

@@ -0,0 +1,372 @@
+// fbx-importer.ts — TS wrapper around the ufbx WASM parser.
+
+import {
+  IMPORT_ERROR_HINTS,
+  type ImportContext,
+  type ImportDiagnostic,
+  ImportError,
+  type Importer,
+  type ImportResult,
+} from '@forgeax/engine-types';
+import { fbxErr } from './errors.js';
+import { initFbxWasm, parseFbx } from './index.js';
+import {
+  type FbxRawAnimDoc,
+  parseAnimationClips,
+  resolveAnimationTargetIds,
+} from './parse-animation-clip.js';
+import { type FbxRawMaterial, parseMaterial } from './parse-material.js';
+import { type FbxRawDocument, type FbxRawMesh, parseMesh } from './parse-mesh.js';
+import { type FbxRawNodes, parseScene } from './parse-scene.js';
+import { type FbxRawSkeletonDoc, parseSkeleton } from './parse-skeleton.js';
+import { type FbxRawSkinDoc, parseSkin } from './parse-skin.js';
+import { parseTextures } from './parse-texture.js';
+import { resolveFbxTexturePath } from './resolve-texture-path.js';
+import { type FbxDecodedTexture, toAssetPack } from './to-asset-pack.js';
+
+export interface FbxSourceKeyOutput {
+  readonly kind: string;
+  readonly name?: string;
+  readonly sourceKey?: string;
+}
+
+export type FbxSourceKeyResult =
+  | { readonly ok: true; readonly keys: readonly string[] }
+  | {
+      readonly ok: false;
+      readonly code: 'missing-source-key' | 'duplicate-source-key' | 'ambiguous-source-key';
+    };
+
+/** Derive FBX output identity from producer semantics, never from sourceIndex. */
+export function sourceKeyForFbxOutput(output: FbxSourceKeyOutput): string | undefined {
+  const kind = output.kind.trim();
+  if (kind.length === 0) return undefined;
+  const explicit = output.sourceKey?.trim();
+  if (explicit !== undefined && explicit.length > 0) return explicit;
+  const name = output.name?.trim();
+  return name === undefined || name.length === 0 ? `fbx:${kind}` : `fbx:${kind}:${name}`;
+}
+
+export function deriveFbxSourceKeys(outputs: readonly FbxSourceKeyOutput[]): FbxSourceKeyResult {
+  const keys = outputs.map(sourceKeyForFbxOutput);
+  if (keys.some((key) => key === undefined)) return { ok: false, code: 'missing-source-key' };
+  const seen = new Set<string>();
+  for (const [index, key] of keys.entries()) {
+    if (key === undefined) continue;
+    if (seen.has(key)) {
+      return {
+        ok: false,
+        code: outputs[index]?.name === undefined ? 'ambiguous-source-key' : 'duplicate-source-key',
+      };
+    }
+    seen.add(key);
+  }
+  return { ok: true, keys: keys as string[] };
+}
+
+function validationError(
+  ctx: ImportContext,
+  textureIndex: number,
+  code: string,
+  actual: string,
+  hint: string,
+): ImportError {
+  const diagnostic: ImportDiagnostic = {
+    code,
+    severity: 'error',
+    sourcePath: `${ctx.source}#textures[${textureIndex}]`,
+    sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+    rule: 'fbx-external-texture-dependency-closure',
+    expected:
+      'every bound FBX texture resolves to one readable supported image in the authorized scope',
+    actual,
+    hint,
+  };
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: diagnostic.expected,
+    hint: IMPORT_ERROR_HINTS['source-validation-failed'],
+    detail: { diagnostics: [diagnostic] },
+  });
+}
+
+const FBX_PARSE_DIAGNOSTIC_MAX = 256;
+const FBX_PARSE_EXPECTED = 'a readable FBX source that ufbx can parse';
+
+function boundedErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.length <= FBX_PARSE_DIAGNOSTIC_MAX
+    ? message
+    : `${message.slice(0, FBX_PARSE_DIAGNOSTIC_MAX - 3)}...`;
+}
+
+function parseValidationError(ctx: ImportContext, error: unknown): ImportError {
+  const actual = boundedErrorMessage(error);
+  const diagnostic: ImportDiagnostic = {
+    code: 'fbx-source-parse-failed',
+    severity: 'error',
+    sourcePath: ctx.source,
+    sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+    rule: 'fbx-source-parse',
+    expected: FBX_PARSE_EXPECTED,
+    actual,
+    hint: 'repair or re-export the FBX source, then retry the same importer and source path',
+  };
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: FBX_PARSE_EXPECTED,
+    actual,
+    hint: IMPORT_ERROR_HINTS['source-validation-failed'],
+    detail: { diagnostics: [diagnostic] },
+  });
+}
+
+function importCandidates(ctx: ImportContext): readonly { readonly relativePath: string }[] {
+  const raw = ctx.importSettings.fbxCandidatePaths;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((path): { readonly relativePath: string }[] =>
+    typeof path === 'string' ? [{ relativePath: path }] : [],
+  );
+}
+
+function mimeForTexture(
+  path: string,
+  bytes: Uint8Array,
+): 'image/png' | 'image/jpeg' | 'image/x-tga' {
+  const lower = path.toLowerCase();
+  if (lower.endsWith('.png') || (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e)) {
+    return 'image/png';
+  }
+  if (
+    lower.endsWith('.jpg') ||
+    lower.endsWith('.jpeg') ||
+    (bytes[0] === 0xff && bytes[1] === 0xd8)
+  ) {
+    return 'image/jpeg';
+  }
+  return 'image/x-tga';
+}
+
+function textureColorSpace(slot: string): 'srgb' | 'linear' {
+  return slot === 'normalTexture' ||
+    slot === 'metallicRoughnessTexture' ||
+    slot === 'occlusionTexture'
+    ? 'linear'
+    : 'srgb';
+}
+
+export const fbxImporter: Importer = {
+  key: 'fbx',
+
+  async import(ctx: ImportContext): Promise<ImportResult> {
+    // ufbx WASM path: read raw FBX bytes via the import context (browser +
+    // Node both resolve through readSource), then parse in-memory. No native
+    // addon / SDK build step (the WASM module self-loads its .wasm).
+    const read = await ctx.readSource();
+    if (!read.ok) {
+      return {
+        ok: false,
+        error: new ImportError({
+          code: 'source-read-failed',
+          expected: `readable source file at meta.source "${ctx.source}"`,
+          hint: IMPORT_ERROR_HINTS['source-read-failed'],
+          detail: {
+            source: ctx.source,
+            reason: read.error instanceof Error ? read.error.message : String(read.error),
+          },
+        }),
+      };
+    }
+
+    await initFbxWasm();
+    let doc: FbxRawDocument & FbxRawSkeletonDoc & FbxRawSkinDoc & FbxRawAnimDoc;
+    try {
+      const jsonStr = parseFbx(read.value);
+      doc = JSON.parse(jsonStr) as FbxRawDocument &
+        FbxRawSkeletonDoc &
+        FbxRawSkinDoc &
+        FbxRawAnimDoc;
+    } catch (error) {
+      return { ok: false, error: parseValidationError(ctx, error) };
+    }
+
+    // NURBS / patch fail-fast: the bridge emits an error envelope for
+    // unsupported surface types (charter P3 explicit failure).
+    const maybeError = doc as unknown as {
+      error?: { code: string; meshType: string; meshName: string };
+    };
+    if (maybeError.error?.code === 'fbx-mesh-type-unsupported') {
+      const e = fbxErr('fbx-mesh-type-unsupported', {
+        meshType: maybeError.error.meshType as 'nurbs' | 'patch',
+        meshName: maybeError.error.meshName,
+      });
+      // The Importer interface returns Promise<ImportedAsset[]> (not Result),
+      // so structural FbxError cannot flow through the import-runner's typed
+      // error return. Throw a plain Error with the code in the message so
+      // AI users can grep import-internal-error.detail.reason for the
+      // 'fbx-mesh-type-unsupported' substring; the structural error rides on
+      // `.cause`.
+      const wrapper = new Error(`${e.code}: ${e.expected}`);
+      (wrapper as { cause?: unknown }).cause = e;
+      throw wrapper;
+    }
+
+    const rawMeshes: readonly FbxRawMesh[] = doc.meshes ?? [];
+    const meshes = rawMeshes.map((raw, i) => parseMesh(raw, i));
+
+    const scene = parseScene(doc as unknown as FbxRawNodes);
+
+    const texturesModule = doc as unknown as { textures?: readonly unknown[] };
+    const textures = parseTextures({ textures: texturesModule.textures as never });
+
+    const materialDocs =
+      (doc as unknown as { materials?: readonly FbxRawMaterial[] }).materials ?? [];
+    const materials =
+      materialDocs.length > 0
+        ? materialDocs.map((raw, i) => parseMaterial(raw, i))
+        : [parseMaterial({ kind: 'fallback' }, 0)];
+
+    const skeleton = parseSkeleton(doc);
+    const skin = parseSkin(doc);
+    const animationTargets = resolveAnimationTargetIds(
+      (doc as unknown as FbxRawNodes).nodes ?? [],
+      doc.clips ?? [],
+    );
+    if (!animationTargets.ok) {
+      const wrapper = new Error(
+        `${animationTargets.error.code}: ${animationTargets.error.expected}`,
+      );
+      (wrapper as { cause?: unknown }).cause = animationTargets.error;
+      throw wrapper;
+    }
+    const animationClips = parseAnimationClips(doc);
+
+    const textureSlots = new Map<number, string>();
+    for (const material of materials) {
+      for (const binding of material.textureBindings ?? []) {
+        const prior = textureSlots.get(binding.textureIndex);
+        const colorSpace = textureColorSpace(binding.slot);
+        if (prior !== undefined && prior !== colorSpace) {
+          return {
+            ok: false,
+            error: validationError(
+              ctx,
+              binding.textureIndex,
+              'fbx-texture-color-space-conflict',
+              `texture ${binding.textureIndex} is used as both ${prior} and ${colorSpace}`,
+              'split the source texture or author one color-space semantic per FBX texture',
+            ),
+          };
+        }
+        textureSlots.set(binding.textureIndex, colorSpace);
+      }
+    }
+
+    const decodedTextures = new Map<number, FbxDecodedTexture>();
+    for (const texture of textures) {
+      const guidDeclared = ctx.subAssets.some(
+        (subAsset) => subAsset.kind === 'texture' && subAsset.sourceIndex === texture.sourceIndex,
+      );
+      if (!guidDeclared) continue;
+
+      let bytes: Uint8Array;
+      let sourcePath = texture.filePath;
+      if (texture.embeddedBytes !== undefined && texture.embeddedBytes.byteLength > 0) {
+        bytes = texture.embeddedBytes;
+        sourcePath = texture.relativeFilePath ?? texture.filePath;
+      } else {
+        if (texture.type !== undefined && texture.type !== 'file') {
+          return {
+            ok: false,
+            error: validationError(
+              ctx,
+              texture.sourceIndex,
+              'fbx-material-texture-slot-unsupported',
+              `texture type ${texture.type} is not a single file texture`,
+              'flatten layered/procedural FBX textures to a file texture before importing',
+            ),
+          };
+        }
+        const resolution = resolveFbxTexturePath(
+          ctx.source,
+          {
+            ...(texture.relativeFilePath === undefined
+              ? {}
+              : { declaredRelativePath: texture.relativeFilePath }),
+            ...(texture.filePath.length === 0 ? {} : { declaredFilename: texture.filePath }),
+            ...(texture.absoluteFilePath === undefined
+              ? {}
+              : { declaredAbsolutePath: texture.absoluteFilePath }),
+          },
+          importCandidates(ctx),
+        );
+        if (!resolution.ok) {
+          return {
+            ok: false,
+            error: validationError(
+              ctx,
+              texture.sourceIndex,
+              resolution.code,
+              `${resolution.requestedPath}; candidates=${resolution.candidates.join(', ') || '<none>'}`,
+              resolution.code === 'fbx-external-texture-ambiguous'
+                ? 'select a folder whose dependency path is unique; first-match guessing is disabled'
+                : 'select the containing folder so the FBX and its referenced texture are in the authorized candidate scope',
+            ),
+          };
+        }
+        const read = await ctx.readSibling(resolution.readUri);
+        if (!read.ok) return read;
+        bytes = read.value;
+        sourcePath = resolution.relativePath;
+      }
+
+      const slot =
+        [...textureSlots.entries()].find(([index]) => index === texture.sourceIndex)?.[1] ?? 'srgb';
+      const decoded = await ctx.decodeImage(bytes, mimeForTexture(sourcePath, bytes), {
+        ...ctx.importSettings,
+        colorSpace: slot,
+      });
+      if (!decoded.ok) {
+        const reason =
+          decoded.error.code === 'image-decode-failed'
+            ? decoded.error.detail.reason
+            : `${decoded.error.code}: ${JSON.stringify(decoded.error.detail)}`;
+        return {
+          ok: false,
+          error: validationError(
+            ctx,
+            texture.sourceIndex,
+            'fbx-external-texture-decode-failed',
+            `${sourcePath}: ${reason}`,
+            'repair or re-export the referenced image, then retry the FBX import',
+          ),
+        };
+      }
+      decodedTextures.set(texture.sourceIndex, {
+        texture: decoded.value.texture,
+        bytes: decoded.value.bytes,
+        ...(decoded.value.mediaType === undefined ? {} : { mediaType: decoded.value.mediaType }),
+        ...(decoded.value.assetCodec === undefined ? {} : { assetCodec: decoded.value.assetCodec }),
+      });
+    }
+
+    return {
+      ok: true,
+      value: {
+        assets: toAssetPack({
+          meshes,
+          scene,
+          materials,
+          textures,
+          skeleton,
+          skin,
+          animationClips,
+          subAssets: ctx.subAssets,
+          decodedTextures,
+          ...(ctx.sourceOverrides === undefined ? {} : { sourceOverrides: ctx.sourceOverrides }),
+        }),
+        sourceDependencies: [],
+      },
+    };
+  },
+};

package/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * @forgeax/engine-fbx — barrel entry point.
+ *
+ * FBX importer via ufbx compiled to WebAssembly. This file carries the WASM
+ * runtime (initFbxWasm / parseFbx) plus the barrel re-exports of the
+ * parse-*.ts bridge layer + `fbxImporter` (single-entry indexability, charter
+ * F1). Both browser and Node resolve through the same self-loading WASM glue.
+ *
+ * Usage:
+ *   import { fbxImporter } from '@forgeax/engine-fbx';   // build-time importer
+ *   // or the low-level parse API:
+ *   import { initFbxWasm, parseFbx } from '@forgeax/engine-fbx';
+ *   await initFbxWasm();                 // load .wasm once
+ *   const json = parseFbx(fbxBytes);     // Uint8Array -> JSON string
+ *   const pod = JSON.parse(json);        // engine FBX POD schema
+ *
+ * WASM asset resolution (mirrors @forgeax/engine-wgpu-wasm):
+ * - Browser / Vite: new URL() resolves to a fetch-able asset URL.
+ * - Node runtime: the emcc glue is built with ENVIRONMENT=web,node, so it
+ *   self-loads the .wasm via fs from the locateFile URL — no manual
+ *   fs.readFile + wasmBinary hand-off in this layer (Derive, Don't Duplicate).
+ * - vitest: runs under Node; same self-load path.
+ */
+
+// The emcc glue (pkg/fbx-wasm.mjs) is a gitignored build artifact — present only
+// after build:wasm / fetch-wasm. It is imported LAZILY inside _loadWasm (not at
+// module top level) so that merely importing @forgeax/engine-fbx — e.g. the
+// studio editor-core barrel re-exporting cookFbxMeta, or the hermetic
+// barrel-export-contract test (bun test, no wasm build) — does NOT require the
+// built artifact. The glue is only needed once a caller invokes initFbxWasm().
+type CreateFbxModule = (opts?: Record<string, unknown>) => Promise<FbxWasmModule>;
+
+/* ── Types ─────────────────────────────────────────────────────────── */
+
+interface FbxWasmModule {
+  /** @internal emcc-exported C entry: parse FBX bytes at ptr into internal result buffer. */
+  _parseFbxWasm(ptr: number, size: number): void;
+  /** @internal emcc-exported C entry: pointer to the result JSON string. */
+  _getResultPtr(): number;
+  /** @internal emcc-exported C entry: byte length of the result JSON string. */
+  _getResultLen(): number;
+  /** @internal emcc-exported C entry: free the result buffer. */
+  _freeResult(): void;
+  /** @internal emscripten runtime: allocate `size` bytes in the wasm heap. */
+  _malloc(size: number): number;
+  /** @internal emscripten runtime: free a wasm-heap pointer. */
+  _free(ptr: number): void;
+  HEAPU8: Uint8Array;
+  UTF8ToString(ptr: number, maxLen?: number): string;
+}
+
+let wasmModule: FbxWasmModule | null = null;
+let initPromise: Promise<FbxWasmModule> | null = null;
+
+/* ── Internal loader ───────────────────────────────────────────────── */
+
+async function _loadWasm(overrideUrl?: string): Promise<FbxWasmModule> {
+  // Lazy-load the emcc glue only now that a caller actually wants the wasm.
+  // @vite-ignore keeps the bundler from eagerly resolving the (possibly unbuilt)
+  // artifact at import-graph time; it resolves at call time in every scenario
+  // (browser/Vite, Node, vitest) exactly as the old top-level import did.
+  const glueId = '../pkg/fbx-wasm.mjs';
+  const createModule = ((await import(/* @vite-ignore */ glueId)) as { default: CreateFbxModule })
+    .default;
+
+  // The emcc glue (ENVIRONMENT=web,node) self-loads the .wasm from this URL:
+  // via fetch() in the browser, via fs in Node. We only tell it where to look.
+  const wasmAssetUrl = overrideUrl
+    ? new URL(overrideUrl, import.meta.url)
+    : new URL('../pkg/fbx-wasm.wasm', import.meta.url);
+
+  const opts: Record<string, unknown> = {
+    locateFile: () => wasmAssetUrl.href,
+  };
+
+  try {
+    return await createModule(opts);
+  } catch (cause) {
+    throw new Error(
+      `@forgeax/engine-fbx: failed to load WASM from ${wasmAssetUrl.href}. ` +
+        'pkg/fbx-wasm.wasm may be missing. Self-help: ' +
+        '(1) fetch a prebuilt artifact via `pnpm -F @forgeax/engine-fbx fetch-wasm`, or ' +
+        '(2) compile locally with emcc via `pnpm -F @forgeax/engine-fbx build:wasm`.',
+      { cause },
+    );
+  }
+}
+
+/* ── Public API ────────────────────────────────────────────────────── */
+
+/**
+ * Initialize the WASM module. Must be called once before `parseFbx`.
+ * Safe to call multiple times (idempotent). Null-resets on failure so
+ * transient errors (e.g. fetch jitter) are retryable.
+ *
+ * @param wasmUrl — optional override URL for the .wasm file
+ */
+export async function initFbxWasm(wasmUrl?: string): Promise<void> {
+  if (wasmModule) return;
+
+  if (!initPromise) {
+    initPromise = _loadWasm(wasmUrl).catch((e: unknown) => {
+      initPromise = null;
+      throw e;
+    });
+  }
+
+  wasmModule = await initPromise;
+}
+
+/**
+ * Parse an FBX file in-memory and return the JSON POD string.
+ *
+ * The returned JSON follows the engine FBX POD schema, containing:
+ * meshes, nodes, materials, skeletons, skins, clips.
+ *
+ * @param fbxBytes — raw FBX file bytes (binary or ASCII)
+ * @returns JSON string matching the engine's FBX POD schema
+ * @throws if WASM module is not initialized or parse fails
+ */
+export function parseFbx(fbxBytes: Uint8Array): string {
+  if (!wasmModule) {
+    throw new Error('@forgeax/engine-fbx: WASM not initialized. Call initFbxWasm() first.');
+  }
+
+  const mod = wasmModule;
+  const size = fbxBytes.byteLength;
+
+  const ptr = mod._malloc(size);
+  if (!ptr) throw new Error('fbx-wasm: malloc failed for input buffer');
+
+  try {
+    mod.HEAPU8.set(fbxBytes, ptr);
+    mod._parseFbxWasm(ptr, size);
+  } finally {
+    mod._free(ptr);
+  }
+
+  const resultPtr = mod._getResultPtr();
+  const resultLen = mod._getResultLen();
+
+  if (!resultPtr || !resultLen) {
+    mod._freeResult();
+    throw new Error('fbx-wasm: parseFbxWasm returned empty result');
+  }
+
+  // Decode via a fresh sliced copy, NOT mod.UTF8ToString. Under
+  // ALLOW_MEMORY_GROWTH=1 the emcc glue backs HEAPU8 with a *resizable*
+  // ArrayBuffer (wasmMemory.toResizableBuffer()); glue's UTF8ArrayToString then
+  // calls TextDecoder.decode(HEAPU8.subarray(...)), which modern Chromium
+  // rejects ("The provided ArrayBuffer value must not be resizable"). HEAPU8
+  // .slice() returns a copy backed by a plain, non-resizable ArrayBuffer, so the
+  // decode is accepted in every environment (browser/Vite, Node, vitest).
+  const bytes = mod.HEAPU8.slice(resultPtr, resultPtr + resultLen);
+  mod._freeResult();
+  const json = new TextDecoder().decode(bytes);
+
+  const firstChars = json.substring(0, 30);
+  if (firstChars.includes('"error"')) {
+    const parsed = JSON.parse(json);
+    if (parsed.error) {
+      throw new Error(`fbx-wasm: ${parsed.error.message || 'parse failed'}`);
+    }
+  }
+
+  return json;
+}
+
+/**
+ * Convenience: parse FBX bytes and return the parsed POD object.
+ */
+export function parseFbxToObject(fbxBytes: Uint8Array): Record<string, unknown> {
+  return JSON.parse(parseFbx(fbxBytes));
+}
+
+/**
+ * Check if the WASM module is ready.
+ */
+export function isFbxWasmReady(): boolean {
+  return wasmModule !== null;
+}
+
+/* ── Bridge-layer barrel (parse-*.ts + importer + errors) ──────────── */
+
+export {
+  FBX_ERROR_HINTS,
+  type FbxError,
+  type FbxErrorCode,
+  type FbxErrorDetail,
+  fbxErr,
+} from './errors.js';
+export {
+  deriveFbxSourceKeys,
+  fbxImporter,
+  sourceKeyForFbxOutput,
+} from './fbx-importer.js';
+export {
+  type FbxRawAnimDoc,
+  type FbxRawClip,
+  parseAnimationClips,
+} from './parse-animation-clip.js';
+export { type FbxRawMaterial, parseMaterial } from './parse-material.js';
+export { type FbxRawDocument, type FbxRawMesh, parseMesh } from './parse-mesh.js';
+export { type FbxRawNode, type FbxRawNodes, parseScene } from './parse-scene.js';
+export { type FbxRawSkeletonDoc, parseSkeleton } from './parse-skeleton.js';
+export { type FbxRawSkinDoc, parseSkin } from './parse-skin.js';
+export { type FbxRawTexture, type FbxRawTextures, parseTextures } from './parse-texture.js';
+export {
+  type FbxTextureCandidate,
+  type FbxTexturePathRequest,
+  type FbxTextureResolution,
+  type FbxTextureResolutionStrategy,
+  resolveFbxTexturePath,
+} from './resolve-texture-path.js';
+export { toAssetPack } from './to-asset-pack.js';