@downdraft/engine 0.0.0 → 0.1.0

package/libraries/models/src/fbx/parsers/binary-parser.ts

@@ -0,0 +1,244 @@
+// ============================================================================
+// FBX Binary Parser — binary FBX → FBXNode[] tree
+// ============================================================================
+// Handles FBX binary format versions 6400+ (uint32 headers) and 7500+
+// (uint64 headers). Zlib-compressed arrays are decompressed via fflate.
+//
+// Reference: Babylon.js `parsers/fbxBinaryParser.ts` (292 lines) — similar
+// structure but emits Babylon's internal node type. We emit our FBXNode.
+//
+
+import { assertFinite, assertPositive, MAX_DECOMPRESS_SIZE } from "@downdraft/engine";
+import { decompressSync } from "fflate";
+import { FBX_HEADER_MAGIC, type FBXNode, type FBXProperty } from "../types";
+
+/**
+ * Parse a binary FBX file into an FBXNode[] tree.
+ *
+ * @param data The raw FBX binary data.
+ * @returns The top-level nodes and the FBX version number.
+ */
+export function parseFBXBinary(data: ArrayBuffer): { nodes: FBXNode[]; version: number } {
+  const view = new DataView(data);
+  const headerStr = new TextDecoder().decode(new Uint8Array(data, 0, 21));
+
+  if (!headerStr.startsWith("Kaydara FBX Binary")) {
+    throw new Error("Not a binary FBX file (missing Kaydara header)");
+  }
+
+  const version = view.getUint32(23, true);
+  const nodes: FBXNode[] = [];
+  let offset = 27; // 21 (magic) + 2 (unknown) + 4 (version)
+
+  while (offset < data.byteLength) {
+    const result = parseFBXNode(view, offset, data.byteLength, version);
+    if (result === null) break;
+    if (result.node === null) {
+      offset = result.nextOffset;
+      break;
+    }
+    nodes.push(result.node);
+    offset = result.nextOffset;
+  }
+
+  return { nodes, version };
+}
+
+/**
+ * Parse a single FBX node from the binary stream.
+ * Returns null when the stream ends; returns { node: null, nextOffset } for
+ * the null-record (end-of-children marker).
+ */
+function parseFBXNode(
+  view: DataView,
+  offset: number,
+  endOffset: number,
+  version: number,
+): { node: FBXNode | null; nextOffset: number } | null {
+  // FBX 7500+ uses uint64 header fields (8+8+8+1 = 25 bytes)
+  // FBX < 7500 uses uint32 header fields (4+4+4+1 = 13 bytes)
+  const is64Bit = version >= 7500;
+  const headerSize = is64Bit ? 25 : 13;
+
+  if (offset + headerSize > view.byteLength) return null;
+
+  let nodeEndOffset: number;
+  let numProperties: number;
+  let propertyListLen: number;
+  let nameLen: number;
+
+  if (is64Bit) {
+    // Read uint64 as two uint32; high 32 bits should be 0 for normal-sized files
+    nodeEndOffset = view.getUint32(offset, true);
+    numProperties = view.getUint32(offset + 8, true);
+    propertyListLen = view.getUint32(offset + 16, true);
+    nameLen = view.getUint8(offset + 24);
+  } else {
+    nodeEndOffset = view.getUint32(offset, true);
+    numProperties = view.getUint32(offset + 4, true);
+    propertyListLen = view.getUint32(offset + 8, true);
+    nameLen = view.getUint8(offset + 12);
+  }
+
+  // Null record: all header fields are 0
+  if (nodeEndOffset === 0 && numProperties === 0 && propertyListLen === 0 && nameLen === 0) {
+    return { node: null, nextOffset: offset + headerSize };
+  }
+  if (nodeEndOffset > view.byteLength) return null;
+
+  // For nodes with endOffset=0, use parent's endOffset as the boundary
+  const effectiveEndOffset = nodeEndOffset === 0 ? endOffset : nodeEndOffset;
+
+  let pos = offset + headerSize + nameLen;
+  const name = new TextDecoder().decode(new Uint8Array(view.buffer, pos - nameLen, nameLen));
+
+  const properties: FBXProperty[] = [];
+  const propEnd = pos + propertyListLen;
+
+  for (let i = 0; i < numProperties && pos < propEnd; i++) {
+    const prop = parseFBXProperty(view, pos);
+    if (prop === null) break;
+    properties.push(prop.property);
+    pos = prop.nextOffset;
+  }
+
+  pos = propEnd;
+
+  const children: FBXNode[] = [];
+  while (pos < effectiveEndOffset) {
+    const child = parseFBXNode(view, pos, effectiveEndOffset, version);
+    if (child === null) break;
+    if (child.node === null) {
+      pos = child.nextOffset;
+      break;
+    }
+    children.push(child.node);
+    pos = child.nextOffset;
+  }
+
+  return {
+    node: { name, properties, children },
+    nextOffset: effectiveEndOffset,
+  };
+}
+
+/** Parse a single FBX property value from the binary stream. */
+function parseFBXProperty(
+  view: DataView,
+  offset: number,
+): { property: FBXProperty; nextOffset: number } | null {
+  const typeCode = String.fromCharCode(view.getUint8(offset));
+
+  switch (typeCode) {
+    case "Y": {
+      const value = view.getInt16(offset + 1, true);
+      return { property: { type: "Y", value }, nextOffset: offset + 3 };
+    }
+    case "C": {
+      const value = view.getUint8(offset + 1) !== 0;
+      return { property: { type: "C", value }, nextOffset: offset + 2 };
+    }
+    case "I": {
+      const value = view.getInt32(offset + 1, true);
+      return { property: { type: "I", value }, nextOffset: offset + 5 };
+    }
+    case "F": {
+      const value = view.getFloat32(offset + 1, true);
+      return { property: { type: "F", value }, nextOffset: offset + 5 };
+    }
+    case "D": {
+      const value = view.getFloat64(offset + 1, true);
+      return { property: { type: "D", value }, nextOffset: offset + 9 };
+    }
+    case "L": {
+      const value = Number(view.getBigInt64(offset + 1, true));
+      return { property: { type: "L", value }, nextOffset: offset + 9 };
+    }
+    case "R": {
+      const length = view.getUint32(offset + 1, true);
+      const value = new Uint8Array(view.buffer, offset + 5, length);
+      return { property: { type: "R", value }, nextOffset: offset + 5 + length };
+    }
+    case "S": {
+      const length = view.getUint32(offset + 1, true);
+      const raw = new TextDecoder().decode(
+        new Uint8Array(view.buffer, offset + 5, length),
+      );
+      // FBX strings contain null terminators and \x00\x01 namespace separators.
+      // Strip everything from the first null byte onward.
+      const nullIdx = raw.indexOf("\x00");
+      const value = nullIdx >= 0 ? raw.substring(0, nullIdx) : raw;
+      return { property: { type: "S", value }, nextOffset: offset + 5 + length };
+    }
+    case "f":
+    case "i":
+    case "d":
+    case "l":
+    case "b": {
+      const arrayLength = view.getUint32(offset + 1, true);
+      const encoding = view.getUint32(offset + 5, true);
+      const compLength = view.getUint32(offset + 9, true);
+      const dataStart = offset + 13;
+
+      assertFinite("fbx arrayLength", arrayLength);
+      assertPositive("fbx arrayLength", arrayLength);
+
+      let values: number[];
+
+      if (encoding === 1) {
+        if (arrayLength > MAX_DECOMPRESS_SIZE) {
+          throw new RangeError(
+            `fbx: decompressed array length ${arrayLength} exceeds max ${MAX_DECOMPRESS_SIZE}`,
+          );
+        }
+        const compressed = new Uint8Array(view.buffer, dataStart, compLength);
+        const decompressed = decompressSync(compressed);
+        values = readFBXArray(decompressed, typeCode, arrayLength);
+      } else {
+        const view2 = new DataView(view.buffer, dataStart, compLength);
+        values = readFBXArrayFromView(view2, typeCode, arrayLength);
+      }
+
+      return {
+        property: { type: typeCode as "f" | "i" | "d" | "l" | "b", value: values, encoding },
+        nextOffset: dataStart + compLength,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/** Read a typed array from decompressed bytes. */
+function readFBXArray(data: Uint8Array, typeCode: string, count: number): number[] {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return readFBXArrayFromView(view, typeCode, count);
+}
+
+/** Read a typed array from a DataView (handles both compressed and uncompressed). */
+function readFBXArrayFromView(view: DataView, typeCode: string, count: number): number[] {
+  const values = new Array<number>(count);
+  switch (typeCode) {
+    case "f": {
+      for (let i = 0; i < count; i++) values[i] = view.getFloat32(i * 4, true);
+      break;
+    }
+    case "i": {
+      for (let i = 0; i < count; i++) values[i] = view.getInt32(i * 4, true);
+      break;
+    }
+    case "d": {
+      for (let i = 0; i < count; i++) values[i] = view.getFloat64(i * 8, true);
+      break;
+    }
+    case "l": {
+      for (let i = 0; i < count; i++) values[i] = Number(view.getBigInt64(i * 8, true));
+      break;
+    }
+    case "b": {
+      for (let i = 0; i < count; i++) values[i] = view.getInt32(i * 4, true) !== 0 ? 1 : 0;
+      break;
+    }
+  }
+  return values;
+}

package/libraries/models/src/fbx/types.ts

@@ -0,0 +1,119 @@
+// ============================================================================
+// FBX Internal Types — node tree, properties, connections
+// ============================================================================
+// Shared between the binary parser and the interpreter layer.
+// The parser produces FBXNode[]; the interpreter consumes it via the
+// connection graph to build ModelData.
+//
+
+/** A single FBX property value (the typed data attached to a node). */
+export type FBXProperty =
+  | { type: "Y"; value: number }
+  | { type: "C"; value: boolean }
+  | { type: "I"; value: number }
+  | { type: "F"; value: number }
+  | { type: "D"; value: number }
+  | { type: "L"; value: number }
+  | { type: "R"; value: Uint8Array }
+  | { type: "S"; value: string }
+  | { type: "f" | "i" | "d" | "l" | "b"; value: number[]; encoding: number };
+
+/** A node in the FBX binary tree (name + properties + children). */
+export interface FBXNode {
+  name: string;
+  properties: FBXProperty[];
+  children: FBXNode[];
+}
+
+/** A connection between two FBX objects (from the Connections node). */
+export interface FBXConnection {
+  /** Connection type: "OO" = Object-Object, "OP" = Object-Property. */
+  type: string;
+  /** Child object ID. */
+  childId: string;
+  /** Parent object ID. */
+  parentId: string;
+  /** Property name for OP connections (e.g. "d|X" for animation curve axis). */
+  property?: string;
+}
+
+/** FBX binary header magic string. */
+export const FBX_HEADER_MAGIC = "Kaydara FBX Binary  \x00";
+
+/** FBX time units per second (46186158000 = int64 of FBX time ticks). */
+export const FBX_TIME_FACTOR = 46186158000;
+
+// ── Helper: extract a property value by type ────────────────────────────────
+
+/** Get the first property of a node as a number. */
+export function propNumber(node: FBXNode | undefined, index: number): number | undefined {
+  if (!node) return undefined;
+  const p = node.properties[index];
+  if (!p) return undefined;
+  if (p.type === "Y" || p.type === "I" || p.type === "F" || p.type === "D" || p.type === "L") {
+    return p.value as number;
+  }
+  return undefined;
+}
+
+/** Get the first property of a node as a string. */
+export function propString(node: FBXNode | undefined, index: number): string | undefined {
+  if (!node) return undefined;
+  const p = node.properties[index];
+  if (!p) return undefined;
+  if (p.type === "S") return p.value as string;
+  return undefined;
+}
+
+/** Get the first property of a node as a number array. */
+export function propArray(node: FBXNode | undefined, index: number): number[] | undefined {
+  if (!node) return undefined;
+  const p = node.properties[index];
+  if (!p) return undefined;
+  if (p.type === "f" || p.type === "i" || p.type === "d" || p.type === "l" || p.type === "b") {
+    return p.value as number[];
+  }
+  return undefined;
+}
+
+/** Get the first property of a node as raw bytes. */
+export function propRaw(node: FBXNode | undefined, index: number): Uint8Array | undefined {
+  if (!node) return undefined;
+  const p = node.properties[index];
+  if (!p) return undefined;
+  if (p.type === "R") return p.value as Uint8Array;
+  return undefined;
+}
+
+/** Find the first child node by name. */
+export function childNode(node: FBXNode, name: string): FBXNode | undefined {
+  return node.children.find((c) => c.name === name);
+}
+
+/** Find all child nodes by name. */
+export function childNodes(node: FBXNode, name: string): FBXNode[] {
+  return node.children.filter((c) => c.name === name);
+}
+
+/** Recursively find all descendant nodes by name (depth-first). */
+export function findNodesByName(node: FBXNode, name: string, results: FBXNode[] = [], depth = 0): FBXNode[] {
+  if (depth > MAX_NODE_DEPTH) return results;
+  if (node.name === name) results.push(node);
+  for (let i = 0; i < node.children.length; i++) {
+    findNodesByName(node.children[i], name, results, depth + 1);
+  }
+  return results;
+}
+
+/** Recursively find all descendant nodes by name (across multiple root nodes). */
+export function findNodesInTree(nodes: FBXNode[], name: string): FBXNode[] {
+  const results: FBXNode[] = [];
+  nodes.forEach((node) => {
+    findNodesByName(node, name, results);
+  });
+  return results;
+}
+
+// Import MAX_NODE_DEPTH from core to avoid circular deps — re-declare here
+// since it's a simple constant.
+const MAX_NODE_DEPTH = 256;

package/libraries/models/src/gltf-extensions.ts

@@ -0,0 +1,196 @@
+import type { AnimationEvent, MaterialData, MorphTargetData, TextureTransform } from "./types";
+
+export interface GLTFExtension {
+  [key: string]: unknown;
+}
+
+export interface ExtensionProcessingContext {
+  textures?: { source?: number; sampler?: number }[];
+  images?: { uri?: string; bufferView?: number; mimeType?: string }[];
+  samplers?: { magFilter?: number; minFilter?: number; wrapS?: number; wrapT?: number }[];
+  bufferData?: ArrayBuffer[];
+}
+
+export function extractTextureTransform(
+  extensions: { [key: string]: unknown } | undefined,
+): TextureTransform | undefined {
+  if (!extensions) return undefined;
+  const raw = extensions["KHR_texture_transform"] as {
+    offset?: number[];
+    rotation?: number;
+    scale?: number[];
+    texCoord?: number;
+  } | undefined;
+  if (!raw) return undefined;
+  return {
+    offset: raw.offset ? [raw.offset[0] ?? 0, raw.offset[1] ?? 0] : [0, 0],
+    rotation: raw.rotation ?? 0,
+    scale: raw.scale ? [raw.scale[0] ?? 1, raw.scale[1] ?? 1] : [1, 1],
+    texCoord: raw.texCoord,
+  };
+}
+
+export function processMaterialExtensions(
+  material: MaterialData,
+  extensions: GLTFExtension | undefined,
+  ctx?: ExtensionProcessingContext,
+): MaterialData {
+  if (!extensions) return material;
+
+  const result = { ...material };
+
+  // KHR_materials_pbrSpecularGlossiness — convert to metallic-roughness
+  const specGloss = extensions["KHR_materials_pbrSpecularGlossiness"] as {
+    diffuseFactor?: number[];
+    diffuseTexture?: { index: number };
+    specularFactor?: number[];
+    glossinessFactor?: number;
+    specularGlossinessTexture?: { index: number };
+  } | undefined;
+
+  if (specGloss) {
+    const diffuse = specGloss.diffuseFactor ?? [1, 1, 1, 1];
+    const specular = specGloss.specularFactor ?? [1, 1, 1];
+    const glossiness = specGloss.glossinessFactor ?? 1;
+
+    result.baseColor = [diffuse[0], diffuse[1], diffuse[2], diffuse[3] ?? 1];
+    // Approximate conversion from specular-glossiness to metallic-roughness
+    const maxSpec = Math.max(specular[0], specular[1], specular[2]);
+    result.metallic = maxSpec > 0.5 ? 1 : 0;
+    result.roughness = Math.max(0.05, 1 - glossiness);
+
+    if (specGloss.diffuseTexture && ctx?.textures && ctx.images) {
+      const tex = ctx.textures[specGloss.diffuseTexture.index];
+      if (tex?.source !== undefined && ctx.images[tex.source]?.uri) {
+        result.textureUri = ctx.images[tex.source].uri;
+      }
+    }
+  }
+
+  // KHR_materials_unlit — set metallic to 0, roughness to 1
+  if (extensions["KHR_materials_unlit"]) {
+    result.metallic = 0;
+    result.roughness = 1;
+  }
+
+  // KHR_materials_emissive_strength — scale emissive color
+  const emissiveStrength = extensions["KHR_materials_emissive_strength"] as {
+    emissiveStrength?: number;
+  } | undefined;
+
+  if (emissiveStrength?.emissiveStrength && result.emissiveColor) {
+    const s = emissiveStrength.emissiveStrength;
+    result.emissiveColor = [
+      result.emissiveColor[0] * s,
+      result.emissiveColor[1] * s,
+      result.emissiveColor[2] * s,
+    ];
+  }
+
+  // KHR_texture_transform — extract UV transform for the baseColor texture.
+  // Per-texture transforms (normal/emissive) are extracted separately by the
+  // parser when it resolves those textures, since the extension lives on the
+  // textureInfo object, not the material.
+  const baseTransform = extractTextureTransform(extensions);
+  if (baseTransform) {
+    result.textureTransform = baseTransform;
+  }
+
+  return result;
+}
+
+export function processMeshPrimitiveExtensions(
+  extensions: GLTFExtension | undefined,
+  _ctx?: ExtensionProcessingContext,
+): { dracoCompressed: boolean; quantized: boolean; meshoptCompressed: boolean } {
+  if (!extensions) return { dracoCompressed: false, quantized: false, meshoptCompressed: false };
+
+  const dracoCompressed = !!extensions["KHR_draco_mesh_compression"];
+  const quantized = !!extensions["KHR_mesh_quantization"];
+  const meshoptCompressed = !!extensions["EXT_meshopt_compression"];
+
+  return { dracoCompressed, quantized, meshoptCompressed };
+}
+
+export interface GLTFMorphTarget {
+  input: string;
+  output: string;
+  interpolation?: "LINEAR" | "STEP" | "CUBICSPLINE";
+}
+
+export interface GLTFMorphTargetData {
+  targets: Array<{
+    POSITION?: number;
+    NORMAL?: number;
+  }>;
+  targetNames?: string[];
+}
+
+export function parseMorphTargets(
+  primitive: { targets?: Array<{ POSITION?: number; NORMAL?: number }> },
+  extras: { targetNames?: string[] } | undefined,
+  accessorData: Map<number, Float32Array>,
+  vertexCount: number,
+): MorphTargetData[] {
+  if (!primitive.targets || primitive.targets.length === 0) return [];
+
+  const result: MorphTargetData[] = [];
+  for (let i = 0; i < primitive.targets.length; i++) {
+    const target = primitive.targets[i];
+    const name = extras?.targetNames?.[i] ?? `morph_${i}`;
+
+    let deltaPositions: Float32Array | undefined;
+    let deltaNormals: Float32Array | undefined;
+
+    if (target.POSITION !== undefined) {
+      const data = accessorData.get(target.POSITION);
+      if (data) {
+        deltaPositions = data;
+      }
+    }
+
+    if (target.NORMAL !== undefined) {
+      const data = accessorData.get(target.NORMAL);
+      if (data) {
+        deltaNormals = data;
+      }
+    }
+
+    if (deltaPositions) {
+      result.push({ name, deltaPositions, deltaNormals });
+    }
+  }
+
+  return result;
+}
+
+export function parseAnimationEvents(
+  extras: { events?: Array<{ time: number; type: string; payload?: Record<string, unknown> }> } | undefined,
+): AnimationEvent[] {
+  if (!extras?.events || !Array.isArray(extras.events)) return [];
+
+  return extras.events.map((e): AnimationEvent => ({
+    time: e.time,
+    type: e.type,
+    ...(e.payload !== undefined ? { payload: e.payload } : {}),
+  }));
+}
+
+export function getSupportedExtensions(): string[] {
+  return [
+    "KHR_materials_pbrSpecularGlossiness",
+    "KHR_materials_unlit",
+    "KHR_materials_emissive_strength",
+    "KHR_texture_transform",
+    "KHR_mesh_quantization",
+    "KHR_draco_mesh_compression",
+    "EXT_meshopt_compression",
+    "KHR_texture_basisu",
+    "KHR_materials_variants",
+    "KHR_lights_punctual",
+  ];
+}
+
+export function isExtensionSupported(name: string): boolean {
+  return getSupportedExtensions().includes(name);
+}