@eva/plugin-evax 2.0.1-beta.27 → 2.0.1-beta.28

package/dist/EVA.plugin.EVAX.js

@@ -2,7 +2,6 @@ globalThis.EVA = globalThis.EVA || {};
 globalThis.EVA.plugin = globalThis.EVA.plugin || {};
 var _EVA_IIFE_EVAX = function (exports, eva_js) {
   'use strict';
-
   class EvaXComponent extends eva_js.Component {
     constructor(gameObject) {
       super(gameObject);

package/dist/plugin-evax.cjs.js

@@ -13,16 +13,62 @@ var EventEmitter__default = /*#__PURE__*/_interopDefaultLegacy(EventEmitter);
 var cloneDeep__default = /*#__PURE__*/_interopDefaultLegacy(cloneDeep);
 var isObject__default = /*#__PURE__*/_interopDefaultLegacy(isObject);
 
+/**
+ * EvaX 状态管理组件
+ *
+ * EvaXComponent 为游戏对象提供响应式状态管理能力，类似于前端框架的状态订阅机制。
+ * 通过监听全局 store 的变化，自动触发组件的回调函数，实现数据驱动的游戏逻辑。
+ *
+ * 主要功能：
+ * - 订阅全局 store 的属性变化
+ * - 支持深度监听（deep watch）
+ * - 自动绑定和解绑事件监听
+ * - 提供响应式数据更新机制
+ *
+ * @example
+ * ```typescript
+ * const player = new GameObject('player');
+ * player.addComponent(new EvaXComponent({
+ *   events: {
+ *     'store.playerHealth': function(newStore, oldStore) {
+ *       // 当 playerHealth 改变时触发
+ *       console.log('血量变化:', oldStore.playerHealth, '->', newStore.playerHealth);
+ *     },
+ *     'store.position': {
+ *       deep: true, // 深度监听
+ *       handler: function(newStore, oldStore) {
+ *         this.gameObject.transform.position = newStore.position;
+ *       }
+ *     }
+ *   }
+ * }));
+ * ```
+ */
 class EvaXComponent extends eva_js.Component {
+    /**
+     * 构造 EvaX 组件
+     * @param gameObject - 所属的游戏对象
+     */
     constructor(gameObject) {
         super(gameObject);
+        /** 事件监听配置对象，key 为 store 路径，value 为回调函数 */
+        // @decorators.IDEProp 复杂编辑后续添加
         this.events = {};
     }
+    /**
+     * 初始化组件
+     *
+     * 配置组件需要监听的 store 属性和对应的回调函数。
+     *
+     * @param option - 初始化配置
+     * @param option.events - 事件监听配置对象
+     */
     init(option = { events: {} }) {
         const { events } = option;
         this.events = events || {};
     }
 }
+/** 组件名称 */
 EvaXComponent.componentName = 'EvaX';
 
 /*! *****************************************************************************
@@ -109,11 +155,63 @@ function updateStore(store, newStore, force) {
     }
 }
 
+/**
+ * EvaX 状态管理系统
+ *
+ * EvaXSystem 提供全局状态管理和响应式数据绑定功能，类似于 Vuex 或 Redux。
+ * 它维护一个全局 store，并在 store 属性变化时通知订阅的组件。
+ * 通过 Object.defineProperty 实现数据劫持，自动追踪依赖和触发更新。
+ *
+ * 核心特性：
+ * - 全局状态 store 管理
+ * - 响应式数据绑定（基于 Object.defineProperty）
+ * - 支持深度监听对象嵌套属性
+ * - 事件驱动的更新机制
+ * - 批量更新优化（在 lateUpdate 中统一触发）
+ *
+ * @example
+ * ```typescript
+ * // 初始化系统并设置初始 store
+ * const evaxSystem = new EvaXSystem();
+ * game.addSystem(evaxSystem);
+ * evaxSystem.init({
+ *   store: {
+ *     playerHealth: 100,
+ *     score: 0,
+ *     position: { x: 0, y: 0 }
+ *   }
+ * });
+ *
+ * // 在游戏逻辑中更新 store
+ * evaxSystem.store.playerHealth -= 10; // 自动触发订阅者
+ *
+ * // 手动更新 store（会合并数据）
+ * evaxSystem.updateStore({ score: 100 });
+ *
+ * // 强制更新 store（会完全替换）
+ * evaxSystem.forceUpdateStore({ playerHealth: 100 });
+ *
+ * // 通过事件总线通信
+ * evaxSystem.on('gameOver', () => {
+ *   console.log('游戏结束');
+ * });
+ * evaxSystem.emit('gameOver');
+ * ```
+ */
 let EvaXSystem = class EvaXSystem extends eva_js.System {
     constructor() {
         super(...arguments);
+        /** 当前帧的 store 变化列表，在 lateUpdate 中批量处理 */
         this.changeList = [];
     }
+    /**
+     * 初始化系统
+     *
+     * 设置全局 store 并绑定默认的事件监听器。
+     *
+     * @param params - 初始化参数
+     * @param params.store - 初始的全局状态对象
+     */
     init({ store = {} } = { store: {} }) {
         this.ee = new EventEmitter__default();
         this.store = store;
@@ -153,6 +251,9 @@ let EvaXSystem = class EvaXSystem extends eva_js.System {
                 case eva_js.OBSERVER_TYPE.ADD:
                     this.add(changed);
                     break;
+                // case OBSERVER_TYPE.CHANGE:
+                //   this.change(changed)
+                //   break;
                 case eva_js.OBSERVER_TYPE.REMOVE:
                     this.remove(changed);
                     break;
@@ -201,6 +302,7 @@ let EvaXSystem = class EvaXSystem extends eva_js.System {
     }
     onDestroy() { }
 };
+/** 系统名称 */
 EvaXSystem.systemName = 'EvaX';
 EvaXSystem = __decorate([
     eva_js.decorators.componentObserver({

package/dist/plugin-evax.d.ts

@@ -9,11 +9,57 @@ declare const _default: {
 };
 export default _default;
 
+/**
+ * EvaX 状态管理组件
+ *
+ * EvaXComponent 为游戏对象提供响应式状态管理能力，类似于前端框架的状态订阅机制。
+ * 通过监听全局 store 的变化，自动触发组件的回调函数，实现数据驱动的游戏逻辑。
+ *
+ * 主要功能：
+ * - 订阅全局 store 的属性变化
+ * - 支持深度监听（deep watch）
+ * - 自动绑定和解绑事件监听
+ * - 提供响应式数据更新机制
+ *
+ * @example
+ * ```typescript
+ * const player = new GameObject('player');
+ * player.addComponent(new EvaXComponent({
+ *   events: {
+ *     'store.playerHealth': function(newStore, oldStore) {
+ *       // 当 playerHealth 改变时触发
+ *       console.log('血量变化:', oldStore.playerHealth, '->', newStore.playerHealth);
+ *     },
+ *     'store.position': {
+ *       deep: true, // 深度监听
+ *       handler: function(newStore, oldStore) {
+ *         this.gameObject.transform.position = newStore.position;
+ *       }
+ *     }
+ *   }
+ * }));
+ * ```
+ */
 export declare class EvaX extends Component<EvaXParams> {
+    /** 组件名称 */
     static componentName: string;
+    /**
+     * 构造 EvaX 组件
+     * @param gameObject - 所属的游戏对象
+     */
     constructor(gameObject: any);
+    /** EvaX 系统实例的引用 */
     evax: EvaXSystem;
+    /** 事件监听配置对象，key 为 store 路径，value 为回调函数 */
     events: Events;
+    /**
+     * 初始化组件
+     *
+     * 配置组件需要监听的 store 属性和对应的回调函数。
+     *
+     * @param option - 初始化配置
+     * @param option.events - 事件监听配置对象
+     */
     init(option?: EvaXParams): void;
 }
 
@@ -21,14 +67,69 @@ declare interface EvaXParams {
     events: Events;
 }
 
+/**
+ * EvaX 状态管理系统
+ *
+ * EvaXSystem 提供全局状态管理和响应式数据绑定功能，类似于 Vuex 或 Redux。
+ * 它维护一个全局 store，并在 store 属性变化时通知订阅的组件。
+ * 通过 Object.defineProperty 实现数据劫持，自动追踪依赖和触发更新。
+ *
+ * 核心特性：
+ * - 全局状态 store 管理
+ * - 响应式数据绑定（基于 Object.defineProperty）
+ * - 支持深度监听对象嵌套属性
+ * - 事件驱动的更新机制
+ * - 批量更新优化（在 lateUpdate 中统一触发）
+ *
+ * @example
+ * ```typescript
+ * // 初始化系统并设置初始 store
+ * const evaxSystem = new EvaXSystem();
+ * game.addSystem(evaxSystem);
+ * evaxSystem.init({
+ *   store: {
+ *     playerHealth: 100,
+ *     score: 0,
+ *     position: { x: 0, y: 0 }
+ *   }
+ * });
+ *
+ * // 在游戏逻辑中更新 store
+ * evaxSystem.store.playerHealth -= 10; // 自动触发订阅者
+ *
+ * // 手动更新 store（会合并数据）
+ * evaxSystem.updateStore({ score: 100 });
+ *
+ * // 强制更新 store（会完全替换）
+ * evaxSystem.forceUpdateStore({ playerHealth: 100 });
+ *
+ * // 通过事件总线通信
+ * evaxSystem.on('gameOver', () => {
+ *   console.log('游戏结束');
+ * });
+ * evaxSystem.emit('gameOver');
+ * ```
+ */
 export declare class EvaXSystem extends System<EvaXSystemParams> {
+    /** 系统名称 */
     static systemName: string;
+    /** 全局状态 store 对象 */
     store: any;
+    /** 内部事件发射器，用于事件通信 */
     private ee;
+    /** 当前帧的 store 变化列表，在 lateUpdate 中批量处理 */
     changeList: {
         key: string;
         oldStore: any;
     }[];
+    /**
+     * 初始化系统
+     *
+     * 设置全局 store 并绑定默认的事件监听器。
+     *
+     * @param params - 初始化参数
+     * @param params.store - 初始的全局状态对象
+     */
     init({ store }?: {
         store?: {};
     }): void;

package/dist/plugin-evax.esm.js

@@ -3,16 +3,62 @@ import EventEmitter from 'eventemitter3';
 import cloneDeep from 'lodash-es/cloneDeep';
 import isObject from 'lodash-es/isObject';
 
+/**
+ * EvaX 状态管理组件
+ *
+ * EvaXComponent 为游戏对象提供响应式状态管理能力，类似于前端框架的状态订阅机制。
+ * 通过监听全局 store 的变化，自动触发组件的回调函数，实现数据驱动的游戏逻辑。
+ *
+ * 主要功能：
+ * - 订阅全局 store 的属性变化
+ * - 支持深度监听（deep watch）
+ * - 自动绑定和解绑事件监听
+ * - 提供响应式数据更新机制
+ *
+ * @example
+ * ```typescript
+ * const player = new GameObject('player');
+ * player.addComponent(new EvaXComponent({
+ *   events: {
+ *     'store.playerHealth': function(newStore, oldStore) {
+ *       // 当 playerHealth 改变时触发
+ *       console.log('血量变化:', oldStore.playerHealth, '->', newStore.playerHealth);
+ *     },
+ *     'store.position': {
+ *       deep: true, // 深度监听
+ *       handler: function(newStore, oldStore) {
+ *         this.gameObject.transform.position = newStore.position;
+ *       }
+ *     }
+ *   }
+ * }));
+ * ```
+ */
 class EvaXComponent extends Component {
+    /**
+     * 构造 EvaX 组件
+     * @param gameObject - 所属的游戏对象
+     */
     constructor(gameObject) {
         super(gameObject);
+        /** 事件监听配置对象，key 为 store 路径，value 为回调函数 */
+        // @decorators.IDEProp 复杂编辑后续添加
         this.events = {};
     }
+    /**
+     * 初始化组件
+     *
+     * 配置组件需要监听的 store 属性和对应的回调函数。
+     *
+     * @param option - 初始化配置
+     * @param option.events - 事件监听配置对象
+     */
     init(option = { events: {} }) {
         const { events } = option;
         this.events = events || {};
     }
 }
+/** 组件名称 */
 EvaXComponent.componentName = 'EvaX';
 
 /*! *****************************************************************************
@@ -99,11 +145,63 @@ function updateStore(store, newStore, force) {
     }
 }
 
+/**
+ * EvaX 状态管理系统
+ *
+ * EvaXSystem 提供全局状态管理和响应式数据绑定功能，类似于 Vuex 或 Redux。
+ * 它维护一个全局 store，并在 store 属性变化时通知订阅的组件。
+ * 通过 Object.defineProperty 实现数据劫持，自动追踪依赖和触发更新。
+ *
+ * 核心特性：
+ * - 全局状态 store 管理
+ * - 响应式数据绑定（基于 Object.defineProperty）
+ * - 支持深度监听对象嵌套属性
+ * - 事件驱动的更新机制
+ * - 批量更新优化（在 lateUpdate 中统一触发）
+ *
+ * @example
+ * ```typescript
+ * // 初始化系统并设置初始 store
+ * const evaxSystem = new EvaXSystem();
+ * game.addSystem(evaxSystem);
+ * evaxSystem.init({
+ *   store: {
+ *     playerHealth: 100,
+ *     score: 0,
+ *     position: { x: 0, y: 0 }
+ *   }
+ * });
+ *
+ * // 在游戏逻辑中更新 store
+ * evaxSystem.store.playerHealth -= 10; // 自动触发订阅者
+ *
+ * // 手动更新 store（会合并数据）
+ * evaxSystem.updateStore({ score: 100 });
+ *
+ * // 强制更新 store（会完全替换）
+ * evaxSystem.forceUpdateStore({ playerHealth: 100 });
+ *
+ * // 通过事件总线通信
+ * evaxSystem.on('gameOver', () => {
+ *   console.log('游戏结束');
+ * });
+ * evaxSystem.emit('gameOver');
+ * ```
+ */
 let EvaXSystem = class EvaXSystem extends System {
     constructor() {
         super(...arguments);
+        /** 当前帧的 store 变化列表，在 lateUpdate 中批量处理 */
         this.changeList = [];
     }
+    /**
+     * 初始化系统
+     *
+     * 设置全局 store 并绑定默认的事件监听器。
+     *
+     * @param params - 初始化参数
+     * @param params.store - 初始的全局状态对象
+     */
     init({ store = {} } = { store: {} }) {
         this.ee = new EventEmitter();
         this.store = store;
@@ -143,6 +241,9 @@ let EvaXSystem = class EvaXSystem extends System {
                 case OBSERVER_TYPE.ADD:
                     this.add(changed);
                     break;
+                // case OBSERVER_TYPE.CHANGE:
+                //   this.change(changed)
+                //   break;
                 case OBSERVER_TYPE.REMOVE:
                     this.remove(changed);
                     break;
@@ -191,6 +292,7 @@ let EvaXSystem = class EvaXSystem extends System {
     }
     onDestroy() { }
 };
+/** 系统名称 */
 EvaXSystem.systemName = 'EvaX';
 EvaXSystem = __decorate([
     decorators.componentObserver({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-evax",
-  "version": "2.0.1-beta.27",
+  "version": "2.0.1-beta.28",
   "description": "@eva/plugin-evax",
   "main": "index.js",
   "module": "dist/plugin-evax.esm.js",
@@ -18,7 +18,7 @@
   "license": "MIT",
   "homepage": "https://eva.js.org",
   "dependencies": {
-    "@eva/eva.js": "2.0.1-beta.27",
+    "@eva/eva.js": "2.0.1-beta.28",
     "eventemitter3": "^3.1.2",
     "lodash-es": "^4.17.21"
   }