@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/ECS/Utils/Matcher.js

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

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

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

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

@@ -0,0 +1,170 @@
+/**
+ * 稀疏集合实现
+ *
+ * 提供O(1)的插入、删除、查找操作，同时保持数据的紧凑存储。
+ * 使用密集数组存储实际数据，稀疏映射提供快速访问
+ *
+ * @template T 存储的数据类型
+ *
+ * @example
+ * ```typescript
+ * const sparseSet = new SparseSet<Entity>();
+ *
+ * sparseSet.add(entity1);
+ * sparseSet.add(entity2);
+ *
+ * if (sparseSet.has(entity1)) {
+ *     sparseSet.remove(entity1);
+ * }
+ *
+ * sparseSet.forEach((entity, index) => {
+ *     console.log(`Entity at index ${index}: ${entity.name}`);
+ * });
+ * ```
+ */
+export declare class SparseSet<T> {
+    /**
+     * 密集存储数组
+     *
+     * 连续存储所有有效数据，确保遍历时的缓存友好性。
+     */
+    private _dense;
+    /**
+     * 稀疏映射表
+     *
+     * 将数据项映射到密集数组中的索引，提供O(1)的查找性能。
+     */
+    private _sparse;
+    /**
+     * 添加元素到集合
+     *
+     * @param item 要添加的元素
+     * @returns 是否成功添加（false表示元素已存在）
+     */
+    add(item: T): boolean;
+    /**
+     * 从集合中移除元素
+     *
+     * 使用swap-and-pop技术保持数组紧凑性：
+     * 1. 将要删除的元素与最后一个元素交换
+     * 2. 删除最后一个元素
+     * 3. 更新映射表
+     *
+     * @param item 要移除的元素
+     * @returns 是否成功移除（false表示元素不存在）
+     */
+    remove(item: T): boolean;
+    /**
+     * 检查元素是否存在于集合中
+     *
+     * @param item 要检查的元素
+     * @returns 元素是否存在
+     */
+    has(item: T): boolean;
+    /**
+     * 获取元素在密集数组中的索引
+     *
+     * @param item 要查询的元素
+     * @returns 索引，如果元素不存在则返回undefined
+     */
+    getIndex(item: T): number | undefined;
+    /**
+     * 根据索引获取元素
+     *
+     * @param index 索引
+     * @returns 元素，如果索引无效则返回undefined
+     */
+    getByIndex(index: number): T | undefined;
+    /**
+     * 获取集合大小
+     */
+    get size(): number;
+    /**
+     * 检查集合是否为空
+     */
+    get isEmpty(): boolean;
+    /**
+     * 遍历集合中的所有元素
+     *
+     * 保证遍历顺序与添加顺序一致（除非中间有删除操作）。
+     * 遍历性能优秀，因为数据在内存中连续存储。
+     *
+     * @param callback 遍历回调函数
+     */
+    forEach(callback: (item: T, index: number) => void): void;
+    /**
+     * 映射集合中的所有元素
+     *
+     * @param callback 映射回调函数
+     * @returns 映射后的新数组
+     */
+    map<U>(callback: (item: T, index: number) => U): U[];
+    /**
+     * 过滤集合中的元素
+     *
+     * @param predicate 过滤条件
+     * @returns 满足条件的元素数组
+     */
+    filter(predicate: (item: T, index: number) => boolean): T[];
+    /**
+     * 查找第一个满足条件的元素
+     *
+     * @param predicate 查找条件
+     * @returns 找到的元素，如果没有则返回undefined
+     */
+    find(predicate: (item: T, index: number) => boolean): T | undefined;
+    /**
+     * 检查是否存在满足条件的元素
+     *
+     * @param predicate 检查条件
+     * @returns 是否存在满足条件的元素
+     */
+    some(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * 检查是否所有元素都满足条件
+     *
+     * @param predicate 检查条件
+     * @returns 是否所有元素都满足条件
+     */
+    every(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * 获取密集数组的只读副本
+     *
+     * 返回数组的浅拷贝，确保外部无法直接修改内部数据。
+     */
+    getDenseArray(): readonly T[];
+    /**
+     * 获取密集数组的直接引用（内部使用）
+     *
+     * 警告：直接修改返回的数组会破坏数据结构的完整性。
+     * 仅在性能关键场景下使用，并确保不会修改数组内容。
+     */
+    getDenseArrayUnsafe(): readonly T[];
+    /**
+     * 清空集合
+     */
+    clear(): void;
+    /**
+     * 转换为数组
+     */
+    toArray(): T[];
+    /**
+     * 转换为Set
+     */
+    toSet(): Set<T>;
+    /**
+     * 获取内存使用统计信息
+     */
+    getMemoryStats(): {
+        denseArraySize: number;
+        sparseMapSize: number;
+        totalMemory: number;
+    };
+    /**
+     * 验证数据结构的完整性
+     *
+     * 调试用方法，检查内部数据结构是否一致。
+     */
+    validate(): boolean;
+}
+//# sourceMappingURL=SparseSet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SparseSet.d.ts","sourceRoot":"","sources":["../../../src/ECS/Utils/SparseSet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,SAAS,CAAC,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAW;IAEzB;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAwB;IAEvC;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAW5B;;;;;;;;;;OAUG;IACI,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAqB/B;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAI5B;;;;;OAKG;IACI,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS;IAI5C;;;;;OAKG;IACI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI/C;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;;;;OAOG;IACI,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAMhE;;;;;OAKG;IACI,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE;IAQ3D;;;;;OAKG;IACI,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,CAAC,EAAE;IAUlE;;;;;OAKG;IACI,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS;IAS1E;;;;;OAKG;IACI,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO;IASpE;;;;;OAKG;IACI,KAAK,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO;IASrE;;;;OAIG;IACI,aAAa,IAAI,SAAS,CAAC,EAAE;IAIpC;;;;;OAKG;IACI,mBAAmB,IAAI,SAAS,CAAC,EAAE;IAI1C;;OAEG;IACI,KAAK,IAAI,IAAI;IAKpB;;OAEG;IACI,OAAO,IAAI,CAAC,EAAE;IAIrB;;OAEG;IACI,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC;IAItB;;OAEG;IACI,cAAc,IAAI;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;KACnB;IAWL;;;;OAIG;IACI,QAAQ,IAAI,OAAO;CAwB7B"}