refactor(core): 改进事件系统类型安全并消除 ESLint 警告 (#208)

2025-11-01 16:12:18 +08:00
parent 57c7e7be3f
commit 3ad5dc9ca3
6 changed files with 310 additions and 159 deletions
--- a/packages/core/src/ECS/Systems/EntityCache.ts
+++ b/packages/core/src/ECS/Systems/EntityCache.ts
@@ -0,0 +1,166 @@
+import { Entity } from '../Entity';
+
+/**
+ * 实体缓存管理器
+ *
+ * 负责管理 EntitySystem 中的实体缓存，提供帧缓存和持久缓存两级缓存机制。
+ * 使用面向对象设计，将数据和行为封装在类中。
+ *
+ * @example
+ * ```typescript
+ * const cache = new EntityCache();
+ * cache.setPersistent(entities);
+ * const cached = cache.getPersistent();
+ * cache.invalidate();
+ * ```
+ */
+export class EntityCache {
+    /**
+     * 帧缓存
+     *
+     * 在update周期内使用，每帧结束后清理
+     */
+    private _frameCache: readonly Entity[] | null = null;
+
+    /**
+     * 持久缓存
+     *
+     * 跨帧使用，直到被显式失效
+     */
+    private _persistentCache: readonly Entity[] | null = null;
+
+    /**
+     * 被跟踪的实体集合
+     *
+     * 用于跟踪哪些实体正在被此系统处理
+     */
+    private _trackedEntities: Set<Entity> = new Set();
+
+    /**
+     * 获取帧缓存
+     */
+    public getFrame(): readonly Entity[] | null {
+        return this._frameCache;
+    }
+
+    /**
+     * 设置帧缓存
+     *
+     * @param entities 要缓存的实体列表
+     */
+    public setFrame(entities: readonly Entity[]): void {
+        this._frameCache = entities;
+    }
+
+    /**
+     * 获取持久缓存
+     */
+    public getPersistent(): readonly Entity[] | null {
+        return this._persistentCache;
+    }
+
+    /**
+     * 设置持久缓存
+     *
+     * @param entities 要缓存的实体列表
+     */
+    public setPersistent(entities: readonly Entity[]): void {
+        this._persistentCache = entities;
+    }
+
+    /**
+     * 获取被跟踪的实体集合
+     */
+    public getTracked(): ReadonlySet<Entity> {
+        return this._trackedEntities;
+    }
+
+    /**
+     * 添加被跟踪的实体
+     *
+     * @param entity 要跟踪的实体
+     */
+    public addTracked(entity: Entity): void {
+        this._trackedEntities.add(entity);
+    }
+
+    /**
+     * 移除被跟踪的实体
+     *
+     * @param entity 要移除的实体
+     */
+    public removeTracked(entity: Entity): void {
+        this._trackedEntities.delete(entity);
+    }
+
+    /**
+     * 检查实体是否被跟踪
+     *
+     * @param entity 要检查的实体
+     */
+    public isTracked(entity: Entity): boolean {
+        return this._trackedEntities.has(entity);
+    }
+
+    /**
+     * 使持久缓存失效
+     *
+     * 当实体变化时调用，强制下次查询时重新计算
+     */
+    public invalidate(): void {
+        this._persistentCache = null;
+    }
+
+    /**
+     * 清除帧缓存
+     *
+     * 在每帧结束时调用
+     */
+    public clearFrame(): void {
+        this._frameCache = null;
+    }
+
+    /**
+     * 清除所有缓存
+     *
+     * 在系统重置或销毁时调用
+     */
+    public clearAll(): void {
+        this._frameCache = null;
+        this._persistentCache = null;
+        this._trackedEntities.clear();
+    }
+
+    /**
+     * 检查是否有有效的持久缓存
+     */
+    public hasPersistent(): boolean {
+        return this._persistentCache !== null;
+    }
+
+    /**
+     * 检查是否有有效的帧缓存
+     */
+    public hasFrame(): boolean {
+        return this._frameCache !== null;
+    }
+
+    /**
+     * 获取缓存统计信息
+     */
+    public getStats(): {
+        hasFrame: boolean;
+        hasPersistent: boolean;
+        trackedCount: number;
+        frameEntityCount: number;
+        persistentEntityCount: number;
+    } {
+        return {
+            hasFrame: this._frameCache !== null,
+            hasPersistent: this._persistentCache !== null,
+            trackedCount: this._trackedEntities.size,
+            frameEntityCount: this._frameCache?.length ?? 0,
+            persistentEntityCount: this._persistentCache?.length ?? 0
+        };
+    }
+}