@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/ECS/Utils/IdentifierPool.js

@@ -0,0 +1,325 @@
+/**
+ * 世代式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 class IdentifierPool {
+    /**
+     * 构造函数
+     *
+     * @param recycleDelay 延迟回收时间（毫秒），默认为100ms
+     * @param expansionBlockSize 内存扩展块大小，默认为1024
+     */
+    constructor(recycleDelay = 100, expansionBlockSize = 1024) {
+        /**
+         * 下一个可用的索引
+         */
+        this._nextAvailableIndex = 0;
+        /**
+         * 空闲的索引列表
+         */
+        this._freeIndices = [];
+        /**
+         * 每个索引对应的世代版本
+         * 动态扩展的Map，按需分配内存
+         */
+        this._generations = new Map();
+        /**
+         * 延迟回收队列
+         * 防止在同一帧内立即重用ID，避免时序问题
+         */
+        this._pendingRecycle = [];
+        /**
+         * 延迟回收时间（毫秒）
+         */
+        this._recycleDelay = 100;
+        /**
+         * 统计信息
+         */
+        this._stats = {
+            totalAllocated: 0,
+            totalRecycled: 0,
+            currentActive: 0,
+            memoryExpansions: 0
+        };
+        this._recycleDelay = recycleDelay;
+        this._expansionBlockSize = expansionBlockSize;
+        // 预分配第一个块的世代信息
+        this._preAllocateGenerations(0, this._expansionBlockSize);
+    }
+    /**
+     * 获取一个可用的ID
+     *
+     * 返回一个32位ID，高16位为世代版本，低16位为索引。
+     *
+     * @returns 新分配的实体ID
+     * @throws {Error} 当达到索引限制时抛出错误
+     */
+    checkOut() {
+        // 处理延迟回收队列
+        this._processDelayedRecycle();
+        let index;
+        if (this._freeIndices.length > 0) {
+            // 重用回收的索引
+            index = this._freeIndices.pop();
+        }
+        else {
+            // 分配新索引
+            if (this._nextAvailableIndex > IdentifierPool.MAX_INDEX) {
+                throw new Error(`实体索引已达到框架设计限制 (${IdentifierPool.MAX_INDEX})。` +
+                    '这意味着您已经分配了超过65535个不同的实体索引。' +
+                    '这是16位索引设计的限制，考虑优化实体回收策略或升级到64位ID设计。');
+            }
+            index = this._nextAvailableIndex++;
+            // 按需扩展世代存储
+            this._ensureGenerationCapacity(index);
+        }
+        const generation = this._generations.get(index) || 1;
+        this._stats.totalAllocated++;
+        this._stats.currentActive++;
+        return this._packId(index, generation);
+    }
+    /**
+     * 回收一个ID
+     *
+     * 验证ID的有效性后，将其加入延迟回收队列。
+     * ID不会立即可重用，而是在延迟时间后才真正回收。
+     *
+     * @param id 要回收的实体ID
+     * @returns 是否成功回收（ID是否有效且未被重复回收）
+     */
+    checkIn(id) {
+        const index = this._unpackIndex(id);
+        const generation = this._unpackGeneration(id);
+        // 验证ID有效性
+        if (!this._isValidId(index, generation)) {
+            return false;
+        }
+        // 检查是否已经在待回收队列中
+        const alreadyPending = this._pendingRecycle.some((item) => item.index === index && item.generation === generation);
+        if (alreadyPending) {
+            return false; // 已经在回收队列中，拒绝重复回收
+        }
+        // 加入延迟回收队列
+        this._pendingRecycle.push({
+            index,
+            generation,
+            timestamp: Date.now()
+        });
+        this._stats.currentActive--;
+        this._stats.totalRecycled++;
+        return true;
+    }
+    /**
+     * 验证ID是否有效
+     *
+     * 检查ID的索引和世代版本是否匹配当前状态。
+     *
+     * @param id 要验证的实体ID
+     * @returns ID是否有效
+     */
+    isValid(id) {
+        const index = this._unpackIndex(id);
+        const generation = this._unpackGeneration(id);
+        return this._isValidId(index, generation);
+    }
+    /**
+     * 获取统计信息
+     *
+     * @returns 池的当前状态统计
+     */
+    getStats() {
+        // 计算平均世代版本
+        let totalGeneration = 0;
+        let generationCount = 0;
+        for (const [index, generation] of this._generations) {
+            if (index < this._nextAvailableIndex) {
+                totalGeneration += generation;
+                generationCount++;
+            }
+        }
+        const averageGeneration = generationCount > 0
+            ? totalGeneration / generationCount
+            : 1;
+        return {
+            totalAllocated: this._stats.totalAllocated,
+            totalRecycled: this._stats.totalRecycled,
+            currentActive: this._stats.currentActive,
+            currentlyFree: this._freeIndices.length,
+            pendingRecycle: this._pendingRecycle.length,
+            maxPossibleEntities: IdentifierPool.MAX_INDEX + 1,
+            maxUsedIndex: this._nextAvailableIndex - 1,
+            memoryUsage: this._calculateMemoryUsage(),
+            memoryExpansions: this._stats.memoryExpansions,
+            averageGeneration: Math.round(averageGeneration * 100) / 100,
+            generationStorageSize: this._generations.size
+        };
+    }
+    /**
+     * 强制执行延迟回收处理
+     *
+     * 在某些情况下可能需要立即处理延迟回收队列，
+     * 比如内存压力大或者需要精确的统计信息时。
+     */
+    forceProcessDelayedRecycle() {
+        this._processDelayedRecycle(true);
+    }
+    /**
+     * 清理过期的延迟回收项
+     *
+     * 将超过延迟时间的回收项真正回收到空闲列表中。
+     *
+     * @param forceAll 是否强制处理所有延迟回收项
+     * @private
+     */
+    _processDelayedRecycle(forceAll = false) {
+        if (this._pendingRecycle.length === 0)
+            return;
+        const now = Date.now();
+        const readyToRecycle = [];
+        const stillPending = [];
+        // 分离已到期和未到期的项
+        for (const item of this._pendingRecycle) {
+            if (forceAll || now - item.timestamp >= this._recycleDelay) {
+                readyToRecycle.push(item);
+            }
+            else {
+                stillPending.push(item);
+            }
+        }
+        // 处理到期的回收项
+        for (const item of readyToRecycle) {
+            // 再次验证ID有效性（防止重复回收）
+            if (this._isValidId(item.index, item.generation)) {
+                // 递增世代版本
+                let newGeneration = item.generation + 1;
+                // 防止世代版本溢出
+                if (newGeneration > IdentifierPool.MAX_GENERATION) {
+                    newGeneration = 1; // 重置为1而不是0
+                }
+                this._generations.set(item.index, newGeneration);
+                // 添加到空闲列表
+                this._freeIndices.push(item.index);
+            }
+        }
+        // 更新待回收队列
+        this._pendingRecycle = stillPending;
+    }
+    /**
+     * 预分配世代信息
+     *
+     * @param startIndex 起始索引
+     * @param count 分配数量
+     * @private
+     */
+    _preAllocateGenerations(startIndex, count) {
+        for (let i = 0; i < count; i++) {
+            const index = startIndex + i;
+            if (index <= IdentifierPool.MAX_INDEX) {
+                this._generations.set(index, 1);
+            }
+        }
+        this._stats.memoryExpansions++;
+    }
+    /**
+     * 确保指定索引的世代信息存在
+     *
+     * @param index 索引
+     * @private
+     */
+    _ensureGenerationCapacity(index) {
+        if (!this._generations.has(index)) {
+            // 计算需要扩展的起始位置
+            const expansionStart = Math.floor(index / this._expansionBlockSize) * this._expansionBlockSize;
+            // 预分配一个块
+            this._preAllocateGenerations(expansionStart, this._expansionBlockSize);
+        }
+    }
+    /**
+     * 计算内存使用量
+     *
+     * @returns 内存使用字节数
+     * @private
+     */
+    _calculateMemoryUsage() {
+        const generationMapSize = this._generations.size * 16; // Map overhead + number pair
+        const freeIndicesSize = this._freeIndices.length * 8;
+        const pendingRecycleSize = this._pendingRecycle.length * 32;
+        return generationMapSize + freeIndicesSize + pendingRecycleSize;
+    }
+    /**
+     * 打包索引和世代为32位ID
+     *
+     * @param index 索引（16位）
+     * @param generation 世代版本（16位）
+     * @returns 打包后的32位ID
+     * @private
+     */
+    _packId(index, generation) {
+        return (generation << 16) | index;
+    }
+    /**
+     * 从ID中解包索引
+     *
+     * @param id 32位ID
+     * @returns 索引部分（16位）
+     * @private
+     */
+    _unpackIndex(id) {
+        return id & 0xFFFF;
+    }
+    /**
+     * 从ID中解包世代版本
+     *
+     * @param id 32位ID
+     * @returns 世代版本部分（16位）
+     * @private
+     */
+    _unpackGeneration(id) {
+        return (id >>> 16) & 0xFFFF;
+    }
+    /**
+     * 内部ID有效性检查
+     *
+     * @param index 索引
+     * @param generation 世代版本
+     * @returns 是否有效
+     * @private
+     */
+    _isValidId(index, generation) {
+        if (index < 0 || index >= this._nextAvailableIndex) {
+            return false;
+        }
+        const currentGeneration = this._generations.get(index);
+        return currentGeneration !== undefined && currentGeneration === generation;
+    }
+}
+/**
+ * 最大索引限制（16位）
+ * 这是框架设计选择：16位索引 + 16位版本 = 32位ID，确保高效位操作
+ * 不是硬件限制，而是性能和内存效率的权衡
+ */
+IdentifierPool.MAX_INDEX = 0xFFFF; // 65535
+/**
+ * 最大世代限制（16位）
+ */
+IdentifierPool.MAX_GENERATION = 0xFFFF; // 65535
+//# sourceMappingURL=IdentifierPool.js.map

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

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

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

@@ -0,0 +1,171 @@
+import { ComponentType } from '../Core/ComponentStorage';
+/**
+ * 查询条件类型
+ */
+export interface QueryCondition {
+    all: ComponentType[];
+    any: ComponentType[];
+    none: ComponentType[];
+    tag?: number;
+    name?: string;
+    component?: ComponentType;
+    matchNothing?: boolean;
+}
+/**
+ * 实体匹配条件描述符
+ *
+ * 用于描述实体查询条件，不执行实际查询
+ *
+ * @example
+ * ```typescript
+ * const matcher = Matcher.all(Position, Velocity)
+ *   .any(Health, Shield)
+ *   .none(Dead);
+ *
+ * // 获取查询条件
+ * const condition = matcher.getCondition();
+ * ```
+ */
+export declare class Matcher {
+    private readonly condition;
+    private constructor();
+    /**
+     * 创建匹配器，要求所有指定的组件
+     * @param types 组件类型
+     */
+    static all(...types: ComponentType[]): Matcher;
+    /**
+     * 创建匹配器，要求至少一个指定的组件
+     * @param types 组件类型
+     */
+    static any(...types: ComponentType[]): Matcher;
+    /**
+     * 创建匹配器，排除指定的组件
+     * @param types 组件类型
+     */
+    static none(...types: ComponentType[]): Matcher;
+    /**
+     * 创建按标签查询的匙配器
+     * @param tag 标签值
+     */
+    static byTag(tag: number): Matcher;
+    /**
+     * 创建按名称查询的匙配器
+     * @param name 实体名称
+     */
+    static byName(name: string): Matcher;
+    /**
+     * 创建单组件查询的匙配器
+     * @param componentType 组件类型
+     */
+    static byComponent(componentType: ComponentType): Matcher;
+    /**
+     * 创建复杂查询构建器
+     */
+    static complex(): Matcher;
+    /**
+     * 创建空匙配器
+     */
+    static empty(): Matcher;
+    /**
+     * 创建不匹配任何实体的匹配器
+     * 用于只需要 onBegin/onEnd 生命周期方法但不需要处理实体的系统
+     *
+     * @example
+     * ```typescript
+     * // 创建一个只在帧开始时执行的系统
+     * class FrameBeginSystem extends EntitySystem {
+     *     constructor() {
+     *         super(Matcher.nothing());
+     *     }
+     *
+     *     protected onBegin(): void {
+     *         // 每帧开始时执行
+     *     }
+     *
+     *     protected process(entities: readonly Entity[]): void {
+     *         // 永远不会被调用，因为没有实体匹配
+     *     }
+     * }
+     * ```
+     */
+    static nothing(): Matcher;
+    /**
+     * 必须包含所有指定组件
+     * @param types 组件类型
+     */
+    all(...types: ComponentType[]): Matcher;
+    /**
+     * 必须包含至少一个指定组件
+     * @param types 组件类型
+     */
+    any(...types: ComponentType[]): Matcher;
+    /**
+     * 不能包含任何指定组件
+     * @param types 组件类型
+     */
+    none(...types: ComponentType[]): Matcher;
+    /**
+     * 排除指定组件（别名方法）
+     * @param types 组件类型
+     */
+    exclude(...types: ComponentType[]): Matcher;
+    /**
+     * 至少包含其中之一（别名方法）
+     * @param types 组件类型
+     */
+    one(...types: ComponentType[]): Matcher;
+    /**
+     * 按标签查询
+     * @param tag 标签值
+     */
+    withTag(tag: number): Matcher;
+    /**
+     * 按名称查询
+     * @param name 实体名称
+     */
+    withName(name: string): Matcher;
+    /**
+     * 单组件查询
+     * @param componentType 组件类型
+     */
+    withComponent(componentType: ComponentType): Matcher;
+    /**
+     * 移除标签条件
+     */
+    withoutTag(): Matcher;
+    /**
+     * 移除名称条件
+     */
+    withoutName(): Matcher;
+    /**
+     * 移除单组件条件
+     */
+    withoutComponent(): Matcher;
+    /**
+     * 获取查询条件（只读）
+     */
+    getCondition(): Readonly<QueryCondition>;
+    /**
+     * 检查是否为空条件
+     * 注意：matchNothing 不算空条件，因为它是明确的"不匹配任何实体"语义
+     */
+    isEmpty(): boolean;
+    /**
+     * 检查是否为"不匹配任何实体"的匹配器
+     */
+    isNothing(): boolean;
+    /**
+     * 重置所有条件
+     */
+    reset(): Matcher;
+    /**
+     * 克隆匹配器
+     */
+    clone(): Matcher;
+    /**
+     * 字符串表示
+     */
+    toString(): string;
+}
+//# sourceMappingURL=Matcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Matcher.d.ts","sourceRoot":"","sources":["../../../src/ECS/Utils/Matcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,aAAa,EAAE,CAAC;IACrB,GAAG,EAAE,aAAa,EAAE,CAAC;IACrB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,OAAO;IAChB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAIxB;IAEF,OAAO;IAIP;;;OAGG;WACW,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAKrD;;;OAGG;WACW,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAKrD;;;OAGG;WACW,IAAI,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAKtD;;;OAGG;WACW,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzC;;;OAGG;WACW,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK3C;;;OAGG;WACW,WAAW,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO;IAKhE;;OAEG;WACW,OAAO,IAAI,OAAO;IAIhC;;OAEG;WACW,KAAK,IAAI,OAAO;IAI9B;;;;;;;;;;;;;;;;;;;;;OAqBG;WACW,OAAO,IAAI,OAAO;IAMhC;;;OAGG;IACI,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAK9C;;;OAGG;IACI,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAK9C;;;OAGG;IACI,IAAI,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAK/C;;;OAGG;IACI,OAAO,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAIlD;;;OAGG;IACI,GAAG,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;IAI9C;;;OAGG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKpC;;;OAGG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKtC;;;OAGG;IACI,aAAa,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO;IAK3D;;OAEG;IACI,UAAU,IAAI,OAAO;IAK5B;;OAEG;IACI,WAAW,IAAI,OAAO;IAK7B;;OAEG;IACI,gBAAgB,IAAI,OAAO;IAKlC;;OAEG;IACI,YAAY,IAAI,QAAQ,CAAC,cAAc,CAAC;IAY/C;;;OAGG;IACI,OAAO,IAAI,OAAO;IAUzB;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,KAAK,IAAI,OAAO;IAWvB;;OAEG;IACI,KAAK,IAAI,OAAO;IAoBvB;;OAEG;IACI,QAAQ,IAAI,MAAM;CAkC5B"}