@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/Core.js

@@ -0,0 +1,553 @@
+import { TimerManager } from './Utils/Timers/TimerManager';
+import { Time } from './Utils/Time';
+import { PerformanceMonitor } from './Utils/PerformanceMonitor';
+import { PoolManager } from './Utils/Pool/PoolManager';
+import { DebugManager } from './Utils/Debug';
+import { createLogger } from './Utils/Logger';
+import { SceneManager } from './ECS/SceneManager';
+import { ServiceContainer } from './Core/ServiceContainer';
+import { PluginManager } from './Core/PluginManager';
+import { WorldManager } from './ECS/WorldManager';
+import { DebugConfigService } from './Utils/Debug/DebugConfigService';
+import { createInstance } from './Core/DI/Decorators';
+/**
+ * 游戏引擎核心类
+ *
+ * 职责：
+ * - 提供全局服务（Timer、Performance、Pool等）
+ * - 管理场景生命周期（内置SceneManager）
+ * - 管理全局管理器的生命周期
+ * - 提供统一的游戏循环更新入口
+ *
+ * @example
+ * ```typescript
+ * // 初始化并设置场景
+ * Core.create({ debug: true });
+ * Core.setScene(new GameScene());
+ *
+ * // 游戏循环（自动更新全局服务和场景）
+ * function gameLoop(deltaTime: number) {
+ *     Core.update(deltaTime);
+ * }
+ *
+ * // 使用定时器
+ * Core.schedule(1.0, false, null, (timer) => {
+ *     console.log("1秒后执行");
+ * });
+ *
+ * // 切换场景
+ * Core.loadScene(new MenuScene());  // 延迟切换
+ * Core.setScene(new GameScene());   // 立即切换
+ *
+ * // 获取当前场景
+ * const currentScene = Core.scene;
+ * ```
+ */
+export class Core {
+    /**
+     * 创建核心实例
+     *
+     * @param config - Core配置对象
+     */
+    constructor(config = {}) {
+        Core._instance = this;
+        // 保存配置
+        this._config = {
+            debug: true,
+            ...config
+        };
+        // 初始化服务容器
+        this._serviceContainer = new ServiceContainer();
+        // 初始化定时器管理器
+        this._timerManager = new TimerManager();
+        this._serviceContainer.registerInstance(TimerManager, this._timerManager);
+        // 初始化性能监控器
+        this._performanceMonitor = new PerformanceMonitor();
+        this._serviceContainer.registerInstance(PerformanceMonitor, this._performanceMonitor);
+        // 在调试模式下启用性能监控
+        if (this._config.debug) {
+            this._performanceMonitor.enable();
+        }
+        // 初始化对象池管理器
+        this._poolManager = new PoolManager();
+        this._serviceContainer.registerInstance(PoolManager, this._poolManager);
+        // 初始化场景管理器
+        this._sceneManager = new SceneManager(this._performanceMonitor);
+        this._serviceContainer.registerInstance(SceneManager, this._sceneManager);
+        // 设置场景切换回调，通知调试管理器
+        this._sceneManager.setSceneChangedCallback(() => {
+            if (this._debugManager) {
+                this._debugManager.onSceneChanged();
+            }
+        });
+        // 初始化World管理器
+        this._worldManager = new WorldManager({ debug: !!this._config.debug, ...this._config.worldManagerConfig });
+        this._serviceContainer.registerInstance(WorldManager, this._worldManager);
+        // 初始化插件管理器
+        this._pluginManager = new PluginManager();
+        this._pluginManager.initialize(this, this._serviceContainer);
+        this._serviceContainer.registerInstance(PluginManager, this._pluginManager);
+        this.debug = this._config.debug ?? true;
+        // 初始化调试管理器
+        if (this._config.debugConfig?.enabled) {
+            const configService = new DebugConfigService();
+            configService.setConfig(this._config.debugConfig);
+            this._serviceContainer.registerInstance(DebugConfigService, configService);
+            this._serviceContainer.registerSingleton(DebugManager, (c) => createInstance(DebugManager, c));
+            this._debugManager = this._serviceContainer.resolve(DebugManager);
+            this._debugManager.onInitialize();
+        }
+        this.initialize();
+    }
+    /**
+     * 获取核心实例
+     *
+     * @returns 全局核心实例
+     */
+    static get Instance() {
+        return this._instance;
+    }
+    /**
+     * 获取服务容器
+     *
+     * 用于注册和解析自定义服务。
+     *
+     * @returns 服务容器实例
+     * @throws 如果Core实例未创建
+     *
+     * @example
+     * ```typescript
+     * // 注册自定义服务
+     * Core.services.registerSingleton(MyService);
+     *
+     * // 解析服务
+     * const myService = Core.services.resolve(MyService);
+     * ```
+     */
+    static get services() {
+        if (!this._instance) {
+            throw new Error('Core实例未创建，请先调用Core.create()');
+        }
+        return this._instance._serviceContainer;
+    }
+    /**
+     * 获取World管理器
+     *
+     * 用于管理多个独立的World实例（高级用户）。
+     *
+     * @returns WorldManager实例
+     * @throws 如果Core实例未创建
+     *
+     * @example
+     * ```typescript
+     * // 创建多个游戏房间
+     * const wm = Core.worldManager;
+     * const room1 = wm.createWorld('room_001');
+     * room1.createScene('game', new GameScene());
+     * room1.start();
+     * ```
+     */
+    static get worldManager() {
+        if (!this._instance) {
+            throw new Error('Core实例未创建，请先调用Core.create()');
+        }
+        return this._instance._worldManager;
+    }
+    /**
+     * 创建Core实例
+     *
+     * 如果实例已存在，则返回现有实例。
+     *
+     * @param config - Core配置，也可以直接传入boolean表示debug模式（向后兼容）
+     * @returns Core实例
+     *
+     * @example
+     * ```typescript
+     * // 方式1：使用配置对象
+     * Core.create({
+     *     debug: true,
+     *     debugConfig: {
+     *         enabled: true,
+     *         websocketUrl: 'ws://localhost:9229'
+     *     }
+     * });
+     *
+     * // 方式2：简单模式（向后兼容）
+     * Core.create(true);  // debug = true
+     * ```
+     */
+    static create(config = true) {
+        if (this._instance == null) {
+            // 向后兼容：如果传入boolean，转换为配置对象
+            const coreConfig = typeof config === 'boolean'
+                ? { debug: config }
+                : config;
+            this._instance = new Core(coreConfig);
+        }
+        else {
+            this._logger.warn('Core实例已创建，返回现有实例');
+        }
+        return this._instance;
+    }
+    /**
+     * 设置当前场景
+     *
+     * @param scene - 要设置的场景
+     * @returns 设置的场景实例
+     *
+     * @example
+     * ```typescript
+     * Core.create({ debug: true });
+     *
+     * // 创建并设置场景
+     * const gameScene = new GameScene();
+     * Core.setScene(gameScene);
+     * ```
+     */
+    static setScene(scene) {
+        if (!this._instance) {
+            Core._logger.warn('Core实例未创建，请先调用Core.create()');
+            throw new Error('Core实例未创建');
+        }
+        return this._instance._sceneManager.setScene(scene);
+    }
+    /**
+     * 获取当前场景
+     *
+     * @returns 当前场景，如果没有场景则返回null
+     */
+    static get scene() {
+        if (!this._instance) {
+            return null;
+        }
+        return this._instance._sceneManager.currentScene;
+    }
+    /**
+     * 获取ECS流式API
+     *
+     * @returns ECS API实例，如果当前没有场景则返回null
+     *
+     * @example
+     * ```typescript
+     * // 使用流式API创建实体
+     * const player = Core.ecsAPI?.createEntity('Player')
+     *     .addComponent(Position, 100, 100)
+     *     .addComponent(Velocity, 50, 0);
+     *
+     * // 查询实体
+     * const enemies = Core.ecsAPI?.query(Enemy, Transform);
+     *
+     * // 发射事件
+     * Core.ecsAPI?.emit('game:start', { level: 1 });
+     * ```
+     */
+    static get ecsAPI() {
+        if (!this._instance) {
+            return null;
+        }
+        return this._instance._sceneManager.api;
+    }
+    /**
+     * 延迟加载场景（下一帧切换）
+     *
+     * @param scene - 要加载的场景
+     *
+     * @example
+     * ```typescript
+     * // 延迟切换场景（在下一帧生效）
+     * Core.loadScene(new MenuScene());
+     * ```
+     */
+    static loadScene(scene) {
+        if (!this._instance) {
+            Core._logger.warn('Core实例未创建，请先调用Core.create()');
+            return;
+        }
+        this._instance._sceneManager.loadScene(scene);
+    }
+    /**
+     * 更新游戏逻辑
+     *
+     * 此方法应该在游戏引擎的更新循环中调用。
+     * 会自动更新全局服务和当前场景。
+     *
+     * @param deltaTime - 外部引擎提供的帧时间间隔（秒）
+     *
+     * @example
+     * ```typescript
+     * // 初始化
+     * Core.create({ debug: true });
+     * Core.setScene(new GameScene());
+     *
+     * // Laya引擎集成
+     * Laya.timer.frameLoop(1, this, () => {
+     *     const deltaTime = Laya.timer.delta / 1000;
+     *     Core.update(deltaTime);  // 自动更新全局服务和场景
+     * });
+     *
+     * // Cocos Creator集成
+     * update(deltaTime: number) {
+     *     Core.update(deltaTime);  // 自动更新全局服务和场景
+     * }
+     * ```
+     */
+    static update(deltaTime) {
+        if (!this._instance) {
+            Core._logger.warn('Core实例未创建，请先调用Core.create()');
+            return;
+        }
+        this._instance.updateInternal(deltaTime);
+    }
+    /**
+     * 调度定时器
+     *
+     * 创建一个定时器，在指定时间后执行回调函数。
+     *
+     * @param timeInSeconds - 延迟时间（秒）
+     * @param repeats - 是否重复执行，默认为false
+     * @param context - 回调函数的上下文，默认为null
+     * @param onTime - 定时器触发时的回调函数
+     * @returns 创建的定时器实例
+     * @throws 如果Core实例未创建或onTime回调未提供
+     *
+     * @example
+     * ```typescript
+     * // 一次性定时器
+     * Core.schedule(1.0, false, null, (timer) => {
+     *     console.log("1秒后执行一次");
+     * });
+     *
+     * // 重复定时器
+     * Core.schedule(0.5, true, null, (timer) => {
+     *     console.log("每0.5秒执行一次");
+     * });
+     * ```
+     */
+    static schedule(timeInSeconds, repeats = false, context, onTime) {
+        if (!this._instance) {
+            throw new Error('Core实例未创建，请先调用Core.create()');
+        }
+        if (!onTime) {
+            throw new Error('onTime callback is required');
+        }
+        return this._instance._timerManager.schedule(timeInSeconds, repeats, context, onTime);
+    }
+    /**
+     * 启用调试功能
+     *
+     * @param config 调试配置
+     */
+    static enableDebug(config) {
+        if (!this._instance) {
+            Core._logger.warn('Core实例未创建，请先调用Core.create()');
+            return;
+        }
+        if (this._instance._debugManager) {
+            this._instance._debugManager.updateConfig(config);
+        }
+        else {
+            const configService = new DebugConfigService();
+            configService.setConfig(config);
+            this._instance._serviceContainer.registerInstance(DebugConfigService, configService);
+            this._instance._serviceContainer.registerSingleton(DebugManager, (c) => createInstance(DebugManager, c));
+            this._instance._debugManager = this._instance._serviceContainer.resolve(DebugManager);
+            this._instance._debugManager.onInitialize();
+        }
+        // 更新Core配置
+        this._instance._config.debugConfig = config;
+    }
+    /**
+     * 禁用调试功能
+     */
+    static disableDebug() {
+        if (!this._instance)
+            return;
+        if (this._instance._debugManager) {
+            this._instance._debugManager.stop();
+            delete this._instance._debugManager;
+        }
+        // 更新Core配置
+        if (this._instance._config.debugConfig) {
+            this._instance._config.debugConfig.enabled = false;
+        }
+    }
+    /**
+     * 获取调试数据
+     *
+     * @returns 当前调试数据，如果调试未启用则返回null
+     */
+    static getDebugData() {
+        if (!this._instance?._debugManager) {
+            return null;
+        }
+        return this._instance._debugManager.getDebugData();
+    }
+    /**
+     * 检查调试是否启用
+     *
+     * @returns 调试状态
+     */
+    static get isDebugEnabled() {
+        return this._instance?._config.debugConfig?.enabled || false;
+    }
+    /**
+     * 获取性能监视器实例
+     *
+     * @returns 性能监视器，如果Core未初始化则返回null
+     */
+    static get performanceMonitor() {
+        return this._instance?._performanceMonitor || null;
+    }
+    /**
+     * 安装插件
+     *
+     * @param plugin - 插件实例
+     * @throws 如果Core实例未创建或插件安装失败
+     *
+     * @example
+     * ```typescript
+     * Core.create({ debug: true });
+     *
+     * // 安装插件
+     * await Core.installPlugin(new MyPlugin());
+     * ```
+     */
+    static async installPlugin(plugin) {
+        if (!this._instance) {
+            throw new Error('Core实例未创建，请先调用Core.create()');
+        }
+        await this._instance._pluginManager.install(plugin);
+    }
+    /**
+     * 卸载插件
+     *
+     * @param name - 插件名称
+     * @throws 如果Core实例未创建或插件卸载失败
+     *
+     * @example
+     * ```typescript
+     * await Core.uninstallPlugin('my-plugin');
+     * ```
+     */
+    static async uninstallPlugin(name) {
+        if (!this._instance) {
+            throw new Error('Core实例未创建，请先调用Core.create()');
+        }
+        await this._instance._pluginManager.uninstall(name);
+    }
+    /**
+     * 获取插件实例
+     *
+     * @param name - 插件名称
+     * @returns 插件实例，如果未安装则返回undefined
+     *
+     * @example
+     * ```typescript
+     * const myPlugin = Core.getPlugin('my-plugin');
+     * if (myPlugin) {
+     *     console.log(myPlugin.version);
+     * }
+     * ```
+     */
+    static getPlugin(name) {
+        if (!this._instance) {
+            return undefined;
+        }
+        return this._instance._pluginManager.getPlugin(name);
+    }
+    /**
+     * 检查插件是否已安装
+     *
+     * @param name - 插件名称
+     * @returns 是否已安装
+     *
+     * @example
+     * ```typescript
+     * if (Core.isPluginInstalled('my-plugin')) {
+     *     console.log('Plugin is installed');
+     * }
+     * ```
+     */
+    static isPluginInstalled(name) {
+        if (!this._instance) {
+            return false;
+        }
+        return this._instance._pluginManager.isInstalled(name);
+    }
+    /**
+     * 初始化核心系统
+     *
+     * 执行核心系统的初始化逻辑。
+     */
+    initialize() {
+        // 核心系统初始化
+        Core._logger.info('Core initialized', {
+            debug: this.debug,
+            debugEnabled: this._config.debugConfig?.enabled || false
+        });
+    }
+    /**
+     * 内部更新方法
+     *
+     * @param deltaTime - 帧时间间隔（秒）
+     */
+    updateInternal(deltaTime) {
+        if (Core.paused)
+            return;
+        // 开始性能监控
+        const frameStartTime = this._performanceMonitor.startMonitoring('Core.update');
+        // 更新时间系统
+        Time.update(deltaTime);
+        // 更新FPS监控（如果性能监控器支持）
+        if ('updateFPS' in this._performanceMonitor && typeof this._performanceMonitor.updateFPS === 'function') {
+            this._performanceMonitor.updateFPS(Time.deltaTime);
+        }
+        // 更新所有可更新的服务
+        const servicesStartTime = this._performanceMonitor.startMonitoring('Services.update');
+        this._serviceContainer.updateAll(deltaTime);
+        this._performanceMonitor.endMonitoring('Services.update', servicesStartTime, this._serviceContainer.getUpdatableCount());
+        // 更新对象池管理器
+        this._poolManager.update();
+        // 更新默认场景（通过 SceneManager）
+        this._sceneManager.update();
+        // 更新额外的 WorldManager
+        this._worldManager.updateAll();
+        // 结束性能监控
+        this._performanceMonitor.endMonitoring('Core.update', frameStartTime);
+    }
+    /**
+     * 销毁Core实例
+     *
+     * 清理所有资源，通常在应用程序关闭时调用。
+     */
+    static destroy() {
+        if (!this._instance)
+            return;
+        // 停止调试管理器
+        if (this._instance._debugManager) {
+            this._instance._debugManager.stop();
+        }
+        // 清理所有服务
+        this._instance._serviceContainer.clear();
+        Core._logger.info('Core destroyed');
+        // 清空实例引用，允许重新创建Core实例
+        this._instance = null;
+    }
+}
+/**
+ * 游戏暂停状态
+ *
+ * 当设置为true时，游戏循环将暂停执行。
+ */
+Core.paused = false;
+/**
+ * 全局核心实例
+ *
+ * 可能为null表示Core尚未初始化或已被销毁
+ */
+Core._instance = null;
+/**
+ * Core专用日志器
+ */
+Core._logger = createLogger('Core');
+//# sourceMappingURL=Core.js.map

package/bin/Core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Core.js","sourceRoot":"","sources":["../src/Core.ts"],"names":[],"mappings":"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"}

package/bin/ECS/Component.d.ts

@@ -0,0 +1,104 @@
+import type { IComponent } from '../Types';
+/**
+ * 游戏组件基类
+ *
+ * ECS架构中的组件（Component）应该是纯数据容器。
+ * 所有游戏逻辑应该在 EntitySystem 中实现，而不是在组件内部。
+ *
+ * @example
+ * 推荐做法：纯数据组件
+ * ```typescript
+ * class HealthComponent extends Component {
+ *     public health: number = 100;
+ *     public maxHealth: number = 100;
+ * }
+ * ```
+ *
+ * @example
+ * 推荐做法：在 System 中处理逻辑
+ * ```typescript
+ * class HealthSystem extends EntitySystem {
+ *     process(entities: Entity[]): void {
+ *         for (const entity of entities) {
+ *             const health = entity.getComponent(HealthComponent);
+ *             if (health && health.health <= 0) {
+ *                 entity.destroy();
+ *             }
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class Component implements IComponent {
+    /**
+     * 组件ID生成器
+     *
+     * 用于为每个组件分配唯一的ID。
+     */
+    private static idGenerator;
+    /**
+     * 组件唯一标识符
+     *
+     * 在整个游戏生命周期中唯一的数字ID。
+     */
+    readonly id: number;
+    /**
+     * 所属实体ID
+     *
+     * 存储实体ID而非引用，避免循环引用，符合ECS数据导向设计。
+     */
+    entityId: number | null;
+    /**
+     * 创建组件实例
+     *
+     * 自动分配唯一ID给组件。
+     */
+    constructor();
+    /**
+     * 组件添加到实体时的回调
+     *
+     * 当组件被添加到实体时调用，可以在此方法中进行初始化操作。
+     *
+     * @remarks
+     * 这是一个生命周期钩子，用于组件的初始化逻辑。
+     * 虽然保留此方法，但建议将复杂的初始化逻辑放在 System 中处理。
+     */
+    onAddedToEntity(): void;
+    /**
+     * 组件从实体移除时的回调
+     *
+     * 当组件从实体中移除时调用，可以在此方法中进行清理操作。
+     *
+     * @remarks
+     * 这是一个生命周期钩子，用于组件的清理逻辑。
+     * 虽然保留此方法，但建议将复杂的清理逻辑放在 System 中处理。
+     */
+    onRemovedFromEntity(): void;
+    /**
+     * 组件反序列化后的回调
+     *
+     * 当组件从场景文件加载或快照恢复后调用，可以在此方法中恢复运行时数据。
+     *
+     * @remarks
+     * 这是一个生命周期钩子，用于恢复无法序列化的运行时数据。
+     * 例如：从图片路径重新加载图片尺寸信息，重建缓存等。
+     *
+     * @example
+     * ```typescript
+     * class TilemapComponent extends Component {
+     *     public tilesetImage: string = '';
+     *     private _tilesetData: TilesetData | undefined;
+     *
+     *     public async onDeserialized(): Promise<void> {
+     *         if (this.tilesetImage) {
+     *             // 重新加载 tileset 图片并恢复运行时数据
+     *             const img = await loadImage(this.tilesetImage);
+     *             this.setTilesetInfo(img.width, img.height, ...);
+     *         }
+     *     }
+     * }
+     * ```
+     */
+    onDeserialized(): void | Promise<void>;
+}
+//# sourceMappingURL=Component.d.ts.map

package/bin/ECS/Component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component.d.ts","sourceRoot":"","sources":["../../src/ECS/Component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,SAAU,YAAW,UAAU;IACjD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW,CAAa;IAEvC;;;;OAIG;IACH,SAAgB,EAAE,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IAEI,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEtC;;;;OAIG;;IAKH;;;;;;;;OAQG;IACI,eAAe,IAAI,IAAI;IAE9B;;;;;;;;OAQG;IACI,mBAAmB,IAAI,IAAI;IAElC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,cAAc,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAChD"}