Owen/src/core/OwenAnimationContext.js

/**
 * @fileoverview Main animation context controller
 * @module core
 */

import { States, Emotions, Config } from '../constants.js'

/**
 * Main controller for the Owen animation system
 * Manages state transitions, animation playback, and user interactions
 * @class
 */
export class OwenAnimationContext {
  /**
   * Create an Owen animation context
   * @param {THREE.Object3D} model - The 3D character model
   * @param {THREE.AnimationMixer} mixer - The Three.js animation mixer
   * @param {AnimationClipFactory} animationClipFactory - Factory for creating clips
   * @param {StateFactory} stateFactory - Factory for creating state handlers
   */
  constructor (model, mixer, animationClipFactory, stateFactory) {
    /**
     * The 3D character model
     * @type {THREE.Object3D}
     */
    this.model = model

    /**
     * The Three.js animation mixer
     * @type {THREE.AnimationMixer}
     */
    this.mixer = mixer

    /**
     * Factory for creating animation clips
     * @type {AnimationClipFactory}
     */
    this.animationClipFactory = animationClipFactory

    /**
     * Factory for creating state handlers
     * @type {StateFactory}
     */
    this.stateFactory = stateFactory

    /**
     * Map of animation clips by name
     * @type {Map<string, AnimationClip>}
     */
    this.clips = new Map()

    /**
     * Map of state handlers by name
     * @type {Map<string, StateHandler>}
     */
    this.states = new Map()

    /**
     * Current active state
     * @type {string}
     */
    this.currentState = States.WAIT

    /**
     * Current active state handler
     * @type {StateHandler|null}
     */
    this.currentStateHandler = null

    /**
     * Timer for inactivity detection
     * @type {number}
     */
    this.inactivityTimer = 0

    /**
     * Inactivity timeout in milliseconds
     * @type {number}
     */
    this.inactivityTimeout = Config.INACTIVITY_TIMEOUT

    /**
     * Whether the system is initialized
     * @type {boolean}
     */
    this.initialized = false
  }

  /**
   * Initialize the animation system
   * @returns {Promise<void>}
   */
  async initialize () {
    if (this.initialized) return

    // Create animation clips from model
    this.clips = await this.animationClipFactory.createClipsFromModel(this.model)

    // Create actions for all clips
    for (const [, clip] of this.clips) {
      clip.createAction(this.mixer)
    }

    // Initialize state handlers
    this.initializeStates()

    // Start in wait state
    await this.transitionTo(States.WAIT)

    this.initialized = true
    console.log('Owen Animation System initialized')
  }

  /**
   * Initialize all state handlers
   * @private
   * @returns {void}
   */
  initializeStates () {
    const stateNames = this.stateFactory.getAvailableStates()

    for (const stateName of stateNames) {
      const handler = this.stateFactory.createStateHandler(stateName, this)
      this.states.set(stateName, handler)
    }
  }

  /**
   * Transition to a new state
   * @param {string} newStateName - The name of the state to transition to
   * @param {string} [emotion=Emotions.NEUTRAL] - The emotion for the transition
   * @returns {Promise<void>}
   * @throws {Error} If state is not found or transition is invalid
   */
  async transitionTo (newStateName, emotion = Emotions.NEUTRAL) {
    if (!this.states.has(newStateName)) {
      throw new Error(`State '${newStateName}' not found`)
    }

    const oldState = this.currentState
    const newStateHandler = this.states.get(newStateName)

    console.log(`Transitioning from ${oldState} to ${newStateName}`)

    // Exit current state
    if (this.currentStateHandler) {
      await this.currentStateHandler.exit(newStateName, emotion)
    }

    // Enter new state
    this.currentState = newStateName
    this.currentStateHandler = newStateHandler
    await this.currentStateHandler.enter(oldState, emotion)

    // Reset inactivity timer
    this.resetActivityTimer()
  }

  /**
   * Handle a user message
   * @param {string} message - The user message
   * @returns {Promise<void>}
   */
  async handleUserMessage (message) {
    console.log(`Handling user message: "${message}"`)

    this.onUserActivity()

    // If sleeping, wake up first
    if (this.currentState === States.SLEEP) {
      await this.transitionTo(States.REACT)
    }

    // Let current state handle the message
    if (this.currentStateHandler) {
      await this.currentStateHandler.handleMessage(message)
    }

    // Transition to appropriate next state based on current state
    if (this.currentState === States.WAIT) {
      await this.transitionTo(States.REACT)
    } else if (this.currentState === States.REACT) {
      await this.transitionTo(States.TYPE)
    }
  }

  /**
   * Called when user activity is detected
   * @returns {void}
   */
  onUserActivity () {
    this.resetActivityTimer()

    // Wake up if sleeping
    if (this.currentState === States.SLEEP) {
      this.transitionTo(States.WAIT)
    }
  }

  /**
   * Reset the inactivity timer
   * @private
   * @returns {void}
   */
  resetActivityTimer () {
    this.inactivityTimer = 0
  }

  /**
   * Handle inactivity timeout
   * @private
   * @returns {Promise<void>}
   */
  async handleInactivity () {
    console.log('Inactivity detected, transitioning to sleep')
    await this.transitionTo(States.SLEEP)
  }

  /**
   * Update the animation system (call every frame)
   * @param {number} deltaTime - Time elapsed since last update (ms)
   * @returns {void}
   */
  update (deltaTime) {
    if (!this.initialized) return

    // Update Three.js mixer
    this.mixer.update(deltaTime / 1000) // Convert to seconds

    // Update current state
    if (this.currentStateHandler) {
      this.currentStateHandler.update(deltaTime)
    }

    // Update inactivity timer
    this.inactivityTimer += deltaTime
    if (this.inactivityTimer > this.inactivityTimeout && this.currentState !== States.SLEEP) {
      this.handleInactivity()
    }
  }

  /**
   * Get an animation clip by name
   * @param {string} name - The animation clip name
   * @returns {AnimationClip|undefined} The animation clip or undefined if not found
   */
  getClip (name) {
    return this.clips.get(name)
  }

  /**
   * Get animation clips matching a pattern
   * @param {string} pattern - Pattern to match (supports * wildcards)
   * @returns {AnimationClip[]} Array of matching clips
   */
  getClipsByPattern (pattern) {
    const regex = new RegExp(pattern.replace(/\*/g, '.*'))
    const matches = []

    for (const [name, clip] of this.clips) {
      if (regex.test(name)) {
        matches.push(clip)
      }
    }

    return matches
  }

  /**
   * Get the current state name
   * @returns {string} The current state name
   */
  getCurrentState () {
    return this.currentState
  }

  /**
   * Get the current state handler
   * @returns {StateHandler|null} The current state handler
   */
  getCurrentStateHandler () {
    return this.currentStateHandler
  }

  /**
   * Get available transitions from current state
   * @returns {string[]} Array of available state transitions
   */
  getAvailableTransitions () {
    if (this.currentStateHandler) {
      return this.currentStateHandler.getAvailableTransitions()
    }
    return []
  }

  /**
   * Get all available animation clip names
   * @returns {string[]} Array of clip names
   */
  getAvailableClips () {
    return Array.from(this.clips.keys())
  }

  /**
   * Get all available state names
   * @returns {string[]} Array of state names
   */
  getAvailableStates () {
    return Array.from(this.states.keys())
  }

  /**
   * Dispose of the animation system and clean up resources
   * @returns {void}
   */
  dispose () {
    // Stop all animations
    for (const [, clip] of this.clips) {
      if (clip.action) {
        clip.action.stop()
      }
    }

    // Clear caches
    this.clips.clear()
    this.states.clear()
    this.animationClipFactory.clearCache()

    this.initialized = false
    console.log('Owen Animation System disposed')
  }
}