@esengine/fsm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ESEngine Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,500 @@
+import * as _esengine_ecs_framework from '@esengine/ecs-framework';
+import { BlueprintNodeTemplate, INodeExecutor, BlueprintNode, ExecutionResult } from '@esengine/blueprint';
+
+/**
+ * @zh 状态机接口
+ * @en State Machine Interface
+ *
+ * @zh 提供有限状态机的核心接口
+ * @en Provides core interfaces for finite state machine
+ */
+/**
+ * @zh 状态配置
+ * @en State configuration
+ */
+interface StateConfig<TState extends string = string, TContext = unknown> {
+    /**
+     * @zh 状态名称
+     * @en State name
+     */
+    readonly name: TState;
+    /**
+     * @zh 进入状态时的回调
+     * @en Callback when entering state
+     */
+    onEnter?: (context: TContext, from: TState | null) => void;
+    /**
+     * @zh 退出状态时的回调
+     * @en Callback when exiting state
+     */
+    onExit?: (context: TContext, to: TState) => void;
+    /**
+     * @zh 状态更新回调
+     * @en State update callback
+     */
+    onUpdate?: (context: TContext, deltaTime: number) => void;
+    /**
+     * @zh 状态标签
+     * @en State tags
+     */
+    tags?: string[];
+    /**
+     * @zh 状态元数据
+     * @en State metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * @zh 转换条件函数
+ * @en Transition condition function
+ */
+type TransitionCondition<TContext = unknown> = (context: TContext) => boolean;
+/**
+ * @zh 转换配置
+ * @en Transition configuration
+ */
+interface TransitionConfig<TState extends string = string, TContext = unknown> {
+    /**
+     * @zh 源状态
+     * @en Source state
+     */
+    readonly from: TState;
+    /**
+     * @zh 目标状态
+     * @en Target state
+     */
+    readonly to: TState;
+    /**
+     * @zh 转换条件
+     * @en Transition condition
+     */
+    condition?: TransitionCondition<TContext>;
+    /**
+     * @zh 转换优先级（数字越大优先级越高）
+     * @en Transition priority (higher number = higher priority)
+     */
+    priority?: number;
+    /**
+     * @zh 转换名称（用于调试）
+     * @en Transition name (for debugging)
+     */
+    name?: string;
+}
+/**
+ * @zh 状态变更事件
+ * @en State change event
+ */
+interface StateChangeEvent<TState extends string = string> {
+    /**
+     * @zh 之前的状态
+     * @en Previous state
+     */
+    readonly from: TState | null;
+    /**
+     * @zh 当前状态
+     * @en Current state
+     */
+    readonly to: TState;
+    /**
+     * @zh 时间戳
+     * @en Timestamp
+     */
+    readonly timestamp: number;
+}
+/**
+ * @zh 状态变更监听器
+ * @en State change listener
+ */
+type StateChangeListener<TState extends string = string> = (event: StateChangeEvent<TState>) => void;
+/**
+ * @zh 状态机接口
+ * @en State machine interface
+ *
+ * @zh 通用有限状态机，用于角色/AI 状态管理
+ * @en Generic finite state machine for character/AI state management
+ *
+ * @example
+ * ```typescript
+ * type PlayerState = 'idle' | 'walk' | 'run' | 'jump' | 'attack';
+ *
+ * const fsm = createStateMachine<PlayerState>('idle');
+ *
+ * fsm.defineState('idle', {
+ *     onEnter: () => console.log('Entering idle'),
+ *     onExit: () => console.log('Exiting idle')
+ * });
+ *
+ * fsm.defineTransition('idle', 'walk', () => isMoving);
+ * fsm.defineTransition('walk', 'run', () => isRunning);
+ *
+ * fsm.transition('walk'); // 手动转换
+ * fsm.evaluateTransitions(); // 自动评估条件
+ * ```
+ */
+interface IStateMachine<TState extends string = string, TContext = unknown> {
+    /**
+     * @zh 当前状态
+     * @en Current state
+     */
+    readonly current: TState;
+    /**
+     * @zh 之前的状态
+     * @en Previous state
+     */
+    readonly previous: TState | null;
+    /**
+     * @zh 状态机上下文
+     * @en State machine context
+     */
+    readonly context: TContext;
+    /**
+     * @zh 是否正在转换中
+     * @en Whether a transition is in progress
+     */
+    readonly isTransitioning: boolean;
+    /**
+     * @zh 当前状态持续时间（毫秒）
+     * @en Current state duration in milliseconds
+     */
+    readonly currentStateDuration: number;
+    /**
+     * @zh 定义状态
+     * @en Define state
+     *
+     * @param state - @zh 状态名称 @en State name
+     * @param config - @zh 状态配置 @en State configuration
+     */
+    defineState(state: TState, config?: Partial<StateConfig<TState, TContext>>): void;
+    /**
+     * @zh 检查状态是否已定义
+     * @en Check if state is defined
+     *
+     * @param state - @zh 状态名称 @en State name
+     */
+    hasState(state: TState): boolean;
+    /**
+     * @zh 获取状态配置
+     * @en Get state configuration
+     *
+     * @param state - @zh 状态名称 @en State name
+     */
+    getStateConfig(state: TState): StateConfig<TState, TContext> | undefined;
+    /**
+     * @zh 获取所有定义的状态
+     * @en Get all defined states
+     */
+    getStates(): TState[];
+    /**
+     * @zh 定义转换
+     * @en Define transition
+     *
+     * @param from - @zh 源状态 @en Source state
+     * @param to - @zh 目标状态 @en Target state
+     * @param condition - @zh 转换条件 @en Transition condition
+     * @param priority - @zh 优先级 @en Priority
+     */
+    defineTransition(from: TState, to: TState, condition?: TransitionCondition<TContext>, priority?: number): void;
+    /**
+     * @zh 移除转换
+     * @en Remove transition
+     *
+     * @param from - @zh 源状态 @en Source state
+     * @param to - @zh 目标状态 @en Target state
+     */
+    removeTransition(from: TState, to: TState): void;
+    /**
+     * @zh 获取从指定状态可用的转换
+     * @en Get available transitions from state
+     *
+     * @param from - @zh 源状态 @en Source state
+     */
+    getTransitionsFrom(from: TState): TransitionConfig<TState, TContext>[];
+    /**
+     * @zh 检查是否可以转换到目标状态
+     * @en Check if can transition to target state
+     *
+     * @param to - @zh 目标状态 @en Target state
+     */
+    canTransition(to: TState): boolean;
+    /**
+     * @zh 转换到目标状态
+     * @en Transition to target state
+     *
+     * @param to - @zh 目标状态 @en Target state
+     * @param force - @zh 强制转换（忽略条件）@en Force transition (ignore condition)
+     * @returns @zh 是否成功 @en Whether successful
+     */
+    transition(to: TState, force?: boolean): boolean;
+    /**
+     * @zh 评估并执行满足条件的转换
+     * @en Evaluate and execute transitions that meet conditions
+     *
+     * @returns @zh 是否发生转换 @en Whether a transition occurred
+     */
+    evaluateTransitions(): boolean;
+    /**
+     * @zh 更新状态机
+     * @en Update state machine
+     *
+     * @param deltaTime - @zh 增量时间（毫秒）@en Delta time in milliseconds
+     */
+    update(deltaTime: number): void;
+    /**
+     * @zh 重置状态机到初始状态
+     * @en Reset state machine to initial state
+     *
+     * @param initialState - @zh 初始状态 @en Initial state
+     */
+    reset(initialState?: TState): void;
+    /**
+     * @zh 监听状态进入事件
+     * @en Listen to state enter event
+     *
+     * @param state - @zh 状态名称 @en State name
+     * @param callback - @zh 回调函数 @en Callback function
+     */
+    onEnter(state: TState, callback: (from: TState | null) => void): () => void;
+    /**
+     * @zh 监听状态退出事件
+     * @en Listen to state exit event
+     *
+     * @param state - @zh 状态名称 @en State name
+     * @param callback - @zh 回调函数 @en Callback function
+     */
+    onExit(state: TState, callback: (to: TState) => void): () => void;
+    /**
+     * @zh 监听任意状态变更
+     * @en Listen to any state change
+     *
+     * @param callback - @zh 回调函数 @en Callback function
+     */
+    onChange(callback: StateChangeListener<TState>): () => void;
+    /**
+     * @zh 获取状态历史
+     * @en Get state history
+     */
+    getHistory(): StateChangeEvent<TState>[];
+    /**
+     * @zh 清除历史
+     * @en Clear history
+     */
+    clearHistory(): void;
+}
+
+/**
+ * @zh 状态机实现
+ * @en State Machine Implementation
+ *
+ * @zh 提供有限状态机的默认实现
+ * @en Provides default implementation for finite state machine
+ */
+
+/**
+ * @zh 状态机配置选项
+ * @en State machine configuration options
+ */
+interface StateMachineOptions<TContext = unknown> {
+    /**
+     * @zh 上下文对象
+     * @en Context object
+     */
+    context?: TContext;
+    /**
+     * @zh 最大历史记录数量
+     * @en Maximum history size
+     */
+    maxHistorySize?: number;
+    /**
+     * @zh 是否启用历史记录
+     * @en Whether to enable history
+     */
+    enableHistory?: boolean;
+}
+/**
+ * @zh 状态机实现
+ * @en State machine implementation
+ */
+declare class StateMachine<TState extends string = string, TContext = unknown> implements IStateMachine<TState, TContext> {
+    private _current;
+    private _previous;
+    private _context;
+    private _isTransitioning;
+    private _stateStartTime;
+    private states;
+    private transitions;
+    private enterListeners;
+    private exitListeners;
+    private changeListeners;
+    private history;
+    private maxHistorySize;
+    private enableHistory;
+    constructor(initialState: TState, options?: StateMachineOptions<TContext>);
+    get current(): TState;
+    get previous(): TState | null;
+    get context(): TContext;
+    get isTransitioning(): boolean;
+    get currentStateDuration(): number;
+    defineState(state: TState, config?: Partial<StateConfig<TState, TContext>>): void;
+    hasState(state: TState): boolean;
+    getStateConfig(state: TState): StateConfig<TState, TContext> | undefined;
+    getStates(): TState[];
+    defineTransition(from: TState, to: TState, condition?: TransitionCondition<TContext>, priority?: number): void;
+    removeTransition(from: TState, to: TState): void;
+    getTransitionsFrom(from: TState): TransitionConfig<TState, TContext>[];
+    canTransition(to: TState): boolean;
+    transition(to: TState, force?: boolean): boolean;
+    evaluateTransitions(): boolean;
+    private performTransition;
+    update(deltaTime: number): void;
+    reset(initialState?: TState): void;
+    onEnter(state: TState, callback: (from: TState | null) => void): () => void;
+    onExit(state: TState, callback: (to: TState) => void): () => void;
+    onChange(callback: StateChangeListener<TState>): () => void;
+    getHistory(): StateChangeEvent<TState>[];
+    clearHistory(): void;
+    /**
+     * @zh 获取状态机的调试信息
+     * @en Get debug info for the state machine
+     */
+    getDebugInfo(): {
+        current: TState;
+        previous: TState | null;
+        duration: number;
+        stateCount: number;
+        transitionCount: number;
+        historySize: number;
+    };
+}
+/**
+ * @zh 创建状态机
+ * @en Create state machine
+ *
+ * @param initialState - @zh 初始状态 @en Initial state
+ * @param options - @zh 配置选项 @en Configuration options
+ * @returns @zh 状态机实例 @en State machine instance
+ */
+declare function createStateMachine<TState extends string = string, TContext = unknown>(initialState: TState, options?: StateMachineOptions<TContext>): IStateMachine<TState, TContext>;
+
+/**
+ * @zh 状态机服务令牌
+ * @en State machine service token
+ *
+ * @zh 用于注入状态机服务
+ * @en Used for injecting state machine service
+ */
+declare const StateMachineToken: _esengine_ecs_framework.ServiceToken<IStateMachine<string, unknown>>;
+
+/**
+ * @zh 状态机蓝图节点
+ * @en State Machine Blueprint Nodes
+ *
+ * @zh 提供状态机功能的蓝图节点
+ * @en Provides blueprint nodes for state machine functionality
+ */
+
+/**
+ * @zh GetCurrentState 节点模板
+ * @en GetCurrentState node template
+ */
+declare const GetCurrentStateTemplate: BlueprintNodeTemplate;
+/**
+ * @zh GetCurrentState 节点执行器
+ * @en GetCurrentState node executor
+ */
+declare class GetCurrentStateExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh TransitionTo 节点模板
+ * @en TransitionTo node template
+ */
+declare const TransitionToTemplate: BlueprintNodeTemplate;
+/**
+ * @zh TransitionTo 节点执行器
+ * @en TransitionTo node executor
+ */
+declare class TransitionToExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh CanTransition 节点模板
+ * @en CanTransition node template
+ */
+declare const CanTransitionTemplate: BlueprintNodeTemplate;
+/**
+ * @zh CanTransition 节点执行器
+ * @en CanTransition node executor
+ */
+declare class CanTransitionExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh IsInState 节点模板
+ * @en IsInState node template
+ */
+declare const IsInStateTemplate: BlueprintNodeTemplate;
+/**
+ * @zh IsInState 节点执行器
+ * @en IsInState node executor
+ */
+declare class IsInStateExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh WasInState 节点模板
+ * @en WasInState node template
+ */
+declare const WasInStateTemplate: BlueprintNodeTemplate;
+/**
+ * @zh WasInState 节点执行器
+ * @en WasInState node executor
+ */
+declare class WasInStateExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh GetStateDuration 节点模板
+ * @en GetStateDuration node template
+ */
+declare const GetStateDurationTemplate: BlueprintNodeTemplate;
+/**
+ * @zh GetStateDuration 节点执行器
+ * @en GetStateDuration node executor
+ */
+declare class GetStateDurationExecutor implements INodeExecutor {
+    execute(_node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh EvaluateTransitions 节点模板
+ * @en EvaluateTransitions node template
+ */
+declare const EvaluateTransitionsTemplate: BlueprintNodeTemplate;
+/**
+ * @zh EvaluateTransitions 节点执行器
+ * @en EvaluateTransitions node executor
+ */
+declare class EvaluateTransitionsExecutor implements INodeExecutor {
+    execute(_node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh ResetStateMachine 节点模板
+ * @en ResetStateMachine node template
+ */
+declare const ResetStateMachineTemplate: BlueprintNodeTemplate;
+/**
+ * @zh ResetStateMachine 节点执行器
+ * @en ResetStateMachine node executor
+ */
+declare class ResetStateMachineExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: unknown): ExecutionResult;
+}
+/**
+ * @zh 状态机节点定义
+ * @en State machine node definitions
+ */
+declare const StateMachineNodeDefinitions: {
+    template: BlueprintNodeTemplate;
+    executor: GetCurrentStateExecutor;
+}[];
+
+export { CanTransitionExecutor, CanTransitionTemplate, EvaluateTransitionsExecutor, EvaluateTransitionsTemplate, GetCurrentStateExecutor, GetCurrentStateTemplate, GetStateDurationExecutor, GetStateDurationTemplate, type IStateMachine, IsInStateExecutor, IsInStateTemplate, ResetStateMachineExecutor, ResetStateMachineTemplate, type StateChangeEvent, type StateChangeListener, type StateConfig, StateMachine, StateMachineNodeDefinitions, type StateMachineOptions, StateMachineToken, type TransitionCondition, type TransitionConfig, TransitionToExecutor, TransitionToTemplate, WasInStateExecutor, WasInStateTemplate, createStateMachine };