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

package/src/fbx-importer.ts

@@ -0,0 +1,146 @@
+// fbx-importer.ts — TS wrapper around the ufbx WASM parser.
+
+import type { ImportContext, Importer, 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 { toAssetPack } from './to-asset-pack.js';
+
+export interface FbxSourceKeyOutput {
+  readonly kind: string;
+  readonly name?: 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 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[] };
+}
+
+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) {
+      const wrapper = new Error(`fbx-source-unreadable: ${ctx.source}`);
+      (wrapper as { cause?: unknown }).cause = read.error;
+      throw wrapper;
+    }
+
+    await initFbxWasm();
+    const jsonStr = parseFbx(read.value);
+    const doc = JSON.parse(jsonStr) as FbxRawDocument &
+      FbxRawSkeletonDoc &
+      FbxRawSkinDoc &
+      FbxRawAnimDoc;
+
+    // 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);
+
+    return {
+      ok: true,
+      value: {
+        assets: toAssetPack({
+          meshes,
+          scene,
+          materials,
+          textures,
+          skeleton,
+          skin,
+          animationClips,
+          subAssets: ctx.subAssets,
+          ...(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';