import { TimerManager } from './Utils/Timers/TimerManager'; import { ITimer } from './Utils/Timers/ITimer'; import { Timer } from './Utils/Timers/Timer'; import { Time } from './Utils/Time'; import { PerformanceMonitor } from './Utils/PerformanceMonitor'; import { PoolManager } from './Utils/Pool/PoolManager'; import { DebugManager } from './Utils/Debug'; import { ICoreConfig, IECSDebugConfig } from './Types'; import { createLogger } from './Utils/Logger'; import { SceneManager } from './ECS/SceneManager'; import { IScene } from './ECS/IScene'; import { ServiceContainer } from './Core/ServiceContainer'; import { PluginManager } from './Core/PluginManager'; import { IPlugin } from './Core/Plugin'; 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 { /** * 游戏暂停状态 * * 当设置为true时,游戏循环将暂停执行。 */ public static paused = false; /** * 全局核心实例 * * 可能为null表示Core尚未初始化或已被销毁 */ private static _instance: Core | null = null; /** * Core专用日志器 */ private static _logger = createLogger('Core'); /** * 调试模式标志 * * 在调试模式下会启用额外的性能监控和错误检查。 */ public readonly debug: boolean; /** * 服务容器 * * 管理所有服务的注册、解析和生命周期。 */ private _serviceContainer: ServiceContainer; private _timerManager: TimerManager; private _performanceMonitor: PerformanceMonitor; private _poolManager: PoolManager; private _debugManager?: DebugManager; /** * 场景管理器 * * 管理当前场景的生命周期。 */ private _sceneManager: SceneManager; /** * World管理器 * * 管理多个独立的World实例(可选)。 */ private _worldManager: WorldManager; /** * 插件管理器 * * 管理所有插件的生命周期。 */ private _pluginManager: PluginManager; /** * Core配置 */ private _config: ICoreConfig; /** * 创建核心实例 * * @param config - Core配置对象 */ private constructor(config: ICoreConfig = {}) { 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 全局核心实例 */ public static get Instance() { return this._instance; } /** * 获取服务容器 * * 用于注册和解析自定义服务。 * * @returns 服务容器实例 * @throws 如果Core实例未创建 * * @example * ```typescript * // 注册自定义服务 * Core.services.registerSingleton(MyService); * * // 解析服务 * const myService = Core.services.resolve(MyService); * ``` */ public static get services(): ServiceContainer { 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(); * ``` */ public static get worldManager(): 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 * ``` */ public static create(config: ICoreConfig | boolean = true): Core { if (this._instance == null) { // 向后兼容:如果传入boolean,转换为配置对象 const coreConfig: ICoreConfig = 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); * ``` */ public static setScene(scene: T): T { if (!this._instance) { Core._logger.warn('Core实例未创建,请先调用Core.create()'); throw new Error('Core实例未创建'); } return this._instance._sceneManager.setScene(scene); } /** * 获取当前场景 * * @returns 当前场景,如果没有场景则返回null */ public static get scene(): IScene | null { 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 }); * ``` */ public static get ecsAPI() { if (!this._instance) { return null; } return this._instance._sceneManager.api; } /** * 延迟加载场景(下一帧切换) * * @param scene - 要加载的场景 * * @example * ```typescript * // 延迟切换场景(在下一帧生效) * Core.loadScene(new MenuScene()); * ``` */ public static loadScene(scene: T): void { 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); // 自动更新全局服务和场景 * } * ``` */ public static update(deltaTime: number): void { 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秒执行一次"); * }); * ``` */ public static schedule(timeInSeconds: number, repeats: boolean = false, context?: TContext, onTime?: (timer: ITimer) => void): Timer { 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 as TContext, onTime); } /** * 启用调试功能 * * @param config 调试配置 */ public static enableDebug(config: IECSDebugConfig): void { 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; } /** * 禁用调试功能 */ public static disableDebug(): void { 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 */ public static getDebugData(): unknown { if (!this._instance?._debugManager) { return null; } return this._instance._debugManager.getDebugData(); } /** * 检查调试是否启用 * * @returns 调试状态 */ public static get isDebugEnabled(): boolean { return this._instance?._config.debugConfig?.enabled || false; } /** * 获取性能监视器实例 * * @returns 性能监视器,如果Core未初始化则返回null */ public static get performanceMonitor(): PerformanceMonitor | null { return this._instance?._performanceMonitor || null; } /** * 安装插件 * * @param plugin - 插件实例 * @throws 如果Core实例未创建或插件安装失败 * * @example * ```typescript * Core.create({ debug: true }); * * // 安装插件 * await Core.installPlugin(new MyPlugin()); * ``` */ public static async installPlugin(plugin: IPlugin): Promise { 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'); * ``` */ public static async uninstallPlugin(name: string): Promise { 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); * } * ``` */ public static getPlugin(name: string): IPlugin | undefined { 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'); * } * ``` */ public static isPluginInstalled(name: string): boolean { if (!this._instance) { return false; } return this._instance._pluginManager.isInstalled(name); } /** * 初始化核心系统 * * 执行核心系统的初始化逻辑。 */ protected initialize() { // 核心系统初始化 Core._logger.info('Core initialized', { debug: this.debug, debugEnabled: this._config.debugConfig?.enabled || false }); } /** * 内部更新方法 * * @param deltaTime - 帧时间间隔(秒) */ private updateInternal(deltaTime: number): void { 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实例 * * 清理所有资源,通常在应用程序关闭时调用。 */ public static destroy(): void { 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; } }