@esengine/ecs-framework 2.2.20 → 2.3.0

package/bin/ECS/Utils/EntityList.js

@@ -0,0 +1,258 @@
+/**
+ * 高性能实体列表管理器
+ * 管理场景中的所有实体，支持快速查找和批量操作
+ */
+export class EntityList {
+    get count() {
+        return this.buffer.length;
+    }
+    constructor(scene) {
+        this.buffer = [];
+        // 索引映射，提升查找性能
+        this._idToEntity = new Map();
+        this._nameToEntities = new Map();
+        // 延迟操作队列
+        this._entitiesToAdd = [];
+        this._entitiesToRemove = [];
+        this._scene = scene;
+    }
+    /**
+     * 添加实体
+     * @param entity 要添加的实体
+     */
+    add(entity) {
+        this.addImmediate(entity);
+    }
+    /**
+     * 立即添加实体
+     * @param entity 要添加的实体
+     */
+    addImmediate(entity) {
+        // 检查是否已存在
+        if (this._idToEntity.has(entity.id)) {
+            return;
+        }
+        this.buffer.push(entity);
+        this._idToEntity.set(entity.id, entity);
+        // 更新名称索引
+        this.updateNameIndex(entity, true);
+    }
+    /**
+     * 移除实体
+     * @param entity 要移除的实体
+     */
+    remove(entity) {
+        this.removeImmediate(entity);
+    }
+    /**
+     * 立即移除实体
+     * @param entity 要移除的实体
+     */
+    removeImmediate(entity) {
+        const index = this.buffer.indexOf(entity);
+        if (index !== -1) {
+            this.buffer.splice(index, 1);
+            this._idToEntity.delete(entity.id);
+            // 更新名称索引
+            this.updateNameIndex(entity, false);
+            // 回收实体ID到ID池
+            if (this._scene && this._scene.identifierPool) {
+                this._scene.identifierPool.checkIn(entity.id);
+            }
+        }
+    }
+    /**
+     * 移除所有实体
+     */
+    removeAllEntities() {
+        // 收集所有实体ID用于回收
+        const idsToRecycle = [];
+        for (let i = this.buffer.length - 1; i >= 0; i--) {
+            idsToRecycle.push(this.buffer[i].id);
+            this.buffer[i].destroy();
+        }
+        // 批量回收ID
+        if (this._scene && this._scene.identifierPool) {
+            for (const id of idsToRecycle) {
+                this._scene.identifierPool.checkIn(id);
+            }
+        }
+        this.buffer.length = 0;
+        this._idToEntity.clear();
+        this._nameToEntities.clear();
+        this._entitiesToAdd.length = 0;
+        this._entitiesToRemove.length = 0;
+    }
+    /**
+     * 更新实体列表，处理延迟操作
+     */
+    updateLists() {
+        // 处理延迟添加的实体
+        if (this._entitiesToAdd.length > 0) {
+            for (const entity of this._entitiesToAdd) {
+                this.addImmediate(entity);
+            }
+            this._entitiesToAdd.length = 0;
+        }
+        // 处理延迟移除的实体
+        if (this._entitiesToRemove.length > 0) {
+            for (const entity of this._entitiesToRemove) {
+                this.removeImmediate(entity);
+            }
+            this._entitiesToRemove.length = 0;
+        }
+    }
+    /**
+     * 更新实体列表
+     *
+     * 处理延迟操作（添加/删除实体）
+     */
+    update() {
+        // 处理延迟操作
+        this.updateLists();
+    }
+    /**
+     * 根据名称查找实体（使用索引，O(1)复杂度）
+     * @param name 实体名称
+     * @returns 找到的第一个实体或null
+     */
+    findEntity(name) {
+        const entities = this._nameToEntities.get(name);
+        return entities && entities.length > 0 ? entities[0] : null;
+    }
+    /**
+     * 根据名称查找所有实体
+     * @param name 实体名称
+     * @returns 找到的所有实体数组
+     */
+    findEntitiesByName(name) {
+        return this._nameToEntities.get(name) || [];
+    }
+    /**
+     * 根据ID查找实体（使用索引，O(1)复杂度）
+     * @param id 实体ID
+     * @returns 找到的实体或null
+     */
+    findEntityById(id) {
+        return this._idToEntity.get(id) || null;
+    }
+    /**
+     * 根据标签查找实体
+     * @param tag 标签
+     * @returns 找到的所有实体数组
+     */
+    findEntitiesByTag(tag) {
+        const result = [];
+        for (const entity of this.buffer) {
+            if (entity.tag === tag) {
+                result.push(entity);
+            }
+        }
+        return result;
+    }
+    /**
+     * 根据组件类型查找实体
+     * @param componentType 组件类型
+     * @returns 找到的所有实体数组
+     */
+    findEntitiesWithComponent(componentType) {
+        const result = [];
+        for (const entity of this.buffer) {
+            if (entity.hasComponent(componentType)) {
+                result.push(entity);
+            }
+        }
+        return result;
+    }
+    /**
+     * 批量操作：对所有实体执行指定操作
+     * @param action 要执行的操作
+     */
+    forEach(action) {
+        for (const entity of this.buffer) {
+            action(entity);
+        }
+    }
+    /**
+     * 批量操作：对符合条件的实体执行指定操作
+     * @param predicate 筛选条件
+     * @param action 要执行的操作
+     */
+    forEachWhere(predicate, action) {
+        for (const entity of this.buffer) {
+            if (predicate(entity)) {
+                action(entity);
+            }
+        }
+    }
+    /**
+     * 更新名称索引
+     * @param entity 实体
+     * @param isAdd 是否为添加操作
+     */
+    updateNameIndex(entity, isAdd) {
+        if (!entity.name) {
+            return;
+        }
+        if (isAdd) {
+            let entities = this._nameToEntities.get(entity.name);
+            if (!entities) {
+                entities = [];
+                this._nameToEntities.set(entity.name, entities);
+            }
+            entities.push(entity);
+        }
+        else {
+            const entities = this._nameToEntities.get(entity.name);
+            if (entities) {
+                const index = entities.indexOf(entity);
+                if (index !== -1) {
+                    entities.splice(index, 1);
+                    // 如果数组为空，删除映射
+                    if (entities.length === 0) {
+                        this._nameToEntities.delete(entity.name);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * 重新排序实体
+     * @param entityId 要移动的实体ID
+     * @param newIndex 新的索引位置
+     */
+    reorderEntity(entityId, newIndex) {
+        const entity = this._idToEntity.get(entityId);
+        if (!entity)
+            return;
+        const currentIndex = this.buffer.indexOf(entity);
+        if (currentIndex === -1 || currentIndex === newIndex)
+            return;
+        // 限制索引范围
+        const clampedIndex = Math.max(0, Math.min(newIndex, this.buffer.length - 1));
+        // 从当前位置移除
+        this.buffer.splice(currentIndex, 1);
+        // 插入到新位置
+        this.buffer.splice(clampedIndex, 0, entity);
+    }
+    /**
+     * 获取实体列表的统计信息
+     * @returns 统计信息
+     */
+    getStats() {
+        let activeCount = 0;
+        for (const entity of this.buffer) {
+            if (entity.enabled && !entity.isDestroyed) {
+                activeCount++;
+            }
+        }
+        return {
+            totalEntities: this.buffer.length,
+            activeEntities: activeCount,
+            pendingAdd: this._entitiesToAdd.length,
+            pendingRemove: this._entitiesToRemove.length,
+            nameIndexSize: this._nameToEntities.size
+        };
+    }
+}
+//# sourceMappingURL=EntityList.js.map

package/bin/ECS/Utils/EntityList.js.map

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

package/bin/ECS/Utils/EntityProcessorList.d.ts

@@ -0,0 +1,56 @@
+import { EntitySystem } from '../Systems/EntitySystem';
+/**
+ * 实体处理器列表管理器
+ * 管理场景中的所有实体系统
+ */
+export declare class EntityProcessorList {
+    private static readonly _logger;
+    private _processors;
+    private _isDirty;
+    /**
+     * 设置为脏状态，需要重新排序
+     */
+    setDirty(): void;
+    /**
+     * 添加实体处理器
+     * @param processor 要添加的处理器
+     */
+    add(processor: EntitySystem): void;
+    /**
+     * 移除实体处理器
+     * @param processor 要移除的处理器
+     */
+    remove(processor: EntitySystem): void;
+    /**
+     * 获取指定类型的处理器
+     * @param type 处理器类型
+     */
+    getProcessor<T extends EntitySystem>(type: new (...args: unknown[]) => T): T | null;
+    /**
+     * 开始处理
+     *
+     * 对所有处理器进行排序以确保正确的执行顺序。
+     */
+    begin(): void;
+    /**
+     * 结束处理
+     */
+    end(): void;
+    /**
+     * 更新所有处理器
+     */
+    update(): void;
+    /**
+     * 后期更新所有处理器
+     */
+    lateUpdate(): void;
+    /**
+     * 排序处理器
+     */
+    private sortProcessors;
+    /** 获取处理器列表 */
+    get processors(): EntitySystem[];
+    /** 获取处理器数量 */
+    get count(): number;
+}
+//# sourceMappingURL=EntityProcessorList.d.ts.map

package/bin/ECS/Utils/EntityProcessorList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityProcessorList.d.ts","sourceRoot":"","sources":["../../../src/ECS/Utils/EntityProcessorList.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAIvD;;;GAGG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAuC;IACtE,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;IACI,QAAQ,IAAI,IAAI;IAIvB;;;OAGG;IACI,GAAG,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI;IAKzC;;;OAGG;IACI,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI;IAO5C;;;OAGG;IACI,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI;IAS1F;;;;OAIG;IACI,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACI,GAAG,IAAI,IAAI;IAalB;;OAEG;IACI,MAAM,IAAI,IAAI;IAWrB;;OAEG;IACI,UAAU,IAAI,IAAI;IAMzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB,cAAc;IACd,IAAW,UAAU,mBAEpB;IAED,cAAc;IACd,IAAW,KAAK,WAEf;CAGJ"}

package/bin/ECS/Utils/EntityProcessorList.js

@@ -0,0 +1,113 @@
+import { createLogger } from '../../Utils/Logger';
+import { getSystemInstanceTypeName } from '../Decorators';
+/**
+ * 实体处理器列表管理器
+ * 管理场景中的所有实体系统
+ */
+export class EntityProcessorList {
+    constructor() {
+        this._processors = [];
+        this._isDirty = false;
+    }
+    /**
+     * 设置为脏状态，需要重新排序
+     */
+    setDirty() {
+        this._isDirty = true;
+    }
+    /**
+     * 添加实体处理器
+     * @param processor 要添加的处理器
+     */
+    add(processor) {
+        this._processors.push(processor);
+        this.setDirty();
+    }
+    /**
+     * 移除实体处理器
+     * @param processor 要移除的处理器
+     */
+    remove(processor) {
+        const index = this._processors.indexOf(processor);
+        if (index !== -1) {
+            this._processors.splice(index, 1);
+        }
+    }
+    /**
+     * 获取指定类型的处理器
+     * @param type 处理器类型
+     */
+    getProcessor(type) {
+        for (const processor of this._processors) {
+            if (processor instanceof type) {
+                return processor;
+            }
+        }
+        return null;
+    }
+    /**
+     * 开始处理
+     *
+     * 对所有处理器进行排序以确保正确的执行顺序。
+     */
+    begin() {
+        this.sortProcessors();
+    }
+    /**
+     * 结束处理
+     */
+    end() {
+        // 清理处理器
+        for (const processor of this._processors) {
+            try {
+                processor.reset();
+            }
+            catch (error) {
+                EntityProcessorList._logger.error(`Error in processor ${getSystemInstanceTypeName(processor)}:`, error);
+            }
+        }
+        this._isDirty = false;
+        this._processors.length = 0;
+    }
+    /**
+     * 更新所有处理器
+     */
+    update() {
+        this.sortProcessors();
+        for (const processor of this._processors) {
+            try {
+                processor.update();
+            }
+            catch (error) {
+                EntityProcessorList._logger.error(`Error in processor ${getSystemInstanceTypeName(processor)}:`, error);
+            }
+        }
+    }
+    /**
+     * 后期更新所有处理器
+     */
+    lateUpdate() {
+        for (const processor of this._processors) {
+            processor.lateUpdate();
+        }
+    }
+    /**
+     * 排序处理器
+     */
+    sortProcessors() {
+        if (this._isDirty) {
+            this._processors.sort((a, b) => a.updateOrder - b.updateOrder);
+            this._isDirty = false;
+        }
+    }
+    /** 获取处理器列表 */
+    get processors() {
+        return this._processors;
+    }
+    /** 获取处理器数量 */
+    get count() {
+        return this._processors.length;
+    }
+}
+EntityProcessorList._logger = createLogger('EntityProcessorList');
+//# sourceMappingURL=EntityProcessorList.js.map

package/bin/ECS/Utils/EntityProcessorList.js.map

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

package/bin/ECS/Utils/IdentifierPool.d.ts

@@ -0,0 +1,203 @@
+/**
+ * 世代式ID池管理器
+ *
+ * 用于管理实体ID的分配和回收，支持世代版本控制以防止悬空引用问题。
+ * 世代式ID由索引和版本组成，当ID被回收时版本会递增，确保旧引用失效。
+ *
+ * 支持动态扩展，理论上可以支持到65535个索引（16位），每个索引65535个版本（16位）。
+ * 总计可以处理超过42亿个独特的ID组合，完全满足ECS大规模实体需求。
+ *
+ * @example
+ * ```typescript
+ * const pool = new IdentifierPool();
+ *
+ * // 分配ID
+ * const id = pool.checkOut(); // 例如: 65536 (版本1，索引0)
+ *
+ * // 回收ID
+ * pool.checkIn(id);
+ *
+ * // 验证ID是否有效
+ * const isValid = pool.isValid(id); // false，因为版本已递增
+ * ```
+ */
+export declare class IdentifierPool {
+    /**
+     * 下一个可用的索引
+     */
+    private _nextAvailableIndex;
+    /**
+     * 空闲的索引列表
+     */
+    private _freeIndices;
+    /**
+     * 每个索引对应的世代版本
+     * 动态扩展的Map，按需分配内存
+     */
+    private _generations;
+    /**
+     * 延迟回收队列
+     * 防止在同一帧内立即重用ID，避免时序问题
+     */
+    private _pendingRecycle;
+    /**
+     * 延迟回收时间（毫秒）
+     */
+    private _recycleDelay;
+    /**
+     * 最大索引限制（16位）
+     * 这是框架设计选择：16位索引 + 16位版本 = 32位ID，确保高效位操作
+     * 不是硬件限制，而是性能和内存效率的权衡
+     */
+    private static readonly MAX_INDEX;
+    /**
+     * 最大世代限制（16位）
+     */
+    private static readonly MAX_GENERATION;
+    /**
+     * 内存扩展块大小
+     * 当需要更多内存时，一次性预分配的索引数量
+     */
+    private _expansionBlockSize;
+    /**
+     * 统计信息
+     */
+    private _stats;
+    /**
+     * 构造函数
+     *
+     * @param recycleDelay 延迟回收时间（毫秒），默认为100ms
+     * @param expansionBlockSize 内存扩展块大小，默认为1024
+     */
+    constructor(recycleDelay?: number, expansionBlockSize?: number);
+    /**
+     * 获取一个可用的ID
+     *
+     * 返回一个32位ID，高16位为世代版本，低16位为索引。
+     *
+     * @returns 新分配的实体ID
+     * @throws {Error} 当达到索引限制时抛出错误
+     */
+    checkOut(): number;
+    /**
+     * 回收一个ID
+     *
+     * 验证ID的有效性后，将其加入延迟回收队列。
+     * ID不会立即可重用，而是在延迟时间后才真正回收。
+     *
+     * @param id 要回收的实体ID
+     * @returns 是否成功回收（ID是否有效且未被重复回收）
+     */
+    checkIn(id: number): boolean;
+    /**
+     * 验证ID是否有效
+     *
+     * 检查ID的索引和世代版本是否匹配当前状态。
+     *
+     * @param id 要验证的实体ID
+     * @returns ID是否有效
+     */
+    isValid(id: number): boolean;
+    /**
+     * 获取统计信息
+     *
+     * @returns 池的当前状态统计
+     */
+    getStats(): {
+        /** 已分配的总索引数 */
+        totalAllocated: number;
+        /** 总计回收次数 */
+        totalRecycled: number;
+        /** 当前活跃实体数 */
+        currentActive: number;
+        /** 当前空闲的索引数 */
+        currentlyFree: number;
+        /** 等待回收的ID数 */
+        pendingRecycle: number;
+        /** 理论最大实体数（设计限制） */
+        maxPossibleEntities: number;
+        /** 当前使用的最大索引 */
+        maxUsedIndex: number;
+        /** 内存使用（字节） */
+        memoryUsage: number;
+        /** 内存扩展次数 */
+        memoryExpansions: number;
+        /** 平均世代版本 */
+        averageGeneration: number;
+        /** 世代存储大小 */
+        generationStorageSize: number;
+    };
+    /**
+     * 强制执行延迟回收处理
+     *
+     * 在某些情况下可能需要立即处理延迟回收队列，
+     * 比如内存压力大或者需要精确的统计信息时。
+     */
+    forceProcessDelayedRecycle(): void;
+    /**
+     * 清理过期的延迟回收项
+     *
+     * 将超过延迟时间的回收项真正回收到空闲列表中。
+     *
+     * @param forceAll 是否强制处理所有延迟回收项
+     * @private
+     */
+    private _processDelayedRecycle;
+    /**
+     * 预分配世代信息
+     *
+     * @param startIndex 起始索引
+     * @param count 分配数量
+     * @private
+     */
+    private _preAllocateGenerations;
+    /**
+     * 确保指定索引的世代信息存在
+     *
+     * @param index 索引
+     * @private
+     */
+    private _ensureGenerationCapacity;
+    /**
+     * 计算内存使用量
+     *
+     * @returns 内存使用字节数
+     * @private
+     */
+    private _calculateMemoryUsage;
+    /**
+     * 打包索引和世代为32位ID
+     *
+     * @param index 索引（16位）
+     * @param generation 世代版本（16位）
+     * @returns 打包后的32位ID
+     * @private
+     */
+    private _packId;
+    /**
+     * 从ID中解包索引
+     *
+     * @param id 32位ID
+     * @returns 索引部分（16位）
+     * @private
+     */
+    private _unpackIndex;
+    /**
+     * 从ID中解包世代版本
+     *
+     * @param id 32位ID
+     * @returns 世代版本部分（16位）
+     * @private
+     */
+    private _unpackGeneration;
+    /**
+     * 内部ID有效性检查
+     *
+     * @param index 索引
+     * @param generation 世代版本
+     * @returns 是否有效
+     * @private
+     */
+    private _isValidId;
+}
+//# sourceMappingURL=IdentifierPool.d.ts.map

package/bin/ECS/Utils/IdentifierPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdentifierPool.d.ts","sourceRoot":"","sources":["../../../src/ECS/Utils/IdentifierPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IACvB;;OAEG;IACH,OAAO,CAAC,mBAAmB,CAAK;IAEhC;;OAEG;IACH,OAAO,CAAC,YAAY,CAAgB;IAEpC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAA6B;IAEjD;;;OAGG;IACH,OAAO,CAAC,eAAe,CAIf;IAER;;OAEG;IACH,OAAO,CAAC,aAAa,CAAe;IAEpC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAU;IAE3C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAU;IAEhD;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAS;IAEpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAKZ;IAEF;;;;;OAKG;gBACS,YAAY,GAAE,MAAY,EAAE,kBAAkB,GAAE,MAAa;IAQzE;;;;;;;OAOG;IACI,QAAQ,IAAI,MAAM;IAgCzB;;;;;;;;OAQG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA+BnC;;;;;;;OAOG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAMnC;;;;OAIG;IACI,QAAQ,IAAI;QACf,eAAe;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,oBAAoB;QACpB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAgB;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa;QACb,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa;QACb,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa;QACb,qBAAqB,EAAE,MAAM,CAAC;KAC7B;IA+BL;;;;;OAKG;IACI,0BAA0B,IAAI,IAAI;IAIzC;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAuC9B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAUjC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAIf;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CAQrB"}