@esengine/fsm 1.0.0

package/dist/index.js

@@ -0,0 +1,772 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/StateMachine.ts
+var _StateMachine = class _StateMachine {
+  constructor(initialState, options = {}) {
+    __publicField(this, "_current");
+    __publicField(this, "_previous", null);
+    __publicField(this, "_context");
+    __publicField(this, "_isTransitioning", false);
+    __publicField(this, "_stateStartTime", 0);
+    __publicField(this, "states", /* @__PURE__ */ new Map());
+    __publicField(this, "transitions", /* @__PURE__ */ new Map());
+    __publicField(this, "enterListeners", /* @__PURE__ */ new Map());
+    __publicField(this, "exitListeners", /* @__PURE__ */ new Map());
+    __publicField(this, "changeListeners", /* @__PURE__ */ new Set());
+    __publicField(this, "history", []);
+    __publicField(this, "maxHistorySize");
+    __publicField(this, "enableHistory");
+    this._current = initialState;
+    this._context = options.context ?? {};
+    this.maxHistorySize = options.maxHistorySize ?? 100;
+    this.enableHistory = options.enableHistory ?? true;
+    this._stateStartTime = Date.now();
+    this.defineState(initialState);
+  }
+  // =========================================================================
+  // 属性 | Properties
+  // =========================================================================
+  get current() {
+    return this._current;
+  }
+  get previous() {
+    return this._previous;
+  }
+  get context() {
+    return this._context;
+  }
+  get isTransitioning() {
+    return this._isTransitioning;
+  }
+  get currentStateDuration() {
+    return Date.now() - this._stateStartTime;
+  }
+  // =========================================================================
+  // 状态定义 | State Definition
+  // =========================================================================
+  defineState(state, config) {
+    const stateConfig = {
+      name: state,
+      ...config
+    };
+    this.states.set(state, stateConfig);
+  }
+  hasState(state) {
+    return this.states.has(state);
+  }
+  getStateConfig(state) {
+    return this.states.get(state);
+  }
+  getStates() {
+    return Array.from(this.states.keys());
+  }
+  // =========================================================================
+  // 转换定义 | Transition Definition
+  // =========================================================================
+  defineTransition(from, to, condition, priority = 0) {
+    if (!this.transitions.has(from)) {
+      this.transitions.set(from, []);
+    }
+    const transitions = this.transitions.get(from);
+    const existingIndex = transitions.findIndex((t) => t.to === to);
+    if (existingIndex >= 0) {
+      transitions.splice(existingIndex, 1);
+    }
+    transitions.push({
+      from,
+      to,
+      condition,
+      priority
+    });
+    transitions.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+  removeTransition(from, to) {
+    const transitions = this.transitions.get(from);
+    if (transitions) {
+      const index = transitions.findIndex((t) => t.to === to);
+      if (index >= 0) {
+        transitions.splice(index, 1);
+      }
+    }
+  }
+  getTransitionsFrom(from) {
+    return this.transitions.get(from) ?? [];
+  }
+  // =========================================================================
+  // 转换操作 | Transition Operations
+  // =========================================================================
+  canTransition(to) {
+    if (this._isTransitioning) {
+      return false;
+    }
+    if (this._current === to) {
+      return false;
+    }
+    const transitions = this.transitions.get(this._current);
+    if (!transitions) {
+      return true;
+    }
+    const transition = transitions.find((t) => t.to === to);
+    if (!transition) {
+      return true;
+    }
+    if (transition.condition) {
+      return transition.condition(this._context);
+    }
+    return true;
+  }
+  transition(to, force = false) {
+    if (this._isTransitioning) {
+      console.warn("StateMachine: Cannot transition while already transitioning");
+      return false;
+    }
+    if (this._current === to) {
+      return false;
+    }
+    if (!force && !this.canTransition(to)) {
+      return false;
+    }
+    this.performTransition(to);
+    return true;
+  }
+  evaluateTransitions() {
+    if (this._isTransitioning) {
+      return false;
+    }
+    const transitions = this.transitions.get(this._current);
+    if (!transitions || transitions.length === 0) {
+      return false;
+    }
+    for (const transition of transitions) {
+      if (!transition.condition || transition.condition(this._context)) {
+        this.performTransition(transition.to);
+        return true;
+      }
+    }
+    return false;
+  }
+  performTransition(to) {
+    this._isTransitioning = true;
+    const from = this._current;
+    const currentConfig = this.states.get(from);
+    if (currentConfig?.onExit) {
+      try {
+        currentConfig.onExit(this._context, to);
+      } catch (error) {
+        console.error(`StateMachine: Error in onExit for state '${from}':`, error);
+      }
+    }
+    const exitListeners = this.exitListeners.get(from);
+    if (exitListeners) {
+      for (const listener of exitListeners) {
+        try {
+          listener(to);
+        } catch (error) {
+          console.error(`StateMachine: Error in exit listener for state '${from}':`, error);
+        }
+      }
+    }
+    this._previous = from;
+    this._current = to;
+    this._stateStartTime = Date.now();
+    if (this.enableHistory) {
+      const event = {
+        from,
+        to,
+        timestamp: this._stateStartTime
+      };
+      this.history.push(event);
+      if (this.history.length > this.maxHistorySize) {
+        this.history.shift();
+      }
+      for (const listener of this.changeListeners) {
+        try {
+          listener(event);
+        } catch (error) {
+          console.error("StateMachine: Error in change listener:", error);
+        }
+      }
+    }
+    const newConfig = this.states.get(to);
+    if (newConfig?.onEnter) {
+      try {
+        newConfig.onEnter(this._context, from);
+      } catch (error) {
+        console.error(`StateMachine: Error in onEnter for state '${to}':`, error);
+      }
+    }
+    const enterListeners = this.enterListeners.get(to);
+    if (enterListeners) {
+      for (const listener of enterListeners) {
+        try {
+          listener(from);
+        } catch (error) {
+          console.error(`StateMachine: Error in enter listener for state '${to}':`, error);
+        }
+      }
+    }
+    this._isTransitioning = false;
+  }
+  // =========================================================================
+  // 生命周期 | Lifecycle
+  // =========================================================================
+  update(deltaTime) {
+    const config = this.states.get(this._current);
+    if (config?.onUpdate) {
+      try {
+        config.onUpdate(this._context, deltaTime);
+      } catch (error) {
+        console.error(`StateMachine: Error in onUpdate for state '${this._current}':`, error);
+      }
+    }
+  }
+  reset(initialState) {
+    const targetState = initialState ?? this._current;
+    this._previous = null;
+    this._current = targetState;
+    this._stateStartTime = Date.now();
+    this._isTransitioning = false;
+    this.clearHistory();
+  }
+  // =========================================================================
+  // 事件监听 | Event Listening
+  // =========================================================================
+  onEnter(state, callback) {
+    if (!this.enterListeners.has(state)) {
+      this.enterListeners.set(state, /* @__PURE__ */ new Set());
+    }
+    this.enterListeners.get(state).add(callback);
+    return () => {
+      this.enterListeners.get(state)?.delete(callback);
+    };
+  }
+  onExit(state, callback) {
+    if (!this.exitListeners.has(state)) {
+      this.exitListeners.set(state, /* @__PURE__ */ new Set());
+    }
+    this.exitListeners.get(state).add(callback);
+    return () => {
+      this.exitListeners.get(state)?.delete(callback);
+    };
+  }
+  onChange(callback) {
+    this.changeListeners.add(callback);
+    return () => {
+      this.changeListeners.delete(callback);
+    };
+  }
+  // =========================================================================
+  // 调试 | Debug
+  // =========================================================================
+  getHistory() {
+    return [
+      ...this.history
+    ];
+  }
+  clearHistory() {
+    this.history = [];
+  }
+  /**
+   * @zh 获取状态机的调试信息
+   * @en Get debug info for the state machine
+   */
+  getDebugInfo() {
+    let transitionCount = 0;
+    for (const transitions of this.transitions.values()) {
+      transitionCount += transitions.length;
+    }
+    return {
+      current: this._current,
+      previous: this._previous,
+      duration: this.currentStateDuration,
+      stateCount: this.states.size,
+      transitionCount,
+      historySize: this.history.length
+    };
+  }
+};
+__name(_StateMachine, "StateMachine");
+var StateMachine = _StateMachine;
+function createStateMachine(initialState, options) {
+  return new StateMachine(initialState, options);
+}
+__name(createStateMachine, "createStateMachine");
+
+// src/tokens.ts
+import { createServiceToken } from "@esengine/ecs-framework";
+var StateMachineToken = createServiceToken("stateMachine");
+
+// src/nodes/StateMachineNodes.ts
+var GetCurrentStateTemplate = {
+  type: "GetCurrentState",
+  title: "Get Current State",
+  category: "logic",
+  description: "Get current state of the state machine / \u83B7\u53D6\u72B6\u6001\u673A\u5F53\u524D\u72B6\u6001",
+  keywords: [
+    "fsm",
+    "state",
+    "current",
+    "get"
+  ],
+  menuPath: [
+    "State Machine",
+    "Get Current State"
+  ],
+  isPure: true,
+  inputs: [],
+  outputs: [
+    {
+      name: "state",
+      displayName: "State",
+      type: "string"
+    },
+    {
+      name: "previous",
+      displayName: "Previous",
+      type: "string"
+    },
+    {
+      name: "duration",
+      displayName: "Duration (ms)",
+      type: "float"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _GetCurrentStateExecutor = class _GetCurrentStateExecutor {
+  execute(node, context) {
+    const ctx = context;
+    const fsm = ctx.stateMachine;
+    return {
+      outputs: {
+        state: fsm?.current ?? "",
+        previous: fsm?.previous ?? "",
+        duration: fsm?.currentStateDuration ?? 0
+      }
+    };
+  }
+};
+__name(_GetCurrentStateExecutor, "GetCurrentStateExecutor");
+var GetCurrentStateExecutor = _GetCurrentStateExecutor;
+var TransitionToTemplate = {
+  type: "TransitionTo",
+  title: "Transition To",
+  category: "logic",
+  description: "Transition to a new state / \u8F6C\u6362\u5230\u65B0\u72B6\u6001",
+  keywords: [
+    "fsm",
+    "state",
+    "transition",
+    "change"
+  ],
+  menuPath: [
+    "State Machine",
+    "Transition To"
+  ],
+  isPure: false,
+  inputs: [
+    {
+      name: "exec",
+      displayName: "",
+      type: "exec"
+    },
+    {
+      name: "state",
+      displayName: "Target State",
+      type: "string",
+      defaultValue: ""
+    },
+    {
+      name: "force",
+      displayName: "Force",
+      type: "bool",
+      defaultValue: false
+    }
+  ],
+  outputs: [
+    {
+      name: "exec",
+      displayName: "",
+      type: "exec"
+    },
+    {
+      name: "success",
+      displayName: "Success",
+      type: "bool"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _TransitionToExecutor = class _TransitionToExecutor {
+  execute(node, context) {
+    const ctx = context;
+    const state = ctx.evaluateInput(node.id, "state", "");
+    const force = ctx.evaluateInput(node.id, "force", false);
+    let success = false;
+    if (state && ctx.stateMachine) {
+      success = ctx.stateMachine.transition(state, force);
+    }
+    return {
+      outputs: {
+        success
+      },
+      nextExec: "exec"
+    };
+  }
+};
+__name(_TransitionToExecutor, "TransitionToExecutor");
+var TransitionToExecutor = _TransitionToExecutor;
+var CanTransitionTemplate = {
+  type: "CanTransition",
+  title: "Can Transition",
+  category: "logic",
+  description: "Check if can transition to state / \u68C0\u67E5\u662F\u5426\u53EF\u4EE5\u8F6C\u6362\u5230\u72B6\u6001",
+  keywords: [
+    "fsm",
+    "state",
+    "transition",
+    "can",
+    "check"
+  ],
+  menuPath: [
+    "State Machine",
+    "Can Transition"
+  ],
+  isPure: true,
+  inputs: [
+    {
+      name: "state",
+      displayName: "Target State",
+      type: "string",
+      defaultValue: ""
+    }
+  ],
+  outputs: [
+    {
+      name: "canTransition",
+      displayName: "Can Transition",
+      type: "bool"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _CanTransitionExecutor = class _CanTransitionExecutor {
+  execute(node, context) {
+    const ctx = context;
+    const state = ctx.evaluateInput(node.id, "state", "");
+    const canTransition = state ? ctx.stateMachine?.canTransition(state) ?? false : false;
+    return {
+      outputs: {
+        canTransition
+      }
+    };
+  }
+};
+__name(_CanTransitionExecutor, "CanTransitionExecutor");
+var CanTransitionExecutor = _CanTransitionExecutor;
+var IsInStateTemplate = {
+  type: "IsInState",
+  title: "Is In State",
+  category: "logic",
+  description: "Check if currently in a specific state / \u68C0\u67E5\u662F\u5426\u5904\u4E8E\u7279\u5B9A\u72B6\u6001",
+  keywords: [
+    "fsm",
+    "state",
+    "is",
+    "check",
+    "current"
+  ],
+  menuPath: [
+    "State Machine",
+    "Is In State"
+  ],
+  isPure: true,
+  inputs: [
+    {
+      name: "state",
+      displayName: "State",
+      type: "string",
+      defaultValue: ""
+    }
+  ],
+  outputs: [
+    {
+      name: "isInState",
+      displayName: "Is In State",
+      type: "bool"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _IsInStateExecutor = class _IsInStateExecutor {
+  execute(node, context) {
+    const ctx = context;
+    const state = ctx.evaluateInput(node.id, "state", "");
+    const isInState = state ? ctx.stateMachine?.current === state : false;
+    return {
+      outputs: {
+        isInState
+      }
+    };
+  }
+};
+__name(_IsInStateExecutor, "IsInStateExecutor");
+var IsInStateExecutor = _IsInStateExecutor;
+var WasInStateTemplate = {
+  type: "WasInState",
+  title: "Was In State",
+  category: "logic",
+  description: "Check if was previously in a specific state / \u68C0\u67E5\u4E4B\u524D\u662F\u5426\u5904\u4E8E\u7279\u5B9A\u72B6\u6001",
+  keywords: [
+    "fsm",
+    "state",
+    "was",
+    "previous",
+    "check"
+  ],
+  menuPath: [
+    "State Machine",
+    "Was In State"
+  ],
+  isPure: true,
+  inputs: [
+    {
+      name: "state",
+      displayName: "State",
+      type: "string",
+      defaultValue: ""
+    }
+  ],
+  outputs: [
+    {
+      name: "wasInState",
+      displayName: "Was In State",
+      type: "bool"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _WasInStateExecutor = class _WasInStateExecutor {
+  execute(node, context) {
+    const ctx = context;
+    const state = ctx.evaluateInput(node.id, "state", "");
+    const wasInState = state ? ctx.stateMachine?.previous === state : false;
+    return {
+      outputs: {
+        wasInState
+      }
+    };
+  }
+};
+__name(_WasInStateExecutor, "WasInStateExecutor");
+var WasInStateExecutor = _WasInStateExecutor;
+var GetStateDurationTemplate = {
+  type: "GetStateDuration",
+  title: "Get State Duration",
+  category: "logic",
+  description: "Get how long current state has been active / \u83B7\u53D6\u5F53\u524D\u72B6\u6001\u6301\u7EED\u65F6\u95F4",
+  keywords: [
+    "fsm",
+    "state",
+    "duration",
+    "time"
+  ],
+  menuPath: [
+    "State Machine",
+    "Get State Duration"
+  ],
+  isPure: true,
+  inputs: [],
+  outputs: [
+    {
+      name: "duration",
+      displayName: "Duration (ms)",
+      type: "float"
+    },
+    {
+      name: "seconds",
+      displayName: "Seconds",
+      type: "float"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _GetStateDurationExecutor = class _GetStateDurationExecutor {
+  execute(_node, context) {
+    const ctx = context;
+    const duration = ctx.stateMachine?.currentStateDuration ?? 0;
+    return {
+      outputs: {
+        duration,
+        seconds: duration / 1e3
+      }
+    };
+  }
+};
+__name(_GetStateDurationExecutor, "GetStateDurationExecutor");
+var GetStateDurationExecutor = _GetStateDurationExecutor;
+var EvaluateTransitionsTemplate = {
+  type: "EvaluateTransitions",
+  title: "Evaluate Transitions",
+  category: "logic",
+  description: "Evaluate and execute automatic transitions / \u8BC4\u4F30\u5E76\u6267\u884C\u81EA\u52A8\u8F6C\u6362",
+  keywords: [
+    "fsm",
+    "state",
+    "transition",
+    "evaluate",
+    "auto"
+  ],
+  menuPath: [
+    "State Machine",
+    "Evaluate Transitions"
+  ],
+  isPure: false,
+  inputs: [
+    {
+      name: "exec",
+      displayName: "",
+      type: "exec"
+    }
+  ],
+  outputs: [
+    {
+      name: "exec",
+      displayName: "",
+      type: "exec"
+    },
+    {
+      name: "transitioned",
+      displayName: "Transitioned",
+      type: "bool"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _EvaluateTransitionsExecutor = class _EvaluateTransitionsExecutor {
+  execute(_node, context) {
+    const ctx = context;
+    const transitioned = ctx.stateMachine?.evaluateTransitions() ?? false;
+    return {
+      outputs: {
+        transitioned
+      },
+      nextExec: "exec"
+    };
+  }
+};
+__name(_EvaluateTransitionsExecutor, "EvaluateTransitionsExecutor");
+var EvaluateTransitionsExecutor = _EvaluateTransitionsExecutor;
+var ResetStateMachineTemplate = {
+  type: "ResetStateMachine",
+  title: "Reset State Machine",
+  category: "logic",
+  description: "Reset state machine to initial state / \u91CD\u7F6E\u72B6\u6001\u673A\u5230\u521D\u59CB\u72B6\u6001",
+  keywords: [
+    "fsm",
+    "state",
+    "reset",
+    "initial"
+  ],
+  menuPath: [
+    "State Machine",
+    "Reset"
+  ],
+  isPure: false,
+  inputs: [
+    {
+      name: "exec",
+      displayName: "",
+      type: "exec"
+    },
+    {
+      name: "state",
+      displayName: "Initial State",
+      type: "string",
+      defaultValue: ""
+    }
+  ],
+  outputs: [
+    {
+      name: "exec",
+      displayName: "",
+      type: "exec"
+    }
+  ],
+  color: "#8b5a8b"
+};
+var _ResetStateMachineExecutor = class _ResetStateMachineExecutor {
+  execute(node, context) {
+    const ctx = context;
+    const state = ctx.evaluateInput(node.id, "state", "");
+    if (ctx.stateMachine) {
+      ctx.stateMachine.reset(state || void 0);
+    }
+    return {
+      outputs: {},
+      nextExec: "exec"
+    };
+  }
+};
+__name(_ResetStateMachineExecutor, "ResetStateMachineExecutor");
+var ResetStateMachineExecutor = _ResetStateMachineExecutor;
+var StateMachineNodeDefinitions = [
+  {
+    template: GetCurrentStateTemplate,
+    executor: new GetCurrentStateExecutor()
+  },
+  {
+    template: TransitionToTemplate,
+    executor: new TransitionToExecutor()
+  },
+  {
+    template: CanTransitionTemplate,
+    executor: new CanTransitionExecutor()
+  },
+  {
+    template: IsInStateTemplate,
+    executor: new IsInStateExecutor()
+  },
+  {
+    template: WasInStateTemplate,
+    executor: new WasInStateExecutor()
+  },
+  {
+    template: GetStateDurationTemplate,
+    executor: new GetStateDurationExecutor()
+  },
+  {
+    template: EvaluateTransitionsTemplate,
+    executor: new EvaluateTransitionsExecutor()
+  },
+  {
+    template: ResetStateMachineTemplate,
+    executor: new ResetStateMachineExecutor()
+  }
+];
+export {
+  CanTransitionExecutor,
+  CanTransitionTemplate,
+  EvaluateTransitionsExecutor,
+  EvaluateTransitionsTemplate,
+  GetCurrentStateExecutor,
+  GetCurrentStateTemplate,
+  GetStateDurationExecutor,
+  GetStateDurationTemplate,
+  IsInStateExecutor,
+  IsInStateTemplate,
+  ResetStateMachineExecutor,
+  ResetStateMachineTemplate,
+  StateMachine,
+  StateMachineNodeDefinitions,
+  StateMachineToken,
+  TransitionToExecutor,
+  TransitionToTemplate,
+  WasInStateExecutor,
+  WasInStateTemplate,
+  createStateMachine
+};
+//# sourceMappingURL=index.js.map