CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

项目统一改用Logger控制管理

Browse Source 
拆分pool类和FluentAPI
This commit is contained in:
YHH
2025-08-08 11:16:00 +08:00
parent 2d389308ea
commit 87dd564a12
51 changed files with 1813 additions and 1491 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/core/jest.config.cjs
View File

@@ -42,7 +42,7 @@ module.exports = {
verbose: true,
transform: {
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: 'tsconfig.test.json',
tsconfig: 'tsconfig.json',
}],
},
moduleNameMapper: {

10
packages/core/package.json
View File

@@ -5,6 +5,16 @@
"type": "module",
"main": "bin/index.js",
"types": "bin/index.d.ts",
"exports": {
".": {
"types": "./bin/index.d.ts",
"import": "./bin/index.js",
"development": {
"types": "./src/index.ts",
"import": "./src/index.ts"
}
}
},
"files": [
"bin/**/*",
"README.md",

24
packages/core/src/Core.ts
View File

@@ -4,12 +4,13 @@ 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';
import { PoolManager } from './Utils/Pool/PoolManager';
import { ECSFluentAPI, createECSAPI } from './ECS/Core/FluentAPI';
import { Scene } from './ECS/Scene';
import { DebugManager } from './Utils/Debug';
import { ICoreConfig, IECSDebugConfig } from './Types';
import { BigIntFactory, EnvironmentInfo } from './ECS/Utils/BigIntCompatibility';
import { createLogger } from './Utils/Logger';
/**
* 游戏引擎核心类
@@ -33,7 +34,7 @@ import { BigIntFactory, EnvironmentInfo } from './ECS/Utils/BigIntCompatibility'
*
* // 调度定时器
* Core.schedule(1.0, false, null, (timer) => {
* console.log("1秒后执行");
* Core._logger.info("1秒后执行");
* });
* ```
*/
@@ -49,6 +50,11 @@ export class Core {
* 全局核心实例
*/
private static _instance: Core;
/**
* Core专用日志器
*/
private static _logger = createLogger('Core');
/**
* 实体系统启用状态
@@ -265,7 +271,7 @@ export class Core {
*/
public static update(deltaTime: number): void {
if (!this._instance) {
console.warn("Core实例未创建，请先调用Core.create()");
Core._logger.warn("Core实例未创建，请先调用Core.create()");
return;
}
@@ -341,7 +347,7 @@ export class Core {
*/
public static enableDebug(config: IECSDebugConfig): void {
if (!this._instance) {
console.warn("Core实例未创建，请先调用Core.create()");
Core._logger.warn("Core实例未创建，请先调用Core.create()");
return;
}
@@ -449,13 +455,13 @@ export class Core {
private logCompatibilityInfo(): void {
const info = this._environmentInfo;
console.log('ECS Framework 兼容性检测结果:');
console.log(` 环境: ${info.environment}`);
console.log(` JavaScript引擎: ${info.jsEngine}`);
console.log(` BigInt支持: ${info.supportsBigInt ? '支持' : '不支持'}`);
Core._logger.info('ECS Framework 兼容性检测结果:');
Core._logger.info(` 环境: ${info.environment}`);
Core._logger.info(` JavaScript引擎: ${info.jsEngine}`);
Core._logger.info(` BigInt支持: ${info.supportsBigInt ? '支持' : '不支持'}`);
if (!info.supportsBigInt) {
console.warn('BigInt兼容模式已启用');
Core._logger.warn('BigInt兼容模式已启用');
}
}

5
packages/core/src/ECS/Core/ComponentStorage.ts
View File

@@ -1,6 +1,7 @@
import { Component } from '../Component';
import { IBigIntLike, BigIntFactory } from '../Utils/BigIntCompatibility';
import { SoAStorage, EnableSoA, HighPrecision, Float64, Int32, SerializeMap, SerializeSet, SerializeArray, DeepCopy } from './SoAStorage';
import { createLogger } from '../../Utils/Logger';
// 重新导出装饰器
export { EnableSoA, HighPrecision, Float64, Int32, SerializeMap, SerializeSet, SerializeArray, DeepCopy };
@@ -15,6 +16,7 @@ export type ComponentType<T extends Component = Component> = new (...args: unkno
* 管理组件类型的位掩码分配
*/
export class ComponentRegistry {
protected static readonly _logger = createLogger('ComponentStorage');
private static componentTypes = new Map<Function, number>();
private static componentNameToType = new Map<string, Function>();
private static componentNameToId = new Map<string, number>();
@@ -400,6 +402,7 @@ export class ComponentStorage<T extends Component> {
* 管理所有组件类型的存储器
*/
export class ComponentStorageManager {
private static readonly _logger = createLogger('ComponentStorage');
private storages = new Map<Function, ComponentStorage<any> | SoAStorage<any>>();
/**
@@ -417,7 +420,7 @@ export class ComponentStorageManager {
if (enableSoA) {
// 使用SoA优化存储
storage = new SoAStorage(componentType);
console.log(`[SoA] 为 ${componentType.name} 启用SoA优化（适用于大规模批量操作）`);
ComponentStorageManager._logger.info(`为 ${componentType.name} 启用SoA优化（适用于大规模批量操作）`);
} else {
// 默认使用原始存储
storage = new ComponentStorage(componentType);

196
packages/core/src/ECS/Core/ComponentStorage/ComponentRegistry.ts Normal file
View File

@@ -0,0 +1,196 @@
import { Component } from '../../Component';
import { IBigIntLike, BigIntFactory } from '../../Utils/BigIntCompatibility';
import { createLogger } from '../../../Utils/Logger';
/**
* 组件类型定义
*/
export type ComponentType<T extends Component = Component> = new (...args: unknown[]) => T;
/**
* 组件注册表
* 管理组件类型的位掩码分配
*/
export class ComponentRegistry {
protected static readonly _logger = createLogger('ComponentStorage');
private static componentTypes = new Map<Function, number>();
private static componentNameToType = new Map<string, Function>();
private static componentNameToId = new Map<string, number>();
private static maskCache = new Map<string, IBigIntLike>();
private static nextBitIndex = 0;
private static maxComponents = 64; // 支持最多64种组件类型
/**
* 注册组件类型并分配位掩码
* @param componentType 组件类型
* @returns 分配的位索引
*/
public static register<T extends Component>(componentType: ComponentType<T>): number {
if (this.componentTypes.has(componentType)) {
return this.componentTypes.get(componentType)!;
}
if (this.nextBitIndex >= this.maxComponents) {
throw new Error(`Maximum number of component types (${this.maxComponents}) exceeded`);
}
const bitIndex = this.nextBitIndex++;
this.componentTypes.set(componentType, bitIndex);
this.componentNameToType.set(componentType.name, componentType);
this.componentNameToId.set(componentType.name, bitIndex);
return bitIndex;
}
/**
* 获取组件类型的位掩码
* @param componentType 组件类型
* @returns 位掩码
*/
public static getBitMask<T extends Component>(componentType: ComponentType<T>): IBigIntLike {
const bitIndex = this.componentTypes.get(componentType);
if (bitIndex === undefined) {
throw new Error(`Component type ${componentType.name} is not registered`);
}
return BigIntFactory.one().shiftLeft(bitIndex);
}
/**
* 获取组件类型的位索引
* @param componentType 组件类型
* @returns 位索引
*/
public static getBitIndex<T extends Component>(componentType: ComponentType<T>): number {
const bitIndex = this.componentTypes.get(componentType);
if (bitIndex === undefined) {
throw new Error(`Component type ${componentType.name} is not registered`);
}
return bitIndex;
}
/**
* 检查组件类型是否已注册
* @param componentType 组件类型
* @returns 是否已注册
*/
public static isRegistered<T extends Component>(componentType: ComponentType<T>): boolean {
return this.componentTypes.has(componentType);
}
/**
* 通过名称获取组件类型
* @param componentName 组件名称
* @returns 组件类型构造函数
*/
public static getComponentType(componentName: string): Function | null {
return this.componentNameToType.get(componentName) || null;
}
/**
* 获取所有已注册的组件类型
* @returns 组件类型映射
*/
public static getAllRegisteredTypes(): Map<Function, number> {
return new Map(this.componentTypes);
}
/**
* 获取所有组件名称到类型的映射
* @returns 名称到类型的映射
*/
public static getAllComponentNames(): Map<string, Function> {
return new Map(this.componentNameToType);
}
/**
* 通过名称获取组件类型ID
* @param componentName 组件名称
* @returns 组件类型ID
*/
public static getComponentId(componentName: string): number | undefined {
return this.componentNameToId.get(componentName);
}
/**
* 注册组件类型（通过名称）
* @param componentName 组件名称
* @returns 分配的组件ID
*/
public static registerComponentByName(componentName: string): number {
if (this.componentNameToId.has(componentName)) {
return this.componentNameToId.get(componentName)!;
}
if (this.nextBitIndex >= this.maxComponents) {
throw new Error(`Maximum number of component types (${this.maxComponents}) exceeded`);
}
const bitIndex = this.nextBitIndex++;
this.componentNameToId.set(componentName, bitIndex);
return bitIndex;
}
/**
* 创建单个组件的掩码
* @param componentName 组件名称
* @returns 组件掩码
*/
public static createSingleComponentMask(componentName: string): IBigIntLike {
const cacheKey = `single:${componentName}`;
if (this.maskCache.has(cacheKey)) {
return this.maskCache.get(cacheKey)!;
}
const componentId = this.getComponentId(componentName);
if (componentId === undefined) {
throw new Error(`Component type ${componentName} is not registered`);
}
const mask = BigIntFactory.one().shiftLeft(componentId);
this.maskCache.set(cacheKey, mask);
return mask;
}
/**
* 创建多个组件的掩码
* @param componentNames 组件名称数组
* @returns 组合掩码
*/
public static createComponentMask(componentNames: string[]): IBigIntLike {
const sortedNames = [...componentNames].sort();
const cacheKey = `multi:${sortedNames.join(',')}`;
if (this.maskCache.has(cacheKey)) {
return this.maskCache.get(cacheKey)!;
}
let mask = BigIntFactory.zero();
for (const name of componentNames) {
const componentId = this.getComponentId(name);
if (componentId !== undefined) {
mask = mask.or(BigIntFactory.one().shiftLeft(componentId));
}
}
this.maskCache.set(cacheKey, mask);
return mask;
}
/**
* 清除掩码缓存
*/
public static clearMaskCache(): void {
this.maskCache.clear();
}
/**
* 重置注册表（用于测试）
*/
public static reset(): void {
this.componentTypes.clear();
this.componentNameToType.clear();
this.componentNameToId.clear();
this.maskCache.clear();
this.nextBitIndex = 0;
}
}

8
packages/core/src/ECS/Core/DirtyTrackingSystem.ts
View File

@@ -1,6 +1,7 @@
import { Entity } from '../Entity';
import { Component } from '../Component';
import { ComponentType } from './ComponentStorage';
import { createLogger } from '../../Utils/Logger';
/**
* 脏标记类型
@@ -89,7 +90,7 @@ export interface DirtyStats {
* dirtySystem.addListener({
* flags: DirtyFlag.TRANSFORM_CHANGED,
* callback: (data) => {
* console.log('Entity position changed:', data.entity.name);
* logger.debug('Entity position changed:', data.entity.name);
* }
* });
*
@@ -98,6 +99,7 @@ export interface DirtyStats {
* ```
*/
export class DirtyTrackingSystem {
private static readonly _logger = createLogger('DirtyTrackingSystem');
/** 脏实体映射表 */
private _dirtyEntities = new Map<Entity, DirtyData>();
@@ -329,7 +331,7 @@ export class DirtyTrackingSystem {
try {
listener.callback(dirtyData);
} catch (error) {
console.error('脏数据监听器错误:', error);
DirtyTrackingSystem._logger.error('脏数据监听器错误:', error);
}
}
}
@@ -346,7 +348,7 @@ export class DirtyTrackingSystem {
try {
listener.callback(dirtyData);
} catch (error) {
console.error('脏数据监听器通知错误:', error);
DirtyTrackingSystem._logger.error('脏数据监听器通知错误:', error);
}
}
}

16
packages/core/src/ECS/Core/EventBus.ts
View File

@@ -9,6 +9,7 @@ import {
ISceneEventData,
IPerformanceEventData
} from '../../Types';
import { createLogger } from '../../Utils/Logger';
import {
TypeSafeEventSystem,
EventListenerConfig,
@@ -26,6 +27,7 @@ import {
* 基于TypeSafeEventSystem，提供类型安全的事件发布订阅机制
*/
export class EventBus implements IEventBus {
private static readonly _logger = createLogger('EventBus');
private eventSystem: TypeSafeEventSystem;
private eventIdCounter = 0;
private isDebugMode = false;
@@ -47,7 +49,7 @@ export class EventBus implements IEventBus {
const enhancedData = this.enhanceEventData(eventType, data);
if (this.isDebugMode) {
console.log(`[EventBus] 发射事件: ${eventType}`, enhancedData);
EventBus._logger.info(`发射事件: ${eventType}`, enhancedData);
}
this.eventSystem.emitSync(eventType, enhancedData);
@@ -65,7 +67,7 @@ export class EventBus implements IEventBus {
const enhancedData = this.enhanceEventData(eventType, data);
if (this.isDebugMode) {
console.log(`[EventBus] 发射异步事件: ${eventType}`, enhancedData);
EventBus._logger.info(`发射异步事件: ${eventType}`, enhancedData);
}
await this.eventSystem.emit(eventType, enhancedData);
@@ -93,7 +95,7 @@ export class EventBus implements IEventBus {
};
if (this.isDebugMode) {
console.log(`[EventBus] 添加监听器: ${eventType}`, eventConfig);
EventBus._logger.info(`添加监听器: ${eventType}`, eventConfig);
}
return this.eventSystem.on(eventType, handler, eventConfig);
@@ -136,7 +138,7 @@ export class EventBus implements IEventBus {
*/
public off(eventType: string, listenerId: string): boolean {
if (this.isDebugMode) {
console.log(`[EventBus] 移除监听器: ${listenerId} 事件: ${eventType}`);
EventBus._logger.info(`移除监听器: ${listenerId} 事件: ${eventType}`);
}
return this.eventSystem.off(eventType, listenerId);
@@ -148,7 +150,7 @@ export class EventBus implements IEventBus {
*/
public offAll(eventType: string): void {
if (this.isDebugMode) {
console.log(`[EventBus] 移除所有监听器: ${eventType}`);
EventBus._logger.info(`移除所有监听器: ${eventType}`);
}
this.eventSystem.offAll(eventType);
@@ -186,7 +188,7 @@ export class EventBus implements IEventBus {
*/
public clear(): void {
if (this.isDebugMode) {
console.log('[EventBus] 清空所有监听器');
EventBus._logger.info('清空所有监听器');
}
this.eventSystem.clear();
@@ -379,7 +381,7 @@ export class EventBus implements IEventBus {
private validateEventType(eventType: string): void {
if (!EventTypeValidator.isValid(eventType)) {
if (this.isDebugMode) {
console.warn(`[EventBus] 未知事件类型: ${eventType}`);
EventBus._logger.warn(`未知事件类型: ${eventType}`);
}
// 在调试模式下添加自定义事件类型
if (this.isDebugMode) {

11
packages/core/src/ECS/Core/EventSystem.ts
View File

@@ -1,3 +1,5 @@
import { createLogger } from '../../Utils/Logger';
/**
* 事件处理器函数类型
*/
@@ -66,6 +68,7 @@ export interface EventBatchConfig {
* 支持同步/异步事件、优先级、批处理等功能
*/
export class TypeSafeEventSystem {
private static readonly _logger = createLogger('EventSystem');
private listeners = new Map<string, InternalEventListener[]>();
private stats = new Map<string, EventStats>();
private batchQueue = new Map<string, any[]>();
@@ -204,7 +207,7 @@ export class TypeSafeEventSystem {
toRemove.push(listener.id);
}
} catch (error) {
console.error(`事件处理器执行错误 ${eventType}:`, error);
TypeSafeEventSystem._logger.error(`事件处理器执行错误 ${eventType}:`, error);
}
}
@@ -336,7 +339,7 @@ export class TypeSafeEventSystem {
// 检查监听器数量限制
if (listeners.length >= this.maxListeners) {
console.warn(`事件类型 ${eventType} 的监听器数量超过最大限制 (${this.maxListeners})`);
TypeSafeEventSystem._logger.warn(`事件类型 ${eventType} 的监听器数量超过最大限制 (${this.maxListeners})`);
return '';
}
@@ -392,7 +395,7 @@ export class TypeSafeEventSystem {
toRemove.push(listener.id);
}
} catch (error) {
console.error(`同步事件处理器执行错误 ${eventType}:`, error);
TypeSafeEventSystem._logger.error(`同步事件处理器执行错误 ${eventType}:`, error);
}
}
@@ -409,7 +412,7 @@ export class TypeSafeEventSystem {
toRemove.push(listener.id);
}
} catch (error) {
console.error(`异步事件处理器执行错误 ${eventType}:`, error);
TypeSafeEventSystem._logger.error(`异步事件处理器执行错误 ${eventType}:`, error);
}
});

649
packages/core/src/ECS/Core/FluentAPI.ts
View File

@@ -1,638 +1,11 @@
import { Entity } from '../Entity';
import { Component } from '../Component';
import { Scene } from '../Scene';
import { ComponentType, ComponentStorageManager } from './ComponentStorage';
import { QuerySystem, QueryBuilder } from './QuerySystem';
import { TypeSafeEventSystem } from './EventSystem';
import { EntitySystem } from '../Systems/EntitySystem';
/**
* 实体构建器 - 提供流式API创建和配置实体
*/
export class EntityBuilder {
private entity: Entity;
private scene: Scene;
private storageManager: ComponentStorageManager;
constructor(scene: Scene, storageManager: ComponentStorageManager) {
this.scene = scene;
this.storageManager = storageManager;
this.entity = new Entity("", scene.identifierPool.checkOut());
}
/**
* 设置实体名称
* @param name 实体名称
* @returns 实体构建器
*/
public named(name: string): EntityBuilder {
this.entity.name = name;
return this;
}
/**
* 设置实体标签
* @param tag 标签
* @returns 实体构建器
*/
public tagged(tag: number): EntityBuilder {
this.entity.tag = tag;
return this;
}
/**
* 添加组件
* @param component 组件实例
* @returns 实体构建器
*/
public with<T extends Component>(component: T): EntityBuilder {
this.entity.addComponent(component);
return this;
}
/**
* 添加多个组件
* @param components 组件数组
* @returns 实体构建器
*/
public withComponents(...components: Component[]): EntityBuilder {
for (const component of components) {
this.entity.addComponent(component);
}
return this;
}
/**
* 条件性添加组件
* @param condition 条件
* @param component 组件实例
* @returns 实体构建器
*/
public withIf<T extends Component>(condition: boolean, component: T): EntityBuilder {
if (condition) {
this.entity.addComponent(component);
}
return this;
}
/**
* 使用工厂函数创建并添加组件
* @param factory 组件工厂函数
* @returns 实体构建器
*/
public withFactory<T extends Component>(factory: () => T): EntityBuilder {
const component = factory();
this.entity.addComponent(component);
return this;
}
/**
* 配置组件属性
* @param componentType 组件类型
* @param configurator 配置函数
* @returns 实体构建器
*/
public configure<T extends Component>(
componentType: ComponentType<T>,
configurator: (component: T) => void
): EntityBuilder {
const component = this.entity.getComponent(componentType);
if (component) {
configurator(component);
}
return this;
}
/**
* 设置实体为启用状态
* @param enabled 是否启用
* @returns 实体构建器
*/
public enabled(enabled: boolean = true): EntityBuilder {
this.entity.enabled = enabled;
return this;
}
/**
* 设置实体为活跃状态
* @param active 是否活跃
* @returns 实体构建器
*/
public active(active: boolean = true): EntityBuilder {
this.entity.active = active;
return this;
}
/**
* 添加子实体
* @param childBuilder 子实体构建器
* @returns 实体构建器
*/
public withChild(childBuilder: EntityBuilder): EntityBuilder {
const child = childBuilder.build();
this.entity.addChild(child);
return this;
}
/**
* 批量添加子实体
* @param childBuilders 子实体构建器数组
* @returns 实体构建器
*/
public withChildren(...childBuilders: EntityBuilder[]): EntityBuilder {
for (const childBuilder of childBuilders) {
const child = childBuilder.build();
this.entity.addChild(child);
}
return this;
}
/**
* 使用工厂函数创建子实体
* @param childFactory 子实体工厂函数
* @returns 实体构建器
*/
public withChildFactory(childFactory: (parent: Entity) => EntityBuilder): EntityBuilder {
const childBuilder = childFactory(this.entity);
const child = childBuilder.build();
this.entity.addChild(child);
return this;
}
/**
* 条件性添加子实体
* @param condition 条件
* @param childBuilder 子实体构建器
* @returns 实体构建器
*/
public withChildIf(condition: boolean, childBuilder: EntityBuilder): EntityBuilder {
if (condition) {
const child = childBuilder.build();
this.entity.addChild(child);
}
return this;
}
/**
* 构建并返回实体
* @returns 构建的实体
*/
public build(): Entity {
return this.entity;
}
/**
* 构建实体并添加到场景
* @returns 构建的实体
*/
public spawn(): Entity {
this.scene.addEntity(this.entity);
return this.entity;
}
/**
* 克隆当前构建器
* @returns 新的实体构建器
*/
public clone(): EntityBuilder {
const newBuilder = new EntityBuilder(this.scene, this.storageManager);
// 这里需要深度克隆实体，简化实现
newBuilder.entity = this.entity; // 实际应该是深度克隆
return newBuilder;
}
}
/**
* 场景构建器 - 提供流式API创建和配置场景
*/
export class SceneBuilder {
private scene: Scene;
constructor() {
this.scene = new Scene();
}
/**
* 设置场景名称
* @param name 场景名称
* @returns 场景构建器
*/
public named(name: string): SceneBuilder {
this.scene.name = name;
return this;
}
/**
* 添加实体
* @param entity 实体
* @returns 场景构建器
*/
public withEntity(entity: Entity): SceneBuilder {
this.scene.addEntity(entity);
return this;
}
/**
* 使用实体构建器添加实体
* @param builderFn 实体构建器函数
* @returns 场景构建器
*/
public withEntityBuilder(builderFn: (builder: EntityBuilder) => EntityBuilder): SceneBuilder {
const builder = new EntityBuilder(this.scene, this.scene.componentStorageManager);
const configuredBuilder = builderFn(builder);
const entity = configuredBuilder.build();
this.scene.addEntity(entity);
return this;
}
/**
* 批量添加实体
* @param entities 实体数组
* @returns 场景构建器
*/
public withEntities(...entities: Entity[]): SceneBuilder {
for (const entity of entities) {
this.scene.addEntity(entity);
}
return this;
}
/**
* 添加系统
* @param system 系统实例
* @returns 场景构建器
*/
public withSystem(system: EntitySystem): SceneBuilder {
this.scene.addSystem(system);
return this;
}
/**
* 批量添加系统
* @param systems 系统数组
* @returns 场景构建器
*/
public withSystems(...systems: EntitySystem[]): SceneBuilder {
for (const system of systems) {
this.scene.addSystem(system);
}
return this;
}
/**
* 构建并返回场景
* @returns 构建的场景
*/
public build(): Scene {
return this.scene;
}
}
/**
* 组件构建器 - 提供流式API创建组件
*/
export class ComponentBuilder<T extends Component> {
private component: T;
constructor(componentClass: new (...args: unknown[]) => T, ...args: unknown[]) {
this.component = new componentClass(...args);
}
/**
* 设置组件属性
* @param property 属性名
* @param value 属性值
* @returns 组件构建器
*/
public set<K extends keyof T>(property: K, value: T[K]): ComponentBuilder<T> {
this.component[property] = value;
return this;
}
/**
* 使用配置函数设置组件
* @param configurator 配置函数
* @returns 组件构建器
*/
public configure(configurator: (component: T) => void): ComponentBuilder<T> {
configurator(this.component);
return this;
}
/**
* 条件性设置属性
* @param condition 条件
* @param property 属性名
* @param value 属性值
* @returns 组件构建器
*/
public setIf<K extends keyof T>(condition: boolean, property: K, value: T[K]): ComponentBuilder<T> {
if (condition) {
this.component[property] = value;
}
return this;
}
/**
* 构建并返回组件
* @returns 构建的组件
*/
public build(): T {
return this.component;
}
}
/**
* ECS流式API主入口
* 提供统一的流式接口
*/
export class ECSFluentAPI {
private scene: Scene;
private querySystem: QuerySystem;
private eventSystem: TypeSafeEventSystem;
constructor(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem) {
this.scene = scene;
this.querySystem = querySystem;
this.eventSystem = eventSystem;
}
/**
* 创建实体构建器
* @returns 实体构建器
*/
public createEntity(): EntityBuilder {
return new EntityBuilder(this.scene, this.scene.componentStorageManager);
}
/**
* 创建场景构建器
* @returns 场景构建器
*/
public createScene(): SceneBuilder {
return new SceneBuilder();
}
/**
* 创建组件构建器
* @param componentClass 组件类
* @param args 构造参数
* @returns 组件构建器
*/
public createComponent<T extends Component>(
componentClass: new (...args: unknown[]) => T,
...args: unknown[]
): ComponentBuilder<T> {
return new ComponentBuilder(componentClass, ...args);
}
/**
* 创建查询构建器
* @returns 查询构建器
*/
public query(): QueryBuilder {
return new QueryBuilder(this.querySystem);
}
/**
* 查找实体（简化版）
* @param componentTypes 组件类型
* @returns 实体数组
*/
public find(...componentTypes: ComponentType[]): Entity[] {
return this.querySystem.queryAll(...componentTypes).entities;
}
/**
* 查找第一个匹配的实体
* @param componentTypes 组件类型
* @returns 实体或null
*/
public findFirst(...componentTypes: ComponentType[]): Entity | null {
const result = this.querySystem.queryAll(...componentTypes);
return result.entities.length > 0 ? result.entities[0] : null;
}
/**
* 按名称查找实体
* @param name 实体名称
* @returns 实体或null
*/
public findByName(name: string): Entity | null {
return this.scene.getEntityByName(name);
}
/**
* 按标签查找实体
* @param tag 标签
* @returns 实体数组
*/
public findByTag(tag: number): Entity[] {
return this.scene.getEntitiesByTag(tag);
}
/**
* 触发事件
* @param eventType 事件类型
* @param event 事件数据
*/
public emit<T>(eventType: string, event: T): void {
this.eventSystem.emitSync(eventType, event);
}
/**
* 异步触发事件
* @param eventType 事件类型
* @param event 事件数据
*/
public async emitAsync<T>(eventType: string, event: T): Promise<void> {
await this.eventSystem.emit(eventType, event);
}
/**
* 监听事件
* @param eventType 事件类型
* @param handler 事件处理器
* @returns 监听器ID
*/
public on<T>(eventType: string, handler: (event: T) => void): string {
return this.eventSystem.on(eventType, handler);
}
/**
* 一次性监听事件
* @param eventType 事件类型
* @param handler 事件处理器
* @returns 监听器ID
*/
public once<T>(eventType: string, handler: (event: T) => void): string {
return this.eventSystem.once(eventType, handler);
}
/**
* 移除事件监听器
* @param eventType 事件类型
* @param listenerId 监听器ID
*/
public off(eventType: string, listenerId: string): void {
this.eventSystem.off(eventType, listenerId);
}
/**
* 批量操作实体
* @param entities 实体数组
* @returns 批量操作器
*/
public batch(entities: Entity[]): EntityBatchOperator {
return new EntityBatchOperator(entities);
}
/**
* 获取场景统计信息
* @returns 统计信息
*/
public getStats(): {
entityCount: number;
systemCount: number;
componentStats: Map<string, any>;
queryStats: unknown;
eventStats: Map<string, any>;
} {
return {
entityCount: this.scene.entities.count,
systemCount: this.scene.systems.length,
componentStats: this.scene.componentStorageManager.getAllStats(),
queryStats: this.querySystem.getStats(),
eventStats: this.eventSystem.getStats() as Map<string, any>
};
}
}
/**
* 实体批量操作器
* 提供对多个实体的批量操作
*/
export class EntityBatchOperator {
private entities: Entity[];
constructor(entities: Entity[]) {
this.entities = entities;
}
/**
* 批量添加组件
* @param component 组件实例
* @returns 批量操作器
*/
public addComponent<T extends Component>(component: T): EntityBatchOperator {
for (const entity of this.entities) {
entity.addComponent(component);
}
return this;
}
/**
* 批量移除组件
* @param componentType 组件类型
* @returns 批量操作器
*/
public removeComponent<T extends Component>(componentType: ComponentType<T>): EntityBatchOperator {
for (const entity of this.entities) {
entity.removeComponentByType(componentType);
}
return this;
}
/**
* 批量设置活跃状态
* @param active 是否活跃
* @returns 批量操作器
*/
public setActive(active: boolean): EntityBatchOperator {
for (const entity of this.entities) {
entity.active = active;
}
return this;
}
/**
* 批量设置标签
* @param tag 标签
* @returns 批量操作器
*/
public setTag(tag: number): EntityBatchOperator {
for (const entity of this.entities) {
entity.tag = tag;
}
return this;
}
/**
* 批量执行操作
* @param operation 操作函数
* @returns 批量操作器
*/
public forEach(operation: (entity: Entity, index: number) => void): EntityBatchOperator {
this.entities.forEach(operation);
return this;
}
/**
* 过滤实体
* @param predicate 过滤条件
* @returns 新的批量操作器
*/
public filter(predicate: (entity: Entity) => boolean): EntityBatchOperator {
return new EntityBatchOperator(this.entities.filter(predicate));
}
/**
* 获取实体数组
* @returns 实体数组
*/
public toArray(): Entity[] {
return this.entities.slice();
}
/**
* 获取实体数量
* @returns 实体数量
*/
public count(): number {
return this.entities.length;
}
}
/**
* 创建ECS流式API实例
* @param scene 场景
* @param querySystem 查询系统
* @param eventSystem 事件系统
* @returns ECS流式API实例
*/
export function createECSAPI(
scene: Scene,
querySystem: QuerySystem,
eventSystem: TypeSafeEventSystem
): ECSFluentAPI {
return new ECSFluentAPI(scene, querySystem, eventSystem);
}
/**
* 全局ECS流式API实例（需要在使用前初始化）
*/
export let ECS: ECSFluentAPI;
/**
* 初始化全局ECS API
* @param scene 场景
* @param querySystem 查询系统
* @param eventSystem 事件系统
*/
export function initializeECS(
scene: Scene,
querySystem: QuerySystem,
eventSystem: TypeSafeEventSystem
): void {
ECS = createECSAPI(scene, querySystem, eventSystem);
}
// 重新导出拆分后的模块以保持向后兼容性
export {
EntityBuilder,
SceneBuilder,
ComponentBuilder,
EntityBatchOperator,
ECSFluentAPI,
createECSAPI,
initializeECS,
ECS
} from './FluentAPI/index';

55
packages/core/src/ECS/Core/FluentAPI/ComponentBuilder.ts Normal file
View File

@@ -0,0 +1,55 @@
import { Component } from '../../Component';
/**
* 组件构建器 - 提供流式API创建组件
*/
export class ComponentBuilder<T extends Component> {
private component: T;
constructor(componentClass: new (...args: unknown[]) => T, ...args: unknown[]) {
this.component = new componentClass(...args);
}
/**
* 设置组件属性
* @param property 属性名
* @param value 属性值
* @returns 组件构建器
*/
public set<K extends keyof T>(property: K, value: T[K]): ComponentBuilder<T> {
this.component[property] = value;
return this;
}
/**
* 使用配置函数设置组件
* @param configurator 配置函数
* @returns 组件构建器
*/
public configure(configurator: (component: T) => void): ComponentBuilder<T> {
configurator(this.component);
return this;
}
/**
* 条件性设置属性
* @param condition 条件
* @param property 属性名
* @param value 属性值
* @returns 组件构建器
*/
public setIf<K extends keyof T>(condition: boolean, property: K, value: T[K]): ComponentBuilder<T> {
if (condition) {
this.component[property] = value;
}
return this;
}
/**
* 构建并返回组件
* @returns 构建的组件
*/
public build(): T {
return this.component;
}
}

210
packages/core/src/ECS/Core/FluentAPI/ECSFluentAPI.ts Normal file
View File

@@ -0,0 +1,210 @@
import { Entity } from '../../Entity';
import { Component } from '../../Component';
import { Scene } from '../../Scene';
import { ComponentType } from '../ComponentStorage';
import { QuerySystem, QueryBuilder } from '../QuerySystem';
import { TypeSafeEventSystem } from '../EventSystem';
import { EntityBuilder } from './EntityBuilder';
import { SceneBuilder } from './SceneBuilder';
import { ComponentBuilder } from './ComponentBuilder';
import { EntityBatchOperator } from './EntityBatchOperator';
/**
* ECS流式API主入口
* 提供统一的流式接口
*/
export class ECSFluentAPI {
private scene: Scene;
private querySystem: QuerySystem;
private eventSystem: TypeSafeEventSystem;
constructor(scene: Scene, querySystem: QuerySystem, eventSystem: TypeSafeEventSystem) {
this.scene = scene;
this.querySystem = querySystem;
this.eventSystem = eventSystem;
}
/**
* 创建实体构建器
* @returns 实体构建器
*/
public createEntity(): EntityBuilder {
return new EntityBuilder(this.scene, this.scene.componentStorageManager);
}
/**
* 创建场景构建器
* @returns 场景构建器
*/
public createScene(): SceneBuilder {
return new SceneBuilder();
}
/**
* 创建组件构建器
* @param componentClass 组件类
* @param args 构造参数
* @returns 组件构建器
*/
public createComponent<T extends Component>(
componentClass: new (...args: unknown[]) => T,
...args: unknown[]
): ComponentBuilder<T> {
return new ComponentBuilder(componentClass, ...args);
}
/**
* 创建查询构建器
* @returns 查询构建器
*/
public query(): QueryBuilder {
return new QueryBuilder(this.querySystem);
}
/**
* 查找实体（简化版）
* @param componentTypes 组件类型
* @returns 实体数组
*/
public find(...componentTypes: ComponentType[]): Entity[] {
return this.querySystem.queryAll(...componentTypes).entities;
}
/**
* 查找第一个匹配的实体
* @param componentTypes 组件类型
* @returns 实体或null
*/
public findFirst(...componentTypes: ComponentType[]): Entity | null {
const result = this.querySystem.queryAll(...componentTypes);
return result.entities.length > 0 ? result.entities[0] : null;
}
/**
* 按名称查找实体
* @param name 实体名称
* @returns 实体或null
*/
public findByName(name: string): Entity | null {
return this.scene.getEntityByName(name);
}
/**
* 按标签查找实体
* @param tag 标签
* @returns 实体数组
*/
public findByTag(tag: number): Entity[] {
return this.scene.getEntitiesByTag(tag);
}
/**
* 触发事件
* @param eventType 事件类型
* @param event 事件数据
*/
public emit<T>(eventType: string, event: T): void {
this.eventSystem.emitSync(eventType, event);
}
/**
* 异步触发事件
* @param eventType 事件类型
* @param event 事件数据
*/
public async emitAsync<T>(eventType: string, event: T): Promise<void> {
await this.eventSystem.emit(eventType, event);
}
/**
* 监听事件
* @param eventType 事件类型
* @param handler 事件处理器
* @returns 监听器ID
*/
public on<T>(eventType: string, handler: (event: T) => void): string {
return this.eventSystem.on(eventType, handler);
}
/**
* 一次性监听事件
* @param eventType 事件类型
* @param handler 事件处理器
* @returns 监听器ID
*/
public once<T>(eventType: string, handler: (event: T) => void): string {
return this.eventSystem.once(eventType, handler);
}
/**
* 移除事件监听器
* @param eventType 事件类型
* @param listenerId 监听器ID
*/
public off(eventType: string, listenerId: string): void {
this.eventSystem.off(eventType, listenerId);
}
/**
* 批量操作实体
* @param entities 实体数组
* @returns 批量操作器
*/
public batch(entities: Entity[]): EntityBatchOperator {
return new EntityBatchOperator(entities);
}
/**
* 获取场景统计信息
* @returns 统计信息
*/
public getStats(): {
entityCount: number;
systemCount: number;
componentStats: Map<string, any>;
queryStats: unknown;
eventStats: Map<string, any>;
} {
return {
entityCount: this.scene.entities.count,
systemCount: this.scene.systems.length,
componentStats: this.scene.componentStorageManager.getAllStats(),
queryStats: this.querySystem.getStats(),
eventStats: this.eventSystem.getStats() as Map<string, any>
};
}
}
/**
* 创建ECS流式API实例
* @param scene 场景
* @param querySystem 查询系统
* @param eventSystem 事件系统
* @returns ECS流式API实例
*/
export function createECSAPI(
scene: Scene,
querySystem: QuerySystem,
eventSystem: TypeSafeEventSystem
): ECSFluentAPI {
return new ECSFluentAPI(scene, querySystem, eventSystem);
}
/**
* 全局ECS流式API实例（需要在使用前初始化）
*/
export let ECS: ECSFluentAPI;
/**
* 初始化全局ECS API
* @param scene 场景
* @param querySystem 查询系统
* @param eventSystem 事件系统
*/
export function initializeECS(
scene: Scene,
querySystem: QuerySystem,
eventSystem: TypeSafeEventSystem
): void {
ECS = createECSAPI(scene, querySystem, eventSystem);
}

98
packages/core/src/ECS/Core/FluentAPI/EntityBatchOperator.ts Normal file
View File

@@ -0,0 +1,98 @@
import { Entity } from '../../Entity';
import { Component } from '../../Component';
import { ComponentType } from '../ComponentStorage';
/**
* 实体批量操作器
* 提供对多个实体的批量操作
*/
export class EntityBatchOperator {
private entities: Entity[];
constructor(entities: Entity[]) {
this.entities = entities;
}
/**
* 批量添加组件
* @param component 组件实例
* @returns 批量操作器
*/
public addComponent<T extends Component>(component: T): EntityBatchOperator {
for (const entity of this.entities) {
entity.addComponent(component);
}
return this;
}
/**
* 批量移除组件
* @param componentType 组件类型
* @returns 批量操作器
*/
public removeComponent<T extends Component>(componentType: ComponentType<T>): EntityBatchOperator {
for (const entity of this.entities) {
entity.removeComponentByType(componentType);
}
return this;
}
/**
* 批量设置活跃状态
* @param active 是否活跃
* @returns 批量操作器
*/
public setActive(active: boolean): EntityBatchOperator {
for (const entity of this.entities) {
entity.active = active;
}
return this;
}
/**
* 批量设置标签
* @param tag 标签
* @returns 批量操作器
*/
public setTag(tag: number): EntityBatchOperator {
for (const entity of this.entities) {
entity.tag = tag;
}
return this;
}
/**
* 批量执行操作
* @param operation 操作函数
* @returns 批量操作器
*/
public forEach(operation: (entity: Entity, index: number) => void): EntityBatchOperator {
this.entities.forEach(operation);
return this;
}
/**
* 过滤实体
* @param predicate 过滤条件
* @returns 新的批量操作器
*/
public filter(predicate: (entity: Entity) => boolean): EntityBatchOperator {
return new EntityBatchOperator(this.entities.filter(predicate));
}
/**
* 获取实体数组
* @returns 实体数组
*/
public toArray(): Entity[] {
return this.entities.slice();
}
/**
* 获取实体数量
* @returns 实体数量
*/
public count(): number {
return this.entities.length;
}
}

200
packages/core/src/ECS/Core/FluentAPI/EntityBuilder.ts Normal file
View File

@@ -0,0 +1,200 @@
import { Entity } from '../../Entity';
import { Component } from '../../Component';
import { Scene } from '../../Scene';
import { ComponentType, ComponentStorageManager } from '../ComponentStorage';
/**
* 实体构建器 - 提供流式API创建和配置实体
*/
export class EntityBuilder {
private entity: Entity;
private scene: Scene;
private storageManager: ComponentStorageManager;
constructor(scene: Scene, storageManager: ComponentStorageManager) {
this.scene = scene;
this.storageManager = storageManager;
this.entity = new Entity("", scene.identifierPool.checkOut());
}
/**
* 设置实体名称
* @param name 实体名称
* @returns 实体构建器
*/
public named(name: string): EntityBuilder {
this.entity.name = name;
return this;
}
/**
* 设置实体标签
* @param tag 标签
* @returns 实体构建器
*/
public tagged(tag: number): EntityBuilder {
this.entity.tag = tag;
return this;
}
/**
* 添加组件
* @param component 组件实例
* @returns 实体构建器
*/
public with<T extends Component>(component: T): EntityBuilder {
this.entity.addComponent(component);
return this;
}
/**
* 添加多个组件
* @param components 组件数组
* @returns 实体构建器
*/
public withComponents(...components: Component[]): EntityBuilder {
for (const component of components) {
this.entity.addComponent(component);
}
return this;
}
/**
* 条件性添加组件
* @param condition 条件
* @param component 组件实例
* @returns 实体构建器
*/
public withIf<T extends Component>(condition: boolean, component: T): EntityBuilder {
if (condition) {
this.entity.addComponent(component);
}
return this;
}
/**
* 使用工厂函数创建并添加组件
* @param factory 组件工厂函数
* @returns 实体构建器
*/
public withFactory<T extends Component>(factory: () => T): EntityBuilder {
const component = factory();
this.entity.addComponent(component);
return this;
}
/**
* 配置组件属性
* @param componentType 组件类型
* @param configurator 配置函数
* @returns 实体构建器
*/
public configure<T extends Component>(
componentType: ComponentType<T>,
configurator: (component: T) => void
): EntityBuilder {
const component = this.entity.getComponent(componentType);
if (component) {
configurator(component);
}
return this;
}
/**
* 设置实体为启用状态
* @param enabled 是否启用
* @returns 实体构建器
*/
public enabled(enabled: boolean = true): EntityBuilder {
this.entity.enabled = enabled;
return this;
}
/**
* 设置实体为活跃状态
* @param active 是否活跃
* @returns 实体构建器
*/
public active(active: boolean = true): EntityBuilder {
this.entity.active = active;
return this;
}
/**
* 添加子实体
* @param childBuilder 子实体构建器
* @returns 实体构建器
*/
public withChild(childBuilder: EntityBuilder): EntityBuilder {
const child = childBuilder.build();
this.entity.addChild(child);
return this;
}
/**
* 批量添加子实体
* @param childBuilders 子实体构建器数组
* @returns 实体构建器
*/
public withChildren(...childBuilders: EntityBuilder[]): EntityBuilder {
for (const childBuilder of childBuilders) {
const child = childBuilder.build();
this.entity.addChild(child);
}
return this;
}
/**
* 使用工厂函数创建子实体
* @param childFactory 子实体工厂函数
* @returns 实体构建器
*/
public withChildFactory(childFactory: (parent: Entity) => EntityBuilder): EntityBuilder {
const childBuilder = childFactory(this.entity);
const child = childBuilder.build();
this.entity.addChild(child);
return this;
}
/**
* 条件性添加子实体
* @param condition 条件
* @param childBuilder 子实体构建器
* @returns 实体构建器
*/
public withChildIf(condition: boolean, childBuilder: EntityBuilder): EntityBuilder {
if (condition) {
const child = childBuilder.build();
this.entity.addChild(child);
}
return this;
}
/**
* 构建并返回实体
* @returns 构建的实体
*/
public build(): Entity {
return this.entity;
}
/**
* 构建实体并添加到场景
* @returns 构建的实体
*/
public spawn(): Entity {
this.scene.addEntity(this.entity);
return this.entity;
}
/**
* 克隆当前构建器
* @returns 新的实体构建器
*/
public clone(): EntityBuilder {
const newBuilder = new EntityBuilder(this.scene, this.storageManager);
// 这里需要深度克隆实体，简化实现
newBuilder.entity = this.entity; // 实际应该是深度克隆
return newBuilder;
}
}

90
packages/core/src/ECS/Core/FluentAPI/SceneBuilder.ts Normal file
View File

@@ -0,0 +1,90 @@
import { Entity } from '../../Entity';
import { Scene } from '../../Scene';
import { EntitySystem } from '../../Systems/EntitySystem';
import { EntityBuilder } from './EntityBuilder';
/**
* 场景构建器 - 提供流式API创建和配置场景
*/
export class SceneBuilder {
private scene: Scene;
constructor() {
this.scene = new Scene();
}
/**
* 设置场景名称
* @param name 场景名称
* @returns 场景构建器
*/
public named(name: string): SceneBuilder {
this.scene.name = name;
return this;
}
/**
* 添加实体
* @param entity 实体
* @returns 场景构建器
*/
public withEntity(entity: Entity): SceneBuilder {
this.scene.addEntity(entity);
return this;
}
/**
* 使用实体构建器添加实体
* @param builderFn 实体构建器函数
* @returns 场景构建器
*/
public withEntityBuilder(builderFn: (builder: EntityBuilder) => EntityBuilder): SceneBuilder {
const builder = new EntityBuilder(this.scene, this.scene.componentStorageManager);
const configuredBuilder = builderFn(builder);
const entity = configuredBuilder.build();
this.scene.addEntity(entity);
return this;
}
/**
* 批量添加实体
* @param entities 实体数组
* @returns 场景构建器
*/
public withEntities(...entities: Entity[]): SceneBuilder {
for (const entity of entities) {
this.scene.addEntity(entity);
}
return this;
}
/**
* 添加系统
* @param system 系统实例
* @returns 场景构建器
*/
public withSystem(system: EntitySystem): SceneBuilder {
this.scene.addSystem(system);
return this;
}
/**
* 批量添加系统
* @param systems 系统数组
* @returns 场景构建器
*/
public withSystems(...systems: EntitySystem[]): SceneBuilder {
for (const system of systems) {
this.scene.addSystem(system);
}
return this;
}
/**
* 构建并返回场景
* @returns 构建的场景
*/
public build(): Scene {
return this.scene;
}
}

5
packages/core/src/ECS/Core/FluentAPI/index.ts Normal file
View File

@@ -0,0 +1,5 @@
export { EntityBuilder } from './EntityBuilder';
export { SceneBuilder } from './SceneBuilder';
export { ComponentBuilder } from './ComponentBuilder';
export { EntityBatchOperator } from './EntityBatchOperator';
export { ECSFluentAPI, createECSAPI, initializeECS, ECS } from './ECSFluentAPI';

13
packages/core/src/ECS/Core/QuerySystem.ts
View File

@@ -2,6 +2,7 @@ import { Entity } from '../Entity';
import { Component } from '../Component';
import { ComponentRegistry, ComponentType } from './ComponentStorage';
import { IBigIntLike, BigIntFactory } from '../Utils/BigIntCompatibility';
import { createLogger } from '../../Utils/Logger';
import { ComponentPoolManager } from './ComponentPool';
import { ComponentIndexManager, IndexType } from './ComponentIndex';
@@ -82,6 +83,7 @@ interface QueryCacheEntry {
* ```
*/
export class QuerySystem {
private _logger = createLogger('QuerySystem');
private entities: Entity[] = [];
private entityIndex: EntityIndex;
private indexDirty = true;
@@ -390,7 +392,7 @@ export class QuerySystem {
* ```typescript
* // 查询同时具有位置和速度组件的实体
* const result = querySystem.queryAll(PositionComponent, VelocityComponent);
* console.log(`找到 ${result.count} 个移动实体`);
* logger.info(`找到 ${result.count} 个移动实体`);
* ```
*/
public queryAll(...componentTypes: ComponentType[]): QueryResult {
@@ -502,7 +504,7 @@ export class QuerySystem {
* ```typescript
* // 查询具有武器或护甲组件的实体
* const result = querySystem.queryAny(WeaponComponent, ArmorComponent);
* console.log(`找到 ${result.count} 个装备实体`);
* logger.info(`找到 ${result.count} 个装备实体`);
* ```
*/
public queryAny(...componentTypes: ComponentType[]): QueryResult {
@@ -560,7 +562,7 @@ export class QuerySystem {
* ```typescript
* // 查询不具有AI和玩家控制组件的实体（如静态物体）
* const result = querySystem.queryNone(AIComponent, PlayerControlComponent);
* console.log(`找到 ${result.count} 个静态实体`);
* logger.info(`找到 ${result.count} 个静态实体`);
* ```
*/
public queryNone(...componentTypes: ComponentType[]): QueryResult {
@@ -878,7 +880,7 @@ export class QuerySystem {
mask = mask.or(bitMask);
hasValidComponents = true;
} catch (error) {
console.warn(`组件类型 ${type.name} 未注册，跳过`);
this._logger.warn(`组件类型 ${type.name} 未注册，跳过`);
}
}
@@ -1054,6 +1056,7 @@ export class QuerySystem {
* ```
*/
export class QueryBuilder {
private _logger = createLogger('QueryBuilder');
private conditions: QueryCondition[] = [];
private querySystem: QuerySystem;
@@ -1148,7 +1151,7 @@ export class QueryBuilder {
const bitMask = ComponentRegistry.getBitMask(type);
mask = mask.or(bitMask);
} catch (error) {
console.warn(`组件类型 ${type.name} 未注册，跳过`);
this._logger.warn(`组件类型 ${type.name} 未注册，跳过`);
}
}
return mask;

6
packages/core/src/ECS/Core/SoAStorage.ts
View File

@@ -1,5 +1,6 @@
import { Component } from '../Component';
import { ComponentType } from './ComponentStorage';
import { createLogger } from '../../Utils/Logger';
/**
* 启用SoA优化装饰器
@@ -113,6 +114,7 @@ export function DeepCopy(target: any, propertyKey: string | symbol): void {
* 使用Structure of Arrays存储模式，在大规模批量操作时提供优异性能
*/
export class SoAStorage<T extends Component> {
private static readonly _logger = createLogger('SoAStorage');
private fields = new Map<string, Float32Array | Float64Array | Int32Array>();
private stringFields = new Map<string, string[]>(); // 专门存储字符串
private serializedFields = new Map<string, string[]>(); // 序列化存储Map/Set/Array
@@ -276,7 +278,7 @@ export class SoAStorage<T extends Component> {
return JSON.stringify(value);
}
} catch (error) {
console.warn(`SoA序列化字段 ${key} 失败:`, error);
SoAStorage._logger.warn(`SoA序列化字段 ${key} 失败:`, error);
return '{}';
}
}
@@ -301,7 +303,7 @@ export class SoAStorage<T extends Component> {
return parsed;
}
} catch (error) {
console.warn(`SoA反序列化字段 ${key} 失败:`, error);
SoAStorage._logger.warn(`SoA反序列化字段 ${key} 失败:`, error);
return null;
}
}

8
packages/core/src/ECS/Entity.ts
View File

@@ -2,6 +2,7 @@ import { Component } from './Component';
import { ComponentRegistry, ComponentType } from './Core/ComponentStorage';
import { EventBus } from './Core/EventBus';
import { IBigIntLike, BigIntFactory } from './Utils/BigIntCompatibility';
import { createLogger } from '../Utils/Logger';
// Forward declaration to avoid circular dependency
interface IScene {
@@ -65,6 +66,11 @@ export class EntityComparer {
* ```
*/
export class Entity {
/**
* Entity专用日志器
*/
private static _logger = createLogger('Entity');
/**
* 实体比较器实例
*/
@@ -630,7 +636,7 @@ export class Entity {
addedComponents.push(this.addComponent(component));
} catch (error) {
// 如果某个组件添加失败，继续添加其他组件
console.warn(`添加组件失败 ${component.constructor.name}:`, error);
Entity._logger.warn(`添加组件失败 ${component.constructor.name}:`, error);
}
}

4
packages/core/src/ECS/Utils/EntityProcessorList.ts
View File

@@ -1,10 +1,12 @@
import { EntitySystem } from '../Systems/EntitySystem';
import { createLogger } from '../../Utils/Logger';
/**
* 实体处理器列表管理器
* 管理场景中的所有实体系统
*/
export class EntityProcessorList {
private static readonly _logger = createLogger('EntityProcessorList');
private _processors: EntitySystem[] = [];
private _isDirty = false;
@@ -73,7 +75,7 @@ export class EntityProcessorList {
try {
processor.update();
} catch (error) {
console.error(`Error in processor ${processor.constructor.name}:`, error);
EntityProcessorList._logger.error(`Error in processor ${processor.constructor.name}:`, error);
}
}
}

310
packages/core/src/Utils/Logger.ts Normal file
View File

@@ -0,0 +1,310 @@
/**
* 日志级别
*/
export enum LogLevel {
Debug = 0,
Info = 1,
Warn = 2,
Error = 3,
Fatal = 4,
None = 5
}
/**
* 日志接口
*/
export interface ILogger {
debug(message: string, ...args: unknown[]): void;
info(message: string, ...args: unknown[]): void;
warn(message: string, ...args: unknown[]): void;
error(message: string, ...args: unknown[]): void;
fatal(message: string, ...args: unknown[]): void;
}
/**
* 日志配置
*/
export interface LoggerConfig {
/** 日志级别 */
level: LogLevel;
/** 是否启用时间戳 */
enableTimestamp: boolean;
/** 是否启用颜色 */
enableColors: boolean;
/** 日志前缀 */
prefix?: string;
/** 自定义输出函数 */
output?: (level: LogLevel, message: string) => void;
}
/**
* 默认控制台日志实现
*/
export class ConsoleLogger implements ILogger {
private _config: LoggerConfig;
constructor(config: Partial<LoggerConfig> = {}) {
this._config = {
level: LogLevel.Info,
enableTimestamp: true,
enableColors: typeof window === 'undefined',
...config
};
}
/**
* 输出调试级别日志
* @param message 日志消息
* @param args 附加参数
*/
public debug(message: string, ...args: unknown[]): void {
this.log(LogLevel.Debug, message, ...args);
}
/**
* 输出信息级别日志
* @param message 日志消息
* @param args 附加参数
*/
public info(message: string, ...args: unknown[]): void {
this.log(LogLevel.Info, message, ...args);
}
/**
* 输出警告级别日志
* @param message 日志消息
* @param args 附加参数
*/
public warn(message: string, ...args: unknown[]): void {
this.log(LogLevel.Warn, message, ...args);
}
/**
* 输出错误级别日志
* @param message 日志消息
* @param args 附加参数
*/
public error(message: string, ...args: unknown[]): void {
this.log(LogLevel.Error, message, ...args);
}
/**
* 输出致命错误级别日志
* @param message 日志消息
* @param args 附加参数
*/
public fatal(message: string, ...args: unknown[]): void {
this.log(LogLevel.Fatal, message, ...args);
}
/**
* 设置日志级别
* @param level 日志级别
*/
public setLevel(level: LogLevel): void {
this._config.level = level;
}
/**
* 设置日志前缀
* @param prefix 前缀字符串
*/
public setPrefix(prefix: string): void {
this._config.prefix = prefix;
}
/**
* 内部日志输出方法
* @param level 日志级别
* @param message 日志消息
* @param args 附加参数
*/
private log(level: LogLevel, message: string, ...args: unknown[]): void {
if (level < this._config.level) {
return;
}
let formattedMessage = message;
// 添加时间戳
if (this._config.enableTimestamp) {
const timestamp = new Date().toISOString();
formattedMessage = `[${timestamp}] ${formattedMessage}`;
}
// 添加前缀
if (this._config.prefix) {
formattedMessage = `[${this._config.prefix}] ${formattedMessage}`;
}
// 添加日志级别
const levelName = LogLevel[level].toUpperCase();
formattedMessage = `[${levelName}] ${formattedMessage}`;
// 使用自定义输出或默认控制台输出
if (this._config.output) {
this._config.output(level, formattedMessage);
} else {
this.outputToConsole(level, formattedMessage, ...args);
}
}
/**
* 输出到控制台
* @param level 日志级别
* @param message 格式化后的消息
* @param args 附加参数
*/
private outputToConsole(level: LogLevel, message: string, ...args: unknown[]): void {
const colors = this._config.enableColors ? this.getColors() : null;
switch (level) {
case LogLevel.Debug:
if (colors) {
console.debug(`${colors.gray}${message}${colors.reset}`, ...args);
} else {
console.debug(message, ...args);
}
break;
case LogLevel.Info:
if (colors) {
console.info(`${colors.blue}${message}${colors.reset}`, ...args);
} else {
console.info(message, ...args);
}
break;
case LogLevel.Warn:
if (colors) {
console.warn(`${colors.yellow}${message}${colors.reset}`, ...args);
} else {
console.warn(message, ...args);
}
break;
case LogLevel.Error:
case LogLevel.Fatal:
if (colors) {
console.error(`${colors.red}${message}${colors.reset}`, ...args);
} else {
console.error(message, ...args);
}
break;
}
}
/**
* 获取控制台颜色配置
* @returns 颜色配置对象
*/
private getColors() {
return {
reset: '\x1b[0m',
red: '\x1b[31m',
yellow: '\x1b[33m',
blue: '\x1b[34m',
gray: '\x1b[90m'
};
}
}
/**
* 日志管理器
*/
export class LoggerManager {
private static _instance: LoggerManager;
private _loggers = new Map<string, ILogger>();
private _defaultLogger: ILogger;
private constructor() {
this._defaultLogger = new ConsoleLogger();
}
/**
* 获取日志管理器实例
* @returns 日志管理器实例
*/
public static getInstance(): LoggerManager {
if (!LoggerManager._instance) {
LoggerManager._instance = new LoggerManager();
}
return LoggerManager._instance;
}
/**
* 获取或创建日志器
* @param name 日志器名称
* @returns 日志器实例
*/
public getLogger(name?: string): ILogger {
if (!name) {
return this._defaultLogger;
}
if (!this._loggers.has(name)) {
const logger = new ConsoleLogger({
prefix: name,
level: LogLevel.Info
});
this._loggers.set(name, logger);
}
return this._loggers.get(name)!;
}
/**
* 设置日志器
* @param name 日志器名称
* @param logger 日志器实例
*/
public setLogger(name: string, logger: ILogger): void {
this._loggers.set(name, logger);
}
/**
* 设置全局日志级别
* @param level 日志级别
*/
public setGlobalLevel(level: LogLevel): void {
if (this._defaultLogger instanceof ConsoleLogger) {
this._defaultLogger.setLevel(level);
}
for (const logger of this._loggers.values()) {
if (logger instanceof ConsoleLogger) {
logger.setLevel(level);
}
}
}
/**
* 创建子日志器
* @param parentName 父日志器名称
* @param childName 子日志器名称
* @returns 子日志器实例
*/
public createChildLogger(parentName: string, childName: string): ILogger {
const fullName = `${parentName}.${childName}`;
return this.getLogger(fullName);
}
}
/**
* 默认日志器实例
*/
export const Logger = LoggerManager.getInstance().getLogger();
/**
* 创建命名日志器
* @param name 日志器名称
* @returns 日志器实例
*/
export function createLogger(name: string): ILogger {
return LoggerManager.getInstance().getLogger(name);
}
/**
* 设置全局日志级别
* @param level 日志级别
*/
export function setGlobalLogLevel(level: LogLevel): void {
LoggerManager.getInstance().setGlobalLevel(level);
}

565
packages/core/src/Utils/Pool.ts
View File

@@ -1,565 +0,0 @@
/**
* 可池化对象接口
*/
export interface IPoolable {
/**
* 重置对象状态，准备重用
*/
reset(): void;
}
/**
* 对象池统计信息
*/
export interface PoolStats {
/** 池中对象数量 */
size: number;
/** 池的最大大小 */
maxSize: number;
/** 总共创建的对象数量 */
totalCreated: number;
/** 总共获取的次数 */
totalObtained: number;
/** 总共释放的次数 */
totalReleased: number;
/** 命中率（从池中获取的比例） */
hitRate: number;
/** 内存使用估算（字节） */
estimatedMemoryUsage: number;
}
/**
* 高性能通用对象池
* 支持任意类型的对象池化，包含详细的统计信息
*/
export class Pool<T extends IPoolable> {
private static _pools = new Map<Function, Pool<any>>();
private _objects: T[] = [];
private _createFn: () => T;
private _maxSize: number;
private _stats: PoolStats;
private _objectSize: number; // 估算的单个对象大小
/**
* 构造函数
* @param createFn 创建对象的函数
* @param maxSize 池的最大大小，默认100
* @param estimatedObjectSize 估算的单个对象大小（字节），默认1024
*/
constructor(createFn: () => T, maxSize: number = 100, estimatedObjectSize: number = 1024) {
this._createFn = createFn;
this._maxSize = maxSize;
this._objectSize = estimatedObjectSize;
this._stats = {
size: 0,
maxSize,
totalCreated: 0,
totalObtained: 0,
totalReleased: 0,
hitRate: 0,
estimatedMemoryUsage: 0
};
}
/**
* 获取指定类型的对象池
* @param type 对象类型
* @param maxSize 池的最大大小
* @param estimatedObjectSize 估算的单个对象大小
* @returns 对象池实例
*/
public static getPool<T extends IPoolable>(
type: new (...args: unknown[]) => T,
maxSize: number = 100,
estimatedObjectSize: number = 1024
): Pool<T> {
let pool = this._pools.get(type);
if (!pool) {
pool = new Pool<T>(() => new type(), maxSize, estimatedObjectSize);
this._pools.set(type, pool);
}
return pool;
}
/**
* 从池中获取对象
* @returns 对象实例
*/
public obtain(): T {
this._stats.totalObtained++;
if (this._objects.length > 0) {
const obj = this._objects.pop()!;
this._stats.size--;
this._updateHitRate();
this._updateMemoryUsage();
return obj;
}
// 池中没有对象，创建新的
const obj = this._createFn();
this._stats.totalCreated++;
this._updateHitRate();
return obj;
}
/**
* 将对象归还到池中
* @param obj 要归还的对象
*/
public free(obj: T): void {
if (this._objects.length < this._maxSize) {
obj.reset();
this._objects.push(obj);
this._stats.size++;
this._stats.totalReleased++;
this._updateMemoryUsage();
}
// 如果池已满，对象会被丢弃（由GC回收）
}
/**
* 预热池，创建指定数量的对象
* @param count 要创建的对象数量
*/
public warmUp(count: number): void {
const targetSize = Math.min(count, this._maxSize);
while (this._objects.length < targetSize) {
const obj = this._createFn();
this._stats.totalCreated++;
this._objects.push(obj);
this._stats.size++;
}
this._updateMemoryUsage();
}
/**
* 清空池
*/
public clear(): void {
this._objects.length = 0;
this._stats.size = 0;
this._updateMemoryUsage();
}
/**
* 获取池中对象数量
*/
public get size(): number {
return this._objects.length;
}
/**
* 获取池的最大大小
*/
public get maxSize(): number {
return this._maxSize;
}
/**
* 设置池的最大大小
*/
public set maxSize(value: number) {
this._maxSize = value;
this._stats.maxSize = value;
// 如果当前池大小超过新的最大值，则移除多余的对象
while (this._objects.length > this._maxSize) {
this._objects.pop();
this._stats.size--;
}
this._updateMemoryUsage();
}
/**
* 获取池的统计信息
*/
public getStats(): PoolStats {
return { ...this._stats };
}
/**
* 重置统计信息
*/
public resetStats(): void {
this._stats.totalCreated = 0;
this._stats.totalObtained = 0;
this._stats.totalReleased = 0;
this._stats.hitRate = 0;
}
/**
* 更新命中率
*/
private _updateHitRate(): void {
if (this._stats.totalObtained > 0) {
const hits = this._stats.totalObtained - this._stats.totalCreated;
this._stats.hitRate = hits / this._stats.totalObtained;
}
}
/**
* 更新内存使用估算
*/
private _updateMemoryUsage(): void {
this._stats.estimatedMemoryUsage = this._stats.size * this._objectSize;
}
/**
* 静态方法：从指定类型的池中获取对象
* @param type 对象类型
* @returns 对象实例
*/
public static obtain<T extends IPoolable>(type: new (...args: unknown[]) => T): T {
return this.getPool(type).obtain();
}
/**
* 静态方法：将对象归还到对应类型的池中
* @param type 对象类型
* @param obj 要归还的对象
*/
public static free<T extends IPoolable>(type: new (...args: unknown[]) => T, obj: T): void {
this.getPool(type).free(obj);
}
/**
* 静态方法：预热指定类型的池
* @param type 对象类型
* @param count 要创建的对象数量
*/
public static warmUp<T extends IPoolable>(type: new (...args: unknown[]) => T, count: number): void {
this.getPool(type).warmUp(count);
}
/**
* 静态方法：清空指定类型的池
* @param type 对象类型
*/
public static clearPool<T extends IPoolable>(type: new (...args: unknown[]) => T): void {
const pool = this._pools.get(type);
if (pool) {
pool.clear();
}
}
/**
* 静态方法：清空所有池
*/
public static clearAllPools(): void {
for (const pool of this._pools.values()) {
pool.clear();
}
this._pools.clear();
}
/**
* 静态方法：获取池的统计信息
* @returns 池的统计信息
*/
public static getStats(): { [typeName: string]: PoolStats } {
const stats: { [typeName: string]: PoolStats } = {};
for (const [type, pool] of this._pools.entries()) {
const typeName = (type as any).name || 'Unknown';
stats[typeName] = pool.getStats();
}
return stats;
}
/**
* 静态方法：获取所有池的总内存使用量
* @returns 总内存使用量（字节）
*/
public static getTotalMemoryUsage(): number {
let total = 0;
for (const pool of this._pools.values()) {
total += pool.getStats().estimatedMemoryUsage;
}
return total;
}
/**
* 静态方法：获取性能报告
* @returns 格式化的性能报告
*/
public static getPerformanceReport(): string {
const stats = this.getStats();
const lines: string[] = [];
lines.push('=== Object Pool Performance Report ===');
lines.push(`Total Memory Usage: ${(this.getTotalMemoryUsage() / 1024 / 1024).toFixed(2)} MB`);
lines.push('');
for (const [typeName, stat] of Object.entries(stats)) {
lines.push(`${typeName}:`);
lines.push(` Size: ${stat.size}/${stat.maxSize}`);
lines.push(` Hit Rate: ${(stat.hitRate * 100).toFixed(1)}%`);
lines.push(` Total Created: ${stat.totalCreated}`);
lines.push(` Total Obtained: ${stat.totalObtained}`);
lines.push(` Memory: ${(stat.estimatedMemoryUsage / 1024).toFixed(1)} KB`);
lines.push('');
}
return lines.join('\n');
}
}
/**
* 分层对象池
* 使用多个不同大小的池来优化内存使用
*/
export class TieredObjectPool<T extends IPoolable> {
private pools: Pool<T>[] = [];
private createFn: () => T;
private resetFn: (obj: T) => void;
private tierSizes: number[];
private totalObtained = 0;
private totalReleased = 0;
/**
* 构造函数
* @param createFn 创建对象的函数
* @param resetFn 重置对象的函数
* @param tierSizes 各层级的大小，默认[10, 50, 200]
* @param estimatedObjectSize 估算的单个对象大小
*/
constructor(
createFn: () => T,
resetFn: (obj: T) => void,
tierSizes: number[] = [10, 50, 200],
estimatedObjectSize: number = 1024
) {
this.createFn = createFn;
this.resetFn = resetFn;
this.tierSizes = tierSizes;
// 初始化不同层级的池
for (const size of tierSizes) {
this.pools.push(new Pool(createFn, size, estimatedObjectSize));
}
}
/**
* 获取对象
* @returns 对象实例
*/
public obtain(): T {
this.totalObtained++;
// 从最小的池开始尝试获取
for (const pool of this.pools) {
if (pool.size > 0) {
return pool.obtain();
}
}
// 所有池都空了，创建新对象
return this.createFn();
}
/**
* 释放对象
* @param obj 要释放的对象
*/
public release(obj: T): void {
this.totalReleased++;
this.resetFn(obj);
// 放入第一个有空间的池
for (const pool of this.pools) {
if (pool.size < pool.maxSize) {
pool.free(obj);
return;
}
}
// 所有池都满了，直接丢弃
}
/**
* 预热所有池
* @param totalCount 总预热数量
*/
public warmUp(totalCount: number): void {
let remaining = totalCount;
for (const pool of this.pools) {
const warmUpCount = Math.min(remaining, pool.maxSize);
pool.warmUp(warmUpCount);
remaining -= warmUpCount;
if (remaining <= 0) break;
}
}
/**
* 清空所有池
*/
public clear(): void {
for (const pool of this.pools) {
pool.clear();
}
}
/**
* 获取统计信息
*/
public getStats(): {
totalSize: number;
totalMaxSize: number;
totalMemoryUsage: number;
tierStats: PoolStats[];
hitRate: number;
} {
let totalSize = 0;
let totalMaxSize = 0;
let totalMemoryUsage = 0;
const tierStats: PoolStats[] = [];
for (const pool of this.pools) {
const stats = pool.getStats();
tierStats.push(stats);
totalSize += stats.size;
totalMaxSize += stats.maxSize;
totalMemoryUsage += stats.estimatedMemoryUsage;
}
const hitRate = this.totalObtained > 0 ?
(this.totalObtained - this.getTotalCreated()) / this.totalObtained : 0;
return {
totalSize,
totalMaxSize,
totalMemoryUsage,
tierStats,
hitRate
};
}
/**
* 获取总创建数量
*/
private getTotalCreated(): number {
return this.pools.reduce((total, pool) => total + pool.getStats().totalCreated, 0);
}
}
/**
* 池管理器
* 统一管理所有对象池
*/
export class PoolManager {
private static instance: PoolManager;
private pools = new Map<string, Pool<any> | TieredObjectPool<any>>();
private autoCompactInterval = 60000; // 60秒
private lastCompactTime = 0;
public static getInstance(): PoolManager {
if (!PoolManager.instance) {
PoolManager.instance = new PoolManager();
}
return PoolManager.instance;
}
/**
* 注册池
* @param name 池名称
* @param pool 池实例
*/
public registerPool<T extends IPoolable>(name: string, pool: Pool<T> | TieredObjectPool<T>): void {
this.pools.set(name, pool);
}
/**
* 获取池
* @param name 池名称
* @returns 池实例
*/
public getPool<T extends IPoolable>(name: string): Pool<T> | TieredObjectPool<T> | null {
return this.pools.get(name) || null;
}
/**
* 更新池管理器（应在游戏循环中调用）
*/
public update(): void {
const now = Date.now();
if (now - this.lastCompactTime > this.autoCompactInterval) {
this.compactAllPools();
this.lastCompactTime = now;
}
}
/**
* 压缩所有池（清理碎片）
*/
public compactAllPools(): void {
// 对于标准池，可以考虑清理一些长时间未使用的对象
// 这里简单实现为重置统计信息
for (const pool of this.pools.values()) {
if (pool instanceof Pool) {
pool.resetStats();
}
}
}
/**
* 获取所有池的统计信息
*/
public getAllStats(): Map<string, any> {
const stats = new Map<string, any>();
for (const [name, pool] of this.pools.entries()) {
if (pool instanceof Pool) {
stats.set(name, pool.getStats());
} else if (pool instanceof TieredObjectPool) {
stats.set(name, pool.getStats());
}
}
return stats;
}
/**
* 生成性能报告
*/
public generateReport(): string {
const lines: string[] = [];
lines.push('=== Pool Manager Report ===');
let totalMemory = 0;
for (const [name, pool] of this.pools.entries()) {
lines.push(`\n${name}:`);
if (pool instanceof Pool) {
const stats = pool.getStats();
lines.push(` Type: Standard Pool`);
lines.push(` Size: ${stats.size}/${stats.maxSize}`);
lines.push(` Hit Rate: ${(stats.hitRate * 100).toFixed(1)}%`);
lines.push(` Memory: ${(stats.estimatedMemoryUsage / 1024).toFixed(1)} KB`);
totalMemory += stats.estimatedMemoryUsage;
} else if (pool instanceof TieredObjectPool) {
const stats = pool.getStats();
lines.push(` Type: Tiered Pool`);
lines.push(` Total Size: ${stats.totalSize}/${stats.totalMaxSize}`);
lines.push(` Hit Rate: ${(stats.hitRate * 100).toFixed(1)}%`);
lines.push(` Memory: ${(stats.totalMemoryUsage / 1024).toFixed(1)} KB`);
totalMemory += stats.totalMemoryUsage;
}
}
lines.push(`\nTotal Memory Usage: ${(totalMemory / 1024 / 1024).toFixed(2)} MB`);
return lines.join('\n');
}
}

29
packages/core/src/Utils/Pool/IPoolable.ts Normal file
View File

@@ -0,0 +1,29 @@
/**
* 可池化对象接口
*/
export interface IPoolable {
/**
* 重置对象状态，准备重用
*/
reset(): void;
}
/**
* 对象池统计信息
*/
export interface PoolStats {
/** 池中对象数量 */
size: number;
/** 池的最大大小 */
maxSize: number;
/** 总共创建的对象数量 */
totalCreated: number;
/** 总共获取的次数 */
totalObtained: number;
/** 总共释放的次数 */
totalReleased: number;
/** 命中率（从池中获取的比例） */
hitRate: number;
/** 内存使用估算（字节） */
estimatedMemoryUsage: number;
}

282
packages/core/src/Utils/Pool/Pool.ts Normal file
View File

@@ -0,0 +1,282 @@
import { IPoolable, PoolStats } from './IPoolable';
/**
* 高性能通用对象池
* 支持任意类型的对象池化，包含详细的统计信息
*/
export class Pool<T extends IPoolable> {
private static _pools = new Map<Function, Pool<any>>();
private _objects: T[] = [];
private _createFn: () => T;
private _maxSize: number;
private _stats: PoolStats;
private _objectSize: number; // 估算的单个对象大小
/**
* 构造函数
* @param createFn 创建对象的函数
* @param maxSize 池的最大大小，默认100
* @param estimatedObjectSize 估算的单个对象大小（字节），默认1024
*/
constructor(createFn: () => T, maxSize: number = 100, estimatedObjectSize: number = 1024) {
this._createFn = createFn;
this._maxSize = maxSize;
this._objectSize = estimatedObjectSize;
this._stats = {
size: 0,
maxSize,
totalCreated: 0,
totalObtained: 0,
totalReleased: 0,
hitRate: 0,
estimatedMemoryUsage: 0
};
}
/**
* 获取指定类型的对象池
* @param type 对象类型
* @param maxSize 池的最大大小
* @param estimatedObjectSize 估算的单个对象大小
* @returns 对象池实例
*/
public static getPool<T extends IPoolable>(
type: new (...args: unknown[]) => T,
maxSize: number = 100,
estimatedObjectSize: number = 1024
): Pool<T> {
let pool = this._pools.get(type);
if (!pool) {
pool = new Pool<T>(() => new type(), maxSize, estimatedObjectSize);
this._pools.set(type, pool);
}
return pool;
}
/**
* 从池中获取对象
* @returns 对象实例
*/
public obtain(): T {
this._stats.totalObtained++;
if (this._objects.length > 0) {
const obj = this._objects.pop()!;
this._stats.size--;
this._updateHitRate();
this._updateMemoryUsage();
return obj;
}
// 池中没有可用对象，创建新对象
this._stats.totalCreated++;
this._updateHitRate();
return this._createFn();
}
/**
* 释放对象回池中
* @param obj 要释放的对象
*/
public release(obj: T): void {
if (!obj) return;
this._stats.totalReleased++;
// 如果池未满，将对象放回池中
if (this._stats.size < this._maxSize) {
// 重置对象状态
obj.reset();
this._objects.push(obj);
this._stats.size++;
this._updateMemoryUsage();
}
// 如果池已满，让对象被垃圾回收
}
/**
* 获取池统计信息
* @returns 统计信息对象
*/
public getStats(): Readonly<PoolStats> {
return { ...this._stats };
}
/**
* 清空池
*/
public clear(): void {
// 重置所有对象
for (const obj of this._objects) {
obj.reset();
}
this._objects.length = 0;
this._stats.size = 0;
this._updateMemoryUsage();
}
/**
* 压缩池（移除多余的对象）
* @param targetSize 目标大小，默认为当前大小的一半
*/
public compact(targetSize?: number): void {
const target = targetSize ?? Math.floor(this._objects.length / 2);
while (this._objects.length > target) {
const obj = this._objects.pop();
if (obj) {
obj.reset();
this._stats.size--;
}
}
this._updateMemoryUsage();
}
/**
* 预填充池
* @param count 预填充的对象数量
*/
public prewarm(count: number): void {
const actualCount = Math.min(count, this._maxSize - this._objects.length);
for (let i = 0; i < actualCount; i++) {
const obj = this._createFn();
obj.reset();
this._objects.push(obj);
this._stats.totalCreated++;
this._stats.size++;
}
this._updateMemoryUsage();
}
/**
* 设置最大池大小
* @param maxSize 新的最大大小
*/
public setMaxSize(maxSize: number): void {
this._maxSize = maxSize;
this._stats.maxSize = maxSize;
// 如果当前池大小超过新的最大值，进行压缩
if (this._objects.length > maxSize) {
this.compact(maxSize);
}
}
/**
* 获取池中可用对象数量
* @returns 可用对象数量
*/
public getAvailableCount(): number {
return this._objects.length;
}
/**
* 检查池是否为空
* @returns 如果池为空返回true
*/
public isEmpty(): boolean {
return this._objects.length === 0;
}
/**
* 检查池是否已满
* @returns 如果池已满返回true
*/
public isFull(): boolean {
return this._objects.length >= this._maxSize;
}
/**
* 获取所有已注册的池类型
* @returns 所有池类型的数组
*/
public static getAllPoolTypes(): Function[] {
return Array.from(this._pools.keys());
}
/**
* 获取所有池的统计信息
* @returns 包含所有池统计信息的对象
*/
public static getAllPoolStats(): Record<string, PoolStats> {
const stats: Record<string, PoolStats> = {};
for (const [type, pool] of this._pools) {
const typeName = type.name || type.toString();
stats[typeName] = pool.getStats();
}
return stats;
}
/**
* 压缩所有池
*/
public static compactAllPools(): void {
for (const pool of this._pools.values()) {
pool.compact();
}
}
/**
* 清空所有池
*/
public static clearAllPools(): void {
for (const pool of this._pools.values()) {
pool.clear();
}
this._pools.clear();
}
/**
* 获取全局池统计信息的格式化字符串
* @returns 格式化的统计信息字符串
*/
public static getGlobalStatsString(): string {
const stats = this.getAllPoolStats();
const lines: string[] = ['=== Object Pool Global Statistics ===', ''];
if (Object.keys(stats).length === 0) {
lines.push('No pools registered');
return lines.join('\n');
}
for (const [typeName, stat] of Object.entries(stats)) {
lines.push(`${typeName}:`);
lines.push(` Size: ${stat.size}/${stat.maxSize}`);
lines.push(` Hit Rate: ${(stat.hitRate * 100).toFixed(1)}%`);
lines.push(` Total Created: ${stat.totalCreated}`);
lines.push(` Total Obtained: ${stat.totalObtained}`);
lines.push(` Memory: ${(stat.estimatedMemoryUsage / 1024).toFixed(1)} KB`);
lines.push('');
}
return lines.join('\n');
}
/**
* 更新命中率
*/
private _updateHitRate(): void {
if (this._stats.totalObtained === 0) {
this._stats.hitRate = 0;
} else {
const hits = this._stats.totalObtained - this._stats.totalCreated;
this._stats.hitRate = hits / this._stats.totalObtained;
}
}
/**
* 更新内存使用估算
*/
private _updateMemoryUsage(): void {
this._stats.estimatedMemoryUsage = this._stats.size * this._objectSize;
}
}

231
packages/core/src/Utils/Pool/PoolManager.ts Normal file
View File

@@ -0,0 +1,231 @@
import { IPoolable, PoolStats } from './IPoolable';
import { Pool } from './Pool';
/**
* 池管理器
* 统一管理所有对象池
*/
export class PoolManager {
private static instance: PoolManager;
private pools = new Map<string, Pool<any>>();
private autoCompactInterval = 60000; // 60秒
private lastCompactTime = 0;
public static getInstance(): PoolManager {
if (!PoolManager.instance) {
PoolManager.instance = new PoolManager();
}
return PoolManager.instance;
}
/**
* 注册池
* @param name 池名称
* @param pool 池实例
*/
public registerPool<T extends IPoolable>(name: string, pool: Pool<T>): void {
this.pools.set(name, pool);
}
/**
* 获取池
* @param name 池名称
* @returns 池实例
*/
public getPool<T extends IPoolable>(name: string): Pool<T> | null {
return this.pools.get(name) || null;
}
/**
* 更新池管理器（应在游戏循环中调用）
*/
public update(): void {
const now = Date.now();
if (now - this.lastCompactTime > this.autoCompactInterval) {
this.compactAllPools();
this.lastCompactTime = now;
}
}
/**
* 创建或获取标准池
* @param name 池名称
* @param createFn 创建函数
* @param maxSize 最大大小
* @param estimatedObjectSize 估算对象大小
* @returns 池实例
*/
public createPool<T extends IPoolable>(
name: string,
createFn: () => T,
maxSize: number = 100,
estimatedObjectSize: number = 1024
): Pool<T> {
let pool = this.pools.get(name) as Pool<T>;
if (!pool) {
pool = new Pool(createFn, maxSize, estimatedObjectSize);
this.pools.set(name, pool);
}
return pool;
}
/**
* 移除池
* @param name 池名称
* @returns 是否成功移除
*/
public removePool(name: string): boolean {
const pool = this.pools.get(name);
if (pool) {
pool.clear();
this.pools.delete(name);
return true;
}
return false;
}
/**
* 获取所有池名称
* @returns 池名称数组
*/
public getPoolNames(): string[] {
return Array.from(this.pools.keys());
}
/**
* 获取池数量
* @returns 池数量
*/
public getPoolCount(): number {
return this.pools.size;
}
/**
* 压缩所有池
*/
public compactAllPools(): void {
for (const pool of this.pools.values()) {
pool.compact();
}
}
/**
* 清空所有池
*/
public clearAllPools(): void {
for (const pool of this.pools.values()) {
pool.clear();
}
}
/**
* 获取所有池的统计信息
* @returns 统计信息映射
*/
public getAllStats(): Map<string, PoolStats> {
const stats = new Map<string, PoolStats>();
for (const [name, pool] of this.pools) {
stats.set(name, pool.getStats());
}
return stats;
}
/**
* 获取总体统计信息
* @returns 总体统计信息
*/
public getGlobalStats(): PoolStats {
let totalSize = 0;
let totalMaxSize = 0;
let totalCreated = 0;
let totalObtained = 0;
let totalReleased = 0;
let totalMemoryUsage = 0;
for (const pool of this.pools.values()) {
const stats = pool.getStats();
totalSize += stats.size;
totalMaxSize += stats.maxSize;
totalCreated += stats.totalCreated;
totalObtained += stats.totalObtained;
totalReleased += stats.totalReleased;
totalMemoryUsage += stats.estimatedMemoryUsage;
}
const hitRate = totalObtained === 0 ? 0 : (totalObtained - totalCreated) / totalObtained;
return {
size: totalSize,
maxSize: totalMaxSize,
totalCreated,
totalObtained,
totalReleased,
hitRate,
estimatedMemoryUsage: totalMemoryUsage
};
}
/**
* 获取格式化的统计信息字符串
* @returns 格式化字符串
*/
public getStatsString(): string {
const lines: string[] = ['=== Pool Manager Statistics ===', ''];
if (this.pools.size === 0) {
lines.push('No pools registered');
return lines.join('\n');
}
const globalStats = this.getGlobalStats();
lines.push(`Total Pools: ${this.pools.size}`);
lines.push(`Global Hit Rate: ${(globalStats.hitRate * 100).toFixed(1)}%`);
lines.push(`Global Memory Usage: ${(globalStats.estimatedMemoryUsage / 1024).toFixed(1)} KB`);
lines.push('');
for (const [name, pool] of this.pools) {
const stats = pool.getStats();
lines.push(`${name}:`);
lines.push(` Size: ${stats.size}/${stats.maxSize}`);
lines.push(` Hit Rate: ${(stats.hitRate * 100).toFixed(1)}%`);
lines.push(` Memory: ${(stats.estimatedMemoryUsage / 1024).toFixed(1)} KB`);
lines.push('');
}
return lines.join('\n');
}
/**
* 设置自动压缩间隔
* @param intervalMs 间隔毫秒数
*/
public setAutoCompactInterval(intervalMs: number): void {
this.autoCompactInterval = intervalMs;
}
/**
* 预填充所有池
*/
public prewarmAllPools(): void {
for (const pool of this.pools.values()) {
const stats = pool.getStats();
const prewarmCount = Math.floor(stats.maxSize * 0.2); // 预填充20%
pool.prewarm(prewarmCount);
}
}
/**
* 重置池管理器
*/
public reset(): void {
this.clearAllPools();
this.pools.clear();
this.lastCompactTime = 0;
}
}

3
packages/core/src/Utils/Pool/index.ts Normal file
View File

@@ -0,0 +1,3 @@
export * from './IPoolable';
export * from './Pool';
export * from './PoolManager';

3
packages/core/src/Utils/index.ts
View File

@@ -4,4 +4,5 @@ export * from './Emitter';
export * from './GlobalManager';
export * from './PerformanceMonitor';
export { Time } from './Time';
export * from './Debug';
export * from './Debug';
export * from './Logger';

11
packages/core/src/index.ts
View File

@@ -13,6 +13,17 @@ export { TimerManager } from './Utils/Timers/TimerManager';
export { ITimer } from './Utils/Timers/ITimer';
export { Timer } from './Utils/Timers/Timer';
// 日志系统
export {
LoggerManager,
ConsoleLogger,
Logger,
createLogger,
setGlobalLogLevel,
LogLevel
} from './Utils/Logger';
export type { ILogger, LoggerConfig } from './Utils/Logger';
// ECS核心组件
export * from './ECS';