@eva/plugin-state-machine 2.1.0-beta.4 → 2.1.0-beta.6

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

@@ -32,6 +32,9 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+var StateMachine_1;
+/** 全局信号名:任意 reset() 都会 emit,供观测与跨实例联动 */
+const FSM_RESET_SIGNAL = 'fsm:reset';
 /**
  * StateMachine 组件 — 简易有限状态机。
  *
@@ -63,7 +66,7 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
  *
  * 不主动 emit 任何 lifecycle 信号超出上述列表;复杂语义请组合多个规则。
  */
-exports.StateMachine = class StateMachine extends eva_js.Component {
+exports.StateMachine = StateMachine_1 = class StateMachine extends eva_js.Component {
     constructor() {
         super(...arguments);
         this.states = {};
@@ -72,6 +75,8 @@ exports.StateMachine = class StateMachine extends eva_js.Component {
         this.subs = [];
         /** 上下文,guard 可读 */
         this.ctx = {};
+        /** reset() 用的 initial state 引用;init 时缓存一次,后续不变 */
+        this.initialState = '';
     }
     init(params) {
         var _a, _b;
@@ -81,18 +86,27 @@ exports.StateMachine = class StateMachine extends eva_js.Component {
         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(to, reason = 'manual') {
+    /**
+     * 主动迁移(代码侧也能调)。
+     *
+     * 第二参向后兼容两种形式:
+     * - `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)
+        if (this.current === to && !force)
             return;
         const from = this.current;
         if (from && ((_a = this.states[from]) === null || _a === void 0 ? void 0 : _a.onExit)) {
@@ -101,6 +115,92 @@ exports.StateMachine = class StateMachine extends eva_js.Component {
         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;
     }
@@ -172,22 +272,91 @@ exports.StateMachine = class StateMachine extends eva_js.Component {
     }
 };
 exports.StateMachine.componentName = 'StateMachine';
-exports.StateMachine = __decorate([
+exports.StateMachine = StateMachine_1 = __decorate([
     eva_js.decorators.componentObserver({})
 ], exports.StateMachine);
 
-/**
- * StateMachineSystem — 仅用于注册;StateMachine 自身在 Component.update 中驱动。
- *
- * 之所以保留这个空 System,是因为 Eva.js 的注册习惯是 component + system 成对出现,
- * 而且未来如果要加全局调度(例如 group: physics 在 HitArea 之后才能切状态)可以扩展这里。
- */
+/** 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

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var t=require("@eva/eva.js"),e=require("@eva/plugin-signal-bus");"function"==typeof SuppressedError&&SuppressedError,exports.StateMachine=class extends t.Component{constructor(){super(...arguments),this.states={},this.current="",this.elapsedInState=0,this.subs=[],this.ctx={}}init(t){var e,s;t&&(this.states=null!==(e=t.states)&&void 0!==e?e:{},this.signalChange=t.signalChange,this.ctx=null!==(s=t.context)&&void 0!==s?s:{},t.initial&&this.states[t.initial]&&this.enter(t.initial,"__init__"))}goto(t,s="manual"){var n;if(!this.states[t])return void console.warn(`[plugin-state-machine] no such state: ${t}`);if(this.current===t)return;const i=this.current;i&&(null===(n=this.states[i])||void 0===n?void 0:n.onExit)&&e.getSignalBus().emit(this.states[i].onExit,{from:i,to:t,reason:s}),this.cleanupSubs(),this.enter(t,s)}get state(){return this.current}enter(t,s){var n;const i=this.current;this.current=t,this.elapsedInState=0;const r=this.states[t];if(!r)return;r.onEnter&&e.getSignalBus().emit(r.onEnter,{from:i,to:t,reason:s}),this.signalChange&&e.getSignalBus().emit(this.signalChange,{from:i,to:t,reason:s});const a=e.getSignalBus();for(const e of null!==(n=r.transitions)&&void 0!==n?n:[]){if(!e.on)continue;const s=e.to,n=e.guard,i=a.on(e.on,()=>{this.current===t&&(n&&!this.evalGuard(n)||this.goto(s,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=function(t,e,s,n){var i,r=arguments.length,a=r<3?e:null===n?n=Object.getOwnPropertyDescriptor(e,s):n;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)a=Reflect.decorate(t,e,s,n);else for(var o=t.length-1;o>=0;o--)(i=t[o])&&(a=(r<3?i(a):r>3?i(e,s,a):i(e,s))||a);return r>3&&a&&Object.defineProperty(e,s,a),a}([t.decorators.componentObserver({})],exports.StateMachine);class s extends t.System{constructor(){super(...arguments),this.name="StateMachine"}}s.systemName="StateMachine",exports.StateMachineSystem=s;
+"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

@@ -1,6 +1,50 @@
 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;
@@ -51,8 +95,50 @@ export declare class StateMachine extends Component<StateMachineParams> {
     /** 上下文,guard 可读 */
     ctx: Record<string, any>;
     init(params?: StateMachineParams): void;
-    /** 主动迁移(代码侧也能调) */
-    goto(to: string, reason?: string): 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;
@@ -72,15 +158,59 @@ export declare interface StateMachineParams {
     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 — 仅用于注册;StateMachine 自身在 Component.update 中驱动。
+ * 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()`。
  *
- * 之所以保留这个空 System,是因为 Eva.js 的注册习惯是 component + system 成对出现,
- * 而且未来如果要加全局调度(例如 group: physics 在 HitArea 之后才能切状态)可以扩展这里。
+ * 默认行为可通过 `params.emitSceneSwitch = false` 关闭(纯静默注册)。
  */
-export declare class StateMachineSystem extends System {
-    static systemName: string;
-    readonly name = "StateMachine";
+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;
 }
 
 /** 单条迁移规则 */

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

@@ -28,6 +28,9 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+var StateMachine_1;
+/** 全局信号名:任意 reset() 都会 emit,供观测与跨实例联动 */
+const FSM_RESET_SIGNAL = 'fsm:reset';
 /**
  * StateMachine 组件 — 简易有限状态机。
  *
@@ -59,7 +62,7 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
  *
  * 不主动 emit 任何 lifecycle 信号超出上述列表;复杂语义请组合多个规则。
  */
-let StateMachine = class StateMachine extends Component {
+let StateMachine = StateMachine_1 = class StateMachine extends Component {
     constructor() {
         super(...arguments);
         this.states = {};
@@ -68,6 +71,8 @@ let StateMachine = class StateMachine extends Component {
         this.subs = [];
         /** 上下文,guard 可读 */
         this.ctx = {};
+        /** reset() 用的 initial state 引用;init 时缓存一次,后续不变 */
+        this.initialState = '';
     }
     init(params) {
         var _a, _b;
@@ -77,18 +82,27 @@ let StateMachine = class StateMachine extends Component {
         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(to, reason = 'manual') {
+    /**
+     * 主动迁移(代码侧也能调)。
+     *
+     * 第二参向后兼容两种形式:
+     * - `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)
+        if (this.current === to && !force)
             return;
         const from = this.current;
         if (from && ((_a = this.states[from]) === null || _a === void 0 ? void 0 : _a.onExit)) {
@@ -97,6 +111,92 @@ let StateMachine = class StateMachine extends Component {
         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;
     }
@@ -168,22 +268,89 @@ let StateMachine = class StateMachine extends Component {
     }
 };
 StateMachine.componentName = 'StateMachine';
-StateMachine = __decorate([
+StateMachine = StateMachine_1 = __decorate([
     decorators.componentObserver({})
 ], StateMachine);
 
-/**
- * StateMachineSystem — 仅用于注册;StateMachine 自身在 Component.update 中驱动。
- *
- * 之所以保留这个空 System,是因为 Eva.js 的注册习惯是 component + system 成对出现,
- * 而且未来如果要加全局调度(例如 group: physics 在 HitArea 之后才能切状态)可以扩展这里。
- */
+/** 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 { StateMachine, StateMachineSystem };
+export { FSM_RESET_SIGNAL, FSM_SCENE_SWITCH_SIGNAL, StateMachine, StateMachineSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-state-machine",
-  "version": "2.1.0-beta.4",
+  "version": "2.1.0-beta.6",
   "description": "Finite state machine — DSL 声明 states/transitions/timeouts/guards/actions,emit state-change 信号。",
   "main": "index.js",
   "module": "dist/plugin-state-machine.esm.js",
@@ -17,7 +17,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@eva/eva.js": "2.1.0-beta.4",
-    "@eva/plugin-signal-bus": "2.1.0-beta.4"
+    "@eva/eva.js": "2.1.0-beta.6",
+    "@eva/plugin-signal-bus": "2.1.0-beta.6"
   }
 }