@downdraft/engine 0.0.0 → 0.1.1

package/asset-bake/src/cache.ts

@@ -0,0 +1,188 @@
+// ============================================================================
+// BakeCache — content-hash cache for baked assets.
+// ============================================================================
+//
+// Stores baked output in `<gameDir>/.downdraft/bake/` keyed by a hash of the
+// source file contents + the bake config version. A `manifest.json` maps
+// source-relative-path → cache entry so we can detect hits without re-hashing
+// on every build (we still verify the source hash to catch content changes).
+//
+// Set DOWNDRAFT_BAKE_FORCE=1 to bypass cache reads (always re-bake).
+//
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { BAKE_CONFIG_VERSION, type ResolvedBakeOptions } from "./config";
+
+export interface BakeCacheEntry {
+  /** Source file path relative to the game root. */
+  sourceRel: string;
+  /** xxh64 of source file contents (hex string). */
+  sourceHash: string;
+  /** Source mtime (ms). Used as a fast-path pre-check. */
+  sourceMtime: number;
+  /** Source byte length. */
+  sourceSize: number;
+  /** Bake config version when this entry was created. */
+  configVersion: number;
+  /** Baked output filename inside the cache dir (e.g. "a1b2c3.glb"). */
+  bakedFile: string;
+  /** Baked output extension. */
+  bakedExt: string;
+  /** Baked byte length. */
+  bakedSize: number;
+  /** Baked MIME type. */
+  bakedMime: string;
+}
+
+export interface BakeCacheManifest {
+  version: number;
+  entries: Record<string, BakeCacheEntry>;
+}
+
+export interface BakeCacheHit {
+  /** Absolute path to the cached baked file. */
+  path: string;
+  ext: string;
+  mimeType: string;
+  size: number;
+}
+
+export class BakeCache {
+  readonly root: string;
+  readonly dir: string;
+  private manifestPath: string;
+  private manifest: BakeCacheManifest;
+  private loaded = false;
+
+  constructor(gameRoot: string) {
+    this.root = gameRoot;
+    this.dir = resolve(gameRoot, ".downdraft", "bake");
+    this.manifestPath = join(this.dir, "manifest.json");
+    this.manifest = { version: BAKE_CONFIG_VERSION, entries: {} };
+  }
+
+  private load(): void {
+    if (this.loaded) return;
+    this.loaded = true;
+    if (!existsSync(this.manifestPath)) return;
+    try {
+      const raw = JSON.parse(readFileSync(this.manifestPath, "utf-8"));
+      if (raw && typeof raw === "object" && raw.entries) {
+        this.manifest = raw as BakeCacheManifest;
+      }
+    } catch {
+      // Corrupt manifest — start fresh.
+      this.manifest = { version: BAKE_CONFIG_VERSION, entries: {} };
+    }
+  }
+
+  private save(): void {
+    if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });
+    writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2) + "\n");
+  }
+
+  /**
+   * Check the cache for a hit. Returns the cached baked file path if the
+   * source content hash matches AND the config version matches. Returns null
+   * on miss or when DOWNDRAFT_BAKE_FORCE=1.
+   */
+  get(sourceAbsPath: string, opts: ResolvedBakeOptions): BakeCacheHit | null {
+    if (process.env.DOWNDRAFT_BAKE_FORCE === "1") return null;
+    this.load();
+    const sourceRel = relative(this.root, sourceAbsPath).split(sep).join("/");
+    const entry = this.manifest.entries[sourceRel];
+    if (!entry) return null;
+    if (entry.configVersion !== BAKE_CONFIG_VERSION) return null;
+
+    // Fast path: mtime unchanged → trust the stored hash without re-reading.
+    let sourceHash: string;
+    try {
+      const st = statSync(sourceAbsPath);
+      if (st.mtimeMs !== entry.sourceMtime || st.size !== entry.sourceSize) {
+        sourceHash = hashFile(sourceAbsPath);
+      } else {
+        sourceHash = entry.sourceHash;
+      }
+    } catch {
+      return null;
+    }
+
+    if (sourceHash !== entry.sourceHash) return null;
+
+    const bakedPath = join(this.dir, entry.bakedFile);
+    if (!existsSync(bakedPath)) return null;
+    return { path: bakedPath, ext: entry.bakedExt, mimeType: entry.bakedMime, size: entry.bakedSize };
+  }
+
+  /**
+   * Store baked output for a source file and return the cache hit.
+   */
+  put(
+    sourceAbsPath: string,
+    bakedBytes: Uint8Array,
+    bakedExt: string,
+    bakedMime: string,
+    opts: ResolvedBakeOptions,
+  ): BakeCacheHit {
+    this.load();
+    if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });
+
+    const sourceRel = relative(this.root, sourceAbsPath).split(sep).join("/");
+    const sourceHash = hashFile(sourceAbsPath);
+    let st: { mtimeMs: number; size: number };
+    try {
+      const s = statSync(sourceAbsPath);
+      st = { mtimeMs: s.mtimeMs, size: s.size };
+    } catch {
+      st = { mtimeMs: 0, size: 0 };
+    }
+
+    const hashName = sourceHash + "." + bakedExt;
+    const bakedPath = join(this.dir, hashName);
+    writeFileSync(bakedPath, bakedBytes);
+
+    const entry: BakeCacheEntry = {
+      sourceRel,
+      sourceHash,
+      sourceMtime: st.mtimeMs,
+      sourceSize: st.size,
+      configVersion: BAKE_CONFIG_VERSION,
+      bakedFile: hashName,
+      bakedExt,
+      bakedSize: bakedBytes.byteLength,
+      bakedMime,
+    };
+    this.manifest.entries[sourceRel] = entry;
+    this.save();
+
+    return { path: bakedPath, ext: bakedExt, mimeType: bakedMime, size: bakedBytes.byteLength };
+  }
+
+  /** Remove stale entries whose source files no longer exist. */
+  pruneStale(): number {
+    this.load();
+    let removed = 0;
+    for (const [rel, entry] of Object.entries(this.manifest.entries)) {
+      const abs = resolve(this.root, ...rel.split("/"));
+      if (!existsSync(abs)) {
+        delete this.manifest.entries[rel];
+        removed++;
+        // Best-effort: remove the baked file too.
+        const bakedPath = join(this.dir, entry.bakedFile);
+        try {
+          unlinkSync(bakedPath);
+        } catch {}
+      }
+    }
+    if (removed > 0) this.save();
+    return removed;
+  }
+}
+
+/** xxh64 hash of a file's contents (hex string, no prefix). */
+export function hashFile(absPath: string): string {
+  const buf = readFileSync(absPath);
+  return createHash("sha256").update(buf).digest("hex").slice(0, 16);
+}

package/asset-bake/src/config.ts

@@ -0,0 +1,186 @@
+// ============================================================================
+// Bake config — option types, defaults, and resolution.
+// ============================================================================
+
+/** Bumped when bake output format/defaults change → cache invalidation. */
+export const BAKE_CONFIG_VERSION = 1;
+
+/** Texture codec target for glTF embedded textures. */
+export type TextureCodecMode = "auto" | "uastc" | "etc1s";
+
+export interface TextureBakeOptions {
+  /** Enable texture → KTX2/basisu transcode. Default: true. */
+  enabled?: boolean;
+  /**
+   * Codec mode.
+   *   "auto"  → UASTC for normal/ORM/emissive slots, ETC1S for base color.
+   *   "uastc" → UASTC for all (higher quality, larger).
+   *   "etc1s" → ETC1S for all (smallest, lower quality).
+   * Default: "auto".
+   */
+  codec?: TextureCodecMode;
+  /** Generate mipmaps. Default: true. */
+  generateMipmap?: boolean;
+  /** ETC1S quality level [1,255]. Default: 224. */
+  etc1sQuality?: number;
+  /** UASTC quality level [0,4]. Default: 2. */
+  uastcLevel?: number;
+  /** Apply UASTC RDO post-processor. Default: false. */
+  uastcRdo?: boolean;
+  /** Max texture dimension (power-of-two friendly). Default: 4096. 0 = no limit. */
+  maxSize?: number;
+}
+
+export interface GltfBakeOptions {
+  /** Enable glTF/GLB baking. Default: true. */
+  enabled?: boolean;
+  /** meshopt compression level. Default: "medium". */
+  meshoptLevel?: "low" | "medium" | "high";
+  /** Remove unused nodes/textures/materials. Default: true. */
+  prune?: boolean;
+  /** Remove duplicate vertices/accessors. Default: true. */
+  dedup?: boolean;
+  /** Weld coincident vertices. Default: true. */
+  weld?: boolean;
+  /** Quantize vertex attributes. Default: true. */
+  quantize?: boolean;
+  /** Texture options. */
+  textures?: TextureBakeOptions;
+}
+
+export interface AudioBakeOptions {
+  /** Enable audio transcoding. Default: true. */
+  enabled?: boolean;
+  /** Target container/codec. Default: "ogg" (Vorbis/Opus). */
+  target?: "ogg" | "mp3" | "wav" | "flac";
+  /** Bitrate in kbps (lossy targets). Default: 96. */
+  bitrate?: number;
+  /** Target sample rate in Hz. 0 = preserve source. Default: 48000. */
+  sampleRate?: number;
+  /** Output channels: 1 (mono), 2 (stereo), 0 = preserve source. Default: 0. */
+  channels?: 0 | 1 | 2;
+}
+
+export interface AssetBakeOptions {
+  /** Master enable. Default: true (the plugin gates this separately). */
+  enabled?: boolean;
+  gltf?: GltfBakeOptions;
+  audio?: AudioBakeOptions;
+  /**
+   * Glob patterns (minimatch-style, relative to game root) to include in
+   * baking. Default: all matched extensions.
+   */
+  include?: string[];
+  /** Glob patterns to exclude. */
+  exclude?: string[];
+}
+
+export interface ResolvedBakeOptions {
+  enabled: boolean;
+  gltf: {
+    enabled: boolean;
+    meshoptLevel: "low" | "medium" | "high";
+    prune: boolean;
+    dedup: boolean;
+    weld: boolean;
+    quantize: boolean;
+    textures: {
+      enabled: boolean;
+      codec: TextureCodecMode;
+      generateMipmap: boolean;
+      etc1sQuality: number;
+      uastcLevel: number;
+      uastcRdo: boolean;
+      maxSize: number;
+    };
+  };
+  audio: {
+    enabled: boolean;
+    target: "ogg" | "mp3" | "wav" | "flac";
+    bitrate: number;
+    sampleRate: number;
+    channels: 0 | 1 | 2;
+  };
+  include: string[];
+  exclude: string[];
+}
+
+export const DEFAULT_BAKE_OPTIONS: ResolvedBakeOptions = {
+  enabled: true,
+  gltf: {
+    enabled: true,
+    meshoptLevel: "medium",
+    prune: true,
+    dedup: true,
+    weld: true,
+    quantize: true,
+    textures: {
+      enabled: true,
+      codec: "auto",
+      generateMipmap: true,
+      etc1sQuality: 224,
+      uastcLevel: 2,
+      uastcRdo: false,
+      maxSize: 4096,
+    },
+  },
+  audio: {
+    enabled: true,
+    target: "ogg",
+    bitrate: 96,
+    sampleRate: 48000,
+    channels: 0,
+  },
+  include: [],
+  exclude: [],
+};
+
+export function resolveOptions(user?: AssetBakeOptions): ResolvedBakeOptions {
+  if (!user) return structuredClone(DEFAULT_BAKE_OPTIONS);
+  const d = structuredClone(DEFAULT_BAKE_OPTIONS);
+  if (user.enabled !== undefined) d.enabled = user.enabled;
+  if (user.include) d.include = user.include;
+  if (user.exclude) d.exclude = user.exclude;
+  if (user.gltf) {
+    const g = user.gltf;
+    if (g.enabled !== undefined) d.gltf.enabled = g.enabled;
+    if (g.meshoptLevel) d.gltf.meshoptLevel = g.meshoptLevel;
+    if (g.prune !== undefined) d.gltf.prune = g.prune;
+    if (g.dedup !== undefined) d.gltf.dedup = g.dedup;
+    if (g.weld !== undefined) d.gltf.weld = g.weld;
+    if (g.quantize !== undefined) d.gltf.quantize = g.quantize;
+    if (g.textures) {
+      const t = g.textures;
+      const dt = d.gltf.textures;
+      if (t.enabled !== undefined) dt.enabled = t.enabled;
+      if (t.codec) dt.codec = t.codec;
+      if (t.generateMipmap !== undefined) dt.generateMipmap = t.generateMipmap;
+      if (t.etc1sQuality !== undefined) dt.etc1sQuality = t.etc1sQuality;
+      if (t.uastcLevel !== undefined) dt.uastcLevel = t.uastcLevel;
+      if (t.uastcRdo !== undefined) dt.uastcRdo = t.uastcRdo;
+      if (t.maxSize !== undefined) dt.maxSize = t.maxSize;
+    }
+  }
+  if (user.audio) {
+    const a = user.audio;
+    const da = d.audio;
+    if (a.enabled !== undefined) da.enabled = a.enabled;
+    if (a.target) da.target = a.target;
+    if (a.bitrate !== undefined) da.bitrate = a.bitrate;
+    if (a.sampleRate !== undefined) da.sampleRate = a.sampleRate;
+    if (a.channels !== undefined) da.channels = a.channels;
+  }
+  return d;
+}
+
+/** Result of baking a single asset. */
+export interface BakeResult {
+  /** Optimized bytes. */
+  bytes: Uint8Array;
+  /** Output file extension (without dot), e.g. "glb", "ogg". */
+  ext: string;
+  /** MIME type of the output. */
+  mimeType: string;
+  /** Original byte length (for logging ratio). */
+  sourceSize: number;
+}

package/asset-bake/src/index.ts

@@ -0,0 +1,36 @@
+// ============================================================================
+// @downdraft/engine/asset-bake — Node-only asset optimization / bake pipeline.
+// ============================================================================
+//
+// Produces GPU-ready assets from source art at build/dev time:
+//   - glTF/GLB → meshopt-compressed, deduped, welded, pruned, quantized GLB
+//     with embedded textures transcoded to Basis Universal KTX2
+//     (KHR_texture_basisu + EXT_meshopt_compression).
+//   - Audio (wav/mp3/ogg) → normalized target container/codec/bitrate.
+//
+// The runtime already decodes all of these:
+//   - meshopt  → packages/engine/libraries/models/src/codecs/meshopt-codec.ts
+//   - basisu   → packages/engine/libraries/models/src/codecs/basisu-codec.ts
+//                (upgraded to transcode via @h00w/basis-universal-transcoder)
+//   - KTX2     → packages/engine/core/src/assets/loader-texture.ts
+//
+// This package is heavy (gltf-transform + meshoptimizer wasm + basisu encoder
+// wasm + jimp) and is only ever imported from the Vite plugin's `load()` hook
+// (Node context). It must never be imported into the renderer bundle.
+//
+
+export { bakeAsset, bakeAssetFromBytes } from "./bake";
+export { bakeGltf } from "./bake-gltf";
+export { bakeAudio } from "./bake-audio";
+export { BakeCache } from "./cache";
+export {
+  resolveOptions,
+  DEFAULT_BAKE_OPTIONS,
+  BAKE_CONFIG_VERSION,
+  type AssetBakeOptions,
+  type ResolvedBakeOptions,
+  type BakeResult,
+  type GltfBakeOptions,
+  type TextureBakeOptions,
+  type AudioBakeOptions,
+} from "./config";

package/core/src/animation/animation-event.ts

@@ -0,0 +1,41 @@
+export interface AnimationEvent {
+  time: number;
+  type: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface AnimationEventTrack {
+  events: AnimationEvent[];
+}
+
+export function createAnimationEventTrack(events: AnimationEvent[]): AnimationEventTrack {
+  const sorted = [...events].sort((a, b) => a.time - b.time);
+  return { events: sorted };
+}
+
+export function getEventsInRange(
+  track: AnimationEventTrack,
+  fromTime: number,
+  toTime: number,
+  duration: number,
+): AnimationEvent[] {
+  const result: AnimationEvent[] = [];
+
+  if (toTime > fromTime) {
+    // Forward playback: events in (fromTime, toTime]
+    track.events.forEach((e) => {
+      if (e.time > fromTime && e.time <= toTime) {
+        result.push(e);
+      }
+    });
+  } else if (toTime < fromTime) {
+    // Backward or wraparound: events in (fromTime, duration] ∪ [0, toTime]
+    track.events.forEach((e) => {
+      if (e.time > fromTime || e.time <= toTime) {
+        result.push(e);
+      }
+    });
+  }
+
+  return result;
+}

package/core/src/animation/bone-mask.ts

@@ -0,0 +1,122 @@
+import type { SkeletonData } from "./skeleton";
+
+export enum BoneMaskPreset {
+  UPPER_BODY = "upper_body",
+  LOWER_BODY = "lower_body",
+  LEFT_ARM = "left_arm",
+  RIGHT_ARM = "right_arm",
+  HEAD = "head",
+  HANDS = "hands",
+  FULL_BODY = "full_body",
+  SPINE_ONLY = "spine_only",
+}
+
+const UPPER_BODY_NAMES = [
+  "spine", "spine1", "spine2", "spine_01", "spine_02", "spine_03",
+  "neck", "head",
+  "clavicle_l", "clavicle_r", "arm_upper_l", "arm_upper_r",
+  "arm_lower_l", "arm_lower_r", "hand_l", "hand_r",
+  "shoulder_l", "shoulder_r",
+  "upperarm_l", "upperarm_r", "lowerarm_l", "lowerarm_r",
+  "LeftArm", "RightArm", "LeftForeArm", "RightForeArm",
+  "LeftHand", "RightHand", "LeftShoulder", "RightShoulder",
+  "Spine", "Spine1", "Spine2", "Neck", "Head",
+];
+
+const LOWER_BODY_NAMES = [
+  "hip", "hips", "pelvis",
+  "thigh_l", "thigh_r", "calf_l", "calf_r", "foot_l", "foot_r",
+  "upperleg_l", "upperleg_r", "lowerleg_l", "lowerleg_r",
+  "LeftUpLeg", "RightUpLeg", "LeftLeg", "RightLeg", "LeftFoot", "RightFoot",
+  "Hips", "Pelvis",
+];
+
+const LEFT_ARM_NAMES = [
+  "clavicle_l", "shoulder_l", "arm_upper_l", "upperarm_l",
+  "arm_lower_l", "lowerarm_l", "hand_l",
+  "LeftArm", "LeftForeArm", "LeftHand", "LeftShoulder",
+];
+
+const RIGHT_ARM_NAMES = [
+  "clavicle_r", "shoulder_r", "arm_upper_r", "upperarm_r",
+  "arm_lower_r", "lowerarm_r", "hand_r",
+  "RightArm", "RightForeArm", "RightHand", "RightShoulder",
+];
+
+const HEAD_NAMES = ["neck", "head", "Neck", "Head"];
+
+const HAND_NAMES = [
+  "hand_l", "hand_r", "LeftHand", "RightHand",
+  "thumb_01_l", "thumb_02_l", "thumb_03_l",
+  "thumb_01_r", "thumb_02_r", "thumb_03_r",
+  "index_01_l", "index_02_l", "index_03_l",
+  "index_01_r", "index_02_r", "index_03_r",
+  "middle_01_l", "middle_02_l", "middle_03_l",
+  "middle_01_r", "middle_02_r", "middle_03_r",
+  "ring_01_l", "ring_02_l", "ring_03_l",
+  "ring_01_r", "ring_02_r", "ring_03_r",
+  "pinky_01_l", "pinky_02_l", "pinky_03_l",
+  "pinky_01_r", "pinky_02_r", "pinky_03_r",
+];
+
+const SPINE_NAMES = [
+  "spine", "spine1", "spine2", "spine_01", "spine_02", "spine_03",
+  "Spine", "Spine1", "Spine2",
+];
+
+const PRESET_NAMES: Record<BoneMaskPreset, string[]> = {
+  [BoneMaskPreset.UPPER_BODY]: UPPER_BODY_NAMES,
+  [BoneMaskPreset.LOWER_BODY]: LOWER_BODY_NAMES,
+  [BoneMaskPreset.LEFT_ARM]: LEFT_ARM_NAMES,
+  [BoneMaskPreset.RIGHT_ARM]: RIGHT_ARM_NAMES,
+  [BoneMaskPreset.HEAD]: HEAD_NAMES,
+  [BoneMaskPreset.HANDS]: HAND_NAMES,
+  [BoneMaskPreset.FULL_BODY]: [],
+  [BoneMaskPreset.SPINE_ONLY]: SPINE_NAMES,
+};
+
+export function buildBoneMask(preset: BoneMaskPreset, skeleton: SkeletonData): Set<number> {
+  if (preset === BoneMaskPreset.FULL_BODY) {
+    return new Set(skeleton.bones.map((_, i) => i));
+  }
+
+  const names = PRESET_NAMES[preset];
+  if (!names || names.length === 0) {
+    return new Set(skeleton.bones.map((_, i) => i));
+  }
+
+  const nameSet = new Set(names.map((n) => n.toLowerCase()));
+  const result = new Set<number>();
+
+  for (let i = 0; i < skeleton.bones.length; i++) {
+    const boneName = skeleton.bones[i].name.toLowerCase();
+    if (nameSet.has(boneName)) {
+      result.add(i);
+    }
+  }
+
+  return result;
+}
+
+const customMasks: Map<string, string[]> = new Map();
+
+export function registerCustomMask(name: string, boneNames: string[]): void {
+  customMasks.set(name, boneNames);
+}
+
+export function buildCustomBoneMask(name: string, skeleton: SkeletonData): Set<number> {
+  const names = customMasks.get(name);
+  if (!names) return new Set(skeleton.bones.map((_, i) => i));
+
+  const nameSet = new Set(names.map((n) => n.toLowerCase()));
+  const result = new Set<number>();
+
+  for (let i = 0; i < skeleton.bones.length; i++) {
+    const boneName = skeleton.bones[i].name.toLowerCase();
+    if (nameSet.has(boneName)) {
+      result.add(i);
+    }
+  }
+
+  return result;
+}