@esengine/ecs-framework 2.1.29 → 2.1.30

package/bin/ECS/Core/DirtyTrackingSystem.js

@@ -0,0 +1,297 @@
+import { createLogger } from '../../Utils/Logger';
+/**
+ * 脏标记类型
+ */
+export var DirtyFlag;
+(function (DirtyFlag) {
+    /** 组件数据已修改 */
+    DirtyFlag[DirtyFlag["COMPONENT_MODIFIED"] = 1] = "COMPONENT_MODIFIED";
+    /** 组件已添加 */
+    DirtyFlag[DirtyFlag["COMPONENT_ADDED"] = 2] = "COMPONENT_ADDED";
+    /** 组件已移除 */
+    DirtyFlag[DirtyFlag["COMPONENT_REMOVED"] = 4] = "COMPONENT_REMOVED";
+    /** 实体位置已改变 */
+    DirtyFlag[DirtyFlag["TRANSFORM_CHANGED"] = 8] = "TRANSFORM_CHANGED";
+    /** 实体状态已改变 */
+    DirtyFlag[DirtyFlag["STATE_CHANGED"] = 16] = "STATE_CHANGED";
+    /** 自定义标记1 */
+    DirtyFlag[DirtyFlag["CUSTOM_1"] = 256] = "CUSTOM_1";
+    /** 自定义标记2 */
+    DirtyFlag[DirtyFlag["CUSTOM_2"] = 512] = "CUSTOM_2";
+    /** 自定义标记3 */
+    DirtyFlag[DirtyFlag["CUSTOM_3"] = 1024] = "CUSTOM_3";
+    /** 所有标记 */
+    DirtyFlag[DirtyFlag["ALL"] = 4294967295] = "ALL";
+})(DirtyFlag || (DirtyFlag = {}));
+/**
+ * 脏标记追踪系统
+ *
+ * 提供高效的组件和实体变更追踪，避免不必要的计算和更新。
+ * 支持细粒度的脏标记和批量处理机制。
+ *
+ * @example
+ * ```typescript
+ * const dirtySystem = new DirtyTrackingSystem();
+ *
+ * // 标记实体的位置组件已修改
+ * dirtySystem.markDirty(entity, DirtyFlag.TRANSFORM_CHANGED, [PositionComponent]);
+ *
+ * // 监听位置变化
+ * dirtySystem.addListener({
+ *     flags: DirtyFlag.TRANSFORM_CHANGED,
+ *     callback: (data) => {
+ *         logger.debug('Entity position changed:', data.entity.name);
+ *     }
+ * });
+ *
+ * // 处理所有脏标记
+ * dirtySystem.processDirtyEntities();
+ * ```
+ */
+export class DirtyTrackingSystem {
+    constructor() {
+        /** 脏实体映射表 */
+        this._dirtyEntities = new Map();
+        /** 脏标记监听器 */
+        this._listeners = [];
+        /** 性能统计 */
+        this._stats = {
+            totalMarkings: 0,
+            totalCleanups: 0,
+            frameCount: 0,
+            totalDirtyPerFrame: 0
+        };
+        /** 当前帧编号 */
+        this._currentFrame = 0;
+        this._batchSize = 100;
+        this._maxProcessingTime = 16;
+        /** 延迟处理队列 */
+        this._processingQueue = [];
+        this._isProcessing = false;
+    }
+    /**
+     * 标记实体为脏状态
+     *
+     * @param entity 要标记的实体
+     * @param flags 脏标记位
+     * @param modifiedComponents 修改的组件类型列表
+     */
+    markDirty(entity, flags, modifiedComponents = []) {
+        this._stats.totalMarkings++;
+        let dirtyData = this._dirtyEntities.get(entity);
+        if (!dirtyData) {
+            dirtyData = {
+                entity,
+                flags: 0,
+                modifiedComponents: new Set(),
+                timestamp: performance.now(),
+                frameNumber: this._currentFrame
+            };
+            this._dirtyEntities.set(entity, dirtyData);
+        }
+        dirtyData.flags |= flags;
+        dirtyData.timestamp = performance.now();
+        dirtyData.frameNumber = this._currentFrame;
+        for (const componentType of modifiedComponents) {
+            dirtyData.modifiedComponents.add(componentType);
+        }
+        this.notifyListeners(dirtyData, flags);
+    }
+    /**
+     * 检查实体是否有指定的脏标记
+     *
+     * @param entity 要检查的实体
+     * @param flags 要检查的标记位
+     * @returns 是否有指定的脏标记
+     */
+    isDirty(entity, flags = DirtyFlag.ALL) {
+        const dirtyData = this._dirtyEntities.get(entity);
+        return dirtyData ? (dirtyData.flags & flags) !== 0 : false;
+    }
+    /**
+     * 清除实体的脏标记
+     *
+     * @param entity 要清除的实体
+     * @param flags 要清除的标记位，默认清除所有
+     */
+    clearDirty(entity, flags = DirtyFlag.ALL) {
+        const dirtyData = this._dirtyEntities.get(entity);
+        if (!dirtyData)
+            return;
+        if (flags === DirtyFlag.ALL) {
+            this._dirtyEntities.delete(entity);
+        }
+        else {
+            dirtyData.flags &= ~flags;
+            if (dirtyData.flags === 0) {
+                this._dirtyEntities.delete(entity);
+            }
+        }
+        this._stats.totalCleanups++;
+    }
+    /**
+     * 获取所有脏实体
+     *
+     * @param flags 过滤标记位，只返回包含指定标记的实体
+     * @returns 脏实体数据数组
+     */
+    getDirtyEntities(flags = DirtyFlag.ALL) {
+        const result = [];
+        for (const dirtyData of this._dirtyEntities.values()) {
+            if ((dirtyData.flags & flags) !== 0) {
+                result.push(dirtyData);
+            }
+        }
+        return result;
+    }
+    /**
+     * 批量处理脏实体
+     *
+     * 使用时间分片的方式处理脏实体，避免单帧卡顿
+     */
+    processDirtyEntities() {
+        if (this._isProcessing)
+            return;
+        this._isProcessing = true;
+        const startTime = performance.now();
+        if (this._processingQueue.length === 0) {
+            this._processingQueue.push(...this._dirtyEntities.values());
+        }
+        let processed = 0;
+        while (this._processingQueue.length > 0 && processed < this._batchSize) {
+            const elapsed = performance.now() - startTime;
+            if (elapsed > this._maxProcessingTime) {
+                break;
+            }
+            const dirtyData = this._processingQueue.shift();
+            this.processEntity(dirtyData);
+            processed++;
+        }
+        if (this._processingQueue.length === 0) {
+            this._isProcessing = false;
+            this.onFrameEnd();
+        }
+    }
+    /**
+     * 添加脏标记监听器
+     *
+     * @param listener 监听器配置
+     */
+    addListener(listener) {
+        this._listeners.push(listener);
+        this._listeners.sort((a, b) => (a.priority || 100) - (b.priority || 100));
+    }
+    /**
+     * 移除脏标记监听器
+     *
+     * @param callback 要移除的回调函数
+     */
+    removeListener(callback) {
+        const index = this._listeners.findIndex(l => l.callback === callback);
+        if (index !== -1) {
+            this._listeners.splice(index, 1);
+        }
+    }
+    /**
+     * 开始新的帧
+     */
+    beginFrame() {
+        this._currentFrame++;
+    }
+    /**
+     * 结束当前帧
+     */
+    endFrame() {
+        if (!this._isProcessing) {
+            this.processDirtyEntities();
+        }
+    }
+    /**
+     * 获取统计信息
+     */
+    getStats() {
+        return {
+            dirtyEntityCount: this._dirtyEntities.size,
+            totalMarkings: this._stats.totalMarkings,
+            totalCleanups: this._stats.totalCleanups,
+            listenerCount: this._listeners.length,
+            avgDirtyPerFrame: this._stats.frameCount > 0 ?
+                this._stats.totalDirtyPerFrame / this._stats.frameCount : 0,
+            estimatedMemoryUsage: this.estimateMemoryUsage()
+        };
+    }
+    /**
+     * 清空所有脏标记和统计信息
+     */
+    clear() {
+        this._dirtyEntities.clear();
+        this._processingQueue.length = 0;
+        this._isProcessing = false;
+        this._stats = {
+            totalMarkings: 0,
+            totalCleanups: 0,
+            frameCount: 0,
+            totalDirtyPerFrame: 0
+        };
+    }
+    /**
+     * 配置批量处理参数
+     *
+     * @param batchSize 每次处理的最大实体数量
+     * @param maxProcessingTime 每帧最大处理时间（毫秒）
+     */
+    configureBatchProcessing(batchSize, maxProcessingTime) {
+        this._batchSize = batchSize;
+        this._maxProcessingTime = maxProcessingTime;
+    }
+    /**
+     * 处理单个脏实体
+     */
+    processEntity(dirtyData) {
+        for (const listener of this._listeners) {
+            if ((dirtyData.flags & listener.flags) !== 0) {
+                try {
+                    listener.callback(dirtyData);
+                }
+                catch (error) {
+                    DirtyTrackingSystem._logger.error('脏数据监听器错误:', error);
+                }
+            }
+        }
+        this.clearDirty(dirtyData.entity);
+    }
+    /**
+     * 通知监听器
+     */
+    notifyListeners(dirtyData, newFlags) {
+        for (const listener of this._listeners) {
+            if ((newFlags & listener.flags) !== 0) {
+                try {
+                    listener.callback(dirtyData);
+                }
+                catch (error) {
+                    DirtyTrackingSystem._logger.error('脏数据监听器通知错误:', error);
+                }
+            }
+        }
+    }
+    /**
+     * 帧结束时的统计更新
+     */
+    onFrameEnd() {
+        this._stats.frameCount++;
+        this._stats.totalDirtyPerFrame += this._dirtyEntities.size;
+    }
+    /**
+     * 估算内存使用量
+     */
+    estimateMemoryUsage() {
+        let usage = 0;
+        usage += this._dirtyEntities.size * 100;
+        usage += this._listeners.length * 50;
+        usage += this._processingQueue.length * 8;
+        return usage;
+    }
+}
+DirtyTrackingSystem._logger = createLogger('DirtyTrackingSystem');
+//# sourceMappingURL=DirtyTrackingSystem.js.map

package/bin/ECS/Core/DirtyTrackingSystem.js.map

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

package/bin/ECS/Core/EntityManager.d.ts

@@ -0,0 +1,379 @@
+import { Entity } from '../Entity';
+import { Component } from '../Component';
+import { ComponentType } from './ComponentStorage';
+import { EventBus } from './EventBus';
+/**
+ * 实体查询构建器
+ *
+ * 提供流式API来构建复杂的实体查询条件。支持组件过滤、标签过滤、状态过滤和自定义条件。
+ *
+ * @example
+ * ```typescript
+ * const results = entityManager.query()
+ *     .withAll(PositionComponent, HealthComponent)
+ *     .without(VelocityComponent)
+ *     .withTag(1)
+ *     .active()
+ *     .where(entity => entity.name.startsWith("Player"))
+ *     .execute();
+ * ```
+ */
+export declare class EntityQueryBuilder {
+    private entityManager;
+    /** 必须包含的组件类型 */
+    private _allComponents;
+    /** 至少包含一个的组件类型 */
+    private _anyComponents;
+    /** 不能包含的组件类型 */
+    private _withoutComponents;
+    /** 必须包含的标签 */
+    private _withTags;
+    /** 不能包含的标签 */
+    private _withoutTags;
+    /** 是否只查询激活状态的实体 */
+    private _activeOnly;
+    /** 是否只查询启用状态的实体 */
+    private _enabledOnly;
+    /** 自定义过滤条件 */
+    private _customPredicates;
+    /**
+     * 创建查询构建器实例
+     * @param entityManager 实体管理器实例
+     */
+    constructor(entityManager: EntityManager);
+    /**
+     * 添加必须包含的组件条件
+     *
+     * 返回的实体必须包含所有指定的组件类型。
+     *
+     * @param componentTypes 组件类型列表
+     * @returns 查询构建器实例，支持链式调用
+     */
+    withAll(...componentTypes: ComponentType[]): EntityQueryBuilder;
+    /**
+     * 添加至少包含一个的组件条件
+     *
+     * 返回的实体必须至少包含其中一个指定的组件类型。
+     *
+     * @param componentTypes 组件类型列表
+     * @returns 查询构建器实例，支持链式调用
+     */
+    withAny(...componentTypes: ComponentType[]): EntityQueryBuilder;
+    /**
+     * 添加不能包含的组件条件
+     *
+     * 返回的实体不能包含任何指定的组件类型。
+     *
+     * @param componentTypes 组件类型列表
+     * @returns 查询构建器实例，支持链式调用
+     */
+    without(...componentTypes: ComponentType[]): EntityQueryBuilder;
+    /**
+     * 添加必须包含的标签条件
+     *
+     * 返回的实体必须具有指定的标签。
+     *
+     * @param tag 标签值
+     * @returns 查询构建器实例，支持链式调用
+     */
+    withTag(tag: number): EntityQueryBuilder;
+    /**
+     * 添加不能包含的标签条件
+     *
+     * 返回的实体不能具有指定的标签。
+     *
+     * @param tag 标签值
+     * @returns 查询构建器实例，支持链式调用
+     */
+    withoutTag(tag: number): EntityQueryBuilder;
+    /**
+     * 添加激活状态过滤条件
+     *
+     * 返回的实体必须处于激活状态（active = true）。
+     *
+     * @returns 查询构建器实例，支持链式调用
+     */
+    active(): EntityQueryBuilder;
+    /**
+     * 添加启用状态过滤条件
+     *
+     * 返回的实体必须处于启用状态（enabled = true）。
+     *
+     * @returns 查询构建器实例，支持链式调用
+     */
+    enabled(): EntityQueryBuilder;
+    /**
+     * 添加自定义过滤条件
+     *
+     * 允许用户定义复杂的过滤逻辑。
+     *
+     * @param predicate 自定义过滤函数，接收实体作为参数，返回布尔值
+     * @returns 查询构建器实例，支持链式调用
+     *
+     * @example
+     * ```typescript
+     * .where(entity => entity.name.startsWith("Player"))
+     * .where(entity => entity.components.length > 5)
+     * ```
+     */
+    where(predicate: (entity: Entity) => boolean): EntityQueryBuilder;
+    /**
+     * 执行查询并返回所有匹配的实体
+     *
+     * @returns 符合所有查询条件的实体数组
+     */
+    execute(): Entity[];
+    /**
+     * 执行查询并返回第一个匹配的实体
+     *
+     * @returns 第一个符合查询条件的实体，如果没有找到则返回null
+     */
+    first(): Entity | null;
+    /**
+     * 执行查询并返回匹配实体的数量
+     *
+     * @returns 符合查询条件的实体数量
+     */
+    count(): number;
+    /**
+     * 对所有匹配的实体执行指定操作
+     *
+     * @param action 要执行的操作函数，接收匹配的实体作为参数
+     */
+    forEach(action: (entity: Entity) => void): void;
+    /**
+     * 检查实体是否匹配所有查询条件
+     *
+     * 按优先级顺序检查各种过滤条件，一旦发现不匹配立即返回false。
+     *
+     * @param entity 要检查的实体
+     * @returns 实体是否匹配所有查询条件
+     */
+    private matchesEntity;
+}
+/**
+ * 实体管理器
+ *
+ * 提供统一的实体管理和查询机制，支持高效的实体操作。
+ * 包括实体的创建、销毁、查询和索引管理功能。
+ *
+ * @example
+ * ```typescript
+ * const entityManager = new EntityManager();
+ *
+ * // 创建实体
+ * const player = entityManager.createEntity("Player");
+ *
+ * // 查询实体
+ * const playerEntity = entityManager.getEntityByName("Player");
+ *
+ * // 复杂查询
+ * const results = entityManager.query()
+ *     .withAll(HealthComponent, PositionComponent)
+ *     .active()
+ *     .execute();
+ * ```
+ */
+export declare class EntityManager {
+    /** 主要实体存储，使用ID作为键 */
+    private _entities;
+    /** 按名称索引的实体映射 */
+    private _entitiesByName;
+    /** 按标签索引的实体映射 */
+    private _entitiesByTag;
+    /** 实体ID分配器 */
+    private _identifierPool;
+    /** 已销毁实体的ID集合 */
+    private _destroyedEntities;
+    /** 性能优化系统 */
+    private _componentIndexManager;
+    private _archetypeSystem;
+    private _dirtyTrackingSystem;
+    /** 事件总线 */
+    private _eventBus;
+    /**
+     * 创建实体管理器实例
+     *
+     * 初始化内部数据结构和ID分配器。
+     */
+    constructor();
+    /**
+     * 获取实体总数
+     *
+     * @returns 当前管理的实体总数量
+     */
+    get entityCount(): number;
+    /**
+     * 获取激活状态的实体数量
+     *
+     * 只计算同时满足激活状态且未被销毁的实体。
+     *
+     * @returns 激活状态的实体数量
+     */
+    get activeEntityCount(): number;
+    /**
+     * 创建新实体
+     *
+     * 分配唯一ID并将实体添加到管理系统中，同时更新相关索引。
+     *
+     * @param name 实体名称，如果未指定则使用时间戳生成默认名称
+     * @returns 创建的实体实例
+     *
+     * @example
+     * ```typescript
+     * const player = entityManager.createEntity("Player");
+     * const enemy = entityManager.createEntity(); // 使用默认名称
+     * ```
+     */
+    createEntity(name?: string): Entity;
+    /**
+     * 批量创建实体
+     *
+     * 为了优化大量实体创建的性能，批量处理索引更新和事件发射。
+     * 适用于需要创建大量实体的场景，如子弹、粒子等。
+     *
+     * @param count 要创建的实体数量
+     * @param namePrefix 实体名称前缀，默认为 Entity
+     * @param skipEvents 是否跳过事件发射以提升性能，默认为 false
+     * @returns 创建的实体数组
+     *
+     * @example
+     * const bullets = entityManager.createEntitiesBatch(100, "Bullet", true);
+     * const particles = entityManager.createEntitiesBatch(500, "Particle");
+     */
+    createEntitiesBatch(count: number, namePrefix?: string, skipEvents?: boolean): Entity[];
+    /**
+     * 销毁实体
+     *
+     * 支持通过实体对象、名称或ID来销毁实体。
+     * 会清理所有相关索引并回收ID。
+     *
+     * @param entityOrId 要销毁的实体，可以是实体对象、名称字符串或ID数字
+     * @returns 是否成功销毁实体
+     *
+     * @example
+     * ```typescript
+     * // 通过实体对象销毁
+     * entityManager.destroyEntity(player);
+     *
+     * // 通过名称销毁
+     * entityManager.destroyEntity("Enemy_1");
+     *
+     * // 通过ID销毁
+     * entityManager.destroyEntity(123);
+     * ```
+     */
+    destroyEntity(entityOrId: Entity | string | number): boolean;
+    /**
+     * 获取所有实体
+     *
+     * 返回当前管理的所有实体的副本数组。
+     *
+     * @returns 所有实体的数组
+     */
+    getAllEntities(): Entity[];
+    /**
+     * 根据ID获取实体
+     *
+     * 支持字符串和数字类型的ID。
+     *
+     * @param id 实体ID，可以是字符串或数字
+     * @returns 对应的实体，如果不存在则返回null
+     */
+    getEntity(id: string | number): Entity | null;
+    /**
+     * 根据名称获取实体
+     *
+     * 如果存在多个同名实体，返回第一个找到的实体。
+     *
+     * @param name 实体名称
+     * @returns 匹配的实体，如果不存在则返回null
+     */
+    getEntityByName(name: string): Entity | null;
+    /**
+     * 根据标签获取实体列表
+     *
+     * 返回所有具有指定标签的实体。
+     *
+     * @param tag 标签值
+     * @returns 具有指定标签的实体数组
+     */
+    getEntitiesByTag(tag: number): Entity[];
+    /**
+     * 获取包含指定组件的所有实体
+     *
+     * 遍历所有实体，查找包含指定组件类型的实体。
+     *
+     * @param componentType 组件类型
+     * @returns 包含指定组件的实体数组
+     *
+     * @example
+     * ```typescript
+     * const entitiesWithHealth = entityManager.getEntitiesWithComponent(HealthComponent);
+     * ```
+     */
+    getEntitiesWithComponent<T extends Component>(componentType: ComponentType<T>): Entity[];
+    /**
+     * 创建查询构建器
+     *
+     * 返回一个新的查询构建器实例，用于构建复杂的实体查询。
+     *
+     * @returns 新的查询构建器实例
+     *
+     * @example
+     * ```typescript
+     * const results = entityManager.query()
+     *     .withAll(PositionComponent, HealthComponent)
+     *     .without(VelocityComponent)
+     *     .active()
+     *     .execute();
+     * ```
+     */
+    query(): EntityQueryBuilder;
+    /**
+     * 使用组件索引进行多组件查询
+     *
+     * @param componentTypes 组件类型数组
+     * @param operation 查询操作：'AND' 或 'OR'
+     * @returns 匹配的实体集合
+     */
+    queryWithComponentIndex(componentTypes: ComponentType[], operation: 'AND' | 'OR'): Set<Entity>;
+    /**
+     * 标记实体组件已修改
+     *
+     * @param entity 修改的实体
+     * @param componentTypes 修改的组件类型
+     */
+    markEntityDirty(entity: Entity, componentTypes: ComponentType[]): void;
+    /**
+     * 获取性能优化统计信息
+     */
+    getOptimizationStats(): any;
+    /**
+     * 获取事件总线实例
+     *
+     * 允许外部代码监听和发射ECS相关事件。
+     *
+     * @returns 事件总线实例
+     */
+    get eventBus(): EventBus;
+    /**
+     * 更新名称索引
+     *
+     * 维护按名称查找实体的索引结构。支持添加和移除操作。
+     *
+     * @param entity 要更新索引的实体
+     * @param isAdd true表示添加到索引，false表示从索引中移除
+     */
+    private updateNameIndex;
+    /**
+     * 更新标签索引
+     *
+     * 维护按标签查找实体的索引结构。支持添加和移除操作。
+     *
+     * @param entity 要更新索引的实体
+     * @param isAdd true表示添加到索引，false表示从索引中移除
+     */
+    private updateTagIndex;
+}
+//# sourceMappingURL=EntityManager.d.ts.map

package/bin/ECS/Core/EntityManager.d.ts.map

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