@directivegames/genesys.js 3.1.24

package/src/components/visual/AnimationStateMachineComponent.ts

@@ -0,0 +1,1079 @@
+/**
+ * AnimationStateMachineComponent manages complex animation transitions.
+ *
+ * It loads animation clips from GLTF sources and orchestrates state-based
+ * playback with parameter-driven transitions. The component keeps a map of
+ * parameters that can be modified at runtime to influence which state is active
+ * and how clips blend. External animation sources may be loaded dynamically,
+ * and one-shot animations can temporarily override the current state.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Define states and transitions in JSON or code and pass via options.
+ * - Update parameters with `setParameter` to trigger transitions.
+ * - Use for characters requiring contextual movement such as walking, jumping,
+ *   or reacting to gameplay events.
+ */
+import * as THREE from 'three';
+
+import { AnimationClipCache } from '../../animation/AnimationClipCache.js';
+import {
+  addSyntheticRootBone,
+  needsSyntheticRoot,
+  retargetAnimationClips
+} from '../../animation/AnimationRetargeting.js';
+import { AssetPath } from '../../storage/storageProvider.js';
+import { EngineClass } from '../../systems/ClassRegistry.js';
+import { AsyncTaskWorker, IAsyncLoadableTag } from '../../utils/IAsyncLoadable.js';
+import { resourceManager } from '../../utils/ResourceManager.js';
+import { SceneComponent } from '../SceneComponent.js';
+
+import { GLTFMeshComponent } from './GLTFMeshComponent.js';
+
+import type { SkeletonProfile } from '../../animation/SkeletonProfile.js';
+import type { IAsyncLoadable } from '../../utils/IAsyncLoadable.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+
+export type ParameterMap = { [key: string]: number | boolean | string };
+
+export interface AnimationStateTransition {
+  to: string;
+  /**
+   * Data-driven condition: all key-value pairs must match parameters for the transition to trigger.
+   * Supports natural language operators for numbers/strings/booleans:
+   *   { speed: { greaterThan: 0.5 }, health: { lessThanOrEqual: 0 }, state: { notEqualTo: 'dead' } }
+   *   { isJumping: { equalTo: true } }
+   *   { isRunning: true } // primitive for equality
+   *   { clipFinished: true } // triggers when the current state's clip finishes
+   */
+  condition: {
+    [key: string]: number | boolean | string | {
+      greaterThan?: number;
+      greaterThanOrEqual?: number;
+      lessThan?: number;
+      lessThanOrEqual?: number;
+      equalTo?: number | boolean | string;
+      notEqualTo?: number | boolean | string;
+    }
+  };
+  blendDuration?: number;
+}
+
+export interface AnimationState {
+  /** Single animation clip or a blend of multiple clips */
+  clip?: string | string[];
+  /**
+   * Blend array: each entry can specify a static weight, or map to a parameter.
+   * Example:
+   *   blend: [
+   *     { clip: 'Run', weightParam: 'runWeight' },
+   *     { clip: 'StrafeRight', weightParam: 'right' },
+   *     { clip: 'StrafeLeft', weight: 0.2 }
+   *   ]
+   */
+  blend?: Array<{
+    clip: string;
+    weight?: number;
+    weightParam?: string;
+    reversed?: boolean;
+  }>;
+  transitions: AnimationStateTransition[];
+}
+
+export interface AnimationClipOptions {
+  loop?: 'LoopOnce' | 'LoopRepeat' | 'LoopPingPong'; // Use string values in config/JSON
+  clampWhenFinished?: boolean;
+  blendMode?: 'NormalAnimationBlendMode' | 'AdditiveAnimationBlendMode'; // Use string values in config/JSON
+}
+
+/**
+ * Configuration for external animation sources with optional retargeting.
+ */
+export interface ExternalAnimationSource {
+  /** URL to the GLTF file containing animations */
+  url: string;
+  /** Skeleton profile URL or name for the skeleton profile of the animations (required for retargeting) */
+  skeletonProfile?: string;
+}
+
+export interface AnimationStateMachineConfig {
+  /** Whether to autoplay the default animation on beginPlay */
+  autoPlay?: boolean;
+  /** Optional initial animation parameters */
+  parameters?: { [key: string]: number | boolean | string };
+  /** Animation state machine definition */
+  states?: { [stateName: string]: AnimationState };
+  /** Initial state name */
+  initialState: string;
+  /** Optional per-clip options, e.g., loop: false */
+  clipOptions?: { [clipName: string]: AnimationClipOptions };
+  /** List of one-shot animation clip names */
+  oneShotClips?: string[];
+  /**
+   * Optional global transitions that apply from any state.
+   * Use the reserved key '__any__'.
+   * Example:
+   *   "states": {
+   *     "__any__": { "transitions": [ ... ] },
+   *     ...
+   *   }
+   */
+  externalAnimationSources?: Array<string | ExternalAnimationSource>;
+  /**
+   * Skeleton profile URL or name for the target character (required for retargeting).
+   * If not specified, external animations are used as-is without retargeting.
+   */
+  targetSkeletonProfile?: string;
+}
+
+export interface AnimationStateMachineOptions extends SceneComponentOptions {
+  /** URL to the animation state machine configuration file */
+  configUrl: string;
+}
+
+@EngineClass('AnimationStateMachineComponent')
+export class AnimationStateMachineComponent extends SceneComponent<AnimationStateMachineOptions> implements IAsyncLoadable {
+  readonly [IAsyncLoadableTag] = true;
+
+  private mixer: THREE.AnimationMixer | null = null;
+  private actions: Map<string, THREE.AnimationAction> = new Map();
+  private gltfComponent: GLTFMeshComponent | null = null;
+  private parameters: Map<string, number | boolean | string> = new Map();
+  private currentState: string | null = null;
+  private stateTime: number = 0;
+  private states: Record<string, AnimationState> = {};
+  private clipOptions: { [clipName: string]: AnimationClipOptions } = {};
+  private oneShotClips: Set<string> = new Set();
+  private isOneShotPlaying: boolean = false;
+  private oneShotPrevState: string | null = null;
+  private oneShotResolve: (() => void) | null = null;
+  private oneShotCurrentClip: string | null = null;
+  private oneShotFreezeOnLastFrame: boolean = false;
+  private clipFinishedFlag: boolean = false;
+  private externalAnimationSources: Array<string | ExternalAnimationSource> = [];
+  private targetSkeletonProfile: SkeletonProfile | null = null;
+  private config: AnimationStateMachineConfig | null = null;
+  private enabled: boolean = true;
+  private isInitialized: boolean = false;
+  private _asyncTaskWorker = new AsyncTaskWorker();
+
+  constructor(options: AnimationStateMachineOptions) {
+    super(options);
+  }
+
+  private async _loadAnim(): Promise<void> {
+    // Load animation config from ResourceManager
+    const configPath = new AssetPath(this.options.configUrl);
+    this.config = await resourceManager.loadJsonObject(configPath);
+    if (!this.config) {
+      console.error(`AnimationStateMachineComponent: Failed to load animation config from ${this.options.configUrl}`);
+      return;
+    }
+
+    // Initialize component state from loaded config
+    if (this.config.parameters) {
+      for (const [key, value] of Object.entries(this.config.parameters)) {
+        this.parameters.set(key, value);
+      }
+    }
+    if (this.config.states) {
+      this.states = this.config.states;
+    }
+    if (this.config.initialState) {
+      this.currentState = this.config.initialState;
+    }
+    if (this.config.clipOptions) {
+      this.clipOptions = this.config.clipOptions;
+    }
+    if (this.config.oneShotClips) {
+      this.oneShotClips = new Set(this.config.oneShotClips);
+    }
+    if (this.config.externalAnimationSources) {
+      this.externalAnimationSources = this.config.externalAnimationSources;
+    }
+
+    this.gltfComponent = this.getActor()?.getComponent(GLTFMeshComponent) ?? null;
+    if (!this.gltfComponent) {
+      console.error('AnimationStateMachineComponent: No GLTFMeshComponent found in actor.');
+    }
+
+    // Load target skeleton profile if retargeting is enabled
+    if (this.config.targetSkeletonProfile) {
+      try {
+        const profilePath = new AssetPath(this.config.targetSkeletonProfile);
+        this.targetSkeletonProfile = await resourceManager.loadJsonObject(profilePath);
+        if (!this.targetSkeletonProfile) {
+          console.error(`AnimationStateMachineComponent: Failed to load target skeleton profile from ${this.config.targetSkeletonProfile}`);
+        }
+      } catch (e) {
+        console.error('AnimationStateMachineComponent: Failed to load target skeleton profile:', e);
+      }
+    }
+
+    // Load external animation sources - but only after the GLTF is loaded
+    // This will be handled in setupAnimations() when the GLTF mesh is ready
+
+    if (this.gltfComponent) {
+      this.gltfComponent.onMeshLoaded.add((meshComponent, mesh) => {
+        this._asyncTaskWorker.runTask(async () => { await this.setupAnimations(); });
+      });
+      if (this.gltfComponent.isModelLoaded()) {
+        await this.setupAnimations();
+      }
+    } else {
+      // No GLTF component found, mark as initialized since setup is complete
+      this.isInitialized = true;
+    }
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+
+    // Reset initialization state
+    this.isInitialized = false;
+
+    this._asyncTaskWorker.runTask(async () => { await this._loadAnim(); });
+  }
+
+  // start IAsyncLoadable implementation
+  public async waitForLoad(): Promise<void> {
+    await this._asyncTaskWorker.waitUntilComplete();
+  }
+
+  public isLoading(): boolean {
+    return this._asyncTaskWorker.isRunning();
+  }
+  // end IAsyncLoadable implementation
+
+  /**
+   * Load external animation sources with optional retargeting.
+   */
+  private async loadExternalAnimationSources(): Promise<void> {
+    if (!this.gltfComponent) {
+      console.error('AnimationStateMachineComponent: Cannot load external animations without GLTFMeshComponent');
+      return;
+    }
+
+    // Get target skeleton if retargeting is enabled
+    const targetSkinnedMeshData = this.targetSkeletonProfile ? this.gltfComponent.getSkinnedMeshData() : null;
+    const targetSkeleton = targetSkinnedMeshData?.skeleton ?? null;
+    const targetSkinnedMesh = targetSkinnedMeshData?.skinnedMesh ?? null;
+
+    if (this.targetSkeletonProfile && (!targetSkeleton || !targetSkinnedMesh)) {
+      console.error('AnimationStateMachineComponent: Target skeleton profile specified but no skinned mesh found on target character');
+      return;
+    }
+
+    await Promise.all(this.externalAnimationSources.map(async (sourceConfig) => {
+      try {
+        // Parse source config (can be string URL or object with profile)
+        const sourceUrl = typeof sourceConfig === 'string' ? sourceConfig : sourceConfig.url;
+        const sourceProfileUrl = typeof sourceConfig === 'string' ? null : sourceConfig.skeletonProfile;
+
+        // Load the source GLTF
+        const modelPath = new AssetPath(sourceUrl);
+        const gltf = await resourceManager.loadModel(modelPath);
+        if (!gltf || !gltf.animations || gltf.animations.length === 0) {
+          console.warn(`AnimationStateMachineComponent: No animations found in ${sourceUrl}`);
+          return;
+        }
+
+        // If retargeting is enabled, load source profile and retarget
+        if (this.targetSkeletonProfile && sourceProfileUrl && targetSkeleton && targetSkinnedMesh) {
+          // Load source skeleton profile
+          const sourceProfilePath = new AssetPath(sourceProfileUrl);
+          const sourceProfile: SkeletonProfile | null = await resourceManager.loadJsonObject(sourceProfilePath);
+
+          if (!sourceProfile) {
+            console.error(`AnimationStateMachineComponent: Failed to load source profile from ${sourceProfileUrl}`);
+            return;
+          }
+
+          // Check if source and target profiles are the same - if so, skip retargeting
+          if (sourceProfile.name === this.targetSkeletonProfile.name) {
+            console.log(`AnimationStateMachineComponent: Source and target use same profile "${sourceProfile.name}", skipping retargeting for ${gltf.animations.length} clips from ${sourceUrl}`);
+            for (const clip of gltf.animations) {
+              AnimationClipCache.instance.addClip(clip);
+            }
+            return;
+          }
+
+          // Get source skeleton from the GLTF
+          const sourceScene = gltf.scene;
+          let sourceSkinnedMesh: THREE.SkinnedMesh | undefined;
+          sourceScene.traverse((node) => {
+            if (node instanceof THREE.SkinnedMesh && node.skeleton && !sourceSkinnedMesh) {
+              sourceSkinnedMesh = node as THREE.SkinnedMesh;
+            }
+          });
+
+          if (!sourceSkinnedMesh || !sourceSkinnedMesh.skeleton) {
+            console.error(`AnimationStateMachineComponent: No skeleton found in source GLTF ${sourceUrl}`);
+            return;
+          }
+
+          const sourceSkeleton = sourceSkinnedMesh.skeleton;
+
+          // Check if target needs a synthetic root bone (source has root, target doesn't)
+          let effectiveTargetProfile = this.targetSkeletonProfile;
+          let effectiveTargetSkeleton = targetSkeleton;
+
+          if (needsSyntheticRoot(sourceProfile, this.targetSkeletonProfile)) {
+            console.log(`AnimationStateMachineComponent: Adding synthetic root bone to target skeleton for retargeting from ${sourceUrl}`);
+            const syntheticResult = addSyntheticRootBone(
+              targetSkeleton,
+              targetSkinnedMesh,
+              this.targetSkeletonProfile
+            );
+            effectiveTargetSkeleton = syntheticResult.skeleton;
+            effectiveTargetProfile = syntheticResult.updatedProfile;
+          }
+
+          // Retarget all clips
+          const results = retargetAnimationClips(
+            gltf.animations,
+            sourceProfile,
+            effectiveTargetProfile,
+            sourceSkeleton,
+            effectiveTargetSkeleton,
+            targetSkinnedMesh
+          );
+
+          // Add successfully retargeted clips to cache
+          let successCount = 0;
+          for (const result of results) {
+            if (result.success && result.clip) {
+              AnimationClipCache.instance.addClip(result.clip);
+              successCount++;
+            } else {
+              console.warn(`AnimationStateMachineComponent: Failed to retarget clip "${result.originalName}" from ${sourceUrl}`);
+            }
+          }
+
+          console.log(`AnimationStateMachineComponent: Retargeted ${successCount}/${gltf.animations.length} clips from ${sourceUrl}`);
+        } else {
+          // No retargeting - add clips as-is
+          for (const clip of gltf.animations) {
+            AnimationClipCache.instance.addClip(clip);
+          }
+          console.log(`AnimationStateMachineComponent: Loaded ${gltf.animations.length} clips from ${sourceUrl} (no retargeting)`);
+        }
+      } catch (e) {
+        const sourceUrl = typeof sourceConfig === 'string' ? sourceConfig : sourceConfig.url;
+        console.error(`AnimationStateMachineComponent: Failed to load external animation source: ${sourceUrl}`, e);
+      }
+    }));
+  }
+
+  private addAnimation(clip: THREE.AnimationClip, animationNameOverride?: string): THREE.AnimationAction {
+    const loopMap = {
+      LoopOnce: THREE.LoopOnce,
+      LoopRepeat: THREE.LoopRepeat,
+      LoopPingPong: THREE.LoopPingPong,
+    } as const;
+    const blendModeMap = {
+      NormalAnimationBlendMode: THREE.NormalAnimationBlendMode,
+      AdditiveAnimationBlendMode: THREE.AdditiveAnimationBlendMode,
+    } as const;
+
+    let processedClip = clip;
+
+    // Filter tracks if a GLTF component and model are available
+    if (this.gltfComponent && this.gltfComponent.getModel()) {
+      const model = this.gltfComponent.getModel();
+      if (model) {
+        const validNodeNames = new Set<string>();
+        model.traverse((node) => {
+          validNodeNames.add(node.name);
+        });
+
+        const originalTracks = processedClip.tracks;
+        const filteredTracks: THREE.KeyframeTrack[] = [];
+        let tracksWereFiltered = false;
+
+        for (const track of originalTracks) {
+          // Extract the base node name (e.g., "mixamorigRightHand" from "mixamorigRightHand.position")
+          const nodeName = track.name.split('.')[0];
+          if (validNodeNames.has(nodeName)) {
+            filteredTracks.push(track);
+          } else {
+            // console.log(`AnimationStateMachine: Filtering out track for missing node '${nodeName}' in clip '${processedClip.name}'`);
+            tracksWereFiltered = true;
+          }
+        }
+
+        if (tracksWereFiltered) {
+          // console.log(`AnimationStateMachine: Clip '${processedClip.name}' had ${originalTracks.length - filteredTracks.length} tracks removed.`);
+          processedClip = new THREE.AnimationClip(
+            processedClip.name,
+            processedClip.duration,
+            filteredTracks,
+            processedClip.blendMode
+          );
+        }
+      }
+    }
+
+    const action = this.mixer!.clipAction(processedClip);
+    // Apply user-defined options for this clip
+    const opts = this.clipOptions[processedClip.name]; // Use processedClip.name in case it was recreated
+    if (opts) {
+      if (opts.loop) {
+        const loopType = loopMap[opts.loop];
+        if (loopType !== undefined) {
+          action.setLoop(loopType, Infinity);
+        }
+      }
+      if (opts.clampWhenFinished) {
+        action.clampWhenFinished = opts.clampWhenFinished;
+      }
+      if (opts.blendMode) {
+        const blendMode = blendModeMap[opts.blendMode];
+        if (blendMode !== undefined) {
+          action.blendMode = blendMode;
+        }
+      }
+    }
+    this.actions.set(animationNameOverride ?? processedClip.name, action);
+    return action;
+  }
+
+  private async setupAnimations(): Promise<void> {
+    if (!this.gltfComponent) return;
+    if (this.isInitialized) return; // Already initialized, avoid duplicate setup
+
+    const model = this.gltfComponent.getModel();
+    const clips = this.gltfComponent.getAnimations();
+
+    if (model) {
+      // Load external animation sources now that the GLTF is ready
+      if (this.externalAnimationSources.length > 0) {
+        await this.loadExternalAnimationSources();
+      }
+
+      // Create mixer on the model root (the GLTF scene Group)
+      this.mixer = new THREE.AnimationMixer(model);
+      this.actions.clear();
+
+      // Get all unique clip names from the state machine definition
+      const stateClipNames = new Set<string>();
+      for (const state of Object.values(this.states)) {
+        if (state.clip) {
+          if (typeof state.clip === 'string') {
+            stateClipNames.add(state.clip);
+          } else if (Array.isArray(state.clip)) {
+            state.clip.forEach(name => stateClipNames.add(name));
+          }
+        }
+        if (state.blend) {
+          state.blend.forEach(b => stateClipNames.add(b.clip));
+        }
+      }
+
+      // Add one-shot clips to the set
+      for (const oneShotClipName of this.oneShotClips) {
+        stateClipNames.add(oneShotClipName);
+      }
+
+      // First, add all original model animations to the cache
+      for (const clip of clips) {
+        if (!AnimationClipCache.instance.hasClip(clip.name)) {
+          AnimationClipCache.instance.addClip(clip);
+        }
+      }
+
+      // Load clips for states first: try cache, then model animations
+      for (const clipName of stateClipNames) {
+        let clip = AnimationClipCache.instance.getClip(clipName);
+        if (!clip) {
+          clip = clips.find(c => c.name === clipName);
+          if (clip) {
+            AnimationClipCache.instance.addClip(clip);
+          }
+        }
+        if (clip) {
+          this.addAnimation(clip);
+        } else {
+          console.warn(`AnimationStateMachineComponent: Clip '${clipName}' not found in cache or model.`);
+        }
+      }
+
+      // Also create actions for ALL clips from the cache (original + retargeted)
+      // This allows external systems to access all animations
+      const allCachedClips = AnimationClipCache.instance.getClipNames();
+      for (const clipName of allCachedClips) {
+        if (!this.actions.has(clipName)) {
+          const clip = AnimationClipCache.instance.getClip(clipName);
+          if (clip) {
+            this.addAnimation(clip);
+          }
+        }
+      }
+
+      // Now that animations are set up, play initial state and mark as initialized
+      this.playInitialState();
+      this.isInitialized = true;
+    }
+  }
+
+  private playInitialState(): void {
+    // Play initial state
+    if (this.currentState && this.states[this.currentState]) {
+      const state = this.states[this.currentState] as AnimationState;
+      if (state.clip) {
+        let clipToPlay: string | undefined = undefined;
+        if (typeof state.clip === 'string') {
+          clipToPlay = state.clip;
+        } else if (Array.isArray(state.clip)) {
+          if (state.clip.length > 0) {
+            const idx = Math.floor(Math.random() * state.clip.length);
+            const candidate = state.clip[idx];
+            if (typeof candidate === 'string') {
+              clipToPlay = candidate;
+            }
+          }
+        }
+        if (typeof clipToPlay === 'string') {
+          this.play(clipToPlay);
+        }
+      }
+      this.stateTime = 0;
+    }
+  }
+
+  private play(clip?: string, blendDuration: number = 0.3): void {
+    if (!this.mixer) return;
+    if (!clip) return;
+    const action = this.actions.get(clip);
+    if (action) {
+      // Find the currently playing action (if any)
+      const prevAction = this.getActiveActions()[0];
+      if (prevAction && prevAction !== action) {
+        prevAction.crossFadeTo(action, blendDuration, false);
+      }
+      action.reset().play();
+      // Listen for finished event to set the flag
+      action.getMixer().addEventListener('finished', this._onClipFinished);
+    }
+  }
+
+  /**
+   * Set one or more animation parameters. If called with (key, value), sets a single parameter.
+   * If called with an object, sets multiple parameters at once and only evaluates the state machine once.
+   *
+   * If the component is not yet initialized, parameters will be stored and applied once initialization completes.
+   */
+  public setParameter(key: string | Record<string, number | boolean | string>, value?: number | boolean | string): void {
+    // Skip parameter updates if disabled
+    if (!this.enabled) {
+      return;
+    }
+
+    // If not initialized yet, warn and ignore parameter changes
+    if (!this.isInitialized) {
+      if (typeof key === 'object' && key !== null) {
+        const keys = Object.keys(key).join(', ');
+        console.warn(`AnimationStateMachineComponent not yet initialized. Ignoring setParameter call for: ${keys}`);
+      } else if (typeof key === 'string') {
+        console.warn(`AnimationStateMachineComponent not yet initialized. Ignoring setParameter call for: ${key}`);
+      }
+      return;
+    }
+
+    if (typeof key === 'object' && key !== null) {
+      for (const [k, v] of Object.entries(key)) {
+        if (!this.parameters.has(k)) {
+          console.error(`Parameter '${k}' does not exist in AnimationStateMachineComponent.`);
+          continue;
+        }
+        this.parameters.set(k, v);
+      }
+      this.evaluateStateMachine();
+    } else if (typeof key === 'string') {
+      if (!this.parameters.has(key)) {
+        console.error(`Parameter '${key}' does not exist in AnimationStateMachineComponent.`);
+        return;
+      }
+      this.parameters.set(key, value as number | boolean | string);
+      this.evaluateStateMachine();
+    }
+  }
+
+  /**
+   * Get an animation parameter
+   */
+  public getParameter(key: string): number | boolean | string {
+    if (!this.parameters.has(key)) {
+      if (!this.isInitialized) {
+        throw new Error(`AnimationStateMachineComponent not yet initialized. Cannot get parameter '${key}'.`);
+      }
+      throw new Error(`Parameter '${key}' does not exist in AnimationStateMachineComponent.`);
+    }
+    return this.parameters.get(key)!;
+  }
+
+  /**
+   * Get all parameters as a plain object
+   */
+  public getAllParameters(): ParameterMap {
+    return Object.fromEntries(this.parameters.entries());
+  }
+
+  /**
+   * Check if a parameter exists
+   */
+  public hasParameter(key: string): boolean {
+    return this.parameters.has(key);
+  }
+
+  /**
+   * Force the state machine to a specific state
+   */
+  public transitionToState(state: string): void {
+    if (!this.states[state]) return;
+    if (this.currentState === state) return; // Guard: don't re-enter the same state
+
+    // Fade out actions of the previous state before setting the new state
+    if (this.currentState && this.states[this.currentState]) {
+      const prevState = this.states[this.currentState];
+      let prevActionNames: string[] = [];
+      if (prevState.blend && prevState.blend.length > 0) {
+        prevActionNames = prevState.blend.map(b => b.reversed ? `${b.clip}#Reversed` : b.clip);
+      } else if (prevState.clip) {
+        if (typeof prevState.clip === 'string') {
+          prevActionNames = [prevState.clip];
+        } else if (Array.isArray(prevState.clip)) {
+          prevActionNames = prevState.clip;
+        }
+      }
+      // Fade out only the actions of the previous state
+      for (const name of prevActionNames) {
+        const action = this.actions.get(name);
+        if (action && action.isRunning()) {
+          action.fadeOut(0.3); // Use default blend duration for fade out
+        }
+      }
+    }
+
+    this.currentState = state;
+    this.stateTime = 0;
+
+    // Find the transition to this state to get the blendDuration
+    let blendDuration = 0.3;
+    if (this.currentState && this.states) {
+      const prevState = this.states[this.currentState];
+      if (prevState && prevState.transitions) {
+        const transition = prevState.transitions.find(t => t.to === state);
+        if (transition && typeof transition.blendDuration === 'number') {
+          blendDuration = transition.blendDuration;
+        }
+      }
+    }
+
+    // Play or blend to the new state's animation(s)
+    const newState = this.states[state];
+    if (newState.blend && newState.blend.length > 0) {
+      this.updateBlendWeights(newState.blend);
+    } else if (newState.clip) {
+      let clipToPlay: string | undefined = undefined;
+      if (typeof newState.clip === 'string') {
+        clipToPlay = newState.clip;
+      } else if (Array.isArray(newState.clip)) {
+        if (newState.clip.length > 0) {
+          const idx = Math.floor(Math.random() * newState.clip.length);
+          const candidate = newState.clip[idx];
+          if (typeof candidate === 'string') {
+            clipToPlay = candidate;
+          }
+        }
+      }
+      if (typeof clipToPlay === 'string') {
+        this.play(clipToPlay, blendDuration);
+      }
+    }
+  }
+
+  /**
+   * Blend to a set of animation clips with given weights (static or parameter-mapped)
+   */
+  private updateBlendWeights(blend: Array<{ clip: string; weight?: number; weightParam?: string; reversed?: boolean }>): void {
+    if (!this.mixer) return;
+    const animationNames: string[] = [];
+    // Start and set weights for blend actions
+    blend.forEach(({ clip, weight, weightParam, reversed }) => {
+      reversed ??= false;
+      const animationName = reversed ? `${clip}#Reversed` : clip;
+      let action: THREE.AnimationAction | undefined;
+      if (typeof clip === 'string') {
+        action = this.actions.get(animationName);
+        if (!action) {
+          const clips = this.gltfComponent?.getAnimations() ?? [];
+          const clipInstance = clips.find(c => c.name === clip);
+          if (clipInstance) {
+            action = this.addAnimation(clipInstance.clone(), animationName);
+            action.timeScale = reversed ? -1 : 1;
+          }
+        }
+      }
+      let w = weight ?? 0;
+      if (weightParam) {
+        const paramValue = this.getParameter(weightParam);
+        if (typeof paramValue === 'number') {
+          w = Math.max(0, Math.min(1, paramValue));
+        }
+      }
+      if (action) {
+        // reset the weights if this is the first time the action is seen
+        if (!animationNames.includes(animationName)) {
+          animationNames.push(animationName);
+          action.setEffectiveWeight(0);
+        }
+        // use accumulated weights in case the action is reused in the blend
+        w += action.getEffectiveWeight();
+        action.setEffectiveWeight(w);
+        action.enabled = true;
+        if (!action.isRunning()) {
+          action.play();
+        }
+      }
+    });
+  }
+
+  /**
+   * Check if the current parameters match the given condition object
+   * Supports operators: greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, equalTo, notEqualTo
+   */
+  private matchesCondition(condition: { [key: string]: any }): boolean {
+    // Special handling for clipFinished
+    if ('clipFinished' in condition) {
+      if (condition.clipFinished === true && this.clipFinishedFlag) {
+        return true;
+      } else if (condition.clipFinished === true && !this.clipFinishedFlag) {
+        return false;
+      }
+    }
+    for (const key in condition) {
+      const param = this.getParameter(key);
+      const cond = condition[key];
+      if (typeof cond === 'object' && cond !== null && !Array.isArray(cond)) {
+        if ('greaterThan' in cond && !(typeof param === 'number' && param > cond.greaterThan)) return false;
+        if ('greaterThanOrEqual' in cond && !(typeof param === 'number' && param >= cond.greaterThanOrEqual)) return false;
+        if ('lessThan' in cond && !(typeof param === 'number' && param < cond.lessThan)) return false;
+        if ('lessThanOrEqual' in cond && !(typeof param === 'number' && param <= cond.lessThanOrEqual)) return false;
+        if ('equalTo' in cond && !(param === cond.equalTo)) return false;
+        if ('notEqualTo' in cond && !(param !== cond.notEqualTo)) return false;
+      } else {
+        if (param !== cond) return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Evaluate the state machine and perform transitions if needed
+   */
+  private evaluateStateMachine(): void {
+    if (this.isOneShotPlaying) return; // Pause state machine during one-shot
+    if (!this.currentState || !this.states[this.currentState]) return;
+
+    // 1. Check global transitions (from '__any__') first
+    const globalState = this.states['__any__'];
+    if (globalState && globalState.transitions) {
+      for (const transition of globalState.transitions) {
+        if (this.matchesCondition(transition.condition)) {
+          this.transitionToState(transition.to);
+          this.clipFinishedFlag = false;
+          return;
+        }
+      }
+    }
+
+    // 2. Check current state's transitions
+    const state = this.states[this.currentState] as AnimationState;
+    for (const transition of state.transitions) {
+      if (this.matchesCondition(transition.condition)) {
+        this.transitionToState(transition.to);
+        this.clipFinishedFlag = false;
+        break;
+      }
+    }
+    // Reset the flag if not used
+    this.clipFinishedFlag = false;
+  }
+
+  /**
+   * Blend to a new animation clip over a given duration (in seconds)
+   */
+  public blendTo(clip: string, duration: number = 0.3): void {
+    if (!this.mixer) return;
+    let nextAction = this.actions.get(clip);
+    // Fade out all other actions instead of stopping them immediately
+    for (const [name, action] of this.actions.entries()) {
+      if (action !== nextAction) {
+        action.fadeOut(duration);
+      }
+    }
+    // Use local variables only, do not use this.currentAction
+    if (nextAction) {
+      nextAction.reset().play();
+    }
+  }
+
+  /**
+   * Called every frame after physics. Used to update state time and evaluate transitions.
+   */
+  public override tickPostPhysics(deltaTime: number): void {
+    super.tickPostPhysics(deltaTime);
+
+    // Skip animation processing if disabled
+    if (!this.enabled) {
+      return;
+    }
+
+    this.stateTime += deltaTime;
+    // Always update blend weights if in a blend state
+    if (this.currentState && this.states[this.currentState]?.blend) {
+      this.updateBlendWeights(this.states[this.currentState].blend!);
+    }
+    this.evaluateStateMachine();
+    if (this.mixer) {
+      this.mixer.update(deltaTime);
+    }
+  }
+
+  /**
+   * Sets whether the animation state machine is enabled
+   * When disabled, all animations are cleared and no further processing occurs
+   */
+  public setEnabled(enabled: boolean): void {
+    if (this.enabled === enabled) return;
+
+    this.enabled = enabled;
+
+    if (!enabled) {
+      this.clearAllAnimations();
+    }
+  }
+
+  /**
+   * Gets whether the animation state machine is enabled
+   */
+  public isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Gets whether the animation state machine has finished initializing
+   * (external animations loaded, parameters set up, and animations configured)
+   */
+  public isReady(): boolean {
+    return this.isInitialized;
+  }
+
+
+  /**
+   * Clears all currently playing animations
+   */
+  private clearAllAnimations(): void {
+    if (!this.mixer) return;
+
+    // Stop and fade out all actions
+    for (const [name, action] of this.actions.entries()) {
+      if (action.isRunning()) {
+        action.fadeOut(0.1); // Quick fade out
+        action.stop();
+      }
+    }
+
+    // Reset state
+    this.isOneShotPlaying = false;
+    this.oneShotCurrentClip = null;
+    this.oneShotPrevState = null;
+    this.clipFinishedFlag = false;
+
+    if (this.oneShotResolve) {
+      this.oneShotResolve();
+      this.oneShotResolve = null;
+    }
+  }
+
+  public getClipNames(): string[] {
+    return Array.from(this.actions.keys());
+  }
+
+  /**
+   * Returns the currently active animation actions based on the current state.
+   */
+  public getActiveActions(): THREE.AnimationAction[] {
+    if (!this.currentState) return [];
+    const state = this.states[this.currentState];
+    if (!state) return [];
+    if (state.blend && state.blend.length > 0) {
+      // Return all actions in the blend
+      return state.blend
+        .map(b => this.actions.get(b.clip))
+        .filter((a): a is THREE.AnimationAction => !!a);
+    } else if (state.clip) {
+      if (typeof state.clip === 'string') {
+        const a = this.actions.get(state.clip);
+        return a ? [a] : [];
+      } else if (Array.isArray(state.clip)) {
+        // Optionally, pick a random one for display, or just return empty (since active action is ambiguous)
+        // We'll return empty to avoid confusion
+        return [];
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Trigger a one-shot animation by name. Returns a promise that resolves when the one-shot finishes.
+   * @param clip The name of the one-shot animation clip to play
+   * @param freezeOnLastFrame If true, the animation will freeze on the last frame and not resume the state machine
+   */
+  public playOneShot(clip: string, freezeOnLastFrame: boolean = false): Promise<void> {
+    if (!this.oneShotClips.has(clip)) {
+      throw new Error(`Clip '${clip}' is not a registered one-shot clip.`);
+    }
+
+    // If a one-shot is already playing, interrupt it properly
+    if (this.isOneShotPlaying) {
+      this.interruptCurrentOneShot();
+    }
+
+    if (!this.mixer) return Promise.resolve();
+    const action = this.actions.get(clip);
+    if (!action) {
+      throw new Error(`One-shot animation action '${clip}' not found.`);
+    }
+    this.isOneShotPlaying = true;
+    this.oneShotPrevState = this.currentState;
+    this.oneShotCurrentClip = clip;
+    this.oneShotFreezeOnLastFrame = freezeOnLastFrame;
+    // Fade out all other actions
+    for (const [name, act] of this.actions.entries()) {
+      if (act !== action) {
+        act.fadeOut(0.2);
+      }
+    }
+    action.reset();
+    action.setLoop(THREE.LoopOnce, 1);
+    action.clampWhenFinished = true;
+    action.enabled = true;
+    action.setEffectiveWeight(1);
+    action.play();
+    // Listen for finished event
+    return new Promise<void>((resolve) => {
+      this.oneShotResolve = resolve;
+      action.getMixer().addEventListener('finished', this._onOneShotFinished);
+    });
+  }
+
+  /**
+   * Interrupts the currently playing one-shot animation and cleans up its state
+   */
+  private interruptCurrentOneShot(): void {
+    if (!this.isOneShotPlaying || !this.oneShotCurrentClip) return;
+
+    // Find and stop the current one-shot action
+    const currentAction = this.actions.get(this.oneShotCurrentClip);
+    if (currentAction && this.mixer) {
+      // Remove the event listener to prevent the old callback from firing
+      currentAction.getMixer().removeEventListener('finished', this._onOneShotFinished);
+
+      // Stop the action and reset its state
+      currentAction.stop();
+      currentAction.enabled = false;
+      currentAction.setEffectiveWeight(0);
+    }
+
+    // Resolve the previous promise if it exists
+    if (this.oneShotResolve) {
+      this.oneShotResolve();
+      this.oneShotResolve = null;
+    }
+
+    // Reset one-shot state variables
+    this.isOneShotPlaying = false;
+    this.oneShotCurrentClip = null;
+    this.oneShotFreezeOnLastFrame = false;
+    // Note: We don't reset oneShotPrevState here since the new one-shot will set it
+  }
+
+  private _onOneShotFinished = (event: any) => {
+    if (!this.isOneShotPlaying) return;
+    if (!event || !event.action) return;
+    if (event.action.getClip().name !== this.oneShotCurrentClip) return;
+    // Clean up
+    event.action.getMixer().removeEventListener('finished', this._onOneShotFinished);
+
+    if (this.oneShotFreezeOnLastFrame) {
+      this.setEnabled(false);
+    } else {
+      // Normal mode: stop action and resume state machine
+      event.action.stop();
+      event.action.enabled = false;
+      event.action.setEffectiveWeight(0);
+      this.isOneShotPlaying = false;
+      this.oneShotCurrentClip = null;
+      this.oneShotFreezeOnLastFrame = false;
+
+      // Resume state machine
+      if (this.oneShotPrevState) {
+        this.transitionToState(this.oneShotPrevState);
+        // Explicitly play the animation for the resumed state
+        const resumedState = this.states[this.oneShotPrevState];
+        if (resumedState) {
+          if (resumedState.blend && resumedState.blend.length > 0) {
+            this.updateBlendWeights(resumedState.blend);
+          } else if (resumedState.clip) {
+            let clipToPlay: string | undefined = undefined;
+            if (typeof resumedState.clip === 'string') {
+              clipToPlay = resumedState.clip;
+            } else if (Array.isArray(resumedState.clip)) {
+              if (resumedState.clip.length > 0) {
+                const idx = Math.floor(Math.random() * resumedState.clip.length);
+                const candidate = resumedState.clip[idx];
+                if (typeof candidate === 'string') {
+                  clipToPlay = candidate;
+                }
+              }
+            }
+            if (typeof clipToPlay === 'string') {
+              this.play(clipToPlay, 0.3);
+            }
+          }
+        }
+        this.oneShotPrevState = null;
+      }
+    }
+
+    if (this.oneShotResolve) {
+      this.oneShotResolve();
+      this.oneShotResolve = null;
+    }
+  };
+
+  private _onClipFinished = (event: any) => {
+    // Only set the flag if the finished action is the current state's clip
+    if (!event || !event.action) return;
+    const currentState = this.currentState && this.states[this.currentState];
+    if (!currentState) return;
+    let relevant = false;
+    if (currentState.clip) {
+      if (typeof currentState.clip === 'string' && event.action.getClip().name === currentState.clip) relevant = true;
+      if (Array.isArray(currentState.clip) && currentState.clip.includes(event.action.getClip().name)) relevant = true;
+    }
+    // For blend states, could check if the finished action is in the blend, but usually only single-clip states are LoopOnce
+    if (relevant) {
+      this.clipFinishedFlag = true;
+    }
+  };
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_AnimationMachine';
+  }
+}