@forgeax/engine-fbx 0.1.2

package/src/parse-scene.ts

@@ -0,0 +1,75 @@
+// parse-scene.ts — FBX JSON POD to ScenePod bridge (t29).
+
+import type { SceneEntityPod, ScenePod } from '@forgeax/engine-types';
+
+export interface FbxRawNode {
+  readonly name: string;
+  readonly transform: {
+    readonly translation: [number, number, number];
+    readonly rotation: [number, number, number, number];
+    readonly scale: [number, number, number];
+  };
+  readonly meshIndex: number;
+  readonly children: readonly number[];
+}
+
+export interface FbxRawNodes {
+  readonly nodes?: readonly FbxRawNode[];
+}
+
+export type FbxNodePathResult =
+  | { readonly ok: true; readonly value: readonly string[] }
+  | {
+      readonly ok: false;
+      readonly reason: 'name-missing' | 'path-invalid' | 'hierarchy-cycle';
+      readonly nodeIndex: number;
+    };
+
+export function buildFbxNodePaths(
+  nodes: readonly { readonly name?: string; readonly children?: readonly number[] }[],
+): readonly FbxNodePathResult[] {
+  const parents = new Map<number, number>();
+  for (let index = 0; index < nodes.length; index++) {
+    for (const child of nodes[index]?.children ?? []) parents.set(child, index);
+  }
+  return nodes.map((_, index) => {
+    const reversed: string[] = [];
+    const visited = new Set<number>();
+    let current: number | undefined = index;
+    while (current !== undefined) {
+      if (visited.has(current)) {
+        return { ok: false, reason: 'hierarchy-cycle', nodeIndex: current };
+      }
+      visited.add(current);
+      const name = nodes[current]?.name;
+      if (name === undefined || name.length === 0) {
+        return { ok: false, reason: 'name-missing', nodeIndex: current };
+      }
+      if (name.includes('/')) {
+        return { ok: false, reason: 'path-invalid', nodeIndex: current };
+      }
+      reversed.push(name);
+      current = parents.get(current);
+    }
+    return { ok: true, value: reversed.reverse() };
+  });
+}
+
+export function parseScene(rawNodes: FbxRawNodes): ScenePod {
+  const nodes = rawNodes.nodes ?? [];
+  const entities: SceneEntityPod[] = nodes.map((n) => ({
+    name: n.name,
+    transform: {
+      translation: n.transform.translation,
+      rotation: n.transform.rotation,
+      scale: n.transform.scale,
+    },
+    meshIndex: n.meshIndex >= 0 ? n.meshIndex : null,
+    children: n.children,
+  }));
+
+  return {
+    entities,
+    rootEntityIndex: 0,
+  };
+}

package/src/parse-skeleton.ts

@@ -0,0 +1,46 @@
+// parse-skeleton.ts — M5 t48: TS bridge for skeleton POD data.
+//
+// Consumes the C++ JSON POD skeleton section emitted by t45 binding.cc
+// (WriteSkeletonData), produces SkeletonPod (types SSOT per requirements AC-05).
+//
+// Input schema (from JSON.parse of binding output):
+//   skeletons?: [{
+//     jointCount: number,
+//     inverseBindMatrices: number[],  // jointCount * 16 packed doubles
+//     jointPaths: string[],
+//   }]
+//
+// Output: SkeletonPod { jointCount, inverseBindMatrices: Float32Array, jointPaths }
+
+import type { SkeletonPod } from '@forgeax/engine-types';
+
+export interface FbxRawSkeleton {
+  readonly jointCount: number;
+  readonly inverseBindMatrices: number[];
+  readonly jointPaths: string[];
+}
+
+export interface FbxRawSkeletonDoc {
+  readonly skeletons?: readonly FbxRawSkeleton[];
+}
+
+/**
+ * Parse the first skeleton from a C++ JSON POD document.
+ * Returns an empty skeleton when the document has no skeleton data.
+ */
+export function parseSkeleton(doc: FbxRawSkeletonDoc): SkeletonPod {
+  const skeletons = doc.skeletons;
+  if (!skeletons || skeletons.length === 0) {
+    return { jointCount: 0, inverseBindMatrices: new Float32Array(0), jointPaths: [] };
+  }
+
+  const skel = skeletons[0];
+  if (!skel) {
+    return { jointCount: 0, inverseBindMatrices: new Float32Array(0), jointPaths: [] };
+  }
+  return {
+    jointCount: skel.jointCount,
+    inverseBindMatrices: new Float32Array(skel.inverseBindMatrices),
+    jointPaths: [...skel.jointPaths],
+  };
+}

package/src/parse-skin.ts

@@ -0,0 +1,71 @@
+// parse-skin.ts — M5 t49: TS bridge for skin POD data.
+//
+// Consumes the C++ JSON POD skin section emitted by t45 binding.cc
+// (WriteSkinData), produces SkinPod (types SSOT per requirements AC-06).
+//
+// Input schema (from JSON.parse of binding output):
+//   skins?: [{
+//     meshSourceIndex: number,
+//     jointPaths: string[],
+//     vertexCount: number,
+//     influences: [{ jointIndices: number[], jointWeights: number[] }],
+//   }]
+//
+// Output: SkinPod { skeletonGuid, jointPaths, vertexCount, influences }
+
+import type { SkinPod, SkinVertexInfluencePod } from '@forgeax/engine-types';
+
+export interface FbxRawSkinInfluence {
+  readonly jointIndices: number[];
+  readonly jointWeights: number[];
+}
+
+export interface FbxRawSkin {
+  readonly meshSourceIndex: number;
+  readonly jointPaths: string[];
+  readonly vertexCount: number;
+  readonly influences: readonly FbxRawSkinInfluence[];
+}
+
+export interface FbxRawSkinDoc {
+  readonly skins?: readonly FbxRawSkin[];
+}
+
+function bridgeSkeletonGuid(_jointPaths: readonly string[]): string {
+  // Deterministic GUID from joint paths. Real GUID assignment happens
+  // at import-runner time; this is a placeholder bridge identifier.
+  return 'fbx-skeleton-000000000000';
+}
+
+function toInfluence(raw: FbxRawSkinInfluence): SkinVertexInfluencePod {
+  // Pad to exactly 4 entries
+  const ji = new Uint16Array(4);
+  const jw = new Float32Array(4);
+  for (let i = 0; i < 4; i++) {
+    ji[i] = raw.jointIndices[i] ?? 0;
+    jw[i] = raw.jointWeights[i] ?? 0;
+  }
+  return { jointIndices: ji, jointWeights: jw };
+}
+
+/**
+ * Parse the first skin from a C++ JSON POD document.
+ * Returns an empty skin when the document has no skin data.
+ */
+export function parseSkin(doc: FbxRawSkinDoc): SkinPod {
+  const skins = doc.skins;
+  if (!skins || skins.length === 0) {
+    return { skeletonGuid: '', jointPaths: [], vertexCount: 0, influences: [] };
+  }
+
+  const skin = skins[0];
+  if (!skin) {
+    return { skeletonGuid: '', jointPaths: [], vertexCount: 0, influences: [] };
+  }
+  return {
+    skeletonGuid: bridgeSkeletonGuid(skin.jointPaths),
+    jointPaths: [...skin.jointPaths],
+    vertexCount: skin.vertexCount,
+    influences: skin.influences.map(toInfluence),
+  };
+}

package/src/parse-texture.ts

@@ -0,0 +1,36 @@
+// parse-texture.ts — FBX JSON POD to TexturePod bridge (t30).
+
+import type { TexturePod } from '@forgeax/engine-types';
+
+export interface FbxRawTexture {
+  readonly name?: string;
+  readonly filePath?: string;
+  readonly relativeFilePath?: string;
+  readonly absoluteFilePath?: string;
+  readonly embeddedBytes?: readonly number[];
+  readonly type?: 'file' | 'layered' | 'procedural' | 'shader' | 'unknown';
+  readonly sourceIndex: number;
+}
+
+export interface FbxRawTextures {
+  readonly textures?: readonly FbxRawTexture[];
+}
+
+function normalizePath(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+export function parseTextures(raw: FbxRawTextures): TexturePod[] {
+  const textures = raw.textures ?? [];
+  return textures.map((t) => ({
+    name: t.name ?? t.filePath ?? t.relativeFilePath ?? `texture-${t.sourceIndex}`,
+    filePath: normalizePath(t.filePath ?? t.relativeFilePath ?? ''),
+    ...(t.relativeFilePath === undefined
+      ? {}
+      : { relativeFilePath: normalizePath(t.relativeFilePath) }),
+    ...(t.absoluteFilePath === undefined ? {} : { absoluteFilePath: t.absoluteFilePath }),
+    ...(t.embeddedBytes === undefined ? {} : { embeddedBytes: Uint8Array.from(t.embeddedBytes) }),
+    ...(t.type === undefined ? {} : { type: t.type }),
+    sourceIndex: t.sourceIndex,
+  }));
+}

package/src/resolve-texture-path.ts

@@ -0,0 +1,152 @@
+export type FbxTextureResolutionStrategy = 'exact' | 'case-folded' | 'suffix' | 'basename';
+
+export interface FbxTexturePathRequest {
+  readonly declaredRelativePath?: string;
+  readonly declaredFilename?: string;
+  readonly declaredAbsolutePath?: string;
+}
+
+export interface FbxTextureCandidate {
+  /** Candidate path relative to the FBX source file's directory. */
+  readonly relativePath: string;
+}
+
+export type FbxTextureResolution =
+  | {
+      readonly ok: true;
+      readonly relativePath: string;
+      /** URI passed to ImportContext.readSibling from the FBX source. */
+      readonly readUri: string;
+      readonly strategy: FbxTextureResolutionStrategy;
+    }
+  | {
+      readonly ok: false;
+      readonly code: 'fbx-external-texture-missing' | 'fbx-external-texture-ambiguous';
+      readonly requestedPath: string;
+      readonly candidates: readonly string[];
+    };
+
+function normalizeSourceRelativePath(raw: string): string | undefined {
+  const value = raw.replaceAll('\\', '/');
+  if (value.startsWith('/') || /^[A-Za-z]:\//.test(value) || value.startsWith('//'))
+    return undefined;
+  const parts: string[] = [];
+  for (const part of value.split('/')) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (parts.at(-1) !== undefined && parts.at(-1) !== '..') parts.pop();
+      else parts.push('..');
+    } else {
+      parts.push(part);
+    }
+  }
+  return parts.join('/');
+}
+
+function requestSegments(raw: string): string[] {
+  const value = raw
+    .replaceAll('\\', '/')
+    .replace(/^[A-Za-z]:\//, '')
+    .replace(/^\/+/, '');
+  return value.split('/').filter((part) => part !== '' && part !== '.');
+}
+
+function uniqueMatches(paths: readonly string[], predicate: (path: string) => boolean): string[] {
+  return [...new Set(paths.filter(predicate))];
+}
+
+function longestSuffixLength(request: readonly string[], candidate: readonly string[]): number {
+  let count = 0;
+  while (
+    count < request.length &&
+    count < candidate.length &&
+    request[request.length - 1 - count]?.toLowerCase() ===
+      candidate[candidate.length - 1 - count]?.toLowerCase()
+  ) {
+    count++;
+  }
+  return count;
+}
+
+/** Resolve an FBX-declared texture against a caller-authorized candidate tree. */
+export function resolveFbxTexturePath(
+  sourcePath: string,
+  request: FbxTexturePathRequest,
+  candidates: readonly FbxTextureCandidate[],
+): FbxTextureResolution {
+  const candidatePaths = candidates.flatMap((candidate) => {
+    const normalized = normalizeSourceRelativePath(candidate.relativePath);
+    return normalized === undefined || normalized.length === 0 ? [] : [normalized];
+  });
+  const requestedPath =
+    request.declaredRelativePath ?? request.declaredFilename ?? request.declaredAbsolutePath ?? '';
+  void sourcePath;
+
+  const choose = (
+    matches: readonly string[],
+    strategy: FbxTextureResolutionStrategy,
+  ): FbxTextureResolution | undefined => {
+    const unique = [...new Set(matches)];
+    if (unique.length === 1) {
+      const relativePath = unique[0];
+      if (relativePath === undefined) return undefined;
+      return {
+        ok: true,
+        relativePath,
+        readUri: relativePath,
+        strategy,
+      };
+    }
+    if (unique.length > 1) {
+      return {
+        ok: false,
+        code: 'fbx-external-texture-ambiguous',
+        requestedPath,
+        candidates: unique,
+      };
+    }
+    return undefined;
+  };
+
+  const relativeRequest = request.declaredRelativePath ?? request.declaredFilename;
+  if (relativeRequest !== undefined && !/^(?:[A-Za-z]:[\\/]|[\\/])/.test(relativeRequest)) {
+    const normalizedRequest = normalizeSourceRelativePath(relativeRequest);
+    if (normalizedRequest !== undefined) {
+      const scopeExact = choose(
+        uniqueMatches(candidatePaths, (path) => path === normalizedRequest),
+        'exact',
+      );
+      if (scopeExact !== undefined) return scopeExact;
+      const scopeFolded = choose(
+        uniqueMatches(
+          candidatePaths,
+          (path) => path.toLowerCase() === normalizedRequest.toLowerCase(),
+        ),
+        'case-folded',
+      );
+      if (scopeFolded !== undefined) return scopeFolded;
+    }
+  }
+
+  const requestedSegments = requestSegments(requestedPath);
+  if (requestedSegments.length > 0) {
+    const scored = candidatePaths.map((path) => ({
+      path,
+      score: longestSuffixLength(requestedSegments, path.split('/')),
+    }));
+    const bestScore = Math.max(0, ...scored.map((entry) => entry.score));
+    if (bestScore > 0) {
+      const best = scored.filter((entry) => entry.score === bestScore).map((entry) => entry.path);
+      const strategy: FbxTextureResolutionStrategy = bestScore === 1 ? 'basename' : 'suffix';
+      const suffix = choose(best, strategy);
+      if (suffix !== undefined) return suffix;
+    }
+  }
+
+  return {
+    ok: false,
+    code: 'fbx-external-texture-missing',
+    requestedPath,
+    candidates: candidatePaths,
+  };
+}