@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/libraries/character/src/loader.ts

@@ -8,6 +8,7 @@
 // ============================================================================
 
 import {
+    bindUnskinnedMeshes,
     loadModel,
     resolveImportSettings,
     type AnimationData,
@@ -117,7 +118,7 @@ export async function loadExternalTextures(
             if (data.byteLength > 4 && isDecodableImage(new Uint8Array(data, 0, 4))) {
               mat.textureData = data;
               foundExternal = true;
-              log.info("CharacterModel", `Material[${mi}] "${mat.name}": loaded ${candidate} from ${dir}`);
+              log.info("character-model", `Material[${mi}] "${mat.name}": loaded ${candidate} from ${dir}`);
               break;
             }
           } catch {
@@ -186,10 +187,10 @@ export function filterOptionalMeshes(
     modelData.nodes.forEach((node) => {
         if (isOptional(node.name)) excludedNames.push(node.name);
     });
-    log.info("CharacterModel", `Filtered ${exclude.size} optional item mesh(es): [${excludedNames.join(", ")}]`);
+    log.info("character-model", `Filtered ${exclude.size} optional item mesh(es): [${excludedNames.join(", ")}]`);
 
     excludeMeshIndices(modelData, exclude);
-    log.info("CharacterModel", `Filtered optional meshes, keeping ${modelData.meshes.length}`);
+    log.info("character-model", `Filtered optional meshes, keeping ${modelData.meshes.length}`);
 }
 
 /**
@@ -218,12 +219,21 @@ function excludeMeshIndices(modelData: ModelData, exclude: Set<number>): void {
     });
 }
 
+/**
+ * Strip a Blender mesh-split `_ptN` suffix so split parts resolve to their
+ * variant's canonical node (e.g. `rb_headwear.005_pt2` → `rb_headwear.005`).
+ */
+function variantPartKey(name: string): string {
+    return name.replace(/_pt\d+$/i, "");
+}
+
 /**
  * Strip the trailing `.NNN` / `_NNN` variant suffix from a node name to get
- * its equipment-slot group (e.g. `f_torso.007` → `f_torso`).
+ * its equipment-slot group (e.g. `f_torso.007` → `f_torso`). Mesh-split
+ * `_ptN` parts fold into their base variant first.
  */
 function variantGroupKey(name: string): string {
-    return name.replace(/[._]\d+$/, "");
+    return variantPartKey(name).replace(/[._]\d+$/, "");
 }
 
 /**
@@ -250,16 +260,21 @@ export function selectVariantMeshes(modelData: ModelData): void {
     const kept: string[] = [];
     for (const list of groups.values()) {
         if (list.length < 2) continue;
+        // Keep the first variant — including every `_ptN` split part that
+        // shares its canonical node name (a variant split across several
+        // nodes is one visual item).
+        const keepPart = variantPartKey(list[0].name);
         kept.push(list[0].name);
-        for (let i = 1; i < list.length; i++) {
+        for (let i = 0; i < list.length; i++) {
             const node = list[i];
+            if (variantPartKey(node.name) === keepPart) continue;
             if (node.meshes) node.meshes.forEach((idx) => { exclude.add(idx);; });
             if (node.mesh !== undefined) exclude.add(node.mesh);
         }
     }
 
     if (exclude.size === 0) return;
-    log.info("CharacterModel", `Variant selection kept [${kept.join(", ")}], dropping ${exclude.size} meshes`);
+    log.info("character-model", `Variant selection kept [${kept.join(", ")}], dropping ${exclude.size} meshes`);
     excludeMeshIndices(modelData, exclude);
 }
 
@@ -278,6 +293,10 @@ export interface CharacterModelLoaderOptions {
   filterOptionalMeshes?: boolean;
   /** Keep one mesh node per variant group (`slot.NNN` siblings). Default true. */
   selectVariantMeshes?: boolean;
+  /** Rigid-bind meshes that carry no skin weights to the nearest bone
+   *  (Unity-style bone-attached accessories like hair, glasses, hats that
+   *  FBX exports without a skin deformer). Default true. */
+  bindUnskinnedMeshes?: boolean;
 }
 
 export interface CharacterModelLoader {
@@ -303,13 +322,13 @@ export function createCharacterModelLoader(opts: CharacterModelLoaderOptions = {
     for (let _i = 0, _it = opts.animations ?? [], _n = _it.length; _i < _n; _i++) { const animDef = _it[_i];
       const url = opts.resolveAnimationUrl?.(animDef.filename) ?? null;
       if (!url) {
-        log.warn("CharacterModel", `Animation not found: ${animDef.filename}`);
+        log.warn("character-model", `Animation not found: ${animDef.filename}`);
         continue;
       }
       try {
         const resp = await fetch(url);
         if (!resp.ok) {
-          log.warn("CharacterModel", `Failed to fetch animation ${animDef.filename}: ${resp.status}`);
+          log.warn("character-model", `Failed to fetch animation ${animDef.filename}: ${resp.status}`);
           continue;
         }
         const buffer = await resp.arrayBuffer();
@@ -319,12 +338,12 @@ export function createCharacterModelLoader(opts: CharacterModelLoaderOptions = {
           const anim = animModel.animations[0];
           anim.name = animDef.state; // Override name with the state name.
           anims.set(animDef.state, anim);
-          log.info("CharacterModel", `Loaded animation: ${animDef.state} from ${animDef.filename} (${anim.duration.toFixed(2)}s, ${anim.channels.length} channels)`);
+          log.info("character-model", `Loaded animation: ${animDef.state} from ${animDef.filename} (${anim.duration.toFixed(2)}s, ${anim.channels.length} channels)`);
         } else {
-          log.warn("CharacterModel", `No animations in ${animDef.filename}`);
+          log.warn("character-model", `No animations in ${animDef.filename}`);
         }
       } catch (err) {
-        log.warn("CharacterModel", `Failed to load animation ${animDef.filename}: ${err}`);
+        log.warn("character-model", `Failed to load animation ${animDef.filename}: ${err}`);
       }
     }
     animCache = anims;
@@ -356,12 +375,18 @@ export function createCharacterModelLoader(opts: CharacterModelLoaderOptions = {
       if (opts.selectVariantMeshes !== false) {
         selectVariantMeshes(modelData);
       }
+      if (opts.bindUnskinnedMeshes !== false) {
+        const bound = bindUnskinnedMeshes(modelData);
+        if (bound > 0) {
+          log.info("character-model", `Rigid-bound ${bound} unskinned mesh(es) to nearest bone (${def.id})`);
+        }
+      }
 
       // Load shared animations and merge into the model data.
       const anims = await loadAnimations();
       if (anims.size > 0) {
         modelData.animations = Array.from(anims.values());
-        log.info("CharacterModel", `Attached ${anims.size} animations to ${def.id}`);
+        log.info("character-model", `Attached ${anims.size} animations to ${def.id}`);
       }
 
       cache.set(def.id, modelData);

package/libraries/character/src/locomotion.ts

@@ -40,6 +40,13 @@ export interface LocomotionConfig {
    * Prevents mid-air state churn when speed changes mid-jump.
    */
   holdAirState?: boolean;
+  /**
+   * Per-transition crossfade overrides (seconds), keyed `"from->to"` with
+   * `"*"` wildcards (e.g. `"Swim->Jump"`, `"Swim->*"`, `"*->Swim"`). More
+   * specific keys win; absent = the animator's default blend duration.
+   * Useful for softening jarring swaps like Swim→Jump on a pool vault.
+   */
+  transitionFades?: Record<string, number>;
 }
 
 export interface LocomotionInput {
@@ -61,6 +68,7 @@ export class LocomotionAnimator extends SkeletonAnimator {
     run: AnimState;
     air?: AnimState | ((speed: number) => AnimState);
     holdAirState: boolean;
+    transitionFades?: Record<string, number>;
   };
 
   constructor(skin: SkinData, config: LocomotionConfig = {}) {
@@ -76,6 +84,7 @@ export class LocomotionAnimator extends SkeletonAnimator {
       runExit: t.runExit ?? 2.5,
       air: config.air,
       holdAirState: config.holdAirState ?? true,
+      transitionFades: config.transitionFades,
     };
   }
 
@@ -118,7 +127,10 @@ export class LocomotionAnimator extends SkeletonAnimator {
       desired = c.idle;
     }
 
-    this.setAnimationState(desired);
+    const fade = c.transitionFades?.[`${this.getCurrentState()}->${desired}`]
+      ?? c.transitionFades?.[`*->${desired}`]
+      ?? c.transitionFades?.[`${this.getCurrentState()}->*`];
+    this.setAnimationState(desired, fade);
     this.tick(dt);
   }
 }

package/libraries/character/src/preview.ts

@@ -17,16 +17,28 @@ import {
     type RenderSurface,
 } from "@downdraft/engine";
 import { ModelRenderer } from "@downdraft/engine/libraries/entities";
-import type { ModelData } from "@downdraft/engine/libraries/models";
+import type { MaterialData, ModelData } from "@downdraft/engine/libraries/models";
 import { createLogger } from "@downdraft/engine/util/logger";
 import { mat4 } from "wgpu-matrix";
 import type { CharacterAnimator } from "./character-animator";
 
 const log = createLogger("info");
 
+export interface CharacterPreviewModel {
+  modelData: ModelData;
+  meshBaseUrl: string;
+  /** Mesh subset to upload (defaults to modelData.meshes) — character
+   *  customizers pass the selected variant meshes here. */
+  meshes?: ModelData["meshes"];
+  /** Materials override (defaults to modelData.materials). */
+  materials?: ModelData["materials"];
+  /** Bounds used to fit the preview scale (defaults to modelData.bounds). */
+  bounds?: { min: [number, number, number]; max: [number, number, number] } | null;
+}
+
 export interface CharacterPreviewOptions {
   /** Resolve a model id to its ModelData (e.g. createCharacterModelLoader). */
-  loadModel(modelId: string): Promise<{ modelData: ModelData; meshBaseUrl: string } | null>;
+  loadModel(modelId: string): Promise<CharacterPreviewModel | null>;
   /** Build the animator for a loaded model. */
   createAnimator(modelData: ModelData): CharacterAnimator;
   /** Orbit distance (default 3.5). */
@@ -36,8 +48,20 @@ export interface CharacterPreviewOptions {
   targetHeight?: number;
   /** Radians/sec rotation speed (default 0.5). */
   rotationSpeed?: number;
+  /** Per-frame animator drive — returns the flat skin matrices. Defaults to
+   *  `animator.advance(dt)` + computeSkinMatrices(), which only runs the
+   *  procedural idle: bones driven exclusively by animation clips stay at
+   *  bind pose (props/accessories can render at the wrong spot). Games with
+   *  a locomotion state machine should pass their in-game update fn (e.g.
+   *  `(a, dt) => a.update(dt, true, 0, pose, false)`) so the preview plays
+   *  the real Idle clip. */
+  advanceAnimator?: (animator: CharacterAnimator, dt: number) => Float32Array;
   /** Clear color (default dark slate). */
   clearColor?: { r: number; g: number; b: number; a: number };
+  /** Render-target format — defaults to the host's preferred canvas format.
+   *  Set when the RenderSurface wraps an offscreen GPUTexture whose format
+   *  differs from the swapchain's (e.g. rgba8unorm for UI compositing). */
+  outputFormat?: GPUTextureFormat;
 }
 
 const UP: [number, number, number] = [0, 1, 0];
@@ -58,6 +82,7 @@ export class CharacterPreview {
   private depthH = 0;
   private rafHandle = 0;
   private rotationAngle = 0;
+  private orbiting = false;
   private lastTime = performance.now();
   private currentModelId: string | null = null;
   private running = false;
@@ -88,13 +113,16 @@ export class CharacterPreview {
       this.ownsDevice = true;
     }
     this.device.lost.then((info) => {
-      log.warn("CharacterPreview", `GPUDevice LOST: ${info.reason} ${info.message}`);
-    });
-    this.device.addEventListener("uncapturederror", (e) => {
-      log.error("CharacterPreview", `uncaptured GPU error: ${(e as GPUUncapturedErrorEvent).error?.message}`);
+      log.warn("character-preview", `GPUDevice LOST: ${info.reason} ${info.message}`);
     });
+    // Native's WgpuDevice is a plain FFI wrapper, not an EventTarget.
+    if (typeof this.device.addEventListener === "function") {
+      this.device.addEventListener("uncapturederror", (e) => {
+        log.error("character-preview", `uncaptured GPU error: ${(e as GPUUncapturedErrorEvent).error?.message}`);
+      });
+    }
     this.context = this.canvas.getContext("webgpu") as unknown as GPUCanvasContext;
-    this.format = navigator.gpu.getPreferredCanvasFormat();
+    this.format = this.opts.outputFormat ?? navigator.gpu.getPreferredCanvasFormat();
     this.context.configure({
       device: this.device,
       format: this.format,
@@ -118,6 +146,15 @@ export class CharacterPreview {
     await this.modelRenderer.init();
   }
 
+  /** The currently-displayed model id (or null before the first setModel). */
+  getModelId(): string | null { return this.currentModelId; }
+
+  /** Pause/resume the auto-turntable — set while the user drag-orbits the
+   *  preview so pointer input and the idle spin don't fight. */
+  setOrbiting(orbiting: boolean): void { this.orbiting = orbiting; }
+  /** Rotate the model yaw by `deltaRad` (drag-to-orbit input). */
+  orbitBy(deltaRad: number): void { this.rotationAngle += deltaRad; }
+
   /** Load (or swap) the model shown in the preview. */
   async setModel(modelId: string): Promise<void> {
     if (!this.device || !this.modelRenderer) return;
@@ -130,23 +167,54 @@ export class CharacterPreview {
       if (this.modelRenderer.hasModel("preview")) {
         this.modelRenderer.removeModel("preview");
       }
-      this.modelRenderer.uploadModel("preview", loaded.modelData.meshes, loaded.modelData.materials, loaded.meshBaseUrl);
-      const bounds = loaded.modelData.bounds;
-      if (bounds && bounds.max[1] - bounds.min[1] > 0) {
-        this.modelScale = 1.8 / (bounds.max[1] - bounds.min[1]);
-        this.modelYOffset = -bounds.min[1] * this.modelScale;
-      } else {
-        this.modelScale = 1;
-        this.modelYOffset = 0;
-      }
+      this.modelRenderer.uploadModel(
+        "preview",
+        loaded.meshes ?? loaded.modelData.meshes,
+        loaded.materials ?? loaded.modelData.materials,
+        loaded.meshBaseUrl,
+      );
+      this.applyBounds(loaded.bounds !== undefined ? loaded.bounds : loaded.modelData.bounds);
       this.animator?.dispose();
       this.animator = this.opts.createAnimator(loaded.modelData);
       this.currentModelId = modelId;
     } catch (err) {
-      log.error("CharacterPreview", `Failed to load model ${modelId}: ${err}`);
+      log.error("character-preview", `Failed to load model ${modelId}: ${err}`);
     }
   }
 
+  private applyBounds(bounds: { min: [number, number, number]; max: [number, number, number] } | null | undefined): void {
+    if (bounds && bounds.max[1] - bounds.min[1] > 0) {
+      this.modelScale = 1.8 / (bounds.max[1] - bounds.min[1]);
+      this.modelYOffset = -bounds.min[1] * this.modelScale;
+    } else {
+      this.modelScale = 1;
+      this.modelYOffset = 0;
+    }
+  }
+
+  /**
+   * Re-upload the displayed model's mesh subset + materials in place —
+   * used by character customizers to apply variant/texture/tint changes
+   * without reloading the model or rebuilding the animator.
+   */
+  refreshModel(
+    meshes: ModelData["meshes"],
+    materials?: ModelData["materials"],
+    bounds?: { min: [number, number, number]; max: [number, number, number] } | null,
+  ): void {
+    if (!this.modelRenderer || !this.currentModelId) return;
+    this.modelRenderer.reuploadModel("preview", meshes, materials);
+    if (bounds !== undefined) this.applyBounds(bounds);
+  }
+
+  /**
+   * Update a registered material's texture/tint in place (forwards to the
+   * underlying ModelRenderer — see updateMeshMaterial).
+   */
+  updateMaterial(materialIndex: number, mat: MaterialData): void {
+    this.modelRenderer?.updateMeshMaterial("preview", materialIndex, mat);
+  }
+
   /** Start the rAF render loop. */
   start(): void {
     if (this.running) return;
@@ -193,15 +261,16 @@ export class CharacterPreview {
     const dt = Math.min(0.1, (now - this.lastTime) / 1000);
     this.lastTime = now;
 
-    // Auto-rotate
-    this.rotationAngle += dt * (this.opts.rotationSpeed ?? 0.5);
+    // Turntable: the MODEL spins, the camera stays put. Orbiting the camera
+    // by the same angle cancels the rotation exactly (the same face always
+    // faces the viewer) — a bug carried over from the original code.
+    if (!this.orbiting) this.rotationAngle += dt * (this.opts.rotationSpeed ?? 0.5);
 
-    // Camera: orbit around the model center at eye height.
     const dist = this.opts.orbitDistance ?? 3.5;
     const pos: [number, number, number] = [
-      Math.sin(this.rotationAngle) * dist,
+      0,
       this.opts.cameraHeight ?? 1.2,
-      Math.cos(this.rotationAngle) * dist,
+      dist,
     ];
     const target: [number, number, number] = [0, this.opts.targetHeight ?? 0.9, 0];
     const proj = mat4.perspective(Math.PI / 4, W / H, 0.1, 100);
@@ -220,8 +289,9 @@ export class CharacterPreview {
 
     // Advance the animation (idle by default) + upload skin matrices.
     if (this.animator && this.modelRenderer.hasModel("preview")) {
-      this.animator.animator.advance(dt);
-      const skinMats = this.animator.computeSkinMatrices();
+      const skinMats = this.opts.advanceAnimator
+        ? this.opts.advanceAnimator(this.animator, dt)
+        : (this.animator.animator.advance(dt), this.animator.computeSkinMatrices());
       this.modelRenderer.updateSkinMatrices(skinMats);
     }
 

package/libraries/devtools/README.md

@@ -2,24 +2,23 @@
 
 DevTools bridge — mirrors profiling and inspection data to a developer UI.
 
-## Two frontends
-
-**Web DevTools (current)** — `WebDevtoolsHost` runs a development-only loopback
-server (`DevToolsServer`, `Bun.serve`: HTTP static + WebSocket JSON-RPC) and
-serves the browser frontend in `packages/devtools-web`. Pressing **F12** in a
-native game opens the devtools in a desktop browser (`--app` window on
-Chromium-family browsers, falling back through brave → vivaldi → firefox →
-chrome → edge → `xdg-open`). Discovery files are written to
-`~/.downdraft/devtools/<pid>.json` (port + token), mirroring the MCP
-`~/.downdraft/port` convention.
-
-**egui overlay (legacy)** — `NativeDebuggerHost` + `DevtoolsMirror` render the
-Rust egui crate's PaintJobs into a GPU texture composited over the frame.
-Kept in-tree while the web path is verified on real hardware; slated for
-removal.
+## Frontends
+
+**Blitz devtools (docked, in-window)** — an html-ui/Blitz document rendered
+inside the game window with Chrome-DevTools-style tabs. Lives in
+`@downdraft/engine/modules/devtools` (`blitz/`). Toggled with **F12**.
+
+**Web DevTools (separate browser window)** — `WebDevtoolsHost` runs a
+development-only loopback server (`DevToolsServer`, `Bun.serve`: HTTP static
++ WebSocket JSON-RPC) and serves the browser frontend in
+`packages/devtools-web`. Pressing **F12** opens the devtools in a desktop
+browser (`--app` window on Chromium-family browsers, falling back through
+brave → vivaldi → firefox → chrome → edge → `xdg-open`). Discovery files are
+written to `~/.downdraft/devtools/<pid>.json` (port + token), mirroring the
+MCP `~/.downdraft/port` convention.
 
 Both frontends consume the same provider/command model:
-`registerEngineProviders(mirror, ctx)` works on either mirror
+`registerEngineProviders(target, ctx)` works on either
 (`DevtoolsProviderTarget`), and `PanelSnapshot` sections (`kv`, `table`,
 `series`, `lines`, `controls`) render in both.
 
@@ -38,9 +37,8 @@ Both frontends consume the same provider/command model:
 ## Key exports
 
 - `WebDevtoolsHost`, `WebDevtoolsMirror`, `DevToolsServer`, `openDevToolsUrl`
-- `NativeDebuggerHost`, `DevtoolsMirror` (legacy egui path)
 - `CdpBridge`, `registerEngineProviders`, `PANEL`, `SNAP_FLAG`, `SNAP_STATUS`,
-  `encodeSnapshot`, `checkpoint`, `notify`, `verifyPixel`
+  `checkpoint`, `notify`, `verifyPixel`
 
 ## Test