@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/Core.d.ts

@@ -0,0 +1,379 @@
+import { ITimer } from './Utils/Timers/ITimer';
+import { Timer } from './Utils/Timers/Timer';
+import { PerformanceMonitor } from './Utils/PerformanceMonitor';
+import { ICoreConfig, IECSDebugConfig } from './Types';
+import { IScene } from './ECS/IScene';
+import { ServiceContainer } from './Core/ServiceContainer';
+import { IPlugin } from './Core/Plugin';
+import { WorldManager } from './ECS/WorldManager';
+/**
+ * 游戏引擎核心类
+ *
+ * 职责：
+ * - 提供全局服务（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 declare class Core {
+    /**
+     * 游戏暂停状态
+     *
+     * 当设置为true时，游戏循环将暂停执行。
+     */
+    static paused: boolean;
+    /**
+     * 全局核心实例
+     *
+     * 可能为null表示Core尚未初始化或已被销毁
+     */
+    private static _instance;
+    /**
+     * Core专用日志器
+     */
+    private static _logger;
+    /**
+     * 调试模式标志
+     *
+     * 在调试模式下会启用额外的性能监控和错误检查。
+     */
+    readonly debug: boolean;
+    /**
+     * 服务容器
+     *
+     * 管理所有服务的注册、解析和生命周期。
+     */
+    private _serviceContainer;
+    private _timerManager;
+    private _performanceMonitor;
+    private _poolManager;
+    private _debugManager?;
+    /**
+     * 场景管理器
+     *
+     * 管理当前场景的生命周期。
+     */
+    private _sceneManager;
+    /**
+     * World管理器
+     *
+     * 管理多个独立的World实例（可选）。
+     */
+    private _worldManager;
+    /**
+     * 插件管理器
+     *
+     * 管理所有插件的生命周期。
+     */
+    private _pluginManager;
+    /**
+     * Core配置
+     */
+    private _config;
+    /**
+     * 创建核心实例
+     *
+     * @param config - Core配置对象
+     */
+    private constructor();
+    /**
+     * 获取核心实例
+     *
+     * @returns 全局核心实例
+     */
+    static get Instance(): Core | null;
+    /**
+     * 获取服务容器
+     *
+     * 用于注册和解析自定义服务。
+     *
+     * @returns 服务容器实例
+     * @throws 如果Core实例未创建
+     *
+     * @example
+     * ```typescript
+     * // 注册自定义服务
+     * Core.services.registerSingleton(MyService);
+     *
+     * // 解析服务
+     * const myService = Core.services.resolve(MyService);
+     * ```
+     */
+    static get services(): 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(): 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?: ICoreConfig | boolean): Core;
+    /**
+     * 设置当前场景
+     *
+     * @param scene - 要设置的场景
+     * @returns 设置的场景实例
+     *
+     * @example
+     * ```typescript
+     * Core.create({ debug: true });
+     *
+     * // 创建并设置场景
+     * const gameScene = new GameScene();
+     * Core.setScene(gameScene);
+     * ```
+     */
+    static setScene<T extends IScene>(scene: T): T;
+    /**
+     * 获取当前场景
+     *
+     * @returns 当前场景，如果没有场景则返回null
+     */
+    static get scene(): IScene | null;
+    /**
+     * 获取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(): import("./ECS").ECSFluentAPI | null;
+    /**
+     * 延迟加载场景（下一帧切换）
+     *
+     * @param scene - 要加载的场景
+     *
+     * @example
+     * ```typescript
+     * // 延迟切换场景（在下一帧生效）
+     * Core.loadScene(new MenuScene());
+     * ```
+     */
+    static loadScene<T extends IScene>(scene: T): void;
+    /**
+     * 更新游戏逻辑
+     *
+     * 此方法应该在游戏引擎的更新循环中调用。
+     * 会自动更新全局服务和当前场景。
+     *
+     * @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: number): void;
+    /**
+     * 调度定时器
+     *
+     * 创建一个定时器，在指定时间后执行回调函数。
+     *
+     * @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<TContext = unknown>(timeInSeconds: number, repeats?: boolean, context?: TContext, onTime?: (timer: ITimer<TContext>) => void): Timer<TContext>;
+    /**
+     * 启用调试功能
+     *
+     * @param config 调试配置
+     */
+    static enableDebug(config: IECSDebugConfig): void;
+    /**
+     * 禁用调试功能
+     */
+    static disableDebug(): void;
+    /**
+     * 获取调试数据
+     *
+     * @returns 当前调试数据，如果调试未启用则返回null
+     */
+    static getDebugData(): unknown;
+    /**
+     * 检查调试是否启用
+     *
+     * @returns 调试状态
+     */
+    static get isDebugEnabled(): boolean;
+    /**
+     * 获取性能监视器实例
+     *
+     * @returns 性能监视器，如果Core未初始化则返回null
+     */
+    static get performanceMonitor(): PerformanceMonitor | null;
+    /**
+     * 安装插件
+     *
+     * @param plugin - 插件实例
+     * @throws 如果Core实例未创建或插件安装失败
+     *
+     * @example
+     * ```typescript
+     * Core.create({ debug: true });
+     *
+     * // 安装插件
+     * await Core.installPlugin(new MyPlugin());
+     * ```
+     */
+    static installPlugin(plugin: IPlugin): Promise<void>;
+    /**
+     * 卸载插件
+     *
+     * @param name - 插件名称
+     * @throws 如果Core实例未创建或插件卸载失败
+     *
+     * @example
+     * ```typescript
+     * await Core.uninstallPlugin('my-plugin');
+     * ```
+     */
+    static uninstallPlugin(name: string): Promise<void>;
+    /**
+     * 获取插件实例
+     *
+     * @param name - 插件名称
+     * @returns 插件实例，如果未安装则返回undefined
+     *
+     * @example
+     * ```typescript
+     * const myPlugin = Core.getPlugin('my-plugin');
+     * if (myPlugin) {
+     *     console.log(myPlugin.version);
+     * }
+     * ```
+     */
+    static getPlugin(name: string): IPlugin | undefined;
+    /**
+     * 检查插件是否已安装
+     *
+     * @param name - 插件名称
+     * @returns 是否已安装
+     *
+     * @example
+     * ```typescript
+     * if (Core.isPluginInstalled('my-plugin')) {
+     *     console.log('Plugin is installed');
+     * }
+     * ```
+     */
+    static isPluginInstalled(name: string): boolean;
+    /**
+     * 初始化核心系统
+     *
+     * 执行核心系统的初始化逻辑。
+     */
+    protected initialize(): void;
+    /**
+     * 内部更新方法
+     *
+     * @param deltaTime - 帧时间间隔（秒）
+     */
+    private updateInternal;
+    /**
+     * 销毁Core实例
+     *
+     * 清理所有资源，通常在应用程序关闭时调用。
+     */
+    static destroy(): void;
+}
+//# sourceMappingURL=Core.d.ts.map

package/bin/Core.d.ts.map

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