@downdraft/engine 0.0.0 → 0.1.1

package/libraries/models/src/sidecar/ddmeta.ts

@@ -0,0 +1,114 @@
+// ============================================================================
+// .ddmeta.json — Downdraft model import settings sidecar format
+// ============================================================================
+// Uses comment-json for JSON-with-comments support, making sidecars
+// human-editable for artists. The format is a superset of JSON.
+//
+
+import { parse as commentParse, stringify as commentStringify } from "comment-json";
+import type { ImportSettings, UnitSystem, UpAxis } from "./types";
+
+/**
+ * Parse a .ddmeta.json file (JSON with comments) into partial ImportSettings.
+ * Returns null if the file is empty or invalid.
+ */
+export function parseDdmeta(jsonText: string): Partial<ImportSettings> | null {
+  let parsed: unknown;
+  try {
+    parsed = commentParse(jsonText);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed as Record<string, unknown>;
+
+  const result: Partial<ImportSettings> = {};
+
+  if (typeof obj["upAxis"] === "string" && (obj["upAxis"] === "y" || obj["upAxis"] === "z")) {
+    result.upAxis = obj["upAxis"] as UpAxis;
+  }
+
+  if (typeof obj["units"] === "string") {
+    const u = obj["units"] as string;
+    if (u === "meters" || u === "centimeters" || u === "inches" || u === "millimeters" || u === "units") {
+      result.units = u as UnitSystem;
+    }
+  }
+
+  if (typeof obj["scale"] === "number" && isFinite(obj["scale"])) {
+    result.scale = obj["scale"];
+  }
+
+  if (Array.isArray(obj["rotation"]) && obj["rotation"].length === 4) {
+    const r = obj["rotation"] as number[];
+    if (r.every((v) => typeof v === "number" && isFinite(v))) {
+      result.rotation = [r[0], r[1], r[2], r[3]] as [number, number, number, number];
+    }
+  }
+
+  if (typeof obj["centerToOrigin"] === "boolean") {
+    result.centerToOrigin = obj["centerToOrigin"];
+  }
+
+  if (obj["autoFit"] === null || typeof obj["autoFit"] === "number") {
+    result.autoFit = obj["autoFit"] as number | null;
+  }
+
+  if (typeof obj["nodeTransforms"] === "string" && (obj["nodeTransforms"] === "apply" || obj["nodeTransforms"] === "ignore")) {
+    result.nodeTransforms = obj["nodeTransforms"] as "apply" | "ignore";
+  }
+
+  return result;
+}
+
+/**
+ * Serialize ImportSettings to a .ddmeta.json string with helpful comments.
+ */
+export function writeDdmeta(settings: ImportSettings): string {
+  const obj = {
+    upAxis: settings.upAxis,
+    units: settings.units,
+    scale: settings.scale,
+    rotation: [...settings.rotation],
+    centerToOrigin: settings.centerToOrigin,
+    autoFit: settings.autoFit,
+    nodeTransforms: settings.nodeTransforms,
+  };
+  return commentStringify(obj, null, 2);
+}
+
+/**
+ * Create a starter .ddmeta.json with commented-out fields and parser-detected
+ * defaults. Artists can uncomment and modify fields as needed.
+ */
+export function createDefaultDdmeta(
+  _modelName: string,
+  parserDefaults: Partial<ImportSettings>,
+): string {
+  const lines: string[] = [
+    "{",
+    `  // Downdraft model import settings for ${_modelName}`,
+    "  // Uncomment and modify fields to override parser-detected defaults.",
+    "",
+    `  "upAxis": "${parserDefaults.upAxis ?? "y"}",  // "y" or "z" — source asset up-axis. Engine is Y-up.`,
+    `  "units": "${parserDefaults.units ?? "meters"}",  // "meters" | "centimeters" | "inches" | "millimeters" | "units"`,
+    "",
+    "  // Additional scale multiplier (applied after unit conversion). Default: 1.0",
+    `  "scale": ${parserDefaults.scale ?? 1.0},`,
+    "",
+    "  // Root pre-rotation quaternion [x, y, z, w]. Default: identity",
+    `  "rotation": [${(parserDefaults.rotation ?? [0, 0, 0, 1]).join(", ")}],`,
+    "",
+    "  // Subtract bounding-box center to place model at origin. Default: false",
+    `  "centerToOrigin": ${parserDefaults.centerToOrigin ?? false},`,
+    "",
+    "  // Auto-fit: null = off, or target max-dimension in meters (e.g. 2.0)",
+    `  "autoFit": ${parserDefaults.autoFit === null ? "null" : parserDefaults.autoFit},`,
+    "",
+    '  // Node transform handling: "apply" = bake node hierarchy into vertices, "ignore" = raw mesh',
+    `  "nodeTransforms": "${parserDefaults.nodeTransforms ?? "apply"}"`,
+    "}",
+  ];
+  return lines.join("\n");
+}

package/libraries/models/src/sidecar/godot-import.ts

@@ -0,0 +1,86 @@
+// ============================================================================
+// Godot .import — parse Godot asset import settings
+// ============================================================================
+// Godot .import files are INI format with [remap] and [params] sections.
+// For 3D scenes/meshes, relevant params include scale, offset, rotation.
+//
+
+import type { ImportSettings } from "./types";
+
+/**
+ * Parse a Godot .import file (INI format) for model import settings.
+ * Returns partial ImportSettings mapped from Godot's fields, or null if
+ * the file doesn't contain relevant import settings.
+ */
+export function parseGodotImport(importText: string): Partial<ImportSettings> | null {
+  // Godot .import files have a [remap] section with a "path" to the imported
+  // resource and a [params] section with import settings.
+  if (!importText.includes("[remap]")) return null;
+
+  const result: Partial<ImportSettings> = {
+    source: "godot",
+  };
+
+  // Parse INI-style sections
+  const sections: Record<string, Record<string, string>> = {};
+  let currentSection = "";
+
+  for (const line of importText.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      currentSection = trimmed.slice(1, -1);
+      sections[currentSection] = {};
+    } else if (currentSection && trimmed.includes("=")) {
+      const eqIdx = trimmed.indexOf("=");
+      const key = trimmed.slice(0, eqIdx).trim();
+      const value = trimmed.slice(eqIdx + 1).trim();
+      sections[currentSection][key] = value;
+    }
+  }
+
+  const params = sections["params"] ?? {};
+
+  // Godot mesh import settings
+  if (params["scale"]) {
+    const scale = parseFloat(params["scale"]);
+    if (isFinite(scale)) {
+      result.scale = scale;
+    }
+  }
+
+  if (params["rotation"]) {
+    // Godot stores rotation as Euler angles in degrees, space-separated or comma-separated
+    const parts = params["rotation"].split(/[\s,]+/).map(parseFloat);
+    if (parts.length >= 3 && parts.every(isFinite)) {
+      // Convert Euler degrees to quaternion (XYZ order)
+      const ex = parts[0] * Math.PI / 180;
+      const ey = parts[1] * Math.PI / 180;
+      const ez = parts[2] * Math.PI / 180;
+      const cx = Math.cos(ex / 2), sx = Math.sin(ex / 2);
+      const cy = Math.cos(ey / 2), sy = Math.sin(ey / 2);
+      const cz = Math.cos(ez / 2), sz = Math.sin(ez / 2);
+      // XYZ extrinsic = ZYX intrinsic
+      result.rotation = [
+        sx * cy * cz - cx * sy * sz,
+        cx * sy * cz + sx * cy * sz,
+        cx * cy * sz - sx * sy * cz,
+        cx * cy * cz + sx * sy * sz,
+      ];
+    }
+  }
+
+  // Godot import format type — check if it's a 3D scene
+  const remap = sections["remap"] ?? {};
+  const importer = remap["importer"];
+  if (importer && !importer.includes("scene") && !importer.includes("mesh") && !importer.includes("gltf")) {
+    // Not a 3D model import — don't return settings
+    return null;
+  }
+
+  // Only return if we found at least one useful setting
+  if (result.scale === undefined && result.rotation === undefined) {
+    return null;
+  }
+
+  return result;
+}

package/libraries/models/src/sidecar/resolver.ts

@@ -0,0 +1,145 @@
+// ============================================================================
+// Sidecar Resolver — resolve ImportSettings from sidecar files or defaults
+// ============================================================================
+// Tries sidecar files in priority order:
+//   1. .ddmeta.json (our format, comment-json)
+//   2. Unity .meta (YAML)
+//   3. Godot .import (INI)
+//   4. Blender extras (from modelData, already parsed from glTF asset.extras)
+//   5. Parser-detected defaults (sourceUpAxis, sourceUnits from ModelData)
+//
+// Each external sidecar is mapped to our ImportSettings shape, then merged
+// with priority: ddmeta > unity > godot > blender > parser defaults.
+//
+
+import type { ModelData } from "../types";
+import type { ImportSettings, SettingsSource } from "./types";
+import { createDefaultImportSettings, mergeImportSettings } from "./types";
+import { parseDdmeta } from "./ddmeta";
+import { parseUnityMeta } from "./unity-meta";
+import { parseGodotImport } from "./godot-import";
+import { parseBlenderExtras } from "./blender-extras";
+
+export interface ResolveOptions {
+  /** Fetch function for sidecar files. Defaults to global fetch. */
+  fetchFn?: (uri: string) => Promise<Response>;
+  /** The model file URI (used to derive sidecar URIs). */
+  modelPath: string;
+  /** The parsed model data (for parser-detected defaults + Blender extras). */
+  modelData: ModelData;
+}
+
+/**
+ * Derive the .ddmeta.json sidecar URI from a model path.
+ * "models/character.fbx" → "models/character.ddmeta.json"
+ */
+export function ddmetaPath(modelPath: string): string {
+  return modelPath.replace(/\.[^.]+$/, ".ddmeta.json");
+}
+
+/**
+ * Derive the Unity .meta sidecar URI from a model path.
+ * "models/character.fbx" → "models/character.fbx.meta"
+ */
+export function unityMetaPath(modelPath: string): string {
+  return modelPath + ".meta";
+}
+
+/**
+ * Derive the Godot .import sidecar URI from a model path.
+ * "models/character.gltf" → "models/character.gltf.import"
+ */
+export function godotImportPath(modelPath: string): string {
+  return modelPath + ".import";
+}
+
+async function tryFetch(
+  fetchFn: (uri: string) => Promise<Response>,
+  uri: string,
+): Promise<string | null> {
+  try {
+    const resp = await fetchFn(uri);
+    if (!resp.ok) return null;
+    const text = await resp.text();
+    // Guard against HTML fallback pages (Vite SPA fallback returns 200 + HTML)
+    if (text.trimStart().startsWith("<!DOCTYPE") || text.trimStart().startsWith("<html")) {
+      return null;
+    }
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve import settings for a model by trying sidecar files in priority
+ * order, then falling back to parser-detected defaults.
+ */
+export async function resolveImportSettings(opts: ResolveOptions): Promise<ImportSettings> {
+  const fetchFn = opts.fetchFn ?? ((uri: string) => fetch(uri));
+  const { modelPath, modelData } = opts;
+
+  // Start with parser-detected defaults
+  const parserDefaults = createDefaultImportSettings(
+    modelData.sourceUpAxis,
+    modelData.sourceUnits,
+  );
+  parserDefaults.source = "parser" as SettingsSource;
+
+  let merged: ImportSettings = parserDefaults;
+  let currentSource: SettingsSource = "parser";
+
+  // 4. Try Blender extras (from modelData — already parsed from glTF JSON)
+  // We need to check if the modelData has glTF asset extras. The glTF parser
+  // already detected sourceUpAxis from Blender extras, so this is redundant
+  // for up-axis. But we keep it for completeness if future Blender settings
+  // are added.
+  // (Blender extras are already reflected in modelData.sourceUpAxis)
+
+  // 3. Try Godot .import
+  const godotText = await tryFetch(fetchFn, godotImportPath(modelPath));
+  if (godotText) {
+    const godotSettings = parseGodotImport(godotText);
+    if (godotSettings) {
+      merged = mergeImportSettings(merged, godotSettings, "godot");
+      currentSource = "godot";
+    }
+  }
+
+  // 2. Try Unity .meta
+  const unityText = await tryFetch(fetchFn, unityMetaPath(modelPath));
+  if (unityText) {
+    const unitySettings = parseUnityMeta(unityText);
+    if (unitySettings) {
+      merged = mergeImportSettings(merged, unitySettings, "unity");
+      currentSource = "unity";
+    }
+  }
+
+  // 1. Try .ddmeta.json (highest priority)
+  const ddmetaText = await tryFetch(fetchFn, ddmetaPath(modelPath));
+  if (ddmetaText) {
+    const ddmetaSettings = parseDdmeta(ddmetaText);
+    if (ddmetaSettings) {
+      merged = mergeImportSettings(merged, ddmetaSettings, "ddmeta");
+      currentSource = "ddmeta";
+    }
+  }
+
+  merged.source = currentSource;
+  return merged;
+}
+
+/**
+ * Synchronous version of resolveImportSettings that only uses parser-detected
+ * defaults and Blender extras (no sidecar file fetching). Used when sidecar
+ * resolution is disabled or for offline processing.
+ */
+export function resolveImportSettingsSync(modelData: ModelData): ImportSettings {
+  const settings = createDefaultImportSettings(
+    modelData.sourceUpAxis,
+    modelData.sourceUnits,
+  );
+  settings.source = "parser";
+  return settings;
+}

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

@@ -0,0 +1,11 @@
+// ============================================================================
+// Import Settings Types — re-exported from @downdraft/engine
+// ============================================================================
+// The canonical definitions live in @downdraft/engine/assets/import-settings.ts
+// so the ImportCache (in core) can store ImportSettings without a cross-package
+// dependency. This module re-exports them for plugin-models convenience.
+//
+
+export { createDefaultImportSettings, mergeImportSettings } from "@downdraft/engine";
+export type { ImportSettings, SettingsSource, UnitSystem, UpAxis } from "@downdraft/engine";
+

package/libraries/models/src/sidecar/unity-meta.ts

@@ -0,0 +1,61 @@
+// ============================================================================
+// Unity .meta — parse Unity asset metadata for model import settings
+// ============================================================================
+// Unity .meta files are YAML. We use targeted regex for the few fields we
+// need (scaleFactor, useFileUnits) rather than a full YAML parser.
+//
+
+import type { ImportSettings } from "./types";
+
+interface UnityModelImporter {
+  scaleFactor?: number;
+  useFileUnits?: boolean;
+  meshCompression?: number;
+}
+
+/**
+ * Parse a Unity .meta file (YAML format) for model import settings.
+ * Returns partial ImportSettings mapped from Unity's fields, or null if
+ * the file is not a ModelImporter .meta.
+ */
+export function parseUnityMeta(metaText: string): Partial<ImportSettings> | null {
+  // Unity .meta files start with "fileFormatVersion:" and have a
+  // "guid:" field. ModelImporter .meta files have "ModelImporter:" header.
+  if (!metaText.includes("ModelImporter")) return null;
+
+  const importer: UnityModelImporter = {};
+
+  // Extract scaleFactor — it's a top-level property in ModelImporter
+  const scaleMatch = metaText.match(/^[\s]*scaleFactor:\s*([\d.]+)/m);
+  if (scaleMatch) {
+    importer.scaleFactor = parseFloat(scaleMatch[1]);
+  }
+
+  // Extract useFileUnits
+  const unitsMatch = metaText.match(/^[\s]*useFileUnits:\s*(\w+)/m);
+  if (unitsMatch) {
+    importer.useFileUnits = unitsMatch[1] === "1" || unitsMatch[1] === "true";
+  }
+
+  // Extract meshCompression (informational only)
+  const compressionMatch = metaText.match(/^[\s]*meshCompression:\s*(\d+)/m);
+  if (compressionMatch) {
+    importer.meshCompression = parseInt(compressionMatch[1], 10);
+  }
+
+  if (importer.scaleFactor === undefined) return null;
+
+  // Unity's scaleFactor converts the model to meters. For FBX files exported
+  // in centimeters (Unity default), scaleFactor is typically 0.01.
+  // We map this to our `scale` multiplier.
+  const result: Partial<ImportSettings> = {
+    scale: importer.scaleFactor,
+    source: "unity",
+  };
+
+  // If useFileUnits is true, Unity uses the file's native units (e.g. cm for FBX).
+  // The scaleFactor already accounts for this conversion.
+  // If useFileUnits is false, Unity treats everything as meters.
+
+  return result;
+}

package/libraries/models/src/skeleton-synthesis.ts

@@ -0,0 +1,132 @@
+// ============================================================================
+// Skeleton Synthesis — build SkinData from the node hierarchy when a file has
+// no skin deformers but does carry joints + animations (e.g. Mixamo clip
+// exports that contain only a bone tree and an AnimationStack).
+//
+// The synthesized skeleton uses each node's local rest TRS (PreRotation is
+// already baked into node.rotation by the FBX node interpreter) and an
+// inverse bind matrix of inverse(restWorld), so bind-pose skin matrices are
+// identity. Bones are emitted parents-first (DFS) as computeSkinMatrices
+// requires.
+// ============================================================================
+
+import { composeMat4Into, invertMat4, multiplyMat4Into } from "@downdraft/engine";
+import type { AnimationData, BoneData, ModelNode, SkinData } from "./types";
+
+/**
+ * Synthesize a SkinData skeleton from the model's node hierarchy.
+ *
+ * Bones = every node in the tree component(s) containing an animation target
+ * (so end-bones like `HeadTop_End` are included even though they aren't
+ * animated directly). If no channel target resolves to a node name, the whole
+ * node tree is used — still better than nothing for skeleton visualization.
+ *
+ * Returns undefined when there are no nodes to build from.
+ */
+export function synthesizeSkeletonSkin(
+  nodes: ModelNode[],
+  animations: AnimationData[],
+  upAxis?: "y" | "z",
+): SkinData | undefined {
+  if (!nodes || nodes.length === 0) return undefined;
+
+  // node index → parent index
+  const parentOf = new Int32Array(nodes.length).fill(-1);
+  for (let i = 0; i < nodes.length; i++) {
+    (nodes[i].children ?? []).forEach((c) => {
+      if (c >= 0 && c < nodes.length) parentOf[c] = i;
+    });
+  }
+
+  // Node indices targeted by at least one animation channel.
+  const nameToNode = new Map<string, number>();
+  for (let i = 0; i < nodes.length; i++) {
+    if (!nameToNode.has(nodes[i].name)) nameToNode.set(nodes[i].name, i);
+  }
+  const animated = new Set<number>();
+  animations.forEach((anim) => {
+    anim.channels.forEach((ch) => {
+      const idx = nameToNode.get(ch.targetNode);
+      if (idx !== undefined) animated.add(idx);
+    });
+  });
+
+  // Bone set = all descendants of the root-most ancestors of animated nodes.
+  // This captures the full skeleton subtree (including unanimated leaf bones).
+  const boneSet = new Set<number>();
+  if (animated.size > 0) {
+    const roots = new Set<number>();
+    for (const idx of animated.values()) {
+      let r = idx;
+      while (parentOf[r] >= 0) r = parentOf[r];
+      roots.add(r);
+    }
+    const stack = [...roots];
+    while (stack.length > 0) {
+      const i = stack.pop()!;
+      if (boneSet.has(i)) continue;
+      boneSet.add(i);
+      (nodes[i].children ?? []).forEach((c) => { stack.push(c);; });
+    }
+  } else {
+    for (let i = 0; i < nodes.length; i++) boneSet.add(i);
+  }
+  if (boneSet.size === 0) return undefined;
+
+  // DFS from each bone root so parents precede children in the output array
+  // (computeSkinMatrices iterates linearly and reads parent world matrices).
+  const bones: BoneData[] = [];
+  const boneNameToIndex = new Map<string, number>();
+  const local = new Float32Array(16);
+  const world = new Float32Array(16);
+
+  const componentRoots: number[] = [];
+  for (const i of boneSet.values()) {
+    if (!boneSet.has(parentOf[i])) componentRoots.push(i);
+  }
+  componentRoots.sort((a, b) => a - b);
+
+  componentRoots.forEach((root) => {
+    const stack: { node: number; parentBone: number; parentWorld: Float32Array | null }[] = [
+      { node: root, parentBone: -1, parentWorld: null },
+    ];
+    while (stack.length > 0) {
+      const { node, parentBone, parentWorld } = stack.pop()!;
+      const n = nodes[node];
+      const boneIdx = bones.length;
+
+      composeMat4Into(
+        n.translation ?? [0, 0, 0],
+        n.rotation ?? [0, 0, 0, 1],
+        n.scale ?? [1, 1, 1],
+        local,
+      );
+      if (parentWorld) multiplyMat4Into(parentWorld, local, world);
+      else world.set(local);
+      // The synthesized skin's rest world matrix doubles as its bind matrix.
+      const ibm = invertMat4(world);
+
+      bones.push({
+        name: n.name || `bone_${boneIdx}`,
+        nodeIndex: node,
+        parentIndex: parentBone,
+        inverseBindMatrix: ibm,
+        restTranslation: n.translation ?? [0, 0, 0],
+        restRotation: n.rotation ?? [0, 0, 0, 1],
+        restScale: n.scale ?? [1, 1, 1],
+      });
+      boneNameToIndex.set(n.name, boneIdx);
+
+      // Push children reversed so DFS emits them in hierarchy order.
+      const kids = n.children ?? [];
+      const worldCopy = new Float32Array(world);
+      for (let k = kids.length - 1; k >= 0; k--) {
+        if (boneSet.has(kids[k])) {
+          stack.push({ node: kids[k], parentBone: boneIdx, parentWorld: worldCopy });
+        }
+      }
+    }
+  });
+
+  return { bones, boneNameToIndex, skeletonUpAxis: upAxis };
+}