@eva/plugin-state-machine 2.1.0-beta.3 → 2.1.0-beta.5

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,60 @@ 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);
+    }
     get state() {
         return this.current;
     }
@@ -172,22 +240,48 @@ 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.sceneChangedHandler = null;
+    }
+    init(params) {
+        if ((params === null || params === void 0 ? void 0 : params.emitSceneSwitch) === false)
+            this.emitSceneSwitch = false;
+    }
+    awake() {
+        if (!this.emitSceneSwitch)
+            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;
+            const payload = { scene, raw };
+            pluginSignalBus.getSignalBus().emit(FSM_SCENE_SWITCH_SIGNAL, payload);
+        };
+        this.game.on('sceneChanged', this.sceneChangedHandler);
+    }
+    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"),s=require("@eva/plugin-signal-bus");"function"==typeof SuppressedError&&SuppressedError;const n="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,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.initialState=t.initial,this.enter(t.initial,"__init__")))}goto(t,e="manual"){var n;const{reason:i,force:a}=this.normalizeGotoOpts(e);if(!this.states[t])return void console.warn(`[plugin-state-machine] no such state: ${t}`);if(this.current===t&&!a)return;const r=this.current;r&&(null===(n=this.states[r])||void 0===n?void 0:n.onExit)&&s.getSignalBus().emit(this.states[r].onExit,{from:r,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,a;const r=this.initialState;if(!r)return void console.warn("[plugin-state-machine] reset() called but no valid initial state");const o=this.current;o&&(null===(i=this.states[o])||void 0===i?void 0:i.onExit)&&s.getSignalBus().emit(this.states[o].onExit,{from:o,to:r,reason:"reset"}),this.cleanupSubs(),this.current="",this.enter(r,"reset");const c={entityId:null===(a=this.gameObject)||void 0===a?void 0:a.name,fsmName:t.componentName,fromState:o,payload:e};s.getSignalBus().emit(n,c)}get state(){return this.current}enter(t,e){var n;const i=this.current;this.current=t,this.elapsedInState=0;const a=this.states[t];if(!a)return;a.onEnter&&s.getSignalBus().emit(a.onEnter,{from:i,to:t,reason:e}),this.signalChange&&s.getSignalBus().emit(this.signalChange,{from:i,to:t,reason:e});const r=s.getSignalBus();for(const e of null!==(n=a.transitions)&&void 0!==n?n:[]){if(!e.on)continue;const s=e.to,n=e.guard,i=r.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=t=function(t,e,s,n){var i,a=arguments.length,r=a<3?e:null===n?n=Object.getOwnPropertyDescriptor(e,s):n;if("object"==typeof Reflect&&"function"==typeof Reflect.decorate)r=Reflect.decorate(t,e,s,n);else for(var o=t.length-1;o>=0;o--)(i=t[o])&&(r=(a<3?i(r):a>3?i(e,s,r):i(e,s))||r);return a>3&&r&&Object.defineProperty(e,s,r),r}([e.decorators.componentObserver({})],exports.StateMachine);const i="fsm:scene-switch";class a extends e.System{constructor(){super(...arguments),this.name="StateMachine",this.emitSceneSwitch=!0,this.sceneChangedHandler=null}init(t){!1===(null==t?void 0:t.emitSceneSwitch)&&(this.emitSceneSwitch=!1)}awake(){this.emitSceneSwitch&&this.game&&(this.sceneChangedHandler=t=>{const e={scene:t&&"object"==typeof t&&"scene"in t?t.scene:void 0,raw:t};s.getSignalBus().emit(i,e)},this.game.on("sceneChanged",this.sceneChangedHandler))}onDestroy(){this.sceneChangedHandler&&this.game&&this.game.off("sceneChanged",this.sceneChangedHandler),this.sceneChangedHandler=null}}a.systemName="StateMachine",exports.FSM_RESET_SIGNAL=n,exports.FSM_SCENE_SWITCH_SIGNAL=i,exports.StateMachineSystem=a;

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,33 @@ 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;
+    /** reset() 用的 initial state 引用;init 时缓存一次,后续不变 */
+    private initialState;
     get state(): string;
     private enter;
     private cleanupSubs;
@@ -72,15 +141,36 @@ export declare interface StateMachineParams {
     context?: Record<string, any>;
 }
 
+export declare class StateMachineSystem extends System<StateMachineSystemParams> {
+    static systemName: string;
+    readonly name = "StateMachine";
+    private emitSceneSwitch;
+    private sceneChangedHandler;
+    init(params?: StateMachineSystemParams): void;
+    awake(): void;
+    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;
 }
 
 /** 单条迁移规则 */

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,60 @@ 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);
+    }
     get state() {
         return this.current;
     }
@@ -168,22 +236,46 @@ 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.sceneChangedHandler = null;
+    }
+    init(params) {
+        if ((params === null || params === void 0 ? void 0 : params.emitSceneSwitch) === false)
+            this.emitSceneSwitch = false;
+    }
+    awake() {
+        if (!this.emitSceneSwitch)
+            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;
+            const payload = { scene, raw };
+            getSignalBus().emit(FSM_SCENE_SWITCH_SIGNAL, payload);
+        };
+        this.game.on('sceneChanged', this.sceneChangedHandler);
+    }
+    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.3",
+  "version": "2.1.0-beta.5",
   "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.3",
-    "@eva/plugin-signal-bus": "2.1.0-beta.3"
+    "@eva/eva.js": "2.1.0-beta.5",
+    "@eva/plugin-signal-bus": "2.1.0-beta.5"
   }
 }