@vgai/engine 0.5.13 → 0.5.15

package/src/adapter/setup-three-root-adapter.ts

@@ -51,6 +51,7 @@ import { createCollisionSystem } from '../physics/collision-system';
 import { createPhysicsRegistry } from '../physics/physics-registry';
 import { createTransformWriter } from '../physics/transform-writer';
 import { updateSceneLODs } from '../render/lod';
+import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
 import {
   disposeSparkRendererWhenIdle,
   SPARK_DISCOVERY_INTERVAL_MS,
@@ -209,6 +210,10 @@ export class SetupThreeRootAdapter implements RootAdapter {
 
     // --- Particles (three.quarks BatchedRenderer) ---
     const particles = setupParticles(scene);
+    // Scene depth for any soft-particle system registered against this world.
+    // Inert (not one traversal, not one draw) until `registerParticleSystem`
+    // arms it — see `../render/soft-particle-depth.ts`.
+    const softParticleDepth = createSoftParticleDepthPass();
 
     // --- Debug draw / assets ---
     const debugDraw = createDebugDraw(scene);
@@ -311,6 +316,13 @@ export class SetupThreeRootAdapter implements RootAdapter {
           // the assembled capture to a pending captureFrame() and restores the
           // patched context — in the SAME finally as gpuTimer.end(). Spark is
           // added before this so its draws fall inside the captured frame.
+          // Soft-particle scene depth goes in FRONT of the frame's own draw:
+          // the fade samples the geometry behind the particle, which cannot be
+          // the depth attachment the particle is drawn into. Deliberately
+          // OUTSIDE the capture and profiler brackets below — it is a prepass,
+          // not part of the frame's presentation, and a captured frame should
+          // show the draws the user sees.
+          softParticleDepth.render(renderer, scene, camera);
           renderDebugWiring?.beforeRender();
           // Issue #1504: CPU render submission, bracketed as its OWN profiler
           // phase nested inside the frame's enclosing `render` phase. This is
@@ -838,6 +850,10 @@ export class SetupThreeRootAdapter implements RootAdapter {
         renderVitals = null;
       });
 
+      // This mount created the depth pass, so this mount ends it — the render
+      // target it holds is drawing-buffer sized and nothing else can reach it.
+      safeStep('softParticleDepth.dispose', () => softParticleDepth.dispose());
+
       // Release analyser taps BEFORE the audio teardown below. A consumer
       // (the editor's meter poll) should dispose its own handle, but Stop must
       // never leak taps regardless.

package/src/adapter/system-adapter.ts

@@ -14,8 +14,60 @@
 import type * as THREE from 'three';
 import type { RenderMemorySnapshot } from '../dev/render-memory';
 import type { FrameCapture } from '../dev/webgl-frame-capture';
+import type { PhysicsAdapter2D } from '../pixi/system-adapters';
 import type { Transform, TransformOwner } from './transform';
 
+export type PhysicsColliderShape =
+  | { readonly type: 'cuboid'; readonly halfExtents: readonly [number, number, number] }
+  | { readonly type: 'ball'; readonly radius: number }
+  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number };
+
+/** Plain-data projection of one native 3D physics collider. The owning
+ * physics implementation keeps the actual collider; editor authoring only
+ * receives the geometry needed to inspect and draw it. */
+export interface PhysicsColliderSnapshot {
+  readonly id: string;
+  readonly shape: PhysicsColliderShape;
+  readonly position: readonly [number, number, number];
+  readonly rotation: readonly [number, number, number, number];
+  /** Absolute world scale used when the native shape was created. Source
+   * dimensions divide by this to recover @react-three/rapier's local args. */
+  readonly scale: readonly [number, number, number];
+  readonly sensor: boolean;
+}
+
+export type PhysicsJointType =
+  | 'fixed'
+  | 'spherical'
+  | 'revolute'
+  | 'prismatic'
+  | 'rope'
+  | 'spring'
+  | 'generic';
+
+/** Plain-data projection of one native 3D impulse joint. Anchors are exposed
+ * in both native body-local space (for persistence) and world space (for
+ * viewport instruments); the actual joint remains owned by the physics lib. */
+export interface PhysicsJointSnapshot {
+  readonly id: string;
+  readonly type: PhysicsJointType;
+  readonly body1: string;
+  readonly body2: string;
+  readonly anchor1: readonly [number, number, number];
+  readonly anchor2: readonly [number, number, number];
+  readonly worldAnchor1: readonly [number, number, number];
+  readonly worldAnchor2: readonly [number, number, number];
+  readonly body1Position: readonly [number, number, number];
+  readonly body2Position: readonly [number, number, number];
+  readonly body1Rotation: readonly [number, number, number, number];
+  readonly body2Rotation: readonly [number, number, number, number];
+  /** The free axis in body-1 local/world space for revolute/prismatic joints. */
+  readonly axis?: readonly [number, number, number];
+  readonly worldAxis?: readonly [number, number, number];
+  readonly limits?: { readonly min: number; readonly max: number };
+  readonly contactsEnabled: boolean;
+}
+
 /**
  * Physics coordination so the editor can stably edit an object a simulation
  * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
@@ -24,11 +76,36 @@ import type { Transform, TransformOwner } from './transform';
  * Object3D keying made this seam structurally unreachable for any non-three
  * world: a Pixi or React world could never expose a physics inspector, because
  * the seam spoke a vocabulary it has no values in — which is why the Pixi
- * surface grew a parallel `PhysicsAdapter2D` (`pixi/system-adapters.ts`)
+ * surface grew a parallel {@link PhysicsAdapter2D} (`pixi/system-adapters.ts`)
  * instead of implementing this. Substrate-specific resolution (id → the native
  * object) is the IMPLEMENTER's job, done once at its own boundary.
+ *
+ * ## `keyedBy`, and why the physics slot's union is TAGGED
+ *
+ * `SystemAdapters['physics']` holds EITHER shape ({@link PhysicsCarrier}),
+ * because a carrier addresses the thing being edited in its surface's own
+ * vocabulary and the canvas lane's is the display object itself. But the two
+ * shapes carry the SAME four member names and are otherwise indistinguishable
+ * at runtime, while the registry that holds them
+ * (`editor/src/authoring/active-systems.ts`) is GAME-scoped and surface-blind —
+ * one object every editor panel reads. An untagged union would therefore be one
+ * nothing could narrow, and every three-lane consumer
+ * (`getActivePhysics()?.freeze(nodeId)`, `play-mode.ts`'s `physics.commit(id,
+ * transform)`) would have to reach it through a cast asserting a fact nobody
+ * checked.
+ *
+ * So `keyedBy` is a real discriminant, and it is REQUIRED on
+ * {@link PhysicsAdapter2D} while OPTIONAL here on purpose: node-id keying is
+ * this seam's original and — until the canvas lane — only vocabulary, so every
+ * existing implementer stays valid untouched, and the shape that needs telling
+ * apart is the one obliged to say so. {@link nodeKeyedPhysics} /
+ * {@link displayKeyedPhysics} are the two narrowings; nothing else should test
+ * the tag by hand.
  */
 export interface PhysicsAdapter {
+  /** Optional tag; see the interface comment. `'node-id'` is the only value,
+   *  and omitting it means the same thing. */
+  readonly keyedBy?: 'node-id';
   /** Returns `'physics'` when a body drives this node, else another owner. */
   ownerOf(nodeId: string): TransformOwner;
   /** Pause the body driving `nodeId` (kinematic / sleep / detach) for editing. */
@@ -53,6 +130,21 @@ export interface PhysicsAdapter {
    * geometry).
    */
   contactPoints?(): Float32Array;
+  /** Optional native collider inspection for one authored node. Implementers
+   * return only shapes they can describe exactly; absence means the editor
+   * offers no collider component UI. */
+  colliders?(nodeId: string): readonly PhysicsColliderSnapshot[];
+  /** Optional gesture preview against the implementation's real collider.
+   * Source persistence remains the AuthoringAdapter's responsibility. */
+  previewCollider?(colliderId: string, shape: PhysicsColliderShape): void;
+  /** Optional native impulse-joint inspection for joints attached to one node. */
+  joints?(nodeId: string): readonly PhysicsJointSnapshot[];
+  /** Optional gesture preview against the implementation's real local anchor. */
+  previewJointAnchor?(
+    jointId: string,
+    endpoint: 0 | 1,
+    anchor: readonly [number, number, number],
+  ): void;
 }
 
 export interface NetPeer {
@@ -377,11 +469,73 @@ export interface AudioAdapter {
    *  environment cannot meter (headless world with no real AudioContext) —
    *  the UI says so rather than showing frozen zeros. */
   acquireMeters?(): AudioMeterHandle | null;
+  /** Optional: tap the real mixed output for a gameplay recording. The
+   * returned stream is the implementation's native browser audio stream; the
+   * caller must dispose the tap when recording ends. Absence means video can
+   * still be recorded, honestly without an audio track. */
+  acquireRecordingStream?(): AudioRecordingHandle | null;
   /** Optional: the audio event ring (bounded, drops oldest). `sinceSeq`
    *  filters to `seq > sinceSeq` — the consumer's fence. */
   audioEvents?(sinceSeq?: number): AudioDebugEvent[];
 }
 
+/** One temporary tap of an audio adapter's mixed output. */
+export interface AudioRecordingHandle {
+  readonly stream: MediaStream;
+  dispose(): void;
+}
+
+/** One native camera known to a runtime camera controller.
+ *
+ * `id` is the controller's own stable key (a shot name, virtual-camera id,
+ * etc.). `nativeId` is OPTIONAL identity from the underlying scene object —
+ * Three.js implementations normally use `Object3D.uuid`; another adapter may
+ * use its renderer's equivalent. The editor uses it only to correlate an
+ * already-selected native camera with this read-only runtime projection. */
+export interface CameraRuntimeCamera {
+  id: string;
+  label: string;
+  nativeId?: string;
+  /** Optional because ownership/cut controllers do not necessarily arbitrate
+   * by priority. A camera brain that does may expose the real value it uses. */
+  priority?: number;
+  enabled?: boolean;
+}
+
+/** A transition the controller is evaluating now. Plain data only: no
+ * renderer camera, tween, graph node, or editor-authored state crosses the
+ * seam. */
+export interface CameraRuntimeTransition {
+  fromCameraId: string | null;
+  toCameraId: string;
+  durationSeconds: number;
+  elapsedSeconds: number;
+  progress: number;
+}
+
+/** Read-only runtime state for a selected native camera's Inspector section.
+ * Runtime follow/aim/collision stays project behavior; this snapshot merely
+ * reports what that behavior already decided. */
+export interface CameraRuntimeSnapshot {
+  cameras: readonly CameraRuntimeCamera[];
+  activeCameraId: string | null;
+  /** The behavior/cinematic currently allowed to drive the rendered camera. */
+  activeControllerId: string | null;
+  ownershipDepth: number;
+  transition: CameraRuntimeTransition | null;
+}
+
+/** Camera-controller INTROSPECTION — not a camera graph or controller API.
+ *
+ * Games continue to author ordinary native cameras and drive them with their
+ * own TS/TSX. A controller registers this adapter only when it can truthfully
+ * expose its active camera, priority and blend state. Absence hides the
+ * runtime UI; the editor never infers a brain from scene structure. */
+export interface CameraAdapter {
+  snapshot(): CameraRuntimeSnapshot;
+  subscribe(listener: () => void): Unsubscribe;
+}
+
 /** One tick-stamped debug event (`ctx.debug.emit`, spec §3.3): `tick`/`simT`
  *  are the engine's own counters AT EMISSION, so events and state reads
  *  correlate frame-exactly across every door (in-page bridge, relay, panels).
@@ -470,15 +624,47 @@ export interface RenderDebugAdapter {
   memorySnapshot?(): RenderMemorySnapshot;
 }
 
+/**
+ * A physics carrier in EITHER surface's vocabulary — node-id keyed for a three
+ * world, display-object keyed for a canvas one. Tagged by `keyedBy`; see
+ * {@link PhysicsAdapter}'s comment for why, and use the two narrowings below
+ * rather than reading the tag directly.
+ */
+export type PhysicsCarrier = PhysicsAdapter | PhysicsAdapter2D;
+
+/** The carrier a NODE-ID-keyed consumer may call, or `null` — including when
+ *  the slot holds a display-keyed carrier, which such a consumer must not
+ *  call and cannot correctly address. */
+export function nodeKeyedPhysics(
+  carrier: PhysicsCarrier | null | undefined,
+): PhysicsAdapter | null {
+  if (!carrier) return null;
+  return isDisplayKeyedPhysics(carrier) ? null : carrier;
+}
+
+/** The carrier a DISPLAY-keyed consumer may call, or `null`. Mirror of
+ *  {@link nodeKeyedPhysics}. */
+export function displayKeyedPhysics(
+  carrier: PhysicsCarrier | null | undefined,
+): PhysicsAdapter2D | null {
+  if (!carrier) return null;
+  return isDisplayKeyedPhysics(carrier) ? carrier : null;
+}
+
+function isDisplayKeyedPhysics(carrier: PhysicsCarrier): carrier is PhysicsAdapter2D {
+  return carrier.keyedBy === 'display';
+}
+
 /**
  * The set of optional subsystem providers a mounted game may expose. Absence of
  * a provider means "capability not supported" — the editor degrades gracefully.
  */
 export interface SystemAdapters {
-  physics?: PhysicsAdapter;
+  physics?: PhysicsCarrier;
   networking?: NetworkingAdapter;
   navigation?: NavigationAdapter;
   audio?: AudioAdapter;
+  camera?: CameraAdapter;
   debug?: DebugAdapter;
   renderDebug?: RenderDebugAdapter;
 }

package/src/animation/camera-ownership.ts

@@ -1,4 +1,9 @@
 import * as THREE from 'three';
+import type {
+  CameraAdapter,
+  CameraRuntimeSnapshot,
+  CameraRuntimeTransition,
+} from '../adapter/system-adapter';
 import type { SystemPhaseName } from '../core/types';
 import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
 import type { CameraOwnershipChangeEvent } from './theatre-director';
@@ -107,7 +112,8 @@ import type { CameraOwnershipChangeEvent } from './theatre-director';
  * ## One unified transition model — cut is just a zero-duration blend
  *
  * Internally, `cut`/`blend`/`applyDirectorEvent` all record exactly one
- * `FrameState` shape: `{ targetKey, fromPose, startTime, durationSeconds }`
+ * `FrameState` shape: `{ targetKey, fromTargetKey, fromPose, startTime,
+ * durationSeconds }`
  * (`durationSeconds` is `0` for a cut). On EVERY clock crossing, the applied
  * pose is a PURE function of `clock.time` and this fixed record — nothing is
  * mutated as time passes:
@@ -236,6 +242,7 @@ export function lerpPose(from: CameraPose, to: CameraPose, t: number): CameraPos
  */
 interface FrameState {
   readonly targetKey: string;
+  readonly fromTargetKey: string | null;
   readonly fromPose: CameraPose;
   readonly startTime: number;
   readonly durationSeconds: number;
@@ -280,7 +287,7 @@ export interface CameraOwnershipSystemOptions {
   phase?: SystemPhaseName;
 }
 
-export interface CameraOwnershipSystem {
+export interface CameraOwnershipSystem extends CameraAdapter {
   /** Push a new ownership frame for `ownerId`, capturing `liveCamera`'s current pose as its restore point. Throws if `ownerId` is already on the stack. */
   take(ownerId: string, options?: CameraOwnershipTakeOptions): void;
   /** Hard-cut the live camera to `cameraKey`'s current pose. `ownerId` must be the current (top-of-stack) owner. */
@@ -312,7 +319,43 @@ export function createCameraOwnershipSystem(
   const phase = options.phase ?? 'render';
 
   const stack: OwnershipFrame[] = [];
+  const listeners = new Set<() => void>();
   let disposed = false;
+  let transitionWasVisible = false;
+
+  function notify(): void {
+    for (const listener of listeners) listener();
+  }
+
+  function transitionSnapshot(frame: OwnershipFrame | undefined): CameraRuntimeTransition | null {
+    const state = frame?.state;
+    if (!state || state.durationSeconds <= 0) return null;
+    const elapsedSeconds = Math.max(0, clock.time - state.startTime);
+    const progress = Math.min(elapsedSeconds / state.durationSeconds, 1);
+    if (progress >= 1) return null;
+    return {
+      fromCameraId: state.fromTargetKey,
+      toCameraId: state.targetKey,
+      durationSeconds: state.durationSeconds,
+      elapsedSeconds,
+      progress,
+    };
+  }
+
+  function snapshot(): CameraRuntimeSnapshot {
+    const top = stack[stack.length - 1];
+    return {
+      cameras: Object.entries(cameras).map(([id, camera]) => ({
+        id,
+        label: camera.name || id,
+        nativeId: camera.uuid,
+      })),
+      activeCameraId: top?.state?.targetKey ?? null,
+      activeControllerId: top?.ownerId ?? null,
+      ownershipDepth: stack.length,
+      transition: transitionSnapshot(top),
+    };
+  }
 
   function requireNotDisposed(action: string): void {
     if (disposed) {
@@ -372,6 +415,7 @@ export function createCameraOwnershipSystem(
 
     frame.state = {
       targetKey: cameraKey,
+      fromTargetKey: frame.state?.targetKey ?? null,
       fromPose: capturePose(liveCamera),
       startTime: clock.time,
       durationSeconds,
@@ -384,6 +428,8 @@ export function createCameraOwnershipSystem(
     // hook's own 'preRender'-phase call site, once more from this module's
     // later 'render'-phase evaluator).
     evaluateFrame(frame);
+    transitionWasVisible = transitionSnapshot(frame) !== null;
+    notify();
   }
 
   function releaseFrame(frame: OwnershipFrame, completed: boolean): void {
@@ -396,7 +442,12 @@ export function createCameraOwnershipSystem(
 
   const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
     const top = stack[stack.length - 1];
-    if (top) evaluateFrame(top);
+    if (top) {
+      evaluateFrame(top);
+      const transitionIsVisible = transitionSnapshot(top) !== null;
+      if (transitionIsVisible || transitionWasVisible) notify();
+      transitionWasVisible = transitionIsVisible;
+    }
   });
 
   return {
@@ -414,6 +465,7 @@ export function createCameraOwnershipSystem(
         restorePose: capturePose(liveCamera),
         state: undefined,
       });
+      notify();
     },
 
     cut(ownerId, cameraKey) {
@@ -442,6 +494,8 @@ export function createCameraOwnershipSystem(
       const top = requireTopOwner(ownerId, 'release');
       stack.pop();
       releaseFrame(top, releaseOptions.completed ?? false);
+      transitionWasVisible = false;
+      notify();
     },
 
     isOwner(ownerId) {
@@ -453,6 +507,14 @@ export function createCameraOwnershipSystem(
       return stack.length;
     },
 
+    snapshot,
+
+    subscribe(listener) {
+      if (disposed) return () => undefined;
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
     dispose() {
       if (disposed) return;
       disposed = true;
@@ -460,7 +522,10 @@ export function createCameraOwnershipSystem(
         const top = stack.pop();
         if (top) releaseFrame(top, false);
       }
+      transitionWasVisible = false;
       handle.dispose();
+      notify();
+      listeners.clear();
     },
   };
 }

package/src/animation/runtime-inspection.ts

@@ -0,0 +1,104 @@
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+/**
+ * Live native animation playback for editor tools. Runtime state is read-only;
+ * an edit-time subject may additionally publish transient preview transport.
+ * This is instrumentation, not an animation asset or graph format.
+ */
+export interface AnimationRuntimeInspection {
+  readonly mixer: THREE.AnimationMixer;
+  readonly clips: ReadonlyMap<string, THREE.AnimationClip>;
+  readonly getSnapshot: () => AnimationRuntimeSnapshot;
+  readonly previewTransport?: AnimationPreviewTransport;
+}
+
+/**
+ * Optional controls for an isolated Asset Lab preview clock. A live gameplay
+ * runtime deliberately omits this: the editor may observe live playback, but
+ * it must not pause or seek the game through an animation inspector.
+ */
+export interface AnimationPreviewTransport {
+  readonly getSnapshot: () => AnimationPreviewTransportSnapshot;
+  readonly setPlaying: (playing: boolean) => void;
+  readonly setLoop: (loop: boolean) => void;
+  readonly setSpeed: (speed: number) => void;
+  readonly seek: (time: number) => void;
+  /** Select a source clip for isolated preview; `null` resumes controller output. */
+  readonly setClip: (name: string | null) => void;
+}
+
+export interface AnimationPreviewTransportSnapshot {
+  readonly clip: string;
+  readonly time: number;
+  readonly playing: boolean;
+  readonly loop: boolean;
+  readonly speed: number;
+  readonly mode: 'controller' | 'clip';
+}
+
+export interface AnimationRuntimeSnapshot {
+  readonly layers: readonly AnimationRuntimeLayer[];
+}
+
+export interface AnimationRuntimeLayer {
+  readonly id: string;
+  readonly state?: string;
+  readonly weight: number;
+  readonly blendMode: 'override' | 'additive';
+  readonly boneMask?: {
+    readonly include?: readonly string[] | undefined;
+    readonly exclude?: readonly string[] | undefined;
+  };
+  readonly actions: readonly AnimationRuntimeAction[];
+  readonly blendSpace?: AnimationRuntimeBlendSpace;
+}
+
+export interface AnimationRuntimeAction {
+  readonly name: string;
+  readonly clip: THREE.AnimationClip;
+  readonly action: THREE.AnimationAction;
+}
+
+export interface AnimationRuntimeBlendSpace {
+  readonly type: '1D' | '2D' | 'direct';
+  readonly parameter: string;
+  readonly parameterY?: string;
+  readonly values: ReadonlyMap<string, number | boolean>;
+  readonly samples: readonly {
+    readonly clip: string;
+    readonly x: number;
+    readonly y?: number;
+    readonly weight: number;
+  }[];
+}
+
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeAnimationRuntimeInspections(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function animationRuntimeInspectionsVersion(): number {
+  return version;
+}
+
+export function attachAnimationRuntimeInspection(
+  owner: THREE.Object3D,
+  inspection: AnimationRuntimeInspection,
+): () => void {
+  setUserData(owner, '_animationRuntime', inspection);
+  notify();
+  return () => {
+    if (getUserData(owner, '_animationRuntime') !== inspection) return;
+    deleteUserData(owner, '_animationRuntime');
+    notify();
+  };
+}

package/src/animation/xstate-animation-binding.ts

@@ -4,6 +4,7 @@ import type { createSystemRunner } from '../core/system-runner';
 import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
 import type { BlendTreeDef } from './anim-graph-types';
 import { evaluateBlendTree } from './blend-node';
+import { attachAnimationRuntimeInspection } from './runtime-inspection';
 import {
   type AnimationBoneMask,
   type AnimationMetaStateNodeLike,
@@ -125,6 +126,10 @@ export interface XStateAnimationBinding {
   /** Advance native actions/mixer. Register this in the engine animation phase. */
   tick: (dt: number) => void;
   readonly actor: XStateAnimationActor;
+  /** Live numeric/boolean values after the binding's optional parameter selector.
+   *  This is the exact parameter surface used by blend evaluation, exposed so
+   *  editor instrumentation never guesses by reading actor context directly. */
+  getParameters: () => ReadonlyMap<string, number | boolean>;
   /** Current native composition, useful to the editor and game diagnostics. */
   getActiveLayers: () => readonly XStateAnimationLayerState[];
   /** Unsubscribe, stop/uncache actions, and remove owner inspection data. Idempotent. */
@@ -245,7 +250,11 @@ function dominantOf(weights: WeightedClip[]): WeightedClip {
 }
 
 /**
- * Bind a native XState actor to native Three actions.
+ * Optional integration that maps a native XState actor to native Three
+ * actions. XState remains a behavior primitive; this bridge is useful when a
+ * project deliberately chooses to let one behavior statechart emit animation
+ * policy, but it is not the engine's animation model. Animation inspection is
+ * published separately through `AnimationRuntimeInspection`.
  *
  * One active animated state is allowed per named layer. Parallel XState
  * regions therefore compose lower-body locomotion, upper-body weapon states,
@@ -358,6 +367,7 @@ export function bindXStateAnimation(
 
   const activeLayers = new Map<string, ActiveState>();
   let disposed = false;
+  let detachRuntimeInspection = () => {};
 
   function silence(weights: WeightedClip[], except: string | undefined, duration: number): void {
     for (const weighted of weights) {
@@ -475,6 +485,7 @@ export function bindXStateAnimation(
   const binding: XStateAnimationBinding = {
     tick,
     actor,
+    getParameters: () => readParameters(actor.getSnapshot().context),
     getActiveLayers: () =>
       [...activeLayers.values()].map((active) => ({
         layer: active.layer,
@@ -491,6 +502,7 @@ export function bindXStateAnimation(
     dispose(): void {
       if (disposed) return;
       disposed = true;
+      detachRuntimeInspection();
       options.systems?.remove('animation', tick);
       subscription.unsubscribe();
       for (const { action, clip } of actionCache.values()) {
@@ -505,6 +517,46 @@ export function bindXStateAnimation(
       }
     },
   };
+  detachRuntimeInspection = attachAnimationRuntimeInspection(owner, {
+    mixer,
+    clips,
+    getSnapshot: () => ({
+      layers: [...activeLayers.values()].map((active) => {
+        const parameters = readParameters(actor.getSnapshot().context);
+        const blendSpace = isBlendTreeAnimationMeta(active.meta)
+          ? {
+              type: active.meta.blendTree.type,
+              parameter: active.meta.blendTree.parameter,
+              ...(active.meta.blendTree.type === '2D'
+                ? { parameterY: active.meta.blendTree.parameterY }
+                : {}),
+              values: parameters,
+              samples: active.meta.blendTree.children.map((child) => ({
+                clip: child.clip,
+                x: child.threshold,
+                ...(child.thresholdY === undefined ? {} : { y: child.thresholdY }),
+                weight:
+                  actionCache
+                    .get(actionKey(active.stateId, active.meta, child.clip))
+                    ?.action.getEffectiveWeight() ?? 0,
+              })),
+            }
+          : undefined;
+        return {
+          id: active.layer,
+          state: active.stateId,
+          weight: layerWeightOf(active.meta),
+          blendMode: blendModeOf(active.meta),
+          ...(active.meta.boneMask ? { boneMask: active.meta.boneMask } : {}),
+          actions: active.natural.map((weighted) => {
+            const cached = actionCache.get(weighted.actionKey)!;
+            return { name: weighted.clip, clip: cached.clip, action: cached.action };
+          }),
+          ...(blendSpace ? { blendSpace } : {}),
+        };
+      }),
+    }),
+  });
   setUserData(owner, '_xstateAnimation', binding);
   notifyInspectionLifecycle();
   options.systems?.add('animation', tick);

package/src/asset-formats/particles.ts

@@ -290,11 +290,42 @@ export const RenderModeSchema = z
 
 // --- Particle Material (our format — asset paths, not Three.js UUIDs) ---
 
+/**
+ * The sprite `map`'s SAMPLER — how the image is addressed outside [0,1], interpolated, and
+ * mip-chained. Separate from the URL because two emitters can name one image and want different
+ * sampling of it; the factory caches per URL *and* sampler for exactly that reason.
+ *
+ * An absent field leaves three's own default alone (clamp-to-edge, linear, mipmapped, anisotropy
+ * 1) rather than restating it — the same "absent means the loader's default" contract the rest of
+ * this descriptor keeps. `map`'s COLOUR SPACE is deliberately not here: a `map` is always a colour
+ * texture, so the factory states sRGB unconditionally (see `particles-factory.ts`).
+ */
+const ParticleMapSamplerSchema = z
+  .object({
+    wrap: z
+      .enum(['clamp', 'repeat', 'mirror'])
+      .optional()
+      .describe('How UVs outside [0,1] address the sprite image (three wrapS/wrapT)'),
+    filter: z
+      .enum(['linear', 'nearest'])
+      .optional()
+      .describe('Texel interpolation — nearest keeps a pixel-art sprite crisp'),
+    mipmaps: z.boolean().optional().describe('Generate and sample a mip chain'),
+    anisotropy: z
+      .number()
+      .optional()
+      .describe('Anisotropic filtering samples, for sprites viewed at grazing angles'),
+  })
+  .describe('Sprite texture sampler state');
+
 const ParticleMaterialSchema = z
   .object({
     type: z.enum(['basic', 'standard']).optional().describe('Particle material shading model'),
     color: z.string().optional().describe('Particle color as CSS hex string'),
     map: z.string().optional().describe('Path to particle sprite texture'),
+    mapSampler: ParticleMapSamplerSchema.optional().describe(
+      'Sampler state applied to the sprite texture named by `map`',
+    ),
     blending: z
       .enum(['normal', 'additive'])
       .optional()