esengine/packages/core/src/Core.ts

import { GlobalManager } from './Utils/GlobalManager';
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 { ECSFluentAPI, createECSAPI } from './ECS/Core/FluentAPI';
import { IScene } from './ECS/IScene';
import { WorldManager, IWorldManagerConfig } from './ECS/WorldManager';
import { DebugManager } from './Utils/Debug';
import { ICoreConfig, IECSDebugConfig } from './Types';
import { createLogger } from './Utils/Logger';

/**
 * 游戏引擎核心类
 * 
 * 负责管理游戏的生命周期、场景切换、全局管理器和定时器系统。
 * 提供统一的游戏循环管理。
 * 
 * @example
 * ```typescript
 * // 创建核心实例
 * const core = Core.create(true);
 * 
 * // 设置场景
 * Core.scene = new MyScene();
 * 
 * // 在游戏循环中更新（Laya引擎示例）
 * Laya.timer.frameLoop(1, this, () => {
 *     const deltaTime = Laya.timer.delta / 1000;
 *     Core.update(deltaTime);
 * });
 * 
 * // 调度定时器
 * Core.schedule(1.0, false, null, (timer) => {
 *     Core._logger.info("1秒后执行");
 * });
 * ```
 */
export class Core {
    /**
     * 游戏暂停状态
     * 
     * 当设置为true时，游戏循环将暂停执行。
     */
    public static paused = false;

    /**
     * 默认World ID
     * 
     * 用于单Scene模式的默认World标识
     */
    private static readonly DEFAULT_WORLD_ID = '__default__';

    /**
     * 默认Scene ID
     * 
     * 用于单Scene模式的默认Scene标识
     */
    private static readonly DEFAULT_SCENE_ID = '__main__';
    
    /**
     * 全局核心实例
     */
    private static _instance: Core;

    /**
     * Core专用日志器
     */
    private static _logger = createLogger('Core');
    
    /**
     * 实体系统启用状态
     * 
     * 控制是否启用ECS实体系统功能。
     */
    public static entitySystemsEnabled: boolean;
    
    /**
     * 调试模式标志
     * 
     * 在调试模式下会启用额外的性能监控和错误检查。
     */
    public readonly debug: boolean;
    
    
    /**
     * 全局管理器集合
     * 
     * 存储所有注册的全局管理器实例。
     */
    public _globalManagers: GlobalManager[] = [];
    
    /**
     * 定时器管理器
     * 
     * 负责管理所有的游戏定时器。
     */
    public _timerManager: TimerManager;

    /**
     * 性能监控器
     * 
     * 监控游戏性能并提供优化建议。
     */
    public _performanceMonitor: PerformanceMonitor;

    /**
     * 对象池管理器
     * 
     * 管理所有对象池的生命周期。
     */
    public _poolManager: PoolManager;

    /**
     * ECS流式API
     * 
     * 提供便捷的ECS操作接口。
     */
    public _ecsAPI?: ECSFluentAPI;
    

    /**
     * 调试管理器
     * 
     * 负责收集和发送调试数据。
     */
    public _debugManager?: DebugManager;

    /**
     * World管理器
     * 
     * 管理多个World实例，支持多房间/多世界架构。
     */
    public _worldManager?: WorldManager;

    /**
     * Core配置
     */
    private _config: ICoreConfig;


    /**
     * 创建核心实例
     * 
     * @param config - Core配置对象
     */
    private constructor(config: ICoreConfig = {}) {
        Core._instance = this;

        // 保存配置
        this._config = {
            debug: true,
            enableEntitySystems: true,
            ...config
        };


        // 初始化管理器
        this._timerManager = new TimerManager();
        Core.registerGlobalManager(this._timerManager);

        // 初始化性能监控器
        this._performanceMonitor = PerformanceMonitor.instance;
        
        // 在调试模式下启用性能监控
        if (this._config.debug) {
            this._performanceMonitor.enable();
        }

        // 初始化对象池管理器
        this._poolManager = PoolManager.getInstance();
        
        Core.entitySystemsEnabled = this._config.enableEntitySystems ?? true;
        this.debug = this._config.debug ?? true;

        // 初始化调试管理器
        if (this._config.debugConfig?.enabled) {
            this._debugManager = new DebugManager(this, this._config.debugConfig);
        }


        this.initialize();
    }

    /**
     * 获取核心实例
     * 
     * @returns 全局核心实例
     */
    public static get Instance() {
        return this._instance;
    }

    /**
     * 获取当前活动的场景（属性访问器）
     * 
     * @returns 当前场景实例，如果没有则返回null
     */
    public static get scene(): IScene | null {
        return this.getScene();
    }

    /**
     * 获取当前活动的场景（方法调用）
     * 
     * @returns 当前场景实例，如果没有则返回null
     */
    public static getScene<T extends IScene>(): T | null {
        if (!this._instance) {
            return null;
        }

        // 确保默认World存在
        this._instance.ensureDefaultWorld();
        
        const defaultWorld = this._instance._worldManager!.getWorld(this.DEFAULT_WORLD_ID);
        return defaultWorld?.getScene(this.DEFAULT_SCENE_ID) as T || null;
    }


    /**
     * 设置当前场景
     * 
     * @param scene - 要设置的场景实例
     * @returns 设置的场景实例，便于链式调用
     */
    public static setScene<T extends IScene>(scene: T): T {
        if (!this._instance) {
            throw new Error("Core实例未创建，请先调用Core.create()");
        }

        // 确保默认World存在
        this._instance.ensureDefaultWorld();
        
        const defaultWorld = this._instance._worldManager!.getWorld(this.DEFAULT_WORLD_ID)!;
        
        // 移除旧的主Scene（如果存在）
        if (defaultWorld.getScene(this.DEFAULT_SCENE_ID)) {
            defaultWorld.removeScene(this.DEFAULT_SCENE_ID);
        }

        // 添加新Scene到默认World
        defaultWorld.createScene(this.DEFAULT_SCENE_ID, scene);
        defaultWorld.setSceneActive(this.DEFAULT_SCENE_ID, true);

        // 触发场景切换回调
        this._instance.onSceneChanged();
        
        return scene;
    }


    /**
     * 创建Core实例
     * 
     * 如果实例已存在，则返回现有实例。
     * 
     * @param config - Core配置，也可以直接传入boolean表示debug模式（向后兼容）
     * @returns Core实例
     */
    public static create(config: ICoreConfig | boolean = true): Core {
        if (this._instance == null) {
            // 向后兼容：如果传入boolean，转换为配置对象
            const coreConfig: ICoreConfig = typeof config === 'boolean' 
                ? { debug: config, enableEntitySystems: true }
                : config;
            this._instance = new Core(coreConfig);
        }
        return this._instance;
    }

    /**
     * 更新游戏逻辑
     * 
     * 此方法应该在游戏引擎的更新循环中调用。
     * 
     * @param deltaTime - 外部引擎提供的帧时间间隔（秒）
     * 
     * @example
     * ```typescript
     * // 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 manager - 要注册的全局管理器
     */
    public static registerGlobalManager(manager: GlobalManager) {
        this._instance._globalManagers.push(manager);
        manager.enabled = true;
    }

    /**
     * 注销全局管理器
     * 
     * 从全局管理器列表中移除管理器，并禁用它。
     * 
     * @param manager - 要注销的全局管理器
     */
    public static unregisterGlobalManager(manager: GlobalManager) {
        this._instance._globalManagers.splice(this._instance._globalManagers.indexOf(manager), 1);
        manager.enabled = false;
    }

    /**
     * 获取指定类型的全局管理器
     * 
     * @param type - 管理器类型构造函数
     * @returns 管理器实例，如果未找到则返回null
     */
    public static getGlobalManager<T extends GlobalManager>(type: new (...args: unknown[]) => T): T | null {
        for (const manager of this._instance._globalManagers) {
            if (manager instanceof type)
                return manager as T;
        }
        return null;
    }

    /**
     * 调度定时器
     * 
     * 创建一个定时器，在指定时间后执行回调函数。
     * 
     * @param timeInSeconds - 延迟时间（秒）
     * @param repeats - 是否重复执行，默认为false
     * @param context - 回调函数的上下文，默认为null
     * @param onTime - 定时器触发时的回调函数
     * @returns 创建的定时器实例
     */
    public static schedule<TContext = unknown>(timeInSeconds: number, repeats: boolean = false, context?: TContext, onTime?: (timer: ITimer<TContext>) => void): Timer<TContext> {
        if (!onTime) {
            throw new Error('onTime callback is required');
        }
        return this._instance._timerManager.schedule(timeInSeconds, repeats, context as TContext, onTime);
    }

    /**
     * 获取ECS流式API
     * 
     * @returns ECS API实例，如果未初始化则返回null
     */
    public static get ecsAPI(): ECSFluentAPI | null {
        return this._instance?._ecsAPI || null;
    }

    /**
     * 启用调试功能
     * 
     * @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 {
            this._instance._debugManager = new DebugManager(this._instance, config);
        }

        // 更新Core配置
        this._instance._config.debugConfig = config;
    }

    /**
     * 禁用调试功能
     */
    public static disableDebug(): void {
        if (!this._instance) return;

        if (this._instance._debugManager) {
            this._instance._debugManager.stop();
            this._instance._debugManager = undefined;
        }

        // 更新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;
    }



    /**
     * 获取WorldManager实例
     *
     * @param config 可选的WorldManager配置，用于覆盖默认配置
     * @returns WorldManager实例，如果未初始化则自动创建
     */
    public static getWorldManager(config?: Partial<IWorldManagerConfig>): WorldManager {
        if (!this._instance) {
            throw new Error("Core实例未创建，请先调用Core.create()");
        }

        if (!this._instance._worldManager) {
            // 多World模式的配置（用户主动获取WorldManager）
            const defaultConfig = {
                maxWorlds: 50,
                autoCleanup: true,
                cleanupInterval: 60000,
                debug: this._instance._config.debug
            };

            this._instance._worldManager = WorldManager.getInstance({
                ...defaultConfig,
                ...config // 用户传入的配置会覆盖默认配置
            });
        }

        return this._instance._worldManager;
    }

    /**
     * 启用World管理
     *
     * 显式启用World功能，用于多房间/多世界架构
     *
     * @param config 可选的WorldManager配置，用于覆盖默认配置
     */
    public static enableWorldManager(config?: Partial<IWorldManagerConfig>): WorldManager {
        return this.getWorldManager(config);
    }

    /**
     * 确保默认World存在
     * 
     * 内部方法，用于懒初始化默认World
     */
    private ensureDefaultWorld(): void {
        if (!this._worldManager) {
            this._worldManager = WorldManager.getInstance({
                maxWorlds: 1,        // 单场景用户只需要1个World
                autoCleanup: false,   // 单场景不需要自动清理
                cleanupInterval: 0,   // 禁用清理定时器
                debug: this._config.debug
            });
        }

        // 检查默认World是否存在
        if (!this._worldManager.getWorld(Core.DEFAULT_WORLD_ID)) {
            this._worldManager.createWorld(Core.DEFAULT_WORLD_ID, {
                name: 'DefaultWorld',
                maxScenes: 1,
                autoCleanup: false
            });
            this._worldManager.setWorldActive(Core.DEFAULT_WORLD_ID, true);
        }
    }

    /**
     * 场景切换回调
     * 
     * 在场景切换时调用，用于重置时间系统等。
     */
    public onSceneChanged() {
        Time.sceneChanged();
        
        // 获取当前Scene（从默认World）
        const currentScene = Core.getScene();
        
        // 初始化ECS API（如果场景支持）
        if (currentScene && currentScene.querySystem && currentScene.eventSystem) {
            this._ecsAPI = createECSAPI(currentScene, currentScene.querySystem, currentScene.eventSystem);
        }

        // 延迟调试管理器通知，避免在场景初始化过程中干扰属性
        if (this._debugManager) {
            queueMicrotask(() => {
                this._debugManager?.onSceneChanged();
            });
        }
    }

    /**
     * 初始化核心系统
     * 
     * 执行核心系统的初始化逻辑。
     */
    protected initialize() {
        // 核心系统初始化
    }


    /**
     * 内部更新方法
     * 
     * @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 managersStartTime = this._performanceMonitor.startMonitoring('GlobalManagers.update');
        for (const globalManager of this._globalManagers) {
            if (globalManager.enabled)
                globalManager.update();
        }
        this._performanceMonitor.endMonitoring('GlobalManagers.update', managersStartTime, this._globalManagers.length);

        // 更新对象池管理器
        this._poolManager.update();

        // 更新所有World
        if (this._worldManager) {
            const worldsStartTime = this._performanceMonitor.startMonitoring('Worlds.update');
            const activeWorlds = this._worldManager.getActiveWorlds();
            let totalWorldEntities = 0;

            for (const world of activeWorlds) {
                // 更新World的全局System
                world.updateGlobalSystems();
                
                // 更新World中的所有Scene
                world.updateScenes();

                // 统计实体数量（用于性能监控）
                const worldStats = world.getStats();
                totalWorldEntities += worldStats.totalEntities;
            }

            this._performanceMonitor.endMonitoring('Worlds.update', worldsStartTime, totalWorldEntities);
        }

        // 更新调试管理器（基于FPS的数据发送）
        if (this._debugManager) {
            this._debugManager.onFrameUpdate(deltaTime);
        }

        // 结束性能监控
        this._performanceMonitor.endMonitoring('Core.update', frameStartTime);
    }
}