@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/ECS/Core/ReactiveQuery.js

@@ -0,0 +1,401 @@
+import { QueryConditionType } from './QueryTypes';
+import { BitMask64Utils } from '../Utils/BigIntCompatibility';
+import { createLogger } from '../../Utils/Logger';
+const logger = createLogger('ReactiveQuery');
+/**
+ * 响应式查询变化类型
+ */
+export var ReactiveQueryChangeType;
+(function (ReactiveQueryChangeType) {
+    /** 实体添加到查询结果 */
+    ReactiveQueryChangeType["ADDED"] = "added";
+    /** 实体从查询结果移除 */
+    ReactiveQueryChangeType["REMOVED"] = "removed";
+    /** 查询结果批量更新 */
+    ReactiveQueryChangeType["BATCH_UPDATE"] = "batch_update";
+})(ReactiveQueryChangeType || (ReactiveQueryChangeType = {}));
+/**
+ * 响应式查询类
+ *
+ * 提供基于事件驱动的实体查询机制,只在实体/组件真正变化时触发通知。
+ *
+ * 核心特性:
+ * - Event-driven: 基于事件的增量更新
+ * - 精确通知: 只通知真正匹配的变化
+ * - 性能优化: 避免每帧重复查询
+ *
+ * @example
+ * ```typescript
+ * // 创建响应式查询
+ * const query = new ReactiveQuery(querySystem, {
+ *     type: QueryConditionType.ALL,
+ *     componentTypes: [Position, Velocity],
+ *     mask: createMask([Position, Velocity])
+ * });
+ *
+ * // 订阅变化
+ * query.subscribe((change) => {
+ *     if (change.type === ReactiveQueryChangeType.ADDED) {
+ *         console.log('新实体:', change.entity);
+ *     }
+ * });
+ *
+ * // 获取当前结果
+ * const entities = query.getEntities();
+ * ```
+ */
+export class ReactiveQuery {
+    constructor(condition, config = {}) {
+        /** 当前查询结果 */
+        this._entities = [];
+        /** 实体ID集合,用于快速查找 */
+        this._entityIdSet = new Set();
+        /**
+         * 实体数组快照 - 用于安全迭代
+         * Entity array snapshot - for safe iteration
+         * 只在实体列表变化时才创建新快照，静态场景下所有系统共享同一快照
+         * Only create new snapshot when entity list changes, static scenes share the same snapshot
+         */
+        this._snapshot = null;
+        /** 监听器列表 */
+        this._listeners = [];
+        /** 是否已激活 */
+        this._active = true;
+        this._condition = condition;
+        this._config = {
+            enableBatchMode: config.enableBatchMode ?? true,
+            batchDelay: config.batchDelay ?? 16, // 默认一帧
+            debug: config.debug ?? false
+        };
+        this._id = this.generateQueryId();
+        this._batchChanges = {
+            added: [],
+            removed: [],
+            timer: null
+        };
+        if (this._config.debug) {
+            logger.debug(`创建ReactiveQuery: ${this._id}`);
+        }
+    }
+    /**
+     * 生成查询ID
+     */
+    generateQueryId() {
+        const typeStr = this._condition.type;
+        const componentsStr = this._condition.componentTypes
+            .map((t) => t.name)
+            .sort()
+            .join(',');
+        return `${typeStr}:${componentsStr}`;
+    }
+    /**
+     * 订阅查询变化
+     *
+     * @param listener 监听器函数
+     * @returns 取消订阅的函数
+     */
+    subscribe(listener) {
+        if (!this._active) {
+            throw new Error(`Cannot subscribe to disposed ReactiveQuery ${this._id}`);
+        }
+        if (typeof listener !== 'function') {
+            throw new TypeError('Listener must be a function');
+        }
+        this._listeners.push(listener);
+        if (this._config.debug) {
+            logger.debug(`订阅ReactiveQuery: ${this._id}, 监听器数量: ${this._listeners.length}`);
+        }
+        return () => {
+            const index = this._listeners.indexOf(listener);
+            if (index !== -1) {
+                this._listeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * 取消所有订阅
+     */
+    unsubscribeAll() {
+        this._listeners.length = 0;
+    }
+    /**
+     * 获取当前查询结果（返回安全快照）
+     * Get current query results (returns safe snapshot)
+     *
+     * 返回的快照在实体列表变化前保持不变，可安全用于迭代。
+     * 静态场景下所有系统共享同一快照，避免每帧创建数组副本。
+     *
+     * The returned snapshot remains unchanged until entity list changes, safe for iteration.
+     * Static scenes share the same snapshot, avoiding array copy every frame.
+     */
+    getEntities() {
+        // 如果快照有效，直接返回 | Return snapshot if valid
+        if (this._snapshot !== null) {
+            return this._snapshot;
+        }
+        // 创建新快照 | Create new snapshot
+        this._snapshot = [...this._entities];
+        return this._snapshot;
+    }
+    /**
+     * 获取查询结果数量
+     */
+    get count() {
+        return this._entities.length;
+    }
+    /**
+     * 检查实体是否匹配查询条件
+     *
+     * @param entity 要检查的实体
+     * @returns 是否匹配
+     */
+    matches(entity) {
+        const entityMask = entity.componentMask;
+        switch (this._condition.type) {
+            case QueryConditionType.ALL:
+                return BitMask64Utils.hasAll(entityMask, this._condition.mask);
+            case QueryConditionType.ANY:
+                return BitMask64Utils.hasAny(entityMask, this._condition.mask);
+            case QueryConditionType.NONE:
+                return BitMask64Utils.hasNone(entityMask, this._condition.mask);
+            default:
+                return false;
+        }
+    }
+    /**
+     * 通知实体添加
+     *
+     * 当Scene中添加实体时调用
+     *
+     * @param entity 添加的实体
+     */
+    notifyEntityAdded(entity) {
+        if (!this._active)
+            return;
+        // 检查实体是否匹配查询条件
+        if (!this.matches(entity)) {
+            return;
+        }
+        // 检查是否已存在
+        if (this._entityIdSet.has(entity.id)) {
+            return;
+        }
+        // 添加到结果集
+        this._entities.push(entity);
+        this._entityIdSet.add(entity.id);
+        this._snapshot = null; // 使快照失效 | Invalidate snapshot
+        // 通知监听器
+        if (this._config.enableBatchMode) {
+            this.addToBatch('added', entity);
+        }
+        else {
+            this.notifyListeners({
+                type: ReactiveQueryChangeType.ADDED,
+                entity
+            });
+        }
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 实体添加 ${entity.name}(${entity.id})`);
+        }
+    }
+    /**
+     * 通知实体移除
+     *
+     * 当Scene中移除实体时调用
+     *
+     * @param entity 移除的实体
+     */
+    notifyEntityRemoved(entity) {
+        if (!this._active)
+            return;
+        // 检查是否在结果集中
+        if (!this._entityIdSet.has(entity.id)) {
+            return;
+        }
+        // 从结果集移除
+        const index = this._entities.indexOf(entity);
+        if (index !== -1) {
+            this._entities.splice(index, 1);
+        }
+        this._entityIdSet.delete(entity.id);
+        this._snapshot = null; // 使快照失效 | Invalidate snapshot
+        // 通知监听器
+        if (this._config.enableBatchMode) {
+            this.addToBatch('removed', entity);
+        }
+        else {
+            this.notifyListeners({
+                type: ReactiveQueryChangeType.REMOVED,
+                entity
+            });
+        }
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 实体移除 ${entity.name}(${entity.id})`);
+        }
+    }
+    /**
+     * 通知实体组件变化
+     *
+     * 当实体的组件发生变化时调用
+     *
+     * @param entity 变化的实体
+     */
+    notifyEntityChanged(entity) {
+        if (!this._active)
+            return;
+        const wasMatching = this._entityIdSet.has(entity.id);
+        const isMatching = this.matches(entity);
+        if (wasMatching && !isMatching) {
+            // 实体不再匹配,从结果集移除
+            this.notifyEntityRemoved(entity);
+        }
+        else if (!wasMatching && isMatching) {
+            // 实体现在匹配,添加到结果集
+            this.notifyEntityAdded(entity);
+        }
+    }
+    /**
+     * 批量初始化查询结果
+     *
+     * @param entities 初始实体列表
+     */
+    initializeWith(entities) {
+        // 清空现有结果
+        this._entities.length = 0;
+        this._entityIdSet.clear();
+        this._snapshot = null; // 使快照失效 | Invalidate snapshot
+        // 筛选匹配的实体
+        for (const entity of entities) {
+            if (this.matches(entity)) {
+                this._entities.push(entity);
+                this._entityIdSet.add(entity.id);
+            }
+        }
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 初始化 ${this._entities.length} 个实体`);
+        }
+    }
+    /**
+     * 添加到批量变化缓存
+     */
+    addToBatch(type, entity) {
+        if (type === 'added') {
+            this._batchChanges.added.push(entity);
+        }
+        else {
+            this._batchChanges.removed.push(entity);
+        }
+        // 启动批量通知定时器
+        if (this._batchChanges.timer === null) {
+            this._batchChanges.timer = setTimeout(() => {
+                this.flushBatchChanges();
+            }, this._config.batchDelay);
+        }
+    }
+    /**
+     * 刷新批量变化
+     */
+    flushBatchChanges() {
+        if (this._batchChanges.added.length === 0 && this._batchChanges.removed.length === 0) {
+            this._batchChanges.timer = null;
+            return;
+        }
+        const added = [...this._batchChanges.added];
+        const removed = [...this._batchChanges.removed];
+        // 清空缓存
+        this._batchChanges.added.length = 0;
+        this._batchChanges.removed.length = 0;
+        this._batchChanges.timer = null;
+        // 通知监听器
+        this.notifyListeners({
+            type: ReactiveQueryChangeType.BATCH_UPDATE,
+            added,
+            removed,
+            entities: this._entities
+        });
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 批量更新 +${added.length} -${removed.length}`);
+        }
+    }
+    /**
+     * 通知所有监听器
+     */
+    notifyListeners(change) {
+        const listeners = [...this._listeners];
+        for (const listener of listeners) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                logger.error(`ReactiveQuery ${this._id}: 监听器执行出错`, error);
+            }
+        }
+    }
+    /**
+     * 暂停响应式查询
+     *
+     * 暂停后不再响应实体变化,但可以继续获取当前结果
+     */
+    pause() {
+        this._active = false;
+        // 清空批量变化缓存
+        if (this._batchChanges.timer !== null) {
+            clearTimeout(this._batchChanges.timer);
+            this._batchChanges.timer = null;
+        }
+        this._batchChanges.added.length = 0;
+        this._batchChanges.removed.length = 0;
+    }
+    /**
+     * 恢复响应式查询
+     */
+    resume() {
+        this._active = true;
+    }
+    /**
+     * 销毁响应式查询
+     *
+     * 释放所有资源,清空监听器和结果集
+     */
+    dispose() {
+        if (this._batchChanges.timer !== null) {
+            clearTimeout(this._batchChanges.timer);
+            this._batchChanges.timer = null;
+        }
+        this._batchChanges.added.length = 0;
+        this._batchChanges.removed.length = 0;
+        this._active = false;
+        this.unsubscribeAll();
+        this._entities.length = 0;
+        this._entityIdSet.clear();
+        this._snapshot = null;
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 已销毁`);
+        }
+    }
+    /**
+     * 获取查询条件
+     */
+    get condition() {
+        return this._condition;
+    }
+    /**
+     * 获取查询ID
+     */
+    get id() {
+        return this._id;
+    }
+    /**
+     * 检查是否激活
+     */
+    get active() {
+        return this._active;
+    }
+    /**
+     * 获取监听器数量
+     */
+    get listenerCount() {
+        return this._listeners.length;
+    }
+}
+//# sourceMappingURL=ReactiveQuery.js.map

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

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

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

@@ -0,0 +1,111 @@
+import { Component } from '../Component';
+import type { Entity } from '../Entity';
+import type { IScene } from '../IScene';
+/**
+ * WeakRef 接口定义
+ *
+ * 用于 ES2020 环境下的类型定义
+ */
+interface IWeakRef<T extends object> {
+    deref(): T | undefined;
+}
+/**
+ * Entity引用记录
+ */
+export interface EntityRefRecord {
+    component: IWeakRef<Component>;
+    propertyKey: string;
+}
+/**
+ * 通过Entity ID获取Scene
+ *
+ * @param entityId Entity ID
+ * @returns Scene实例，如果不存在则返回null
+ */
+export declare function getSceneByEntityId(entityId: number): IScene | null;
+/**
+ * Entity引用追踪器
+ *
+ * 追踪Component中对Entity的引用，当Entity被销毁时自动清理所有引用。
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ReferenceTracker();
+ * tracker.registerReference(targetEntity, component, 'parent');
+ * targetEntity.destroy(); // 自动将 component.parent 设为 null
+ * ```
+ */
+export declare class ReferenceTracker {
+    /**
+     * Entity ID -> 引用该Entity的所有组件记录
+     */
+    private _references;
+    /**
+     * 注册Entity引用
+     *
+     * @param entity 被引用的Entity
+     * @param component 持有引用的Component
+     * @param propertyKey Component中存储引用的属性名
+     */
+    registerReference(entity: Entity, component: Component, propertyKey: string): void;
+    /**
+     * 注销Entity引用
+     *
+     * @param entity 被引用的Entity
+     * @param component 持有引用的Component
+     * @param propertyKey Component中存储引用的属性名
+     */
+    unregisterReference(entity: Entity, component: Component, propertyKey: string): void;
+    /**
+     * 清理所有指向指定Entity的引用
+     *
+     * 将所有引用该Entity的Component属性设为null。
+     *
+     * @param entityId 被销毁的Entity ID
+     */
+    clearReferencesTo(entityId: number): void;
+    /**
+     * 清理Component的所有引用注册
+     *
+     * 当Component被移除时调用，清理该Component注册的所有引用。
+     *
+     * @param component 被移除的Component
+     */
+    clearComponentReferences(component: Component): void;
+    /**
+     * 获取指向指定Entity的所有引用记录
+     *
+     * @param entityId Entity ID
+     * @returns 引用记录数组（仅包含有效引用）
+     */
+    getReferencesTo(entityId: number): EntityRefRecord[];
+    /**
+     * 清理所有失效的WeakRef引用
+     *
+     * 遍历所有记录，移除已被GC回收的Component引用。
+     */
+    cleanup(): void;
+    /**
+     * 注册Entity到Scene的映射
+     *
+     * @param entityId Entity ID
+     * @param scene Scene实例
+     */
+    registerEntityScene(entityId: number, scene: IScene): void;
+    /**
+     * 注销Entity到Scene的映射
+     *
+     * @param entityId Entity ID
+     */
+    unregisterEntityScene(entityId: number): void;
+    /**
+     * 获取调试信息
+     */
+    getDebugInfo(): object;
+    /**
+     * 查找指定的引用记录
+     */
+    private _findRecord;
+}
+export {};
+//# sourceMappingURL=ReferenceTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReferenceTracker.d.ts","sourceRoot":"","sources":["../../../src/ECS/Core/ReferenceTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;GAIG;AACH,UAAU,QAAQ,CAAC,CAAC,SAAS,MAAM;IAC/B,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1B;AA0CD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;CACvB;AASD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IACzB;;OAEG;IACH,OAAO,CAAC,WAAW,CAAgD;IAEnE;;;;;;OAMG;IACI,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAoBzF;;;;;;OAMG;IACI,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAkB3F;;;;;;OAMG;IACI,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA2BhD;;;;;;OAMG;IACI,wBAAwB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAqB3D;;;;;OAKG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE;IAkB3D;;;;OAIG;IACI,OAAO,IAAI,IAAI;IA0BtB;;;;;OAKG;IACI,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjE;;;;OAIG;IACI,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpD;;OAEG;IACI,YAAY,IAAI,MAAM;IAuB7B;;OAEG;IACH,OAAO,CAAC,WAAW;CAatB"}