@forgeax/engine-fbx 0.1.2

package/src/to-asset-pack.ts

@@ -0,0 +1,813 @@
+// to-asset-pack.ts — aggregate parsed sub-assets into ImportedAsset[] (t31).
+//
+// GUID import-stable iron law: GUIDs come from `ctx.subAssets[]` (the external
+// meta), never minted here. Each parsed POD is matched to its declared GUID by
+// (kind, sourceIndex); a parsed asset that no sub-asset declares is dropped so
+// the produced set stays a subset of the declared set (mirrors gltfImporter).
+// The import-runner then validates produced == declared and rejects mismatches.
+
+import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
+import { packMeshBinV4 } from '@forgeax/engine-import';
+import { box3 } from '@forgeax/engine-math';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type {
+  AnimationClipPod,
+  AssetCodec,
+  AssetRef,
+  ImportedAsset,
+  MaterialAsset,
+  MaterialPod,
+  MaterialTextureBindingPod,
+  MaterialTextureValue,
+  MeshAsset,
+  MeshMaterialSlot,
+  MeshMaterialSlotTopologyEntry,
+  MeshPod,
+  SceneAsset,
+  ScenePod,
+  SkeletonPod,
+  SkinPod,
+  SourceOverrideMap,
+  TextureAsset,
+  TexturePod,
+} from '@forgeax/engine-types';
+import {
+  IMPORT_ERROR_HINTS,
+  ImportError,
+  reconcileMeshMaterialSlotTopology,
+  resolveMeshMaterialSlotDefaultGuid,
+} from '@forgeax/engine-types';
+import { buildFbxNodePaths } from './parse-scene.js';
+
+type SubAsset = {
+  readonly guid: string;
+  readonly sourceIndex: number;
+  readonly kind: string;
+  readonly sourceKey?: string;
+};
+
+/** Resolve the meta-declared GUID for a parsed (kind, sourceIndex) pair. */
+function makeGuidResolver(
+  subAssets: readonly SubAsset[],
+): (kind: string, sourceIndex: number) => string | undefined {
+  const byKey = new Map<string, string>();
+  for (const sub of subAssets) byKey.set(`${sub.kind}:${sub.sourceIndex}`, sub.guid);
+  return (kind, sourceIndex) => byKey.get(`${kind}:${sourceIndex}`);
+}
+
+export function buildMeshAsset(
+  pod: MeshPod,
+  guid: string,
+  influences?: readonly { jointIndices: Uint16Array; jointWeights: Float32Array }[],
+  materialContext: {
+    readonly guidByIndex?: ReadonlyMap<number, string>;
+    readonly nameByIndex?: ReadonlyMap<number, string>;
+    readonly sourceKeyByIndex?: ReadonlyMap<number, string>;
+    readonly previousMaterialSlots?: readonly MeshMaterialSlotTopologyEntry[];
+    readonly materialSlotDefaultOverrides?: Readonly<Record<string, string | null>>;
+    readonly meshSourceKey?: string;
+  } = {},
+): ImportedAsset {
+  const vc = pod.vertices.length / 3;
+  const n = pod.attributes.NORMAL as Float32Array | undefined;
+  // feat-20260629-multi-uv-set-support m1-w6: scan all TEXCOORD_n sets
+  // (n in [0,7]) from MeshPod.attributes. TEXCOORD_0 -> uv (set 0),
+  // TEXCOORD_n for n>=1 -> uvN attribute. >8 sets truncated per D-6.
+  // uvSetCount = max(n) + 1 (not count of keys) so sparse sets (TEXCOORD_0+TEXCOORD_2
+  // without TEXCOORD_1) still get correct interleaved stride with zero-filled gap.
+  let uvSetCount = 1; // always at least 1 (uv slot in interleaved)
+  for (const key of Object.keys(pod.attributes)) {
+    if (key.startsWith('TEXCOORD_')) {
+      const n = Number(key.slice('TEXCOORD_'.length));
+      if (Number.isFinite(n) && n >= 0 && n <= 7) {
+        uvSetCount = Math.max(uvSetCount, n + 1);
+      }
+    }
+  }
+
+  const u = pod.attributes.TEXCOORD_0 as Float32Array | undefined;
+
+  // Skinned meshes use the 18-float interleaved stride (mirror of gltfImporter):
+  // 12 floats (position/normal/uv/tangent) + uint16x4 joints (2 float slots, via
+  // an aliased Uint16 view) + float32x4 weights = 18 floats / 72 bytes. The
+  // runtime deriveVertexBufferLayout expects skinIndex at byte 48, skinWeight at
+  // byte 56. Unskinned meshes keep the 12-float layout.
+  const skinned = influences !== undefined && influences.length === vc && vc > 0;
+  // feat-20260629-multi-uv-set-support m1-w6: dynamic stride.
+  // Canonical interleaved order = position/normal/uv/tangent/skinIndex/skinWeight/uv1..uv7.
+  // Base stride: 12 (unskinned) / 18 (skinned). Extra UV sets add 2F each.
+  // UV1 offset: 12 (unskinned) / 18 (skinned) -- same as glTF bridge m1-w3.
+  const BASE_FLOATS = skinned ? 18 : 12;
+  const UV1_OFFSET = skinned ? 18 : 12;
+  const FLOATS_PER_VERT = BASE_FLOATS + (uvSetCount - 1) * 2;
+  const ib = new Float32Array(vc * FLOATS_PER_VERT);
+  const ibU16 = skinned ? new Uint16Array(ib.buffer) : undefined;
+  const skinIndexAttr = skinned ? new Uint16Array(vc * 4) : undefined;
+  const skinWeightAttr = skinned ? new Float32Array(vc * 4) : undefined;
+
+  for (let i = 0; i < vc; i++) {
+    const d = i * FLOATS_PER_VERT;
+    const p = i * 3;
+    const t = i * 2;
+    ib[d + 0] = pod.vertices[p + 0] ?? 0;
+    ib[d + 1] = pod.vertices[p + 1] ?? 0;
+    ib[d + 2] = pod.vertices[p + 2] ?? 0;
+    ib[d + 3] = n?.[p + 0] ?? 0;
+    ib[d + 4] = n?.[p + 1] ?? 0;
+    ib[d + 5] = n?.[p + 2] ?? 0;
+    ib[d + 6] = u?.[t + 0] ?? 0;
+    ib[d + 7] = u?.[t + 1] ?? 0;
+    ib[d + 8] = 1;
+    ib[d + 9] = 0;
+    ib[d + 10] = 0;
+    ib[d + 11] = 1;
+    if (skinned && ibU16 && skinIndexAttr && skinWeightAttr) {
+      const inf = influences[i];
+      const u16Base = (d + 12) * 2; // float slot 12 -> uint16 index (d+12)*2
+      const sd = i * 4;
+      for (let k = 0; k < 4; k++) {
+        const ji = inf?.jointIndices[k] ?? 0;
+        const jw = inf?.jointWeights[k] ?? 0;
+        ibU16[u16Base + k] = ji;
+        ib[d + 14 + k] = jw;
+        skinIndexAttr[sd + k] = ji;
+        skinWeightAttr[sd + k] = jw;
+      }
+    }
+    // feat-20260629-multi-uv-set-support m1-w6: write uv1..uvK after skin data.
+    // Canonical interleaved order matches glTF bridge m1-w3:
+    // position/normal/uv/tangent/skinIndex/skinWeight/uv1..uv7.
+    // UV1 starts at UV1_OFFSET (12 for unskinned, 18 for skinned) in float slots.
+    // Each additional UV set 2F. Missing texcoordK -> zero-fill (implicit).
+    for (let k = 1; k < uvSetCount; k++) {
+      const srcKey = `TEXCOORD_${k}`;
+      const srcArr = pod.attributes[srcKey] as Float32Array | undefined;
+      const interleavedOffset = UV1_OFFSET + (k - 1) * 2;
+      if (srcArr !== undefined) {
+        ib[d + interleavedOffset + 0] = srcArr[t + 0] ?? 0;
+        ib[d + interleavedOffset + 1] = srcArr[t + 1] ?? 0;
+      }
+      // else: zero-fill (implicit -- Float32Array defaults to 0)
+    }
+  }
+
+  // feat-20260629-multi-uv-set-support m1-w6: per-UV-set standalone typed arrays
+  // for MeshAsset.attributes (uv1..uvK). TEXCOORD_n -> attributes.uvN.
+  // Preserve sparse source-set semantics in the importer-facing mesh.
+  const extraUvAttrs: Record<string, Float32Array> = {};
+  for (let k = 1; k < uvSetCount; k++) {
+    const srcKey = `TEXCOORD_${k}`;
+    const srcArr = pod.attributes[srcKey] as Float32Array | undefined;
+    if (srcArr !== undefined) {
+      const cat = new Float32Array(vc * 2);
+      for (let i = 0; i < vc; i++) {
+        const t2 = i * 2;
+        cat[t2 + 0] = srcArr[t2 + 0] ?? 0;
+        cat[t2 + 1] = srcArr[t2 + 1] ?? 0;
+      }
+      extraUvAttrs[`uv${k}`] = cat;
+    }
+  }
+
+  const attributes: MeshAsset['attributes'] = {
+    position: pod.vertices,
+    normal: n ?? new Float32Array(vc * 3).fill(0),
+    uv: u ?? new Float32Array(vc * 2).fill(0),
+    tangent: new Float32Array(vc * 4).fill(0).map((_, i) => (i % 4 === 0 || i % 4 === 3 ? 1 : 0)),
+    ...(skinIndexAttr ? { skinIndex: skinIndexAttr } : {}),
+    ...(skinWeightAttr ? { skinWeight: skinWeightAttr } : {}),
+    ...extraUvAttrs,
+  };
+
+  const materialSlots: MeshMaterialSlot[] = [];
+  const slotByMaterial = new Map<number | null, number>();
+  const usedNames = new Set<string>();
+  const uniqueName = (raw: string): string => {
+    const base = raw.trim() || 'Material';
+    let candidate = base;
+    let suffix = 2;
+    while (usedNames.has(candidate)) candidate = `${base}_${suffix++}`;
+    usedNames.add(candidate);
+    return candidate;
+  };
+  const materialSlotFor = (materialIndex: number | null): number => {
+    const existing = slotByMaterial.get(materialIndex);
+    if (existing !== undefined) return existing;
+    const guidString =
+      materialIndex === null ? undefined : materialContext.guidByIndex?.get(materialIndex);
+    const parsed = guidString === undefined ? undefined : AssetGuid.parse(guidString);
+    const slotIndex = materialSlots.length;
+    materialSlots.push({
+      slotName: uniqueName(
+        materialIndex === null
+          ? 'Default'
+          : (materialContext.nameByIndex?.get(materialIndex) ?? `Material_${materialIndex}`),
+      ),
+      sourceKey:
+        materialIndex === null
+          ? 'fbx:default'
+          : (materialContext.sourceKeyByIndex?.get(materialIndex) ??
+            `fbx:material:${materialIndex}`),
+      ...(parsed?.ok ? { defaultMaterial: parsed.value } : {}),
+    });
+    slotByMaterial.set(materialIndex, slotIndex);
+    return slotIndex;
+  };
+  const currentMesh: MeshAsset = {
+    kind: 'mesh',
+    vertices: ib,
+    ...(pod.indices ? { indices: pod.indices } : {}),
+    aabb: box3.fromPositions(box3.create(), pod.vertices),
+    attributes,
+    ...(pod.morphTargets === undefined
+      ? {}
+      : {
+          morphTargets: pod.morphTargets.map((target) => ({
+            ...(target.position === undefined
+              ? {}
+              : { position: new Float32Array(target.position) }),
+            ...(target.normal === undefined ? {} : { normal: new Float32Array(target.normal) }),
+            ...(target.tangent === undefined ? {} : { tangent: new Float32Array(target.tangent) }),
+          })),
+        }),
+    ...(pod.morphWeights === undefined ? {} : { morphWeights: new Float32Array(pod.morphWeights) }),
+    submeshes: pod.submeshes.map((sm) => ({
+      indexOffset: sm.indexOffset,
+      indexCount: sm.indexCount,
+      vertexCount: vc,
+      topology: sm.topology,
+      materialSlot: materialSlotFor(sm.materialIndex),
+    })),
+    materialSlots,
+  };
+
+  const reconciled = reconcileMeshMaterialSlotTopology(
+    currentMesh.materialSlots.map((slot) => ({
+      slotName: slot.slotName,
+      ...(slot.sourceKey === undefined ? {} : { sourceKey: slot.sourceKey }),
+      ...(slot.defaultMaterial === undefined
+        ? {}
+        : { defaultMaterialGuid: AssetGuid.format(slot.defaultMaterial) }),
+    })),
+    materialContext.previousMaterialSlots,
+  );
+  if (!reconciled.ok) {
+    throw new ImportError({
+      code: 'mesh-material-slot-topology-change',
+      expected: `unambiguous material slot identity for mesh ${guid}`,
+      hint: IMPORT_ERROR_HINTS['mesh-material-slot-topology-change'],
+      detail: {
+        meshGuid: guid,
+        ...(materialContext.meshSourceKey === undefined
+          ? {}
+          : { meshSourceKey: materialContext.meshSourceKey }),
+        previousIndices: reconciled.error.previousIndices,
+        nextIndices: reconciled.error.nextIndices,
+      },
+    });
+  }
+  const mesh: MeshAsset = {
+    ...currentMesh,
+    submeshes: currentMesh.submeshes.map((submesh) => ({
+      ...submesh,
+      materialSlot: reconciled.currentToStableSlot[submesh.materialSlot] as number,
+    })),
+    materialSlots: reconciled.slots.map((slot, stableIndex) => {
+      const active = reconciled.currentToStableSlot.includes(stableIndex);
+      const effectiveDefault = resolveMeshMaterialSlotDefaultGuid(
+        slot,
+        active
+          ? materialContext.materialSlotDefaultOverrides?.[slot.sourceKey ?? slot.slotName]
+          : undefined,
+      );
+      const parsed = effectiveDefault === undefined ? undefined : AssetGuid.parse(effectiveDefault);
+      return {
+        slotName: slot.slotName,
+        ...(slot.sourceKey === undefined ? {} : { sourceKey: slot.sourceKey }),
+        ...(active && parsed?.ok ? { defaultMaterial: parsed.value } : {}),
+      };
+    }),
+  };
+
+  // The wire projection is dense even when the source mesh intentionally
+  // preserves sparse UV-set presence. Missing intermediate slots are zeroed
+  // only for the canonical v4 payload.
+  const wireAttributes = { ...mesh.attributes } as Record<string, Float32Array | Uint16Array>;
+  for (let k = 1; k < uvSetCount; k++) {
+    if (wireAttributes[`uv${k}`] === undefined) {
+      wireAttributes[`uv${k}`] = new Float32Array(vc * 2);
+    }
+  }
+  const wireMesh: MeshAsset = { ...mesh, attributes: wireAttributes };
+
+  const refs: AssetRef[] = [];
+  const seenRefs = new Set<string>();
+  for (let slotIndex = 0; slotIndex < mesh.materialSlots.length; slotIndex++) {
+    const defaultMaterial = mesh.materialSlots[slotIndex]?.defaultMaterial;
+    const materialGuid =
+      defaultMaterial === undefined ? undefined : AssetGuid.format(defaultMaterial);
+    if (materialGuid !== undefined && !seenRefs.has(materialGuid.toLowerCase())) {
+      seenRefs.add(materialGuid.toLowerCase());
+      refs.push({
+        guid: materialGuid,
+        sourceField: { fieldName: 'materialSlots', arrayIndex: slotIndex },
+      });
+    }
+  }
+
+  return {
+    guid,
+    kind: 'mesh',
+    ...(pod.name !== undefined ? { name: pod.name } : {}),
+    payload: mesh,
+    refs,
+    artifacts: {
+      body: {
+        mediaType: 'application/x-forgeax-mesh',
+        assetCodec: { name: 'mesh-binary', version: '4' },
+        bytes: (() => {
+          const packed = packMeshBinV4(
+            wireMesh as never,
+            materialContext.meshSourceKey ?? 'fbx://mesh',
+            refs.map((ref) => ref.guid),
+          );
+          if (!packed.ok) {
+            throw new ImportError({
+              code: 'import-internal-error',
+              expected: 'mesh-bin v4 producer to accept the canonical FBX mesh projection',
+              hint: 're-cook the FBX source with its Meta sidecar after fixing the mesh payload',
+              detail: { reason: `${packed.error.code}: ${packed.error.actual}` },
+            });
+          }
+          return packed.value;
+        })(),
+      },
+    },
+  };
+}
+
+export interface FbxDecodedTexture {
+  readonly texture: TextureAsset;
+  readonly bytes: Uint8Array;
+  readonly mediaType?: string;
+  readonly assetCodec?: AssetCodec;
+}
+
+function materialBindings(pod: MaterialPod): readonly MaterialTextureBindingPod[] {
+  if (pod.textureBindings !== undefined) return pod.textureBindings;
+  const bindings: MaterialTextureBindingPod[] = [];
+  const legacy: readonly [MaterialTextureBindingPod['slot'], number | undefined][] = [
+    ['baseColorTexture', pod.baseColorTextureIndex],
+    ['metallicRoughnessTexture', pod.metallicRoughnessTextureIndex],
+    ['normalTexture', pod.normalTextureIndex],
+    ['specularTintTexture', pod.specularTintTextureIndex],
+    ['emissiveTexture', pod.emissiveTextureIndex],
+    ['occlusionTexture', pod.occlusionTextureIndex],
+  ];
+  for (const [slot, textureIndex] of legacy) {
+    if (textureIndex !== undefined) bindings.push({ slot, textureIndex });
+  }
+  return bindings;
+}
+
+function buildMaterialAsset(
+  pod: MaterialPod,
+  guid: string,
+  skinned = false,
+  textureGuidByIndex: ReadonlyMap<number, string> = new Map(),
+): ImportedAsset {
+  // A material consumed by a skinned mesh must select the pbr-skin shader so the
+  // runtime PSO chain (LayoutKind 'pbr-skin' + 18-float vertex layout + joint
+  // palette) is exercised; the render-system fail-fasts otherwise (mirror of
+  // gltfImporter's `skinned` routing).
+  const values: Record<string, NonNullable<MaterialAsset['values']>[string]> = {
+    baseColor: pod.baseColorFactor as readonly [number, number, number, number],
+    metallic: pod.metallicFactor,
+    roughness: pod.roughnessFactor,
+  };
+  const refs: AssetRef[] = [];
+  for (const binding of materialBindings(pod)) {
+    const textureGuid = textureGuidByIndex.get(binding.textureIndex);
+    if (textureGuid === undefined) continue;
+    const textureValue: MaterialTextureValue = {
+      // Runtime material loading interprets texture handles as indexes into
+      // this asset's refs[]; the GUID is carried by the corresponding edge.
+      texture: refs.length as unknown as MaterialTextureValue['texture'],
+      ...(binding.texCoord === undefined ? {} : { coordinates: { set: binding.texCoord } }),
+    };
+    values[binding.slot] = textureValue;
+    refs.push({
+      guid: textureGuid,
+      sourceField: { componentName: '<material>', fieldName: binding.slot },
+    });
+  }
+  const mat: MaterialAsset = {
+    kind: 'material',
+    colorSpace: 'linear',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: skinned ? 'forgeax::pbr-skin' : 'forgeax::default-standard-pbr' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values,
+  };
+  return {
+    guid,
+    kind: 'material',
+    ...(pod.name !== undefined ? { name: pod.name } : {}),
+    payload: mat,
+    refs,
+    artifacts: {},
+  };
+}
+
+interface SceneBuildContext {
+  /** mesh sourceIndex -> MeshFilter.assetHandle (a scene refs[] index). */
+  readonly meshHandleByIndex: ReadonlyMap<number, number>;
+  /** mesh sourceIndex carrying the skin deformer; null when the scene has no skin. */
+  readonly skinnedMeshIndex: number | null;
+  /** Skin.skeleton handle (a scene refs[] index); undefined when no skeleton. */
+  readonly skeletonHandle: number | undefined;
+  /** Scene refs[]: [mesh..., skeleton..., skin...] GUIDs. */
+  readonly refs: readonly string[];
+  /**
+   * Skin GUIDs (inline strings) injected into the SceneAsset payload and the
+   * scene envelope's refs[] so the typed scene load pulls each
+   * SkinAsset on the browser-async pack-fetch path. Mirrors gltf-importer:
+   * stored as GUID strings (the on-disk round-trip + parseScenePayload's
+   * resolveSkinGuids accept both shapes).
+   */
+  readonly skinGuids: readonly string[];
+  readonly animationTargetIds: ReadonlySet<string>;
+  readonly morphWeightsByMeshIndex: ReadonlyMap<
+    number,
+    { readonly targetCount: number; readonly weights?: Float32Array }
+  >;
+}
+
+function buildSceneAsset(pod: ScenePod, guid: string, ctx: SceneBuildContext): ImportedAsset {
+  // ChildOf wiring: ScenePod.children[] holds flattened-array indices; invert to
+  // a parent map so each entity emits ChildOf { parent } (localId === array idx).
+  const parentOf = new Map<number, number>();
+  for (let i = 0; i < pod.entities.length; i++) {
+    const e = pod.entities[i];
+    if (!e) continue;
+    for (const childIdx of e.children ?? []) parentOf.set(childIdx, i);
+  }
+  const targetIdByEntity = new Map<number, string>();
+  const nodePaths = buildFbxNodePaths(pod.entities);
+  for (let index = 0; index < nodePaths.length; index++) {
+    const path = nodePaths[index];
+    if (path === undefined || !path.ok) continue;
+    const targetId = deriveAnimationTargetId(path.value);
+    if (ctx.animationTargetIds.has(targetId)) targetIdByEntity.set(index, targetId);
+  }
+
+  const entities = pod.entities.map((e, idx) => {
+    const components: Record<string, Record<string, unknown>> = {
+      Transform: {
+        pos: [e.transform.translation[0], e.transform.translation[1], e.transform.translation[2]],
+        // Quaternion component order [x, y, z, w] (E6).
+        quat: [
+          e.transform.rotation[0],
+          e.transform.rotation[1],
+          e.transform.rotation[2],
+          e.transform.rotation[3],
+        ],
+        scale: [e.transform.scale[0], e.transform.scale[1], e.transform.scale[2]],
+      },
+    };
+
+    // Name is required for postSpawnResolveJoints to match SkinAsset.jointPaths
+    // against the spawned subtree (the skeleton joint resolution path).
+    if (e.name) components.Name = { value: e.name };
+    const targetId = targetIdByEntity.get(idx);
+    if (targetId !== undefined) components.AnimationTargetId = { value: targetId };
+
+    const parent = parentOf.get(idx);
+    if (parent !== undefined) components.ChildOf = { parent };
+
+    if (e.meshIndex !== null) {
+      const meshHandle = ctx.meshHandleByIndex.get(e.meshIndex);
+      if (meshHandle !== undefined) components.MeshFilter = { assetHandle: meshHandle };
+
+      components.MeshRenderer = { materials: [] };
+      const morph = ctx.morphWeightsByMeshIndex.get(e.meshIndex);
+      if (morph !== undefined && morph.targetCount > 0) {
+        const weights = morph.weights ?? new Float32Array(morph.targetCount);
+        if (weights.length !== morph.targetCount) {
+          throw new Error('fbxScene: MorphWeights length does not match morph targets');
+        }
+        components.MorphWeights = { weights: Array.from(weights) };
+      }
+      // Skinned mesh node carries Skin { skeleton: <handle> }; instantiate
+      // resolves the handle and postSpawnResolveJoints fills Skin.joints[].
+      if (ctx.skinnedMeshIndex === e.meshIndex && ctx.skeletonHandle !== undefined) {
+        components.Skin = { skeleton: ctx.skeletonHandle };
+      }
+    }
+
+    return { localId: idx as never, components };
+  });
+
+  const scene: SceneAsset = {
+    kind: 'scene',
+    entities,
+    ...(ctx.skinGuids.length > 0 ? { skinGuids: ctx.skinGuids } : {}),
+  } as SceneAsset;
+
+  return {
+    guid,
+    kind: 'scene',
+    ...(pod.name !== undefined ? { name: pod.name } : {}),
+    payload: scene,
+    refs: ctx.refs.map((guid) => ({ guid })),
+    artifacts: {},
+  };
+}
+
+function buildTextureAsset(
+  pod: TexturePod,
+  guid: string,
+  decoded: FbxDecodedTexture,
+): ImportedAsset {
+  return {
+    guid,
+    kind: 'texture',
+    ...(pod.name !== undefined ? { name: pod.name } : {}),
+    payload: decoded.texture,
+    refs: [],
+    artifacts: {
+      body: {
+        mediaType: decoded.mediaType?.startsWith('image/ktx2')
+          ? decoded.mediaType
+          : 'application/x-forgeax-rgba8',
+        ...(decoded.assetCodec === undefined ? {} : { assetCodec: decoded.assetCodec }),
+        bytes: decoded.bytes,
+      },
+    },
+  };
+}
+
+export function toAssetPack(params: {
+  readonly meshes: readonly MeshPod[];
+  readonly scene: ScenePod;
+  readonly materials: readonly MaterialPod[];
+  readonly textures: readonly TexturePod[];
+  readonly skeleton: SkeletonPod;
+  readonly skin: SkinPod;
+  readonly animationClips: readonly AnimationClipPod[];
+  readonly subAssets: readonly SubAsset[];
+  readonly sourceOverrides?: SourceOverrideMap;
+  readonly decodedTextures?: ReadonlyMap<number, FbxDecodedTexture>;
+}): readonly ImportedAsset[] {
+  const assets: ImportedAsset[] = [];
+  const guidOf = makeGuidResolver(params.subAssets);
+  const textureGuidByIndex = new Map<number, string>();
+  for (const texture of params.subAssets) {
+    if (texture.kind === 'texture') textureGuidByIndex.set(texture.sourceIndex, texture.guid);
+  }
+  const materialGuidByIndex = new Map<number, string>();
+  const materialNameByIndex = new Map<number, string>();
+  const materialSourceKeyByIndex = new Map<number, string>();
+  for (let materialIndex = 0; materialIndex < params.materials.length; materialIndex++) {
+    const materialGuid = guidOf('material', materialIndex);
+    if (materialGuid !== undefined) materialGuidByIndex.set(materialIndex, materialGuid);
+    const materialSourceKey = params.subAssets.find(
+      (entry) => entry.kind === 'material' && entry.sourceIndex === materialIndex,
+    )?.sourceKey;
+    if (materialSourceKey !== undefined) {
+      materialSourceKeyByIndex.set(materialIndex, materialSourceKey);
+    }
+    const materialName = params.materials[materialIndex]?.name;
+    if (materialName !== undefined) materialNameByIndex.set(materialIndex, materialName);
+  }
+
+  // The skin deforms the (single) first mesh; its per-vertex influences promote
+  // both the mesh (18-float skinned layout) and its material (pbr-skin shader).
+  const hasSkin = params.skin.vertexCount > 0;
+  const skinnedMeshSourceIndex = hasSkin ? (params.meshes[0]?.sourceIndex ?? null) : null;
+
+  for (const mesh of params.meshes) {
+    const meshDeclaration = params.subAssets.find(
+      (entry) => entry.kind === 'mesh' && entry.sourceIndex === mesh.sourceIndex,
+    );
+    const guid = meshDeclaration?.guid;
+    if (guid === undefined) continue;
+    const previousRaw =
+      meshDeclaration?.sourceKey === undefined
+        ? undefined
+        : params.sourceOverrides?.[meshDeclaration.sourceKey]?.materialSlots;
+    const previousMaterialSlots = Array.isArray(previousRaw)
+      ? previousRaw.filter(
+          (slot): slot is MeshMaterialSlotTopologyEntry =>
+            slot !== null &&
+            typeof slot === 'object' &&
+            !Array.isArray(slot) &&
+            typeof (slot as { slotName?: unknown }).slotName === 'string',
+        )
+      : undefined;
+    const authoredRaw =
+      meshDeclaration?.sourceKey === undefined
+        ? undefined
+        : params.sourceOverrides?.[meshDeclaration.sourceKey]?.materialSlotDefaultOverrides;
+    const materialSlotDefaultOverrides =
+      authoredRaw !== null && typeof authoredRaw === 'object' && !Array.isArray(authoredRaw)
+        ? Object.fromEntries(
+            Object.entries(authoredRaw).filter(
+              (entry): entry is [string, string | null] =>
+                typeof entry[1] === 'string' || entry[1] === null,
+            ),
+          )
+        : undefined;
+    const inf = mesh.sourceIndex === skinnedMeshSourceIndex ? params.skin.influences : undefined;
+    assets.push(
+      buildMeshAsset(mesh, guid, inf, {
+        guidByIndex: materialGuidByIndex,
+        nameByIndex: materialNameByIndex,
+        sourceKeyByIndex: materialSourceKeyByIndex,
+        ...(previousMaterialSlots === undefined ? {} : { previousMaterialSlots }),
+        ...(materialSlotDefaultOverrides === undefined ? {} : { materialSlotDefaultOverrides }),
+        ...(meshDeclaration?.sourceKey === undefined
+          ? {}
+          : { meshSourceKey: meshDeclaration.sourceKey }),
+      }),
+    );
+  }
+
+  for (let i = 0; i < params.materials.length; i++) {
+    const mat = params.materials[i];
+    if (!mat) continue;
+    const guid = guidOf('material', i);
+    // Single-mesh fixtures: any material is consumed by the skinned mesh.
+    if (guid !== undefined) {
+      assets.push(buildMaterialAsset(mat, guid, hasSkin, textureGuidByIndex));
+    }
+  }
+
+  for (const tex of params.textures) {
+    const guid = guidOf('texture', tex.sourceIndex);
+    if (guid !== undefined) {
+      const decoded = params.decodedTextures?.get(tex.sourceIndex);
+      if (decoded === undefined) {
+        throw new Error(`fbx texture ${tex.sourceIndex} was declared but not decoded`);
+      }
+      assets.push(buildTextureAsset(tex, guid, decoded));
+    }
+  }
+
+  // Scene refs[] ordering (mirror of gltfImporter): only direct scene
+  // dependencies live here. Mesh defaults belong to MeshAsset refs and
+  // textures belong to MaterialAsset refs, so the scene concatenates
+  //   [mesh GUIDs..., skeleton GUIDs..., skin GUIDs...]
+  // each section in declared sourceIndex order. Build the section -> refs-index
+  // maps here so buildSceneAsset can stamp the right indices.
+  const declaredByKind = (kind: string): string[] =>
+    params.subAssets
+      .filter((s) => s.kind === kind)
+      .slice()
+      .sort((a, b) => a.sourceIndex - b.sourceIndex)
+      .map((s) => s.guid);
+
+  const meshGuids = declaredByKind('mesh');
+  const skeletonGuids = declaredByKind('skeleton');
+  const skinGuids = declaredByKind('skin');
+  const sceneRefs = [...meshGuids, ...skeletonGuids, ...skinGuids];
+
+  // mesh sourceIndex -> scene refs[] index (mesh section starts at 0).
+  const meshHandleByIndex = new Map<number, number>();
+  params.subAssets
+    .filter((s) => s.kind === 'mesh')
+    .forEach((s) => {
+      const idx = meshGuids.indexOf(s.guid);
+      if (idx >= 0) meshHandleByIndex.set(s.sourceIndex, idx);
+    });
+  // skeleton handle = first skeleton's scene refs[] index.
+  const skeletonRefBase = meshGuids.length;
+  const skeletonHandle = skeletonGuids.length > 0 ? skeletonRefBase : undefined;
+  // Single-mesh fixtures: the skin deforms the (only) mesh node.
+  const skinnedMeshIndex =
+    params.skin.vertexCount > 0 ? (params.meshes[0]?.sourceIndex ?? null) : null;
+
+  // Skeleton asset (t48). refs[] empty (skeleton is leaf data). The runtime
+  // SkeletonAsset POD is { inverseBindMatrices, jointCount } — joint paths live
+  // on the parallel SkinAsset (mirror of gltfImporter's emit policy). The native
+  // binding derives the skeleton from the skin's clusters, so jointCount /
+  // inverseBindMatrices already align 1:1 with the skin's jointPaths and the
+  // per-vertex skinIndex influences (runtime requires
+  // SkeletonAsset.jointCount === Skin.joints.length).
+  const skeletonGuid = guidOf('skeleton', 0);
+  if (params.skeleton.jointCount > 0 && skeletonGuid !== undefined) {
+    assets.push({
+      guid: skeletonGuid,
+      kind: 'skeleton',
+      payload: {
+        kind: 'skeleton',
+        inverseBindMatrices: params.skeleton.inverseBindMatrices,
+        jointCount: params.skeleton.jointCount,
+      } as never,
+      refs: [],
+      artifacts: {},
+    });
+  }
+
+  // Skin asset (t49). The runtime SkinAsset POD is { skeletonGuid, jointPaths };
+  // per-vertex influences live in the mesh vertex buffer, not the SkinAsset.
+  // refs[] carries the skeleton GUID cross-edge (mirror of gltfImporter) so the
+  // runner / runtime asset graph sees the skin->skeleton link.
+  const skinGuid = guidOf('skin', 0);
+  if (params.skin.vertexCount > 0 && skinGuid !== undefined) {
+    assets.push({
+      guid: skinGuid,
+      kind: 'skin',
+      payload: {
+        kind: 'skin',
+        skeletonGuid: skeletonGuid ?? '',
+        jointPaths: params.skin.jointPaths,
+      } as never,
+      refs:
+        skeletonGuid !== undefined
+          ? [{ guid: skeletonGuid, sourceField: { fieldName: 'skeleton' } }]
+          : [],
+      artifacts: {},
+    });
+  }
+
+  // Animation clip assets (t50)
+  for (let i = 0; i < params.animationClips.length; i++) {
+    const clip = params.animationClips[i];
+    if (!clip) continue;
+    const guid = guidOf('animation-clip', i);
+    if (guid === undefined) continue;
+    assets.push({
+      guid,
+      kind: 'animation-clip',
+      payload: {
+        kind: 'animation-clip',
+        name: clip.name ?? `Clip${i}`,
+        duration: clip.duration,
+        channels: clip.channels.map((ch) => ({
+          targetId: ch.targetId,
+          property: ch.property,
+          sampler: {
+            input: Array.from(ch.sampler.input),
+            output: Array.from(ch.sampler.output),
+            interpolation: ch.sampler.interpolation,
+          },
+        })),
+      } as never,
+      refs: [],
+      artifacts: {},
+    });
+  }
+
+  const sceneGuid = guidOf('scene', 0);
+  const animationTargetIds = new Set(
+    params.animationClips.flatMap((clip) => clip.channels.map((channel) => channel.targetId)),
+  );
+  const morphWeightsByMeshIndex = new Map<
+    number,
+    { readonly targetCount: number; readonly weights?: Float32Array }
+  >();
+  for (const mesh of params.meshes) {
+    const targetCount = mesh.morphTargets?.length ?? 0;
+    if (targetCount > 0) {
+      morphWeightsByMeshIndex.set(mesh.sourceIndex, {
+        targetCount,
+        ...(mesh.morphWeights === undefined
+          ? {}
+          : { weights: new Float32Array(mesh.morphWeights) }),
+      });
+    }
+  }
+  if (sceneGuid !== undefined) {
+    assets.push(
+      buildSceneAsset(params.scene, sceneGuid, {
+        meshHandleByIndex,
+        skinnedMeshIndex,
+        skeletonHandle,
+        refs: sceneRefs,
+        skinGuids,
+        animationTargetIds,
+        morphWeightsByMeshIndex,
+      }),
+    );
+  }
+
+  // XOR identity rule (aligned with the glTF importer): a single-asset package
+  // derives its name from the package path, so the stored entry name is dropped.
+  // Only multi-asset packages keep per-entry stored names. FBX is almost always
+  // multi-asset (a scene asset is always emitted), so this strips name only in
+  // the degenerate single-asset case.
+  if (assets.length === 1) {
+    const only = assets[0];
+    if (only && 'name' in only) {
+      const { name: _dropped, ...rest } = only;
+      assets[0] = rest;
+    }
+  }
+
+  return assets;
+}