Skip to content

Code-first video & image, rendered natively on WebGPU.

37.3 KB
Raw Blame
import fs from "node:fs";
import path from "node:path";
import { inflateSync } from "node:zlib";
import { type Mat4, Matrix4Math, type Vec3 } from "../math3d/index.js";
import {
	accumulateVertexNormals,
	resolveModelTransform,
} from "./mesh-utils.js";
import { poseNodes, type Quat } from "./pose.js";
import {
	isSupportedTexture,
	readTextureFile,
	textureMime,
	warnMissingTexture,
} from "./texture-files.js";
import type {
	AnimationClip3D,
	LoadModelOptions,
	Material3D,
	Mesh3DData,
	Model3DData,
	ModelNode3D,
	NodeAnimationTrack3D,
	Skin3D,
} from "./types.js";

interface FBXNode {
	name: string;
	props: unknown[];
	children: FBXNode[];
}

export class FbxLoader {
	public static readonly FBX_KTIME = 46186158000.0;

	/**
	 * Parses binary or text FBX buffer/string into Model3DData.
	 */
	public static parse(
		bufferOrString: ArrayBuffer | Uint8Array | string,
		options: LoadModelOptions = {},
	): Model3DData {
		const rootNode =
			typeof bufferOrString === "string"
				? FbxLoader.parseAscii(bufferOrString)
				: FbxLoader.isBinary(bufferOrString)
					? FbxLoader.parseBinary(bufferOrString)
					: FbxLoader.parseAscii(new TextDecoder().decode(bufferOrString));

		return FbxLoader.buildModelFromTree(rootNode, options);
	}

	public static isBinary(buffer: ArrayBuffer | Uint8Array): boolean {
		const view = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
		if (view.length < 27) return false;
		const header = "Kaydara FBX Binary  \0\x1a\0";
		for (let i = 0; i < header.length; i++) {
			if (view[i] !== header.charCodeAt(i)) return false;
		}
		return true;
	}

	/**
	 * Parses Binary FBX 7.x/6.x format.
	 */
	public static parseBinary(buffer: ArrayBuffer | Uint8Array): FBXNode {
		const u8 = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
		const view = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);

		const version = view.getUint32(23, true);
		const is64Bit = version >= 7500;
		let offset = 27;

		const root: FBXNode = { name: "Root", props: [], children: [] };

		const readNode = (): FBXNode | null => {
			if (offset >= u8.byteLength) return null;

			let endOffset: number;
			let numProperties: number;
			let nameLen: number;

			if (is64Bit) {
				if (offset + 25 > u8.byteLength) return null;
				endOffset = Number(view.getBigUint64(offset, true));
				numProperties = Number(view.getBigUint64(offset + 8, true));
				nameLen = view.getUint8(offset + 24);
				offset += 25;
			} else {
				if (offset + 13 > u8.byteLength) return null;
				endOffset = view.getUint32(offset, true);
				numProperties = view.getUint32(offset + 4, true);
				nameLen = view.getUint8(offset + 12);
				offset += 13;
			}

			// Null node (0 endOffset) signifies end of child block
			if (endOffset === 0) {
				return null;
			}

			const name = new TextDecoder().decode(
				u8.subarray(offset, offset + nameLen),
			);
			offset += nameLen;

			const props: unknown[] = [];
			for (let p = 0; p < numProperties; p++) {
				const typeCode = String.fromCharCode(u8[offset]!);
				offset += 1;

				switch (typeCode) {
					case "Y": {
						props.push(view.getInt16(offset, true));
						offset += 2;
						break;
					}
					case "C":
					case "B": {
						props.push(view.getUint8(offset) !== 0);
						offset += 1;
						break;
					}
					case "I": {
						props.push(view.getInt32(offset, true));
						offset += 4;
						break;
					}
					case "F": {
						props.push(view.getFloat32(offset, true));
						offset += 4;
						break;
					}
					case "D": {
						props.push(view.getFloat64(offset, true));
						offset += 8;
						break;
					}
					case "L": {
						props.push(Number(view.getBigInt64(offset, true)));
						offset += 8;
						break;
					}
					case "S": {
						const len = view.getUint32(offset, true);
						offset += 4;
						const str = new TextDecoder().decode(
							u8.subarray(offset, offset + len),
						);
						props.push(str);
						offset += len;
						break;
					}
					case "R": {
						const len = view.getUint32(offset, true);
						offset += 4;
						const raw = u8.subarray(offset, offset + len);
						props.push(raw);
						offset += len;
						break;
					}
					case "f":
					case "d":
					case "i":
					case "l":
					case "b":
					case "c": {
						const arrayLen = view.getUint32(offset, true);
						const encoding = view.getUint32(offset + 4, true);
						const compressedLen = view.getUint32(offset + 8, true);
						offset += 12;

						let arrayBuffer: Uint8Array;
						if (encoding === 1) {
							const compressedData = u8.subarray(
								offset,
								offset + compressedLen,
							);
							arrayBuffer = inflateSync(compressedData);
							offset += compressedLen;
						} else {
							const byteSize =
								typeCode === "d" || typeCode === "l"
									? 8
									: typeCode === "f" || typeCode === "i"
										? 4
										: 1;
							const totalBytes = arrayLen * byteSize;
							arrayBuffer = u8.subarray(offset, offset + totalBytes);
							offset += totalBytes;
						}

						const arrayView = new DataView(
							arrayBuffer.buffer,
							arrayBuffer.byteOffset,
							arrayBuffer.byteLength,
						);
						if (typeCode === "f") {
							const arr = new Float32Array(arrayLen);
							for (let k = 0; k < arrayLen; k++) {
								arr[k] = arrayView.getFloat32(k * 4, true);
							}
							props.push(arr);
						} else if (typeCode === "d") {
							const arr = new Float64Array(arrayLen);
							for (let k = 0; k < arrayLen; k++) {
								arr[k] = arrayView.getFloat64(k * 8, true);
							}
							props.push(arr);
						} else if (typeCode === "i") {
							const arr = new Int32Array(arrayLen);
							for (let k = 0; k < arrayLen; k++) {
								arr[k] = arrayView.getInt32(k * 4, true);
							}
							props.push(arr);
						} else if (typeCode === "l") {
							const arr = new Float64Array(arrayLen);
							for (let k = 0; k < arrayLen; k++) {
								arr[k] = Number(arrayView.getBigInt64(k * 8, true));
							}
							props.push(arr);
						} else if (typeCode === "b") {
							const arr = new Uint8Array(arrayLen);
							for (let k = 0; k < arrayLen; k++) {
								arr[k] = arrayView.getUint8(k);
							}
							props.push(arr);
						} else {
							props.push(arrayBuffer);
						}
						break;
					}
					default:
						break;
				}
			}

			const children: FBXNode[] = [];
			while (offset < endOffset) {
				const child = readNode();
				if (child) {
					children.push(child);
				} else {
					break;
				}
			}

			offset = endOffset;
			return { name, props, children };
		};

		while (offset < u8.byteLength - (is64Bit ? 25 : 13)) {
			const node = readNode();
			if (node) {
				root.children.push(node);
			} else {
				break;
			}
		}

		return root;
	}

	/**
	 * Parses ASCII FBX format.
	 */
	public static parseAscii(text: string): FBXNode {
		const root: FBXNode = { name: "Root", props: [], children: [] };
		const stack: FBXNode[] = [root];

		const lines = text.split(/\r?\n/);
		for (let i = 0; i < lines.length; i++) {
			const line = lines[i]?.trim();
			if (!line || line.startsWith(";")) continue;

			if (line === "}") {
				if (stack.length > 1) stack.pop();
				continue;
			}

			const colonIdx = line.indexOf(":");
			if (colonIdx === -1) continue;

			const name = line.substring(0, colonIdx).trim();
			const rest = line.substring(colonIdx + 1).trim();

			const hasBrace = rest.endsWith("{");
			const propStr = hasBrace ? rest.slice(0, -1).trim() : rest;

			const props: unknown[] = [];
			if (propStr) {
				const rawProps = propStr.split(",").map((p) => p.trim());
				for (const p of rawProps) {
					if (p.startsWith('"') && p.endsWith('"')) {
						props.push(p.slice(1, -1));
					} else if (!Number.isNaN(Number(p))) {
						props.push(Number(p));
					} else {
						props.push(p);
					}
				}
			}

			const node: FBXNode = { name, props, children: [] };
			const parent = stack[stack.length - 1];
			if (parent) {
				parent.children.push(node);
			}

			if (hasBrace) {
				stack.push(node);
			}
		}

		return root;
	}

	/** Material properties a texture can feed, by the FBX (or Maya / 3ds Max) property name. */
	private static textureSlot(prop: string): "diffuse" | "normal" | undefined {
		const p = prop.toLowerCase();
		if (
			p === "diffusecolor" ||
			p === "diffuse" ||
			p.endsWith("|basecolor") ||
			p.endsWith("|base_color") ||
			p === "basecolor"
		)
			return "diffuse";
		if (
			p === "normalmap" ||
			p.endsWith("|normalcamera") ||
			p.endsWith("|bump_map")
		)
			return "normal";
		return undefined;
	}

	/**
	 * Fills a material's diffuse / normal map from its connected Texture
	 * objects: the bytes embedded in the Video's `Content`, else the file
	 * named by `RelativeFilename` / `FileName`, looked up next to the model.
	 */
	private static attachTextures(
		material: Material3D,
		materialId: number | string,
		objects: Map<number | string, { name: string; node: FBXNode }>,
		connections: Array<{
			childId: number | string;
			parentId: number | string;
			propName?: string;
		}>,
		basePath: string | undefined,
	): void {
		const stringChild = (node: FBXNode | undefined, name: string) => {
			const value = node?.children.find((c) => c.name === name)?.props[0];
			return typeof value === "string" && value ? value : undefined;
		};
		for (const c of connections) {
			if (c.parentId !== materialId || !c.propName) continue;
			const slot = FbxLoader.textureSlot(c.propName);
			const texture = objects.get(c.childId);
			if (!slot || texture?.node.name !== "Texture") continue;
			if (
				slot === "diffuse"
					? material.diffuseTextureBuffer
					: material.normalTextureBuffer
			)
				continue;

			const video = connections
				.filter((v) => v.parentId === c.childId && !v.propName)
				.map((v) => objects.get(v.childId)?.node)
				.find((n) => n?.name === "Video");
			const ref =
				stringChild(texture.node, "RelativeFilename") ??
				stringChild(texture.node, "FileName") ??
				stringChild(video, "RelativeFilename") ??
				stringChild(video, "Filename");

			if (ref && !isSupportedTexture(ref)) {
				warnMissingTexture("FbxLoader", material.name, ref);
				continue;
			}
			let bytes: Uint8Array | undefined;
			const content = video?.children.find((n) => n.name === "Content")
				?.props[0];
			if (content instanceof Uint8Array && content.length > 0) bytes = content;
			else if (ref) bytes = readTextureFile(ref, basePath)?.bytes;

			if (!bytes) {
				if (ref) warnMissingTexture("FbxLoader", material.name, ref);
				continue;
			}
			if (slot === "diffuse") {
				material.diffuseTextureBuffer = bytes;
				material.diffuseTextureMime = textureMime(ref ?? "");
				if (ref) material.diffuseTexture = ref;
				// FBX UVs commonly tile; textures repeat by default in FBX tools.
				material.textureWrap = "repeat";
			} else {
				material.normalTextureBuffer = bytes;
				if (ref) material.normalTexture = ref;
			}
		}
	}

	/**
	 * Builds ready-to-render Model3DData from parsed FBX node tree.
	 */
	public static buildModelFromTree(
		root: FBXNode,
		options: LoadModelOptions = {},
	): Model3DData {
		const objectsNode = root.children.find((c) => c.name === "Objects");
		const connectionsNode = root.children.find((c) => c.name === "Connections");

		interface ObjectEntry {
			id: number | string;
			name: string;
			type: string;
			node: FBXNode;
		}

		const objects = new Map<number | string, ObjectEntry>();
		if (objectsNode) {
			for (const child of objectsNode.children) {
				const id = (child.props[0] as number | string) ?? 0;
				const nameWithSub = String(child.props[1] ?? "");
				const parts = nameWithSub.split("::");
				const name = parts.length > 1 ? parts[1]! : parts[0]!;
				const type = String(child.props[2] ?? child.name);
				objects.set(id, { id, name, type, node: child });
			}
		}

		// Parse connections DAG: OO (Object-Object) and OP (Object-Property)
		interface Connection {
			childId: number | string;
			parentId: number | string;
			propName?: string;
		}
		const connections: Connection[] = [];
		if (connectionsNode) {
			for (const connNode of connectionsNode.children) {
				if (connNode.name === "C" || connNode.name === "Connect") {
					const mode = String(connNode.props[0]);
					const childId = (connNode.props[1] as number | string) ?? 0;
					const parentId = (connNode.props[2] as number | string) ?? 0;
					const propName =
						mode === "OP" ? String(connNode.props[3]) : undefined;
					connections.push({ childId, parentId, propName });
				}
			}
		}

		// Geometry -> Model -> Material: a mesh uses its model's first material.
		const materialNameForGeometry = (geometryId: number | string) => {
			for (const c of connections) {
				// Some exporters connect the material to the geometry itself.
				const mat =
					c.parentId === geometryId ? objects.get(c.childId) : undefined;
				if (mat?.node.name === "Material" && !c.propName) return mat.name;
			}
			for (const g of connections) {
				if (g.childId !== geometryId || g.propName) continue;
				for (const m of connections) {
					if (m.parentId !== g.parentId || m.propName) continue;
					const mat = objects.get(m.childId);
					if (mat?.node.name === "Material") return mat.name;
				}
			}
			return undefined;
		};

		// 1. Parse Geometry Meshes
		const meshes: Mesh3DData[] = [];
		const materials: Record<string, Material3D> = {};

		function extractArrayProp(
			node: FBXNode | undefined,
		): number[] | Float32Array | Float64Array | Int32Array {
			if (!node) return [];
			if (
				node.props[0] instanceof Float32Array ||
				node.props[0] instanceof Float64Array ||
				node.props[0] instanceof Int32Array ||
				Array.isArray(node.props[0])
			) {
				return node.props[0];
			}
			const aChild = node.children.find((c) => c.name === "a");
			if (aChild && aChild.props.length > 0) {
				return aChild.props as number[];
			}
			if (
				Array.isArray(node.props) &&
				node.props.length > 0 &&
				typeof node.props[0] === "number"
			) {
				return node.props as number[];
			}
			return [];
		}

		// Scene graph: every Model is a node (glTF semantics), parented by its
		// OO connection to another Model. Pre-/post-rotations fold into the
		// rotation; pivots and offsets are not supported.
		const modelIds = [...objects.values()]
			.filter((o) => o.node.name === "Model")
			.map((o) => o.id);
		const nodeIndexById = new Map(modelIds.map((id, i) => [id, i]));
		const nodes: ModelNode3D[] = modelIds.map((id) => {
			const model = objects.get(id)!;
			const parentConn = connections.find(
				(c) => c.childId === id && !c.propName && nodeIndexById.has(c.parentId),
			);
			return {
				name: model.name,
				parent: parentConn ? nodeIndexById.get(parentConn.parentId)! : -1,
				translation: readVec3(model.node, "Lcl Translation", 0),
				rotation: modelRotation(
					model.node,
					fbxEulerToQuat(
						readVec3(model.node, "Lcl Rotation", 0),
						rotationOrder(model.node),
					),
				),
				scale: readVec3(model.node, "Lcl Scaling", 1),
			};
		});
		const modelOfGeometry = (geometryId: number | string) =>
			connections.find(
				(c) =>
					c.childId === geometryId &&
					!c.propName &&
					nodeIndexById.has(c.parentId),
			)?.parentId;

		const skins: Skin3D[] = [];
		for (const [id, entry] of objects) {
			if (
				entry.node.name === "Geometry" &&
				(entry.type === "Mesh" ||
					entry.node.props[2] === "Mesh" ||
					entry.type === "")
			) {
				const geomNode = entry.node;

				const verticesNode = geomNode.children.find(
					(c) => c.name === "Vertices",
				);
				const indicesNode = geomNode.children.find(
					(c) => c.name === "PolygonVertexIndex",
				);
				if (!verticesNode || !indicesNode) continue;

				const rawVerts = extractArrayProp(verticesNode);
				const rawPolyIndices = extractArrayProp(indicesNode);
				const layer = (
					name: string,
					data: string,
					index: string,
					size: number,
				) => {
					const node = geomNode.children.find((c) => c.name === name);
					if (!node) return undefined;
					return layerElement(
						node,
						extractArrayProp(node.children.find((c) => c.name === data)),
						extractArrayProp(node.children.find((c) => c.name === index)),
						size,
					);
				};
				const normalAt = layer(
					"LayerElementNormal",
					"Normals",
					"NormalsIndex",
					3,
				);
				const uvAt = layer("LayerElementUV", "UV", "UVIndex", 2);

				// Triangulate polygons (the last index of each is stored as -(i + 1)).
				// Each corner keeps its control point and its polygon-vertex index,
				// which ByPolygonVertex layers (normals, UVs) are indexed by.
				const corners: Array<{ cp: number; pv: number; poly: number }> = [];
				let polygon: Array<{ cp: number; pv: number }> = [];
				let polyIndex = 0;
				for (let i = 0; i < rawPolyIndices.length; i++) {
					const idx = rawPolyIndices[i]!;
					polygon.push({ cp: idx < 0 ? -(idx + 1) : idx, pv: i });
					if (idx >= 0) continue;
					for (let k = 1; k < polygon.length - 1; k++) {
						for (const c of [polygon[0]!, polygon[k]!, polygon[k + 1]!])
							corners.push({ ...c, poly: polyIndex });
					}
					polygon = [];
					polyIndex++;
				}

				const numVerts = corners.length;
				const outPositions = new Float32Array(numVerts * 3);
				const outNormals = new Float32Array(numVerts * 3);
				const outUvs = new Float32Array(numVerts * 2);
				const outIndices = new Array<number>(numVerts);
				corners.forEach(({ cp, pv, poly }, v) => {
					outPositions[v * 3] = rawVerts[cp * 3] ?? 0;
					outPositions[v * 3 + 1] = rawVerts[cp * 3 + 1] ?? 0;
					outPositions[v * 3 + 2] = rawVerts[cp * 3 + 2] ?? 0;
					const n = normalAt?.(cp, pv, poly);
					outNormals.set(n ?? [0, 0, 1], v * 3);
					const uv = uvAt?.(cp, pv, poly);
					outUvs[v * 2] = uv?.[0] ?? 0;
					outUvs[v * 2 + 1] = 1.0 - (uv?.[1] ?? 0);
					outIndices[v] = v;
				});

				if (!normalAt || options.smoothNormals) {
					outNormals.fill(0);
					accumulateVertexNormals(outPositions, outIndices, outNormals);
				}

				// Skin: each cluster deforms the control points in its Indexes by its
				// Weights, driven by the bone Model linked to it.
				const skinConn = connections.find(
					(c) =>
						c.parentId === id &&
						objects.get(c.childId)?.node.name === "Deformer" &&
						objects.get(c.childId)?.node.props[2] === "Skin",
				);

				let jointIndices: Float32Array | undefined;
				let jointWeights: Float32Array | undefined;
				let skinIndex: number | undefined;
				if (skinConn) {
					const joints: number[] = [];
					const inverseBinds: number[] = [];
					// Per control point: up to 4 (joint, weight) influences.
					const influences = new Map<number, Array<[number, number]>>();
					for (const cc of connections) {
						const cluster = objects.get(cc.childId);
						if (
							cc.parentId !== skinConn.childId ||
							cluster?.node.name !== "Deformer" ||
							cluster.node.props[2] !== "Cluster"
						)
							continue;
						const boneId = connections.find(
							(b) => b.parentId === cluster.id && nodeIndexById.has(b.childId),
						)?.childId;
						if (boneId === undefined) continue;
						const joint = joints.length;
						joints.push(nodeIndexById.get(boneId)!);
						// Vertices sit in the mesh's bind space (Transform); the bone's
						// bind-pose world matrix is TransformLink.
						const transform = matrixChild(cluster.node, "Transform");
						const link = matrixChild(cluster.node, "TransformLink");
						inverseBinds.push(
							...Matrix4Math.multiply(
								Matrix4Math.invert(link) ?? Matrix4Math.identity(),
								transform,
							),
						);
						const cpIndexes = extractArrayProp(
							cluster.node.children.find((c) => c.name === "Indexes"),
						);
						const cpWeights = extractArrayProp(
							cluster.node.children.find((c) => c.name === "Weights"),
						);
						for (let k = 0; k < cpIndexes.length; k++) {
							const weight = Number(cpWeights[k] ?? 0);
							if (!(weight > 0)) continue;
							const cp = Number(cpIndexes[k]);
							const list = influences.get(cp) ?? [];
							list.push([joint, weight]);
							influences.set(cp, list);
						}
					}
					if (joints.length > 0) {
						skinIndex = skins.length;
						skins.push({
							joints,
							inverseBindMatrices: new Float32Array(inverseBinds),
						});
						jointIndices = new Float32Array(numVerts * 4);
						jointWeights = new Float32Array(numVerts * 4);
						corners.forEach(({ cp }, v) => {
							// The 4 strongest influences, renormalized to sum to 1.
							const top = (influences.get(cp) ?? [])
								.sort((a, b) => b[1] - a[1])
								.slice(0, 4);
							const total = top.reduce((sum, [, w]) => sum + w, 0);
							top.forEach(([joint, weight], slot) => {
								jointIndices![v * 4 + slot] = joint;
								jointWeights![v * 4 + slot] = total > 0 ? weight / total : 0;
							});
						});
					}
				}

				const modelId = modelOfGeometry(id);
				const isLarge = numVerts > 65535;
				meshes.push({
					id: `fbx_mesh_${id}`,
					name: entry.name,
					positions: outPositions,
					normals: outNormals,
					uvs: outUvs,
					indices: isLarge
						? new Uint32Array(outIndices)
						: new Uint16Array(outIndices),
					jointIndices,
					jointWeights,
					materialName: materialNameForGeometry(id) ?? entry.name,
					node: modelId !== undefined ? nodeIndexById.get(modelId) : undefined,
					skin: skinIndex,
				});
			}
		}

		// 2. Parse Materials
		for (const [, entry] of objects) {
			if (entry.node.name === "Material") {
				const matNode = entry.node;
				const props70 = matNode.children.find((c) => c.name === "Properties70");

				let diffuseColor: [number, number, number, number] = [1, 1, 1, 1];
				let shininess = 32.0;
				let opacity = 1.0;

				if (props70) {
					for (const p of props70.children) {
						if (p.name === "P") {
							const pName = String(p.props[0]);
							if (pName === "DiffuseColor" || pName === "Color") {
								const r = Number(p.props[4] ?? 1);
								const g = Number(p.props[5] ?? 1);
								const b = Number(p.props[6] ?? 1);
								diffuseColor = [r, g, b, 1.0];
							} else if (
								pName === "Shininess" ||
								pName === "ShininessExponent"
							) {
								shininess = Number(p.props[4] ?? 32);
							} else if (pName === "Opacity") {
								opacity = Number(p.props[4] ?? 1);
								diffuseColor[3] = opacity;
							}
						}
					}
				}

				const material: Material3D = {
					name: entry.name,
					diffuseColor,
					shininess,
					opacity,
				};
				FbxLoader.attachTextures(
					material,
					entry.id,
					objects,
					connections,
					options.basePath,
				);
				materials[entry.name] = material;
			}
		}

		// 3. Parse Animation Stacks & Takes
		const animations: AnimationClip3D[] = [];
		for (const [id, entry] of objects) {
			if (entry.node.name === "AnimationStack") {
				const stackName = entry.name || "Take 001";
				const tracks: NodeAnimationTrack3D[] = [];

				// Find connected AnimationLayer
				const layerConn = connections.find(
					(c) =>
						c.parentId === id &&
						objects.get(c.childId)?.node.name === "AnimationLayer",
				);

				if (layerConn) {
					// Find connected AnimationCurveNodes
					const curveNodeConns = connections.filter(
						(c) =>
							c.parentId === layerConn.childId &&
							objects.get(c.childId)?.node.name === "AnimationCurveNode",
					);

					// One entry per (model, transform); its X/Y/Z curves merge into one track.
					const groups = new Map<
						string,
						{
							nodeName: string;
							modelId: number | string | undefined;
							model: FBXNode | undefined;
							kind: TransformKind;
							defaults: Vec3;
							channels: Array<FbxCurve | undefined>;
						}
					>();

					for (const cnc of curveNodeConns) {
						const curveNodeObj = objects.get(cnc.childId);
						if (!curveNodeObj) continue;

						// Find connected Model/Bone; the OP connection names the property.
						const modelConn = connections.find(
							(c) =>
								c.childId === curveNodeObj.id &&
								objects.get(c.parentId)?.node.name === "Model",
						);
						const targetModel = modelConn
							? objects.get(modelConn.parentId)
							: undefined;
						const kind =
							transformKindFromProperty(modelConn?.propName) ??
							transformKindFromProperty(curveNodeObj.name);
						if (!kind) continue;

						const key = `${targetModel?.id ?? curveNodeObj.id}|${kind}`;
						let group = groups.get(key);
						if (!group) {
							const model = targetModel?.node;
							group = {
								nodeName: targetModel?.name ?? curveNodeObj.name,
								modelId: targetModel?.id,
								model,
								kind,
								defaults: staticTransform(model, curveNodeObj.node, kind),
								channels: [undefined, undefined, undefined],
							};
							groups.set(key, group);
						}

						// Find connected AnimationCurves; "d|X" / "d|Y" / "d|Z" pick the channel.
						const curveConns = connections.filter(
							(c) =>
								c.parentId === curveNodeObj.id &&
								objects.get(c.childId)?.node.name === "AnimationCurve",
						);
						curveConns.forEach((cc, order) => {
							const axis = axisFromProperty(cc.propName) ?? order;
							if (axis > 2) return;
							const curveObj = objects.get(cc.childId)?.node;
							const times = extractArrayProp(
								curveObj?.children.find((c) => c.name === "KeyTime"),
							);
							const values = extractArrayProp(
								curveObj?.children.find((c) => c.name === "KeyValueFloat"),
							);
							const n = Math.min(times.length, values.length);
							if (n === 0) return;
							group.channels[axis] = {
								times: Array.from(times.slice(0, n), (t) => Number(t)),
								values: Array.from(values.slice(0, n), (v) => Number(v)),
							};
						});
					}

					for (const group of groups.values()) {
						const track = buildTransformTrack(group);
						if (!track) continue;
						if (group.modelId !== undefined)
							track.node = nodeIndexById.get(group.modelId);
						// Rotation keys are Lcl Rotation; the node also carries pre/post rotation.
						if (track.rotations && group.model) {
							for (let k = 0; k < track.rotations.length; k += 4) {
								const q = Array.from(
									track.rotations.subarray(k, k + 4),
								) as Quat;
								track.rotations.set(modelRotation(group.model, q), k);
							}
						}
						tracks.push(track);
					}
				}

				let maxDuration = 1.0;
				for (const t of tracks) {
					if (t.times.length > 0) {
						const lastT = t.times[t.times.length - 1] ?? 0;
						if (lastT > maxDuration) maxDuration = lastT;
					}
				}

				animations.push({
					name: stackName,
					duration: maxDuration,
					fps: 30,
					tracks,
				});
			}
		}

		// Bounds of the meshes where the rest pose places them; centering and
		// size become a root transform, since skinned vertices move with bones.
		const model: Model3DData = {
			meshes,
			materials,
			animations,
			nodes,
			skins,
			bounds: {
				min: [0, 0, 0],
				max: [0, 0, 0],
				center: [0, 0, 0],
				size: [0, 0, 0],
				boundingSphereRadius: 0,
			},
		};
		const rest = poseNodes(model, undefined, 0);
		const lo: Vec3 = [Infinity, Infinity, Infinity];
		const hi: Vec3 = [-Infinity, -Infinity, -Infinity];
		for (const mesh of meshes) {
			const place = mesh.node !== undefined ? rest[mesh.node] : undefined;
			for (let i = 0; i < mesh.positions.length; i += 3) {
				const p: Vec3 = [
					mesh.positions[i]!,
					mesh.positions[i + 1]!,
					mesh.positions[i + 2]!,
				];
				const q = place ? Matrix4Math.projectPoint(place, p) : p;
				for (let a = 0; a < 3; a++) {
					if (q[a]! < lo[a]!) lo[a] = q[a]!;
					if (q[a]! > hi[a]!) hi[a] = q[a]!;
				}
			}
		}
		if (!Number.isFinite(lo[0])) {
			lo.fill(-1);
			hi.fill(1);
		}
		const { offset, scale } = resolveModelTransform(
			{
				min: lo,
				max: hi,
				center: [
					(lo[0] + hi[0]) * 0.5,
					(lo[1] + hi[1]) * 0.5,
					(lo[2] + hi[2]) * 0.5,
				],
				size: [hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]],
			},
			options,
		);
		model.rootTransform = Matrix4Math.multiply(
			Matrix4Math.scale(scale[0], scale[1], scale[2]),
			Matrix4Math.translate(-offset[0], -offset[1], -offset[2]),
		);
		const min: Vec3 = [0, 1, 2].map(
			(a) => (lo[a]! - offset[a]!) * scale[a]!,
		) as Vec3;
		const max: Vec3 = [0, 1, 2].map(
			(a) => (hi[a]! - offset[a]!) * scale[a]!,
		) as Vec3;
		model.bounds = {
			min,
			max,
			center: [
				(min[0] + max[0]) * 0.5,
				(min[1] + max[1]) * 0.5,
				(min[2] + max[2]) * 0.5,
			],
			size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
			boundingSphereRadius:
				Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) * 0.5,
		};
		return model;
	}
}

/** A Properties70 vector (Lcl Translation / Rotation / Scaling), `fallback` where absent. */
function readVec3(node: FBXNode, name: string, fallback: number): Vec3 {
	const v = readProperty70(node, name);
	return [0, 1, 2].map((a) => {
		const x = v?.[a];
		return x !== undefined && Number.isFinite(x) ? x : fallback;
	}) as Vec3;
}

function multiplyQuat(a: Quat, b: Quat): Quat {
	return [
		a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
		a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
		a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
		a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
	];
}

/**
 * A Model's full local rotation for an Lcl Rotation `q`:
 * PreRotation · q · PostRotation⁻¹ (FBX always applies pre/post in XYZ order).
 */
function modelRotation(model: FBXNode, q: Quat): Quat {
	const pre = readProperty70(model, "PreRotation");
	const post = readProperty70(model, "PostRotation");
	let out = q;
	if (pre)
		out = multiplyQuat(fbxEulerToQuat(readVec3(model, "PreRotation", 0)), out);
	if (post) {
		const p = fbxEulerToQuat(readVec3(model, "PostRotation", 0));
		out = multiplyQuat(out, [-p[0], -p[1], -p[2], p[3]]);
	}
	return out;
}

/** A 4×4 matrix child (`Transform: *16 { a: … }`), identity when absent. */
function matrixChild(node: FBXNode, name: string): Mat4 {
	const child = node.children.find((c) => c.name === name);
	const raw =
		child?.children.find((c) => c.name === "a")?.props ?? child?.props;
	const values =
		raw?.[0] instanceof Float64Array || raw?.[0] instanceof Float32Array
			? Array.from(raw[0] as ArrayLike<number>)
			: (raw ?? []).map(Number);
	return values.length === 16 ? (values as Mat4) : Matrix4Math.identity();
}

/**
 * A geometry layer (normals, UVs) as a lookup by corner: its mapping says
 * whether values are per control point, per polygon vertex, per polygon or
 * one for all; IndexToDirect layers go through their index array.
 */
function layerElement(
	layer: FBXNode,
	data: ArrayLike<number>,
	index: ArrayLike<number>,
	size: number,
): ((cp: number, pv: number, poly: number) => number[]) | undefined {
	if (data.length === 0) return undefined;
	const text = (name: string) =>
		String(layer.children.find((c) => c.name === name)?.props[0] ?? "");
	const mapping = text("MappingInformationType");
	const indexed =
		/^Index/.test(text("ReferenceInformationType")) && index.length > 0;
	return (cp, pv, poly) => {
		let i =
			mapping === "ByPolygonVertex"
				? pv
				: mapping === "ByPolygon"
					? poly
					: mapping === "AllSame"
						? 0
						: cp; // ByControlPoint / ByVertice
		if (indexed) i = Number(index[i] ?? i);
		return Array.from({ length: size }, (_, c) =>
			Number(data[i * size + c] ?? 0),
		);
	};
}

/** Which local transform an AnimationCurveNode drives. */
type TransformKind = "T" | "R" | "S";

/** One AnimationCurve channel; times stay in FBX KTime ticks. */
interface FbxCurve {
	times: number[];
	values: number[];
}

/**
 * Classifies a curve node from its OP connection property ("Lcl Translation",
 * "Lcl Rotation", "Lcl Scaling") or, failing that, its short name ("T", "R", "S").
 */
function transformKindFromProperty(
	name: string | undefined,
): TransformKind | undefined {
	switch (name) {
		case "Lcl Translation":
		case "T":
			return "T";
		case "Lcl Rotation":
		case "R":
			return "R";
		case "Lcl Scaling":
		case "S":
			return "S";
		default:
			return undefined;
	}
}

/** Channel index of a curve from its curve-node connection property ("d|X" → 0). */
function axisFromProperty(name: string | undefined): number | undefined {
	switch (name) {
		case "d|X":
			return 0;
		case "d|Y":
			return 1;
		case "d|Z":
			return 2;
		default:
			return undefined;
	}
}

/** Numeric values of a Properties70 `P` entry (they start at props[4]). */
function readProperty70(
	node: FBXNode | undefined,
	name: string,
): number[] | undefined {
	const props70 = node?.children.find((c) => c.name === "Properties70");
	const p = props70?.children.find(
		(c) => c.name === "P" && c.props[0] === name,
	);
	if (!p) return undefined;
	return p.props.slice(4).map((v) => Number(v));
}

/** A model's rest value for one transform, used where a channel has no curve. */
function staticTransform(
	model: FBXNode | undefined,
	curveNode: FBXNode,
	kind: TransformKind,
): Vec3 {
	const fallback = kind === "S" ? 1 : 0;
	const modelProp = readProperty70(
		model,
		kind === "T"
			? "Lcl Translation"
			: kind === "R"
				? "Lcl Rotation"
				: "Lcl Scaling",
	);
	const out: Vec3 = [fallback, fallback, fallback];
	for (let axis = 0; axis < 3; axis++) {
		const fromModel = modelProp?.[axis];
		const fromCurveNode = readProperty70(curveNode, `d|${"XYZ"[axis]}`)?.[0];
		const value = fromModel ?? fromCurveNode;
		if (value !== undefined && Number.isFinite(value)) out[axis] = value;
	}
	return out;
}

/** FBX EOrder enum (Model "RotationOrder"): axes in the order they are applied. */
const FBX_ROTATION_ORDERS = ["XYZ", "XZY", "YZX", "YXZ", "ZXY", "ZYX"] as const;

function rotationOrder(model: FBXNode | undefined): string {
	const order = readProperty70(model, "RotationOrder")?.[0] ?? 0;
	// 6 (eSphericXYZ) and anything unknown fall back to XYZ.
	return FBX_ROTATION_ORDERS[order] ?? "XYZ";
}

/**
 * Euler degrees → [x, y, z, w] quaternion. FBX applies the axes in `order`
 * (XYZ: X first, so R = Rz·Ry·Rx).
 */
export function fbxEulerToQuat(
	degrees: Vec3,
	order = "XYZ",
): [number, number, number, number] {
	let q: [number, number, number, number] = [0, 0, 0, 1];
	for (const axisName of order) {
		const axis = "XYZ".indexOf(axisName);
		const half = ((degrees[axis] ?? 0) * Math.PI) / 360;
		const s = Math.sin(half);
		const a: [number, number, number, number] = [0, 0, 0, Math.cos(half)];
		a[axis] = s;
		// q = a · q: each later axis is applied after the ones before it.
		q = [
			a[3] * q[0] + a[0] * q[3] + a[1] * q[2] - a[2] * q[1],
			a[3] * q[1] - a[0] * q[2] + a[1] * q[3] + a[2] * q[0],
			a[3] * q[2] + a[0] * q[1] - a[1] * q[0] + a[2] * q[3],
			a[3] * q[3] - a[0] * q[0] - a[1] * q[1] - a[2] * q[2],
		];
	}
	return q;
}

/** Linear sample of a curve at `t` (KTime ticks), clamped to its ends. */
function sampleCurve(curve: FbxCurve, t: number): number {
	const { times, values } = curve;
	const last = times.length - 1;
	if (t <= times[0]!) return values[0]!;
	if (t >= times[last]!) return values[last]!;
	let k = 0;
	while (k < last - 1 && times[k + 1]! <= t) k++;
	const t0 = times[k]!;
	const t1 = times[k + 1]!;
	const u = t1 > t0 ? (t - t0) / (t1 - t0) : 0;
	return values[k]! + (values[k + 1]! - values[k]!) * u;
}

/**
 * Merges a transform's X/Y/Z curves onto one sorted key set: channels without
 * a key at some time are interpolated, channels without a curve keep the
 * static value. Rotations become quaternions in the model's RotationOrder.
 */
function buildTransformTrack(group: {
	nodeName: string;
	model: FBXNode | undefined;
	kind: TransformKind;
	defaults: Vec3;
	channels: Array<FbxCurve | undefined>;
}): NodeAnimationTrack3D | undefined {
	const keySet = new Set<number>();
	for (const channel of group.channels) {
		for (const t of channel?.times ?? []) keySet.add(t);
	}
	if (keySet.size === 0) return undefined;
	const keys = [...keySet].sort((a, b) => a - b);

	const times = new Float32Array(keys.length);
	const isRotation = group.kind === "R";
	const values = new Float32Array(keys.length * (isRotation ? 4 : 3));
	const order = isRotation ? rotationOrder(group.model) : "XYZ";
	let prev: [number, number, number, number] | undefined;

	keys.forEach((key, k) => {
		times[k] = key / FbxLoader.FBX_KTIME;
		const v: Vec3 = [0, 1, 2].map((axis) => {
			const channel = group.channels[axis];
			return channel ? sampleCurve(channel, key) : group.defaults[axis]!;
		}) as Vec3;
		if (!isRotation) {
			values.set(v, k * 3);
			return;
		}
		const q = fbxEulerToQuat(v, order);
		// Keep neighbours in the same hemisphere so slerp takes the short way.
		if (
			prev &&
			prev[0] * q[0] + prev[1] * q[1] + prev[2] * q[2] + prev[3] * q[3] < 0
		) {
			for (let i = 0; i < 4; i++) q[i] = -q[i]!;
		}
		prev = q;
		values.set(q, k * 4);
	});

	return {
		nodeName: group.nodeName,
		times,
		translations: group.kind === "T" ? values : undefined,
		rotations: isRotation ? values : undefined,
		scales: group.kind === "S" ? values : undefined,
	};
}

export function parseFBX(
	bufferOrText: ArrayBuffer | Uint8Array | string,
	options: LoadModelOptions = {},
): Model3DData {
	return FbxLoader.parse(bufferOrText, options);
}

export function loadFBX(
	srcOrData: string | ArrayBuffer | Uint8Array,
	options: LoadModelOptions = {},
): Model3DData {
	let data: string | ArrayBuffer | Uint8Array = srcOrData;
	if (typeof srcOrData === "string") {
		const trimmed = srcOrData.trim();
		const isInline =
			trimmed.includes("FBXHeaderExtension") || trimmed.includes("Kaydara FBX");
		if (!isInline && typeof fs !== "undefined" && fs.existsSync) {
			try {
				let filePath = srcOrData.startsWith("file://")
					? srcOrData.slice(7)
					: srcOrData;
				try {
					filePath = decodeURIComponent(filePath);
				} catch (_) {}
				if (fs.existsSync(filePath)) {
					const buf = fs.readFileSync(filePath);
					data = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
					// Textures are looked up next to the model.
					options = { basePath: path.dirname(filePath), ...options };
				}
			} catch (_) {}
		}
	}
	return FbxLoader.parse(data, options);
}