@eva/plugin-state-machine 2.1.0-beta.1 → 2.1.0-beta.10

package/dist/plugin-state-machine.cjs.js

@@ -0,0 +1,362 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var eva_js = require('@eva/eva.js');
+var pluginSignalBus = require('@eva/plugin-signal-bus');
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+var StateMachine_1;
+/** 全局信号名:任意 reset() 都会 emit,供观测与跨实例联动 */
+const FSM_RESET_SIGNAL = 'fsm:reset';
+/**
+ * StateMachine 组件 — 简易有限状态机。
+ *
+ * DSL 用法:
+ * ```json
+ * {
+ *   "type": "StateMachine",
+ *   "props": {
+ *     "initial": "moving",
+ *     "states": {
+ *       "moving":   { "onEnter": "monster:state-moving",
+ *                     "transitions": [
+ *                       { "on": "monster:hit", "to": "knockback" },
+ *                       { "after": 3000, "to": "resting" }
+ *                     ] },
+ *       "resting":  { "transitions": [{ "after": 1000, "to": "moving" }] },
+ *       "knockback":{ "transitions": [{ "after": 800, "to": "resting" }] }
+ *     },
+ *     "signalChange": "monster:state-change"
+ *   }
+ * }
+ * ```
+ *
+ * 行为:
+ * - 进入状态:emit `onEnter` + `signalChange` { from, to }
+ * - `transitions[i].on`: 监听信号,信号触发即迁移
+ * - `transitions[i].after`: 进入状态 N ms 后自动迁移
+ * - `transitions[i].guard`: JS 表达式,以 `ctx` 为变量,假则跳过该规则
+ *
+ * 不主动 emit 任何 lifecycle 信号超出上述列表;复杂语义请组合多个规则。
+ */
+exports.StateMachine = StateMachine_1 = class StateMachine extends eva_js.Component {
+    constructor() {
+        super(...arguments);
+        this.states = {};
+        this.current = '';
+        this.elapsedInState = 0;
+        this.subs = [];
+        /** 上下文,guard 可读 */
+        this.ctx = {};
+        /** reset() 用的 initial state 引用;init 时缓存一次,后续不变 */
+        this.initialState = '';
+    }
+    init(params) {
+        var _a, _b;
+        if (!params)
+            return;
+        this.states = (_a = params.states) !== null && _a !== void 0 ? _a : {};
+        this.signalChange = params.signalChange;
+        this.ctx = (_b = params.context) !== null && _b !== void 0 ? _b : {};
+        if (params.initial && this.states[params.initial]) {
+            this.initialState = params.initial;
+            this.enter(params.initial, '__init__');
+        }
+    }
+    /**
+     * 主动迁移(代码侧也能调)。
+     *
+     * 第二参向后兼容两种形式:
+     * - `goto('idle', 'manual')` 旧签名,等价于 `{ reason: 'manual' }`
+     * - `goto('idle', { reason: 'manual', force: true })` 新签名,`force:true` 时
+     *   即便 `current === to` 也走 exit→enter,用于"重入同 state 重新初始化定时器/订阅"
+     */
+    goto(to, opts = 'manual') {
+        var _a;
+        const { reason, force } = this.normalizeGotoOpts(opts);
+        if (!this.states[to]) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-state-machine] no such state: ${to}`);
+            return;
+        }
+        if (this.current === to && !force)
+            return;
+        const from = this.current;
+        if (from && ((_a = this.states[from]) === null || _a === void 0 ? void 0 : _a.onExit)) {
+            pluginSignalBus.getSignalBus().emit(this.states[from].onExit, { from, to, reason });
+        }
+        this.cleanupSubs();
+        this.enter(to, reason);
+    }
+    normalizeGotoOpts(opts) {
+        var _a;
+        if (typeof opts === 'string')
+            return { reason: opts, force: false };
+        return {
+            reason: (_a = opts.reason) !== null && _a !== void 0 ? _a : 'manual',
+            force: opts.force === true,
+        };
+    }
+    /**
+     * 显式 reset:强制回到 initial 并重发 onEnter,清掉所有挂在旧 state 上的订阅。
+     *
+     * 为什么独立于 goto:
+     * - 跨 scene 切换时,挂在 globalEntities 上的 FSM 实例不会被销毁;
+     *   `current` 保留旧值,旧 state 的 signal subs 仍生效,业务想"重置到 initial
+     *   重发 onEnter"时用 `goto(initial)` 会被 short-circuit。
+     * - `reset()` 走的是 `current = '' → enter(initial)`,绕过 short-circuit,
+     *   并 emit `'fsm:reset'` 让消费方观测。
+     * - 如果原 state 配了 `onExit`,会先 emit 一次再清订阅。
+     *
+     * 框架不会自动调 reset —— 跨 scene 是否要 reset 是消费方语义。
+     * StateMachineSystem 只在 sceneChanged 时 emit `'fsm:scene-switch'` 提醒。
+     */
+    reset(payload) {
+        var _a, _b;
+        const initial = this.initialState;
+        if (!initial) {
+            // eslint-disable-next-line no-console
+            console.warn('[plugin-state-machine] reset() called but no valid initial state');
+            return;
+        }
+        const fromState = this.current;
+        // 1. 先发 onExit(如果当前 state 有)
+        if (fromState && ((_a = this.states[fromState]) === null || _a === void 0 ? void 0 : _a.onExit)) {
+            pluginSignalBus.getSignalBus().emit(this.states[fromState].onExit, {
+                from: fromState,
+                to: initial,
+                reason: 'reset',
+            });
+        }
+        // 2. 清订阅 + 把 current 拉回空串,让 enter() 不被 short-circuit
+        this.cleanupSubs();
+        this.current = '';
+        // 3. 重发 onEnter(走 enter() 标准路径)
+        this.enter(initial, 'reset');
+        // 4. emit 全局观测信号
+        const resetPayload = {
+            entityId: (_b = this.gameObject) === null || _b === void 0 ? void 0 : _b.name,
+            fsmName: StateMachine_1.componentName,
+            fromState,
+            payload,
+        };
+        pluginSignalBus.getSignalBus().emit(FSM_RESET_SIGNAL, resetPayload);
+    }
+    /**
+     * 重发当前状态的 onEnter 信号(不 exit、不改 current、不重新订阅 transitions)。
+     *
+     * 用于 scene 切换 / restartScene 之后:globalEntities 上的 StateMachine 实例不销毁、
+     * 不发生状态转换,所以不会重发 onEnter;但本 scene 重建出的新 controller(如依赖
+     * `meta:fsm:enter:PLAYING` 激活的 cannon)需要这个信号才能 active。restartScene
+     * 完成后由 GlobalEntitiesManager 对 global StateMachine 调 reenterCurrent(),让新
+     * controller 收到 enter 信号(ADR-0017 选项 D)。
+     *
+     * 与 reset() 区别:reset 回 initial 并清订阅;reenterCurrent 保持当前状态,只补发
+     * onEnter(+ signalChange),订阅不动。
+     * 与 goto(current, {force}) 区别:force 会先 emit onExit 再重新订阅;reenterCurrent
+     * 不 exit、不重订阅(订阅还活着),更轻,适合 scene 切换后补发。
+     *
+     * 当前没进入任何状态(init 前)时是 no-op。
+     */
+    reenterCurrent(payload) {
+        if (!this.current)
+            return;
+        const cfg = this.states[this.current];
+        if (!cfg)
+            return;
+        const from = this.current;
+        const to = this.current;
+        const bus = pluginSignalBus.getSignalBus();
+        if (cfg.onEnter) {
+            bus.emit(cfg.onEnter, Object.assign({ from, to, reason: 'reenter' }, (payload || {})));
+        }
+        if (this.signalChange) {
+            bus.emit(this.signalChange, { from, to, reason: 'reenter' });
+        }
+    }
+    get state() {
+        return this.current;
+    }
+    enter(to, reason) {
+        var _a;
+        const from = this.current;
+        this.current = to;
+        this.elapsedInState = 0;
+        const cfg = this.states[to];
+        if (!cfg)
+            return;
+        if (cfg.onEnter)
+            pluginSignalBus.getSignalBus().emit(cfg.onEnter, { from, to, reason });
+        if (this.signalChange)
+            pluginSignalBus.getSignalBus().emit(this.signalChange, { from, to, reason });
+        // 订阅本 state 的 on 信号
+        const bus = pluginSignalBus.getSignalBus();
+        for (const t of (_a = cfg.transitions) !== null && _a !== void 0 ? _a : []) {
+            if (!t.on)
+                continue;
+            const target = t.to;
+            const guard = t.guard;
+            const h = bus.on(t.on, () => {
+                if (this.current !== to)
+                    return; // 已经离开
+                if (guard && !this.evalGuard(guard))
+                    return;
+                this.goto(target, t.on);
+            });
+            this.subs.push(h);
+        }
+    }
+    cleanupSubs() {
+        for (const h of this.subs)
+            h.dispose();
+        this.subs = [];
+    }
+    evalGuard(guard) {
+        try {
+            // 简单 expression eval,只暴露 ctx
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+            const fn = new Function('ctx', `return (${guard});`);
+            return Boolean(fn(this.ctx));
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-state-machine] bad guard "${guard}":`, err);
+            return false;
+        }
+    }
+    update(e) {
+        this.elapsedInState += e.deltaTime;
+        const cfg = this.states[this.current];
+        if (!(cfg === null || cfg === void 0 ? void 0 : cfg.transitions))
+            return;
+        for (const t of cfg.transitions) {
+            if (t.after == null)
+                continue;
+            if (this.elapsedInState < t.after)
+                continue;
+            if (t.guard && !this.evalGuard(t.guard))
+                continue;
+            this.goto(t.to, `after:${t.after}`);
+            return;
+        }
+    }
+    onDestroy() {
+        this.cleanupSubs();
+    }
+};
+exports.StateMachine.componentName = 'StateMachine';
+exports.StateMachine = StateMachine_1 = __decorate([
+    eva_js.decorators.componentObserver({})
+], exports.StateMachine);
+
+/** scene 切换观测信号:框架不自动 reset 任何 FSM,只 emit 让消费方决定 */
+const FSM_SCENE_SWITCH_SIGNAL = 'fsm:scene-switch';
+class StateMachineSystem extends eva_js.System {
+    constructor() {
+        super(...arguments);
+        this.name = 'StateMachine';
+        this.emitSceneSwitch = true;
+        this.autoResetOnSceneSwitch = false;
+        this.sceneChangedHandler = null;
+    }
+    init(params) {
+        if ((params === null || params === void 0 ? void 0 : params.emitSceneSwitch) === false)
+            this.emitSceneSwitch = false;
+        if ((params === null || params === void 0 ? void 0 : params.autoResetOnSceneSwitch) === true)
+            this.autoResetOnSceneSwitch = true;
+    }
+    awake() {
+        if (!this.emitSceneSwitch && !this.autoResetOnSceneSwitch)
+            return;
+        if (!this.game)
+            return;
+        this.sceneChangedHandler = (raw) => {
+            // game.emit('sceneChanged', { scene, mode, params }) — 透传整包,
+            // 同时把 scene 抽到顶层方便消费方判断
+            const scene = raw && typeof raw === 'object' && 'scene' in raw
+                ? raw.scene
+                : undefined;
+            if (this.emitSceneSwitch) {
+                const payload = { scene, raw };
+                pluginSignalBus.getSignalBus().emit(FSM_SCENE_SWITCH_SIGNAL, payload);
+            }
+            if (this.autoResetOnSceneSwitch) {
+                this.resetAllStateMachines();
+            }
+        };
+        this.game.on('sceneChanged', this.sceneChangedHandler);
+    }
+    /**
+     * 遍历 game.gameObjects 找所有 StateMachine Component 调 reset()。
+     * 仅在 `autoResetOnSceneSwitch === true` 时被 awake 钩子调用。
+     *
+     * 注意:walk 失败时 swallow error 不抛(scene 切换 latency 路径不应被
+     * 单个 FSM 异常阻断,fsm.reset 内部已有 fail-safe console.warn)。
+     */
+    resetAllStateMachines() {
+        var _a, _b, _c, _d, _e;
+        if (!this.game)
+            return;
+        const gameObjects = (_a = this.game.gameObjects) !== null && _a !== void 0 ? _a : [];
+        for (const go of gameObjects) {
+            if (!go || typeof go !== 'object')
+                continue;
+            const comps = (_b = go.components) !== null && _b !== void 0 ? _b : [];
+            for (const comp of comps) {
+                if (!comp)
+                    continue;
+                // duck-typing:同时识别 constructor.componentName 与 instance.name
+                const componentName = (_e = (_d = (_c = comp === null || comp === void 0 ? void 0 : comp.constructor) === null || _c === void 0 ? void 0 : _c.componentName) !== null && _d !== void 0 ? _d : comp === null || comp === void 0 ? void 0 : comp.name) !== null && _e !== void 0 ? _e : '';
+                if (componentName !== 'StateMachine')
+                    continue;
+                if (typeof comp.reset !== 'function')
+                    continue;
+                try {
+                    comp.reset();
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[plugin-state-machine] auto-reset failed:', err);
+                }
+            }
+        }
+    }
+    onDestroy() {
+        if (this.sceneChangedHandler && this.game) {
+            this.game.off('sceneChanged', this.sceneChangedHandler);
+        }
+        this.sceneChangedHandler = null;
+    }
+}
+StateMachineSystem.systemName = 'StateMachine';
+
+exports.FSM_RESET_SIGNAL = FSM_RESET_SIGNAL;
+exports.FSM_SCENE_SWITCH_SIGNAL = FSM_SCENE_SWITCH_SIGNAL;
+exports.StateMachineSystem = StateMachineSystem;

package/dist/plugin-state-machine.cjs.prod.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var t,e=require("@eva/eva.js"),n=require("@eva/plugin-signal-bus");"function"==typeof SuppressedError&&SuppressedError;const s="fsm:reset";exports.StateMachine=t=class extends e.Component{constructor(){super(...arguments),this.states={},this.current="",this.elapsedInState=0,this.subs=[],this.ctx={},this.initialState=""}init(t){var e,n;t&&(this.states=null!==(e=t.states)&&void 0!==e?e:{},this.signalChange=t.signalChange,this.ctx=null!==(n=t.context)&&void 0!==n?n:{},t.initial&&this.states[t.initial]&&(this.initialState=t.initial,this.enter(t.initial,"__init__")))}goto(t,e="manual"){var s;const{reason:i,force:o}=this.normalizeGotoOpts(e);if(!this.states[t])return void console.warn(`[plugin-state-machine] no such state: ${t}`);if(this.current===t&&!o)return;const a=this.current;a&&(null===(s=this.states[a])||void 0===s?void 0:s.onExit)&&n.getSignalBus().emit(this.states[a].onExit,{from:a,to:t,reason:i}),this.cleanupSubs(),this.enter(t,i)}normalizeGotoOpts(t){var e;return"string"==typeof t?{reason:t,force:!1}:{reason:null!==(e=t.reason)&&void 0!==e?e:"manual",force:!0===t.force}}reset(e){var i,o;const a=this.initialState;if(!a)return void console.warn("[plugin-state-machine] reset() called but no valid initial state");const r=this.current;r&&(null===(i=this.states[r])||void 0===i?void 0:i.onExit)&&n.getSignalBus().emit(this.states[r].onExit,{from:r,to:a,reason:"reset"}),this.cleanupSubs(),this.current="",this.enter(a,"reset");const c={entityId:null===(o=this.gameObject)||void 0===o?void 0:o.name,fsmName:t.componentName,fromState:r,payload:e};n.getSignalBus().emit(s,c)}reenterCurrent(t){if(!this.current)return;const e=this.states[this.current];if(!e)return;const s=this.current,i=this.current,o=n.getSignalBus();e.onEnter&&o.emit(e.onEnter,Object.assign({from:s,to:i,reason:"reenter"},t||{})),this.signalChange&&o.emit(this.signalChange,{from:s,to:i,reason:"reenter"})}get state(){return this.current}enter(t,e){var s;const i=this.current;this.current=t,this.elapsedInState=0;const o=this.states[t];if(!o)return;o.onEnter&&n.getSignalBus().emit(o.onEnter,{from:i,to:t,reason:e}),this.signalChange&&n.getSignalBus().emit(this.signalChange,{from:i,to:t,reason:e});const a=n.getSignalBus();for(const e of null!==(s=o.transitions)&&void 0!==s?s:[]){if(!e.on)continue;const n=e.to,s=e.guard,i=a.on(e.on,()=>{this.current===t&&(s&&!this.evalGuard(s)||this.goto(n,e.on))});this.subs.push(i)}}cleanupSubs(){for(const t of this.subs)t.dispose();this.subs=[]}evalGuard(t){try{const e=new Function("ctx",`return (${t});`);return Boolean(e(this.ctx))}catch(e){return console.warn(`[plugin-state-machine] bad guard "${t}":`,e),!1}}update(t){this.elapsedInState+=t.deltaTime;const e=this.states[this.current];if(null==e?void 0:e.transitions)for(const t of e.transitions)if(null!=t.after&&!(this.elapsedInState<t.after)&&(!t.guard||this.evalGuard(t.guard)))return void this.goto(t.to,`after:${t.after}`)}onDestroy(){this.cleanupSubs()}},exports.StateMachine.componentName="StateMachine",exports.StateMachine=t=function(t,e,n,s){var i,o=arguments.length,a=o<3?e:null===s?s=Object.getOwnPropertyDescriptor(e,n):s;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)a=Reflect.decorate(t,e,n,s);else for(var r=t.length-1;r>=0;r--)(i=t[r])&&(a=(o<3?i(a):o>3?i(e,n,a):i(e,n))||a);return o>3&&a&&Object.defineProperty(e,n,a),a}([e.decorators.componentObserver({})],exports.StateMachine);const i="fsm:scene-switch";class o extends e.System{constructor(){super(...arguments),this.name="StateMachine",this.emitSceneSwitch=!0,this.autoResetOnSceneSwitch=!1,this.sceneChangedHandler=null}init(t){!1===(null==t?void 0:t.emitSceneSwitch)&&(this.emitSceneSwitch=!1),!0===(null==t?void 0:t.autoResetOnSceneSwitch)&&(this.autoResetOnSceneSwitch=!0)}awake(){(this.emitSceneSwitch||this.autoResetOnSceneSwitch)&&this.game&&(this.sceneChangedHandler=t=>{const e=t&&"object"==typeof t&&"scene"in t?t.scene:void 0;if(this.emitSceneSwitch){const s={scene:e,raw:t};n.getSignalBus().emit(i,s)}this.autoResetOnSceneSwitch&&this.resetAllStateMachines()},this.game.on("sceneChanged",this.sceneChangedHandler))}resetAllStateMachines(){var t,e,n,s,i;if(!this.game)return;const o=null!==(t=this.game.gameObjects)&&void 0!==t?t:[];for(const t of o){if(!t||"object"!=typeof t)continue;const o=null!==(e=t.components)&&void 0!==e?e:[];for(const t of o){if(!t)continue;if("StateMachine"===(null!==(i=null!==(s=null===(n=null==t?void 0:t.constructor)||void 0===n?void 0:n.componentName)&&void 0!==s?s:null==t?void 0:t.name)&&void 0!==i?i:"")&&"function"==typeof t.reset)try{t.reset()}catch(t){console.warn("[plugin-state-machine] auto-reset failed:",t)}}}}onDestroy(){this.sceneChangedHandler&&this.game&&this.game.off("sceneChanged",this.sceneChangedHandler),this.sceneChangedHandler=null}}o.systemName="StateMachine",exports.FSM_RESET_SIGNAL=s,exports.FSM_SCENE_SWITCH_SIGNAL=i,exports.StateMachineSystem=o;

package/dist/plugin-state-machine.d.ts

@@ -0,0 +1,228 @@
+import { Component } from '@eva/eva.js';
+import { System } from '@eva/eva.js';
+
+/** 全局信号名:任意 reset() 都会 emit,供观测与跨实例联动 */
+export declare const FSM_RESET_SIGNAL = "fsm:reset";
+
+/** scene 切换观测信号:框架不自动 reset 任何 FSM,只 emit 让消费方决定 */
+export declare const FSM_SCENE_SWITCH_SIGNAL = "fsm:scene-switch";
+
+/**
+ * 全局信号 `'fsm:reset'` 的 payload。
+ * 任意 StateMachine.reset() 调用都会 emit 这条信号,便于消费方观测。
+ */
+export declare interface FsmResetPayload {
+    /** gameObject.name(在 framework 层是实体身份的最小可得线索) */
+    entityId: string | undefined;
+    /** 组件名(目前固定 'StateMachine',为未来子类预留) */
+    fsmName: string;
+    /** reset 前所处的 state(可能是 '' / initial / 任意业务 state) */
+    fromState: string;
+    /** 调用方透传的 payload(reset() 入参) */
+    payload?: any;
+}
+
+/**
+ * 全局信号 `'fsm:scene-switch'` 的 payload。
+ * StateMachineSystem 在 game `sceneChanged` 时 emit,**框架不自动 reset**,
+ * 消费方根据自己语义决定是否手动 reset 挂在 globalEntities 上的 FSM。
+ */
+export declare interface FsmSceneSwitchPayload {
+    /** 新 scene 标识(无法稳定取到时为 undefined) */
+    scene?: unknown;
+    /** game.emit('sceneChanged', payload) 的原始 payload 透传 */
+    raw?: unknown;
+}
+
+/** goto() 第二参可选 options;旧调用 goto(to, 'reason') 保留向后兼容 */
+export declare interface GotoOptions {
+    /** 迁移原因,落到 onEnter / onExit / signalChange payload 的 reason 字段 */
+    reason?: string;
+    /**
+     * 即便 current === to 也强制走 exit→enter 一遍。
+     * 默认 false(no-op short-circuit)。常用于"重入同一 state 重新初始化定时器/订阅"。
+     */
+    force?: boolean;
+}
+
+export declare interface StateConfig {
+    /** 进入时 emit 的信号 */
+    onEnter?: string;
+    /** 退出时 emit 的信号 */
+    onExit?: string;
+    /** 该状态下的迁移规则 */
+    transitions?: TransitionRule[];
+}
+
+/**
+ * StateMachine 组件 — 简易有限状态机。
+ *
+ * DSL 用法:
+ * ```json
+ * {
+ *   "type": "StateMachine",
+ *   "props": {
+ *     "initial": "moving",
+ *     "states": {
+ *       "moving":   { "onEnter": "monster:state-moving",
+ *                     "transitions": [
+ *                       { "on": "monster:hit", "to": "knockback" },
+ *                       { "after": 3000, "to": "resting" }
+ *                     ] },
+ *       "resting":  { "transitions": [{ "after": 1000, "to": "moving" }] },
+ *       "knockback":{ "transitions": [{ "after": 800, "to": "resting" }] }
+ *     },
+ *     "signalChange": "monster:state-change"
+ *   }
+ * }
+ * ```
+ *
+ * 行为:
+ * - 进入状态:emit `onEnter` + `signalChange` { from, to }
+ * - `transitions[i].on`: 监听信号,信号触发即迁移
+ * - `transitions[i].after`: 进入状态 N ms 后自动迁移
+ * - `transitions[i].guard`: JS 表达式,以 `ctx` 为变量,假则跳过该规则
+ *
+ * 不主动 emit 任何 lifecycle 信号超出上述列表;复杂语义请组合多个规则。
+ */
+export declare class StateMachine extends Component<StateMachineParams> {
+    static componentName: string;
+    private states;
+    private current;
+    private signalChange?;
+    private elapsedInState;
+    private subs;
+    /** 上下文,guard 可读 */
+    ctx: Record<string, any>;
+    init(params?: StateMachineParams): void;
+    /**
+     * 主动迁移(代码侧也能调)。
+     *
+     * 第二参向后兼容两种形式:
+     * - `goto('idle', 'manual')` 旧签名,等价于 `{ reason: 'manual' }`
+     * - `goto('idle', { reason: 'manual', force: true })` 新签名,`force:true` 时
+     *   即便 `current === to` 也走 exit→enter,用于"重入同 state 重新初始化定时器/订阅"
+     */
+    goto(to: string, opts?: string | GotoOptions): void;
+    private normalizeGotoOpts;
+    /**
+     * 显式 reset:强制回到 initial 并重发 onEnter,清掉所有挂在旧 state 上的订阅。
+     *
+     * 为什么独立于 goto:
+     * - 跨 scene 切换时,挂在 globalEntities 上的 FSM 实例不会被销毁;
+     *   `current` 保留旧值,旧 state 的 signal subs 仍生效,业务想"重置到 initial
+     *   重发 onEnter"时用 `goto(initial)` 会被 short-circuit。
+     * - `reset()` 走的是 `current = '' → enter(initial)`,绕过 short-circuit,
+     *   并 emit `'fsm:reset'` 让消费方观测。
+     * - 如果原 state 配了 `onExit`,会先 emit 一次再清订阅。
+     *
+     * 框架不会自动调 reset —— 跨 scene 是否要 reset 是消费方语义。
+     * StateMachineSystem 只在 sceneChanged 时 emit `'fsm:scene-switch'` 提醒。
+     */
+    reset(payload?: any): void;
+    /**
+     * 重发当前状态的 onEnter 信号(不 exit、不改 current、不重新订阅 transitions)。
+     *
+     * 用于 scene 切换 / restartScene 之后:globalEntities 上的 StateMachine 实例不销毁、
+     * 不发生状态转换,所以不会重发 onEnter;但本 scene 重建出的新 controller(如依赖
+     * `meta:fsm:enter:PLAYING` 激活的 cannon)需要这个信号才能 active。restartScene
+     * 完成后由 GlobalEntitiesManager 对 global StateMachine 调 reenterCurrent(),让新
+     * controller 收到 enter 信号(ADR-0017 选项 D)。
+     *
+     * 与 reset() 区别:reset 回 initial 并清订阅;reenterCurrent 保持当前状态,只补发
+     * onEnter(+ signalChange),订阅不动。
+     * 与 goto(current, {force}) 区别:force 会先 emit onExit 再重新订阅;reenterCurrent
+     * 不 exit、不重订阅(订阅还活着),更轻,适合 scene 切换后补发。
+     *
+     * 当前没进入任何状态(init 前)时是 no-op。
+     */
+    reenterCurrent(payload?: any): void;
+    /** reset() 用的 initial state 引用;init 时缓存一次,后续不变 */
+    private initialState;
+    get state(): string;
+    private enter;
+    private cleanupSubs;
+    private evalGuard;
+    update(e: {
+        deltaTime: number;
+    }): void;
+    onDestroy(): void;
+}
+
+export declare interface StateMachineParams {
+    initial: string;
+    states: Record<string, StateConfig>;
+    /** 状态切换 emit 信号 */
+    signalChange?: string;
+    /** 上下文变量,可在 guard 中读 */
+    context?: Record<string, any>;
+}
+
+export declare class StateMachineSystem extends System<StateMachineSystemParams> {
+    static systemName: string;
+    readonly name = "StateMachine";
+    private emitSceneSwitch;
+    private autoResetOnSceneSwitch;
+    private sceneChangedHandler;
+    init(params?: StateMachineSystemParams): void;
+    awake(): void;
+    /**
+     * 遍历 game.gameObjects 找所有 StateMachine Component 调 reset()。
+     * 仅在 `autoResetOnSceneSwitch === true` 时被 awake 钩子调用。
+     *
+     * 注意:walk 失败时 swallow error 不抛(scene 切换 latency 路径不应被
+     * 单个 FSM 异常阻断,fsm.reset 内部已有 fail-safe console.warn)。
+     */
+    private resetAllStateMachines;
+    onDestroy(): void;
+}
+
+/**
+ * StateMachineSystem — 仅用于注册 + scene 切换观测。
+ *
+ * StateMachine 自身在 Component.update 中驱动。本 System 不主动 tick FSM。
+ *
+ * 跨 scene 行为:
+ * - 挂在 globalEntities 上的 FSM 实例不会被销毁,`current` 保留旧值。
+ * - 业务可能希望"切场景后回到 initial 重发 onEnter",但**这是消费方语义**,
+ *   框架不能擅自 reset(否则关卡内 FSM 在 retry-scene 时全部清空,反而越权)。
+ * - 因此本 System 只在 game `sceneChanged` 时 emit `'fsm:scene-switch'` 信号,
+ *   消费方根据自己语义在监听器内调 `fsmComponent.reset()`。
+ *
+ * 默认行为可通过 `params.emitSceneSwitch = false` 关闭(纯静默注册)。
+ */
+declare interface StateMachineSystemParams {
+    /**
+     * 是否在 game `sceneChanged` 时 emit `'fsm:scene-switch'` 信号。默认 true。
+     * 关闭后挂载该 System 与原版空 System 等价。
+     */
+    emitSceneSwitch?: boolean;
+    /**
+     * 是否在 game `sceneChanged` 时自动对所有 StateMachine 实例调 `reset()`(ADR-0024B)。
+     *
+     * **默认 false**(向后兼容,与 ADR-0011/0017 "framework 不自动 reset"契约一致)。
+     *
+     * 设为 true 时,System 在 sceneChanged 后会:
+     *   1. 先 emit `'fsm:scene-switch'` 观测信号(保持既有契约)
+     *   2. 再 walk 当前 game.gameObjects,找所有 StateMachine Component 调 `reset()`
+     *
+     * 注意:scene-scoped 实体上的 FSM 会随 scene 销毁,reset 主要影响 globalEntities
+     * 上的 FSM。这是 ctx.fsm.attach(BehaviorContext)在 detach 时的 fallback —
+     * BehaviorScript 控制更细粒度的 attach handle 时不需要开启 autoReset。
+     */
+    autoResetOnSceneSwitch?: boolean;
+}
+
+/** 单条迁移规则 */
+export declare interface TransitionRule {
+    /** 触发该迁移的信号名 */
+    on?: string;
+    /** 进入该状态后等待 N ms 自动迁移(可与 on 二选一) */
+    after?: number;
+    /** 目标状态名 */
+    to: string;
+    /** 可选:JS 表达式字符串,以 ctx 为上下文 */
+    guard?: string;
+}
+
+export { }

package/dist/plugin-state-machine.esm.js

@@ -0,0 +1,356 @@
+import { Component, decorators, System } from '@eva/eva.js';
+import { getSignalBus } from '@eva/plugin-signal-bus';
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+var StateMachine_1;
+/** 全局信号名:任意 reset() 都会 emit,供观测与跨实例联动 */
+const FSM_RESET_SIGNAL = 'fsm:reset';
+/**
+ * StateMachine 组件 — 简易有限状态机。
+ *
+ * DSL 用法:
+ * ```json
+ * {
+ *   "type": "StateMachine",
+ *   "props": {
+ *     "initial": "moving",
+ *     "states": {
+ *       "moving":   { "onEnter": "monster:state-moving",
+ *                     "transitions": [
+ *                       { "on": "monster:hit", "to": "knockback" },
+ *                       { "after": 3000, "to": "resting" }
+ *                     ] },
+ *       "resting":  { "transitions": [{ "after": 1000, "to": "moving" }] },
+ *       "knockback":{ "transitions": [{ "after": 800, "to": "resting" }] }
+ *     },
+ *     "signalChange": "monster:state-change"
+ *   }
+ * }
+ * ```
+ *
+ * 行为:
+ * - 进入状态:emit `onEnter` + `signalChange` { from, to }
+ * - `transitions[i].on`: 监听信号,信号触发即迁移
+ * - `transitions[i].after`: 进入状态 N ms 后自动迁移
+ * - `transitions[i].guard`: JS 表达式,以 `ctx` 为变量,假则跳过该规则
+ *
+ * 不主动 emit 任何 lifecycle 信号超出上述列表;复杂语义请组合多个规则。
+ */
+let StateMachine = StateMachine_1 = class StateMachine extends Component {
+    constructor() {
+        super(...arguments);
+        this.states = {};
+        this.current = '';
+        this.elapsedInState = 0;
+        this.subs = [];
+        /** 上下文,guard 可读 */
+        this.ctx = {};
+        /** reset() 用的 initial state 引用;init 时缓存一次,后续不变 */
+        this.initialState = '';
+    }
+    init(params) {
+        var _a, _b;
+        if (!params)
+            return;
+        this.states = (_a = params.states) !== null && _a !== void 0 ? _a : {};
+        this.signalChange = params.signalChange;
+        this.ctx = (_b = params.context) !== null && _b !== void 0 ? _b : {};
+        if (params.initial && this.states[params.initial]) {
+            this.initialState = params.initial;
+            this.enter(params.initial, '__init__');
+        }
+    }
+    /**
+     * 主动迁移(代码侧也能调)。
+     *
+     * 第二参向后兼容两种形式:
+     * - `goto('idle', 'manual')` 旧签名,等价于 `{ reason: 'manual' }`
+     * - `goto('idle', { reason: 'manual', force: true })` 新签名,`force:true` 时
+     *   即便 `current === to` 也走 exit→enter,用于"重入同 state 重新初始化定时器/订阅"
+     */
+    goto(to, opts = 'manual') {
+        var _a;
+        const { reason, force } = this.normalizeGotoOpts(opts);
+        if (!this.states[to]) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-state-machine] no such state: ${to}`);
+            return;
+        }
+        if (this.current === to && !force)
+            return;
+        const from = this.current;
+        if (from && ((_a = this.states[from]) === null || _a === void 0 ? void 0 : _a.onExit)) {
+            getSignalBus().emit(this.states[from].onExit, { from, to, reason });
+        }
+        this.cleanupSubs();
+        this.enter(to, reason);
+    }
+    normalizeGotoOpts(opts) {
+        var _a;
+        if (typeof opts === 'string')
+            return { reason: opts, force: false };
+        return {
+            reason: (_a = opts.reason) !== null && _a !== void 0 ? _a : 'manual',
+            force: opts.force === true,
+        };
+    }
+    /**
+     * 显式 reset:强制回到 initial 并重发 onEnter,清掉所有挂在旧 state 上的订阅。
+     *
+     * 为什么独立于 goto:
+     * - 跨 scene 切换时,挂在 globalEntities 上的 FSM 实例不会被销毁;
+     *   `current` 保留旧值,旧 state 的 signal subs 仍生效,业务想"重置到 initial
+     *   重发 onEnter"时用 `goto(initial)` 会被 short-circuit。
+     * - `reset()` 走的是 `current = '' → enter(initial)`,绕过 short-circuit,
+     *   并 emit `'fsm:reset'` 让消费方观测。
+     * - 如果原 state 配了 `onExit`,会先 emit 一次再清订阅。
+     *
+     * 框架不会自动调 reset —— 跨 scene 是否要 reset 是消费方语义。
+     * StateMachineSystem 只在 sceneChanged 时 emit `'fsm:scene-switch'` 提醒。
+     */
+    reset(payload) {
+        var _a, _b;
+        const initial = this.initialState;
+        if (!initial) {
+            // eslint-disable-next-line no-console
+            console.warn('[plugin-state-machine] reset() called but no valid initial state');
+            return;
+        }
+        const fromState = this.current;
+        // 1. 先发 onExit(如果当前 state 有)
+        if (fromState && ((_a = this.states[fromState]) === null || _a === void 0 ? void 0 : _a.onExit)) {
+            getSignalBus().emit(this.states[fromState].onExit, {
+                from: fromState,
+                to: initial,
+                reason: 'reset',
+            });
+        }
+        // 2. 清订阅 + 把 current 拉回空串,让 enter() 不被 short-circuit
+        this.cleanupSubs();
+        this.current = '';
+        // 3. 重发 onEnter(走 enter() 标准路径)
+        this.enter(initial, 'reset');
+        // 4. emit 全局观测信号
+        const resetPayload = {
+            entityId: (_b = this.gameObject) === null || _b === void 0 ? void 0 : _b.name,
+            fsmName: StateMachine_1.componentName,
+            fromState,
+            payload,
+        };
+        getSignalBus().emit(FSM_RESET_SIGNAL, resetPayload);
+    }
+    /**
+     * 重发当前状态的 onEnter 信号(不 exit、不改 current、不重新订阅 transitions)。
+     *
+     * 用于 scene 切换 / restartScene 之后:globalEntities 上的 StateMachine 实例不销毁、
+     * 不发生状态转换,所以不会重发 onEnter;但本 scene 重建出的新 controller(如依赖
+     * `meta:fsm:enter:PLAYING` 激活的 cannon)需要这个信号才能 active。restartScene
+     * 完成后由 GlobalEntitiesManager 对 global StateMachine 调 reenterCurrent(),让新
+     * controller 收到 enter 信号(ADR-0017 选项 D)。
+     *
+     * 与 reset() 区别:reset 回 initial 并清订阅;reenterCurrent 保持当前状态,只补发
+     * onEnter(+ signalChange),订阅不动。
+     * 与 goto(current, {force}) 区别:force 会先 emit onExit 再重新订阅;reenterCurrent
+     * 不 exit、不重订阅(订阅还活着),更轻,适合 scene 切换后补发。
+     *
+     * 当前没进入任何状态(init 前)时是 no-op。
+     */
+    reenterCurrent(payload) {
+        if (!this.current)
+            return;
+        const cfg = this.states[this.current];
+        if (!cfg)
+            return;
+        const from = this.current;
+        const to = this.current;
+        const bus = getSignalBus();
+        if (cfg.onEnter) {
+            bus.emit(cfg.onEnter, Object.assign({ from, to, reason: 'reenter' }, (payload || {})));
+        }
+        if (this.signalChange) {
+            bus.emit(this.signalChange, { from, to, reason: 'reenter' });
+        }
+    }
+    get state() {
+        return this.current;
+    }
+    enter(to, reason) {
+        var _a;
+        const from = this.current;
+        this.current = to;
+        this.elapsedInState = 0;
+        const cfg = this.states[to];
+        if (!cfg)
+            return;
+        if (cfg.onEnter)
+            getSignalBus().emit(cfg.onEnter, { from, to, reason });
+        if (this.signalChange)
+            getSignalBus().emit(this.signalChange, { from, to, reason });
+        // 订阅本 state 的 on 信号
+        const bus = getSignalBus();
+        for (const t of (_a = cfg.transitions) !== null && _a !== void 0 ? _a : []) {
+            if (!t.on)
+                continue;
+            const target = t.to;
+            const guard = t.guard;
+            const h = bus.on(t.on, () => {
+                if (this.current !== to)
+                    return; // 已经离开
+                if (guard && !this.evalGuard(guard))
+                    return;
+                this.goto(target, t.on);
+            });
+            this.subs.push(h);
+        }
+    }
+    cleanupSubs() {
+        for (const h of this.subs)
+            h.dispose();
+        this.subs = [];
+    }
+    evalGuard(guard) {
+        try {
+            // 简单 expression eval,只暴露 ctx
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+            const fn = new Function('ctx', `return (${guard});`);
+            return Boolean(fn(this.ctx));
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-state-machine] bad guard "${guard}":`, err);
+            return false;
+        }
+    }
+    update(e) {
+        this.elapsedInState += e.deltaTime;
+        const cfg = this.states[this.current];
+        if (!(cfg === null || cfg === void 0 ? void 0 : cfg.transitions))
+            return;
+        for (const t of cfg.transitions) {
+            if (t.after == null)
+                continue;
+            if (this.elapsedInState < t.after)
+                continue;
+            if (t.guard && !this.evalGuard(t.guard))
+                continue;
+            this.goto(t.to, `after:${t.after}`);
+            return;
+        }
+    }
+    onDestroy() {
+        this.cleanupSubs();
+    }
+};
+StateMachine.componentName = 'StateMachine';
+StateMachine = StateMachine_1 = __decorate([
+    decorators.componentObserver({})
+], StateMachine);
+
+/** scene 切换观测信号:框架不自动 reset 任何 FSM,只 emit 让消费方决定 */
+const FSM_SCENE_SWITCH_SIGNAL = 'fsm:scene-switch';
+class StateMachineSystem extends System {
+    constructor() {
+        super(...arguments);
+        this.name = 'StateMachine';
+        this.emitSceneSwitch = true;
+        this.autoResetOnSceneSwitch = false;
+        this.sceneChangedHandler = null;
+    }
+    init(params) {
+        if ((params === null || params === void 0 ? void 0 : params.emitSceneSwitch) === false)
+            this.emitSceneSwitch = false;
+        if ((params === null || params === void 0 ? void 0 : params.autoResetOnSceneSwitch) === true)
+            this.autoResetOnSceneSwitch = true;
+    }
+    awake() {
+        if (!this.emitSceneSwitch && !this.autoResetOnSceneSwitch)
+            return;
+        if (!this.game)
+            return;
+        this.sceneChangedHandler = (raw) => {
+            // game.emit('sceneChanged', { scene, mode, params }) — 透传整包,
+            // 同时把 scene 抽到顶层方便消费方判断
+            const scene = raw && typeof raw === 'object' && 'scene' in raw
+                ? raw.scene
+                : undefined;
+            if (this.emitSceneSwitch) {
+                const payload = { scene, raw };
+                getSignalBus().emit(FSM_SCENE_SWITCH_SIGNAL, payload);
+            }
+            if (this.autoResetOnSceneSwitch) {
+                this.resetAllStateMachines();
+            }
+        };
+        this.game.on('sceneChanged', this.sceneChangedHandler);
+    }
+    /**
+     * 遍历 game.gameObjects 找所有 StateMachine Component 调 reset()。
+     * 仅在 `autoResetOnSceneSwitch === true` 时被 awake 钩子调用。
+     *
+     * 注意:walk 失败时 swallow error 不抛(scene 切换 latency 路径不应被
+     * 单个 FSM 异常阻断,fsm.reset 内部已有 fail-safe console.warn)。
+     */
+    resetAllStateMachines() {
+        var _a, _b, _c, _d, _e;
+        if (!this.game)
+            return;
+        const gameObjects = (_a = this.game.gameObjects) !== null && _a !== void 0 ? _a : [];
+        for (const go of gameObjects) {
+            if (!go || typeof go !== 'object')
+                continue;
+            const comps = (_b = go.components) !== null && _b !== void 0 ? _b : [];
+            for (const comp of comps) {
+                if (!comp)
+                    continue;
+                // duck-typing:同时识别 constructor.componentName 与 instance.name
+                const componentName = (_e = (_d = (_c = comp === null || comp === void 0 ? void 0 : comp.constructor) === null || _c === void 0 ? void 0 : _c.componentName) !== null && _d !== void 0 ? _d : comp === null || comp === void 0 ? void 0 : comp.name) !== null && _e !== void 0 ? _e : '';
+                if (componentName !== 'StateMachine')
+                    continue;
+                if (typeof comp.reset !== 'function')
+                    continue;
+                try {
+                    comp.reset();
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[plugin-state-machine] auto-reset failed:', err);
+                }
+            }
+        }
+    }
+    onDestroy() {
+        if (this.sceneChangedHandler && this.game) {
+            this.game.off('sceneChanged', this.sceneChangedHandler);
+        }
+        this.sceneChangedHandler = null;
+    }
+}
+StateMachineSystem.systemName = 'StateMachine';
+
+export { FSM_RESET_SIGNAL, FSM_SCENE_SWITCH_SIGNAL, StateMachine, StateMachineSystem };

package/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('./dist/plugin-state-machine.cjs.prod.js');
+} else {
+  module.exports = require('./dist/plugin-state-machine.cjs.js');
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@eva/plugin-state-machine",
-  "version": "2.1.0-beta.1",
+  "version": "2.1.0-beta.10",
   "description": "Finite state machine — DSL 声明 states/transitions/timeouts/guards/actions,emit state-change 信号。",
-  "main": "lib/index.ts",
-  "module": "lib/index.ts",
-  "types": "lib/index.ts",
+  "main": "index.js",
+  "module": "dist/plugin-state-machine.esm.js",
+  "types": "dist/plugin-state-machine.d.ts",
   "files": [
-    "lib"
+    "index.js",
+    "dist"
   ],
   "keywords": [
     "eva.js",
@@ -16,7 +17,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@eva/eva.js": "2.1.0-beta.1",
-    "@eva/plugin-signal-bus": "2.1.0-beta.1"
+    "@eva/eva.js": "2.1.0-beta.10",
+    "@eva/plugin-signal-bus": "2.1.0-beta.10"
   }
 }

package/lib/StateMachine.ts

@@ -1,136 +0,0 @@
-import { Component, decorators } from '@eva/eva.js';
-import { getSignalBus, SignalHandle } from '@eva/plugin-signal-bus';
-import type { StateMachineParams, StateConfig } from './types';
-
-/**
- * StateMachine 组件 — 简易有限状态机。
- *
- * DSL 用法:
- * ```json
- * {
- *   "type": "StateMachine",
- *   "props": {
- *     "initial": "moving",
- *     "states": {
- *       "moving":   { "onEnter": "monster:state-moving",
- *                     "transitions": [
- *                       { "on": "monster:hit", "to": "knockback" },
- *                       { "after": 3000, "to": "resting" }
- *                     ] },
- *       "resting":  { "transitions": [{ "after": 1000, "to": "moving" }] },
- *       "knockback":{ "transitions": [{ "after": 800, "to": "resting" }] }
- *     },
- *     "signalChange": "monster:state-change"
- *   }
- * }
- * ```
- *
- * 行为:
- * - 进入状态:emit `onEnter` + `signalChange` { from, to }
- * - `transitions[i].on`: 监听信号,信号触发即迁移
- * - `transitions[i].after`: 进入状态 N ms 后自动迁移
- * - `transitions[i].guard`: JS 表达式,以 `ctx` 为变量,假则跳过该规则
- *
- * 不主动 emit 任何 lifecycle 信号超出上述列表;复杂语义请组合多个规则。
- */
-@decorators.componentObserver({})
-export class StateMachine extends Component<StateMachineParams> {
-  static componentName = 'StateMachine';
-
-  private states: Record<string, StateConfig> = {};
-  private current: string = '';
-  private signalChange?: string;
-  private elapsedInState = 0;
-  private subs: SignalHandle[] = [];
-
-  /** 上下文,guard 可读 */
-  ctx: Record<string, any> = {};
-
-  init(params?: StateMachineParams) {
-    if (!params) return;
-    this.states = params.states ?? {};
-    this.signalChange = params.signalChange;
-    this.ctx = params.context ?? {};
-    if (params.initial && this.states[params.initial]) {
-      this.enter(params.initial, '__init__');
-    }
-  }
-
-  /** 主动迁移(代码侧也能调) */
-  goto(to: string, reason: string = 'manual') {
-    if (!this.states[to]) {
-      // eslint-disable-next-line no-console
-      console.warn(`[plugin-state-machine] no such state: ${to}`);
-      return;
-    }
-    if (this.current === to) return;
-    const from = this.current;
-    if (from && this.states[from]?.onExit) {
-      getSignalBus().emit(this.states[from].onExit!, { from, to, reason });
-    }
-    this.cleanupSubs();
-    this.enter(to, reason);
-  }
-
-  get state(): string {
-    return this.current;
-  }
-
-  private enter(to: string, reason: string) {
-    const from = this.current;
-    this.current = to;
-    this.elapsedInState = 0;
-    const cfg = this.states[to];
-    if (!cfg) return;
-    if (cfg.onEnter) getSignalBus().emit(cfg.onEnter, { from, to, reason });
-    if (this.signalChange) getSignalBus().emit(this.signalChange, { from, to, reason });
-    // 订阅本 state 的 on 信号
-    const bus = getSignalBus();
-    for (const t of cfg.transitions ?? []) {
-      if (!t.on) continue;
-      const target = t.to;
-      const guard = t.guard;
-      const h = bus.on(t.on, () => {
-        if (this.current !== to) return; // 已经离开
-        if (guard && !this.evalGuard(guard)) return;
-        this.goto(target, t.on!);
-      });
-      this.subs.push(h);
-    }
-  }
-
-  private cleanupSubs() {
-    for (const h of this.subs) h.dispose();
-    this.subs = [];
-  }
-
-  private evalGuard(guard: string): boolean {
-    try {
-      // 简单 expression eval,只暴露 ctx
-      // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
-      const fn = new Function('ctx', `return (${guard});`);
-      return Boolean(fn(this.ctx));
-    } catch (err) {
-      // eslint-disable-next-line no-console
-      console.warn(`[plugin-state-machine] bad guard "${guard}":`, err);
-      return false;
-    }
-  }
-
-  update(e: { deltaTime: number }) {
-    this.elapsedInState += e.deltaTime;
-    const cfg = this.states[this.current];
-    if (!cfg?.transitions) return;
-    for (const t of cfg.transitions) {
-      if (t.after == null) continue;
-      if (this.elapsedInState < t.after) continue;
-      if (t.guard && !this.evalGuard(t.guard)) continue;
-      this.goto(t.to, `after:${t.after}`);
-      return;
-    }
-  }
-
-  onDestroy() {
-    this.cleanupSubs();
-  }
-}

package/lib/StateMachineSystem.ts

@@ -1,12 +0,0 @@
-import { System } from '@eva/eva.js';
-
-/**
- * StateMachineSystem — 仅用于注册;StateMachine 自身在 Component.update 中驱动。
- *
- * 之所以保留这个空 System,是因为 Eva.js 的注册习惯是 component + system 成对出现,
- * 而且未来如果要加全局调度(例如 group: physics 在 HitArea 之后才能切状态)可以扩展这里。
- */
-export class StateMachineSystem extends System {
-  static systemName = 'StateMachine';
-  readonly name = 'StateMachine';
-}

package/lib/index.ts

@@ -1,3 +0,0 @@
-export { StateMachine } from './StateMachine';
-export { StateMachineSystem } from './StateMachineSystem';
-export type { StateMachineParams, StateConfig, TransitionRule } from './types';

package/lib/types.ts

@@ -1,29 +0,0 @@
-/** 单条迁移规则 */
-export interface TransitionRule {
-  /** 触发该迁移的信号名 */
-  on?: string;
-  /** 进入该状态后等待 N ms 自动迁移(可与 on 二选一) */
-  after?: number;
-  /** 目标状态名 */
-  to: string;
-  /** 可选:JS 表达式字符串,以 ctx 为上下文 */
-  guard?: string;
-}
-
-export interface StateConfig {
-  /** 进入时 emit 的信号 */
-  onEnter?: string;
-  /** 退出时 emit 的信号 */
-  onExit?: string;
-  /** 该状态下的迁移规则 */
-  transitions?: TransitionRule[];
-}
-
-export interface StateMachineParams {
-  initial: string;
-  states: Record<string, StateConfig>;
-  /** 状态切换 emit 信号 */
-  signalChange?: string;
-  /** 上下文变量,可在 guard 中读 */
-  context?: Record<string, any>;
-}