CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

响应式查询

Browse Source
This commit is contained in:
YHH
2025-10-11 18:31:20 +08:00
parent 701f538e57
commit 23d81bca35
5 changed files with 1343 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
packages/core/src/ECS/Core/QuerySystem.ts
View File

@@ -6,6 +6,7 @@ import { createLogger } from '../../Utils/Logger';
import { getComponentTypeName } from '../Decorators';
import { Archetype, ArchetypeSystem } from './ArchetypeSystem';
import { ComponentTypeManager } from "../Utils";
import { ReactiveQuery, ReactiveQueryConfig } from './ReactiveQuery';
/**
* 查询条件类型
@@ -133,6 +134,7 @@ export class QuerySystem {
public setEntities(entities: Entity[]): void {
this.entities = entities;
this.clearQueryCache();
this.clearReactiveQueries();
this.rebuildIndexes();
}
@@ -152,6 +154,8 @@ export class QuerySystem {
this.archetypeSystem.addEntity(entity);
// 通知响应式查询
this.notifyReactiveQueriesEntityAdded(entity);
// 只有在非延迟模式下才立即清理缓存
if (!deferCacheClear) {
@@ -240,6 +244,9 @@ export class QuerySystem {
this.archetypeSystem.removeEntity(entity);
// 通知响应式查询
this.notifyReactiveQueriesEntityRemoved(entity);
this.clearQueryCache();
// 更新版本号
@@ -270,6 +277,9 @@ export class QuerySystem {
// 重新添加实体到索引（基于新的组件状态）
this.addEntityToIndexes(entity);
// 通知响应式查询
this.notifyReactiveQueriesEntityChanged(entity);
// 清理查询缓存，因为实体组件状态已改变
this.clearQueryCache();
@@ -359,7 +369,7 @@ export class QuerySystem {
* 查询包含所有指定组件的实体
*
* 返回同时包含所有指定组件类型的实体列表。
* 系统会自动选择最高效的查询策略，包括索引查找和缓存机制。
* 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
*
* @param componentTypes 要查询的组件类型列表
* @returns 查询结果，包含匹配的实体和性能信息
@@ -375,38 +385,20 @@ export class QuerySystem {
const startTime = performance.now();
this.queryStats.totalQueries++;
// 生成缓存键
const cacheKey = this.generateCacheKey('all', componentTypes);
// 使用内部响应式查询作为智能缓存
const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.ALL, componentTypes);
// 检查缓存
const cached = this.getFromCache(cacheKey);
if (cached) {
// 从响应式查询获取结果(永远是最新的)
const entities = reactiveQuery.getEntities();
// 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
this.queryStats.cacheHits++;
return {
entities: cached,
count: cached.length,
executionTime: performance.now() - startTime,
fromCache: true
};
}
this.queryStats.archetypeHits++;
const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'AND');
const entities: Entity[] = [];
for (const archetype of archetypeResult.archetypes) {
for (const entity of archetype.entities) {
entities.push(entity);
}
}
this.addToCache(cacheKey, entities);
return {
entities,
count: entities.length,
executionTime: performance.now() - startTime,
fromCache: false
fromCache: true
};
}
@@ -438,7 +430,7 @@ export class QuerySystem {
* 查询包含任意指定组件的实体
*
* 返回包含任意一个指定组件类型的实体列表。
* 使用集合合并算法确保高效的查询性能。
* 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
*
* @param componentTypes 要查询的组件类型列表
* @returns 查询结果，包含匹配的实体和性能信息
@@ -454,48 +446,28 @@ export class QuerySystem {
const startTime = performance.now();
this.queryStats.totalQueries++;
const cacheKey = this.generateCacheKey('any', componentTypes);
// 使用内部响应式查询作为智能缓存
const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.ANY, componentTypes);
// 检查缓存
const cached = this.getFromCache(cacheKey);
if (cached) {
// 从响应式查询获取结果(永远是最新的)
const entities = reactiveQuery.getEntities();
// 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
this.queryStats.cacheHits++;
return {
entities: cached,
count: cached.length,
entities,
count: entities.length,
executionTime: performance.now() - startTime,
fromCache: true
};
}
this.queryStats.archetypeHits++;
const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'OR');
const entities = this.acquireResultArray();
for (const archetype of archetypeResult.archetypes) {
for (const entity of archetype.entities) {
entities.push(entity);
}
}
const frozenEntities = [...entities];
this.releaseResultArray(entities);
this.addToCache(cacheKey, frozenEntities);
return {
entities: frozenEntities,
count: frozenEntities.length,
executionTime: performance.now() - startTime,
fromCache: false
};
}
/**
* 查询不包含任何指定组件的实体
*
* 返回不包含任何指定组件类型的实体列表。
* 适用于排除特定类型实体的查询场景。
* 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
*
* @param componentTypes 要排除的组件类型列表
* @returns 查询结果，包含匹配的实体和性能信息
@@ -511,32 +483,20 @@ export class QuerySystem {
const startTime = performance.now();
this.queryStats.totalQueries++;
const cacheKey = this.generateCacheKey('none', componentTypes);
// 使用内部响应式查询作为智能缓存
const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.NONE, componentTypes);
// 检查缓存
const cached = this.getFromCache(cacheKey);
if (cached) {
// 从响应式查询获取结果(永远是最新的)
const entities = reactiveQuery.getEntities();
// 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
this.queryStats.cacheHits++;
return {
entities: cached,
count: cached.length,
executionTime: performance.now() - startTime,
fromCache: true
};
}
const mask = this.createComponentMask(componentTypes);
const entities = this.entities.filter(entity =>
BitMask64Utils.hasNone(entity.componentMask, mask)
);
this.addToCache(cacheKey, entities);
return {
entities,
count: entities.length,
executionTime: performance.now() - startTime,
fromCache: false
fromCache: true
};
}
@@ -759,6 +719,20 @@ export class QuerySystem {
this.componentMaskCache.clear();
}
/**
* 清除所有响应式查询
*
* 销毁所有响应式查询实例并清理索引
* 通常在setEntities时调用以确保缓存一致性
*/
private clearReactiveQueries(): void {
for (const query of this._reactiveQueries.values()) {
query.dispose();
}
this._reactiveQueries.clear();
this._reactiveQueriesByComponent.clear();
}
/**
* 高效的缓存键生成
*/
@@ -897,6 +871,181 @@ export class QuerySystem {
public getEntityArchetype(entity: Entity): Archetype | undefined {
return this.archetypeSystem.getEntityArchetype(entity);
}
// ============================================================
// 响应式查询支持(内部智能缓存)
// ============================================================
/**
* 响应式查询集合(内部使用,作为智能缓存)
* 传统查询API(queryAll/queryAny/queryNone)内部自动使用响应式查询优化性能
*/
private _reactiveQueries: Map<string, ReactiveQuery> = new Map();
/**
* 按组件类型索引的响应式查询
* 用于快速定位哪些查询关心某个组件类型
*/
private _reactiveQueriesByComponent: Map<ComponentType, Set<ReactiveQuery>> = new Map();
/**
* 获取或创建内部响应式查询(作为智能缓存)
*
* @param queryType 查询类型
* @param componentTypes 组件类型列表
* @returns 响应式查询实例
*/
private getOrCreateReactiveQuery(
queryType: QueryConditionType,
componentTypes: ComponentType[]
): ReactiveQuery {
// 生成缓存键(与传统缓存键格式一致)
const cacheKey = this.generateCacheKey(queryType, componentTypes);
// 检查是否已存在响应式查询
let reactiveQuery = this._reactiveQueries.get(cacheKey);
if (!reactiveQuery) {
// 创建查询条件
const mask = this.createComponentMask(componentTypes);
const condition: QueryCondition = {
type: queryType,
componentTypes,
mask
};
// 创建响应式查询(禁用批量模式,保持实时性)
reactiveQuery = new ReactiveQuery(condition, {
enableBatchMode: false,
debug: false
});
// 初始化查询结果(使用传统方式获取初始数据)
const initialEntities = this.executeTraditionalQuery(queryType, componentTypes);
reactiveQuery.initializeWith(initialEntities);
// 注册响应式查询
this._reactiveQueries.set(cacheKey, reactiveQuery);
// 为每个组件类型注册索引
for (const type of componentTypes) {
let queries = this._reactiveQueriesByComponent.get(type);
if (!queries) {
queries = new Set();
this._reactiveQueriesByComponent.set(type, queries);
}
queries.add(reactiveQuery);
}
this._logger.debug(`创建内部响应式查询缓存: ${cacheKey}`);
}
return reactiveQuery;
}
/**
* 执行传统查询(内部使用,用于响应式查询初始化)
*
* @param queryType 查询类型
* @param componentTypes 组件类型列表
* @returns 匹配的实体列表
*/
private executeTraditionalQuery(
queryType: QueryConditionType,
componentTypes: ComponentType[]
): Entity[] {
switch (queryType) {
case QueryConditionType.ALL: {
const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'AND');
const entities: Entity[] = [];
for (const archetype of archetypeResult.archetypes) {
for (const entity of archetype.entities) {
entities.push(entity);
}
}
return entities;
}
case QueryConditionType.ANY: {
const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'OR');
const entities: Entity[] = [];
for (const archetype of archetypeResult.archetypes) {
for (const entity of archetype.entities) {
entities.push(entity);
}
}
return entities;
}
case QueryConditionType.NONE: {
const mask = this.createComponentMask(componentTypes);
return this.entities.filter(entity =>
BitMask64Utils.hasNone(entity.componentMask, mask)
);
}
default:
return [];
}
}
/**
* 通知所有响应式查询实体已添加
*
* 使用组件类型索引,只通知关心该实体组件的查询
*
* @param entity 添加的实体
*/
private notifyReactiveQueriesEntityAdded(entity: Entity): void {
if (this._reactiveQueries.size === 0) return;
const notified = new Set<ReactiveQuery>();
for (const component of entity.components) {
const componentType = component.constructor as ComponentType;
const queries = this._reactiveQueriesByComponent.get(componentType);
if (queries) {
for (const query of queries) {
if (!notified.has(query)) {
query.notifyEntityAdded(entity);
notified.add(query);
}
}
}
}
}
/**
* 通知所有响应式查询实体已移除
*
* 使用组件类型索引,只通知关心该实体组件的查询
* 注意:实体移除时可能已经清空了components,所以需要通知所有查询让它们自己判断
*
* @param entity 移除的实体
*/
private notifyReactiveQueriesEntityRemoved(entity: Entity): void {
if (this._reactiveQueries.size === 0) return;
for (const query of this._reactiveQueries.values()) {
query.notifyEntityRemoved(entity);
}
}
/**
* 通知所有响应式查询实体已变化
*
* 实体组件变化时需要通知所有查询,因为:
* 1. 可能从匹配变为不匹配(移除组件)
* 2. 可能从不匹配变为匹配(添加组件)
* 让每个查询自己判断是否需要响应
*
* @param entity 变化的实体
*/
private notifyReactiveQueriesEntityChanged(entity: Entity): void {
if (this._reactiveQueries.size === 0) return;
for (const query of this._reactiveQueries.values()) {
query.notifyEntityChanged(entity);
}
}
}
/**

458
packages/core/src/ECS/Core/ReactiveQuery.ts Normal file
View File

@@ -0,0 +1,458 @@
import { Entity } from '../Entity';
import { QueryCondition, QueryConditionType } from './QuerySystem';
import { BitMask64Utils } from '../Utils/BigIntCompatibility';
import { createLogger } from '../../Utils/Logger';
const logger = createLogger('ReactiveQuery');
/**
* 响应式查询变化类型
*/
export enum ReactiveQueryChangeType {
/** 实体添加到查询结果 */
ADDED = 'added',
/** 实体从查询结果移除 */
REMOVED = 'removed',
/** 查询结果批量更新 */
BATCH_UPDATE = 'batch_update'
}
/**
* 响应式查询变化事件
*/
export interface ReactiveQueryChange {
/** 变化类型 */
type: ReactiveQueryChangeType;
/** 变化的实体 */
entity?: Entity;
/** 批量变化的实体 */
entities?: readonly Entity[];
/** 新增的实体列表(仅batch_update时有效) */
added?: readonly Entity[];
/** 移除的实体列表(仅batch_update时有效) */
removed?: readonly Entity[];
}
/**
* 响应式查询监听器
*/
export type ReactiveQueryListener = (change: ReactiveQueryChange) => void;
/**
* 响应式查询配置
*/
export interface ReactiveQueryConfig {
/** 是否启用批量模式(减少通知频率) */
enableBatchMode?: boolean;
/** 批量模式的延迟时间(毫秒) */
batchDelay?: number;
/** 调试模式 */
debug?: boolean;
}
/**
* 响应式查询类
*
* 提供基于事件驱动的实体查询机制,只在实体/组件真正变化时触发通知。
*
* 核心特性:
* - 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 {
/** 当前查询结果 */
private _entities: Entity[] = [];
/** 实体ID集合,用于快速查找 */
private _entityIdSet: Set<number> = new Set();
/** 查询条件 */
private readonly _condition: QueryCondition;
/** 监听器列表 */
private _listeners: ReactiveQueryListener[] = [];
/** 配置 */
private readonly _config: ReactiveQueryConfig;
/** 批量变化缓存 */
private _batchChanges: {
added: Entity[];
removed: Entity[];
timer: ReturnType<typeof setTimeout> | null;
};
/** 查询ID(用于调试) */
private readonly _id: string;
/** 是否已激活 */
private _active: boolean = true;
constructor(condition: QueryCondition, config: ReactiveQueryConfig = {}) {
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
*/
private generateQueryId(): string {
const typeStr = this._condition.type;
const componentsStr = this._condition.componentTypes
.map(t => t.name)
.sort()
.join(',');
return `${typeStr}:${componentsStr}`;
}
/**
* 订阅查询变化
*
* @param listener 监听器函数
* @returns 取消订阅的函数
*/
public subscribe(listener: ReactiveQueryListener): () => void {
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);
}
};
}
/**
* 取消所有订阅
*/
public unsubscribeAll(): void {
this._listeners.length = 0;
}
/**
* 获取当前查询结果
*/
public getEntities(): readonly Entity[] {
return this._entities;
}
/**
* 获取查询结果数量
*/
public get count(): number {
return this._entities.length;
}
/**
* 检查实体是否匹配查询条件
*
* @param entity 要检查的实体
* @returns 是否匹配
*/
public matches(entity: Entity): boolean {
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 添加的实体
*/
public notifyEntityAdded(entity: Entity): void {
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);
// 通知监听器
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 移除的实体
*/
public notifyEntityRemoved(entity: Entity): void {
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);
// 通知监听器
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 变化的实体
*/
public notifyEntityChanged(entity: Entity): void {
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 初始实体列表
*/
public initializeWith(entities: readonly Entity[]): void {
// 清空现有结果
this._entities.length = 0;
this._entityIdSet.clear();
// 筛选匹配的实体
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} 个实体`);
}
}
/**
* 添加到批量变化缓存
*/
private addToBatch(type: 'added' | 'removed', entity: Entity): void {
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);
}
}
/**
* 刷新批量变化
*/
private flushBatchChanges(): void {
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}`);
}
}
/**
* 通知所有监听器
*/
private notifyListeners(change: ReactiveQueryChange): void {
for (const listener of this._listeners) {
try {
listener(change);
} catch (error) {
logger.error(`ReactiveQuery ${this._id}: 监听器执行出错`, error);
}
}
}
/**
* 暂停响应式查询
*
* 暂停后不再响应实体变化,但可以继续获取当前结果
*/
public pause(): void {
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;
}
/**
* 恢复响应式查询
*/
public resume(): void {
this._active = true;
}
/**
* 销毁响应式查询
*
* 释放所有资源,清空监听器和结果集
*/
public dispose(): void {
this.pause();
this.unsubscribeAll();
this._entities.length = 0;
this._entityIdSet.clear();
if (this._config.debug) {
logger.debug(`ReactiveQuery ${this._id}: 已销毁`);
}
}
/**
* 获取查询条件
*/
public get condition(): QueryCondition {
return this._condition;
}
/**
* 获取查询ID
*/
public get id(): string {
return this._id;
}
/**
* 检查是否激活
*/
public get active(): boolean {
return this._active;
}
/**
* 获取监听器数量
*/
public get listenerCount(): number {
return this._listeners.length;
}
}

2
packages/core/src/ECS/index.ts
View File

@@ -16,3 +16,5 @@ export * from './Core/StorageDecorators';
export * from './Serialization';
export { ReferenceTracker, getSceneByEntityId } from './Core/ReferenceTracker';
export type { EntityRefRecord } from './Core/ReferenceTracker';
export { ReactiveQuery, ReactiveQueryChangeType } from './Core/ReactiveQuery';
export type { ReactiveQueryChange, ReactiveQueryListener, ReactiveQueryConfig } from './Core/ReactiveQuery';

471
packages/core/tests/ECS/Core/ReactiveQuery.test.ts Normal file
View File

@@ -0,0 +1,471 @@
import { Scene } from '../../../src/ECS/Scene';
import { Component } from '../../../src/ECS/Component';
import { ReactiveQueryChangeType } from '../../../src/ECS/Core/ReactiveQuery';
class PositionComponent extends Component {
public x: number = 0;
public y: number = 0;
constructor(x: number = 0, y: number = 0) {
super();
this.x = x;
this.y = y;
}
public reset(): void {
this.x = 0;
this.y = 0;
}
}
class VelocityComponent extends Component {
public vx: number = 0;
public vy: number = 0;
constructor(vx: number = 0, vy: number = 0) {
super();
this.vx = vx;
this.vy = vy;
}
public reset(): void {
this.vx = 0;
this.vy = 0;
}
}
class HealthComponent extends Component {
public hp: number = 100;
constructor(hp: number = 100) {
super();
this.hp = hp;
}
public reset(): void {
this.hp = 100;
}
}
describe('ReactiveQuery', () => {
let scene: Scene;
beforeEach(() => {
scene = new Scene();
});
afterEach(() => {
scene.end();
jest.clearAllTimers();
});
describe('基础功能', () => {
test('应该能够创建响应式查询', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent]);
expect(query).toBeDefined();
expect(query.count).toBe(0);
expect(query.getEntities()).toEqual([]);
});
test('应该能够初始化查询结果', () => {
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new PositionComponent(10, 20));
const entity2 = scene.createEntity('entity2');
entity2.addComponent(new PositionComponent(30, 40));
const query = scene.querySystem.createReactiveQuery([PositionComponent]);
expect(query.count).toBe(2);
expect(query.getEntities()).toContain(entity1);
expect(query.getEntities()).toContain(entity2);
});
test('应该能够销毁响应式查询', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent]);
scene.querySystem.destroyReactiveQuery(query);
expect(query.active).toBe(false);
});
});
describe('实体添加通知', () => {
test('应该在添加匹配实体时通知订阅者', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
expect(changes).toHaveLength(1);
expect(changes[0].type).toBe(ReactiveQueryChangeType.ADDED);
expect(changes[0].entity).toBe(entity);
});
test('不应该在添加不匹配实体时通知订阅者', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
const entity = scene.createEntity('test');
entity.addComponent(new HealthComponent(100));
expect(changes).toHaveLength(0);
});
test('批量模式应该合并通知', (done) => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: true,
batchDelay: 10
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new PositionComponent(10, 20));
const entity2 = scene.createEntity('entity2');
entity2.addComponent(new PositionComponent(30, 40));
setTimeout(() => {
expect(changes).toHaveLength(1);
expect(changes[0].type).toBe(ReactiveQueryChangeType.BATCH_UPDATE);
expect(changes[0].added).toHaveLength(2);
done();
}, 50);
});
});
describe('实体移除通知', () => {
test('应该在移除匹配实体时通知订阅者', () => {
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
scene.destroyEntities([entity]);
expect(changes).toHaveLength(1);
expect(changes[0].type).toBe(ReactiveQueryChangeType.REMOVED);
expect(changes[0].entity).toBe(entity);
});
test('不应该在移除不匹配实体时通知订阅者', () => {
const entity = scene.createEntity('test');
entity.addComponent(new HealthComponent(100));
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
scene.destroyEntities([entity]);
expect(changes).toHaveLength(0);
});
});
describe('实体变化通知', () => {
test('应该在实体从不匹配变为匹配时通知添加', () => {
const entity = scene.createEntity('test');
entity.addComponent(new HealthComponent(100));
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
entity.addComponent(new PositionComponent(10, 20));
expect(changes).toHaveLength(1);
expect(changes[0].type).toBe(ReactiveQueryChangeType.ADDED);
expect(changes[0].entity).toBe(entity);
});
test('应该在实体从匹配变为不匹配时通知移除', () => {
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
const positionComp = entity.getComponent(PositionComponent);
if (positionComp) {
entity.removeComponent(positionComp);
}
expect(changes).toHaveLength(1);
expect(changes[0].type).toBe(ReactiveQueryChangeType.REMOVED);
expect(changes[0].entity).toBe(entity);
});
test('应该在实体组件变化但仍匹配时不通知', () => {
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
entity.addComponent(new HealthComponent(100));
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
const healthComp = entity.getComponent(HealthComponent);
if (healthComp) {
entity.removeComponent(healthComp);
}
expect(changes).toHaveLength(0);
});
});
describe('多组件查询', () => {
test('应该正确匹配多个组件', () => {
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new PositionComponent(10, 20));
entity1.addComponent(new VelocityComponent(1, 1));
const entity2 = scene.createEntity('entity2');
entity2.addComponent(new PositionComponent(30, 40));
const query = scene.querySystem.createReactiveQuery([PositionComponent, VelocityComponent]);
expect(query.count).toBe(1);
expect(query.getEntities()).toContain(entity1);
expect(query.getEntities()).not.toContain(entity2);
});
test('应该在实体满足所有组件时通知添加', () => {
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
const query = scene.querySystem.createReactiveQuery([PositionComponent, VelocityComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
entity.addComponent(new VelocityComponent(1, 1));
expect(changes).toHaveLength(1);
expect(changes[0].type).toBe(ReactiveQueryChangeType.ADDED);
expect(changes[0].entity).toBe(entity);
});
});
describe('订阅管理', () => {
test('应该能够取消订阅', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
const unsubscribe = query.subscribe((change) => {
changes.push(change);
});
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new PositionComponent(10, 20));
expect(changes).toHaveLength(1);
unsubscribe();
const entity2 = scene.createEntity('entity2');
entity2.addComponent(new PositionComponent(30, 40));
expect(changes).toHaveLength(1);
});
test('应该能够取消所有订阅', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes1: any[] = [];
query.subscribe((change) => {
changes1.push(change);
});
const changes2: any[] = [];
query.subscribe((change) => {
changes2.push(change);
});
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new PositionComponent(10, 20));
expect(changes1).toHaveLength(1);
expect(changes2).toHaveLength(1);
query.unsubscribeAll();
const entity2 = scene.createEntity('entity2');
entity2.addComponent(new PositionComponent(30, 40));
expect(changes1).toHaveLength(1);
expect(changes2).toHaveLength(1);
});
test('应该能够暂停和恢复查询', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
query.pause();
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new PositionComponent(10, 20));
expect(changes).toHaveLength(0);
query.resume();
const entity2 = scene.createEntity('entity2');
entity2.addComponent(new PositionComponent(30, 40));
expect(changes).toHaveLength(1);
});
});
describe('性能测试', () => {
test('应该高效处理大量实体变化', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
let changeCount = 0;
query.subscribe(() => {
changeCount++;
});
const startTime = performance.now();
for (let i = 0; i < 1000; i++) {
const entity = scene.createEntity(`entity${i}`);
entity.addComponent(new PositionComponent(i, i));
}
const endTime = performance.now();
expect(changeCount).toBe(1000);
expect(endTime - startTime).toBeLessThan(100);
});
test('批量模式应该减少通知次数', (done) => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: true,
batchDelay: 10
});
let changeCount = 0;
query.subscribe(() => {
changeCount++;
});
for (let i = 0; i < 100; i++) {
const entity = scene.createEntity(`entity${i}`);
entity.addComponent(new PositionComponent(i, i));
}
setTimeout(() => {
expect(changeCount).toBe(1);
done();
}, 50);
});
});
describe('边界情况', () => {
test('应该处理重复添加同一实体', () => {
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
scene.querySystem.addEntity(entity);
scene.querySystem.addEntity(entity);
expect(changes).toHaveLength(0);
});
test('应该处理查询结果为空的情况', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent]);
expect(query.count).toBe(0);
expect(query.getEntities()).toEqual([]);
});
test('应该在销毁后停止通知', () => {
const query = scene.querySystem.createReactiveQuery([PositionComponent], {
enableBatchMode: false
});
const changes: any[] = [];
query.subscribe((change) => {
changes.push(change);
});
query.dispose();
const entity = scene.createEntity('test');
entity.addComponent(new PositionComponent(10, 20));
expect(changes).toHaveLength(0);
});
});
});

173
packages/core/tests/ECS/Core/ReactiveQueryIntegration.test.ts Normal file
View File

@@ -0,0 +1,173 @@
import { Scene } from '../../../src/ECS/Scene';
import { Component } from '../../../src/ECS/Component';
import { EntitySystem } from '../../../src/ECS/Systems/EntitySystem';
import { Matcher } from '../../../src/ECS/Utils/Matcher';
import { ReactiveQuery, ReactiveQueryChangeType } from '../../../src/ECS/Core/ReactiveQuery';
class TransformComponent extends Component {
public x: number = 0;
public y: number = 0;
constructor(x: number = 0, y: number = 0) {
super();
this.x = x;
this.y = y;
}
public reset(): void {
this.x = 0;
this.y = 0;
}
}
class RenderableComponent extends Component {
public visible: boolean = true;
public reset(): void {
this.visible = true;
}
}
class ReactiveRenderSystem extends EntitySystem {
private reactiveQuery!: ReactiveQuery;
private addedCount = 0;
private removedCount = 0;
public override initialize(): void {
super.initialize();
if (this.scene) {
this.reactiveQuery = this.scene.querySystem.createReactiveQuery(
[TransformComponent, RenderableComponent],
{
enableBatchMode: false
}
);
this.reactiveQuery.subscribe((change) => {
if (change.type === ReactiveQueryChangeType.ADDED) {
this.addedCount++;
} else if (change.type === ReactiveQueryChangeType.REMOVED) {
this.removedCount++;
}
});
}
}
public getAddedCount(): number {
return this.addedCount;
}
public getRemovedCount(): number {
return this.removedCount;
}
public getQueryEntities() {
return this.reactiveQuery.getEntities();
}
public override dispose(): void {
if (this.reactiveQuery && this.scene) {
this.scene.querySystem.destroyReactiveQuery(this.reactiveQuery);
}
}
}
describe('ReactiveQuery集成测试', () => {
let scene: Scene;
let renderSystem: ReactiveRenderSystem;
beforeEach(() => {
scene = new Scene();
renderSystem = new ReactiveRenderSystem(Matcher.empty());
scene.addEntityProcessor(renderSystem);
});
afterEach(() => {
scene.end();
jest.clearAllTimers();
});
describe('EntitySystem集成', () => {
test('应该在实体添加时收到通知', () => {
const entity1 = scene.createEntity('entity1');
entity1.addComponent(new TransformComponent(10, 20));
entity1.addComponent(new RenderableComponent());
expect(renderSystem.getAddedCount()).toBe(1);
expect(renderSystem.getQueryEntities()).toContain(entity1);
});
test('应该在实体移除时收到通知', () => {
const entity = scene.createEntity('entity');
entity.addComponent(new TransformComponent(10, 20));
entity.addComponent(new RenderableComponent());
expect(renderSystem.getAddedCount()).toBe(1);
scene.destroyEntities([entity]);
expect(renderSystem.getRemovedCount()).toBe(1);
expect(renderSystem.getQueryEntities()).not.toContain(entity);
});
test('应该在组件变化时收到正确通知', () => {
const entity = scene.createEntity('entity');
entity.addComponent(new TransformComponent(10, 20));
expect(renderSystem.getAddedCount()).toBe(0);
entity.addComponent(new RenderableComponent());
expect(renderSystem.getAddedCount()).toBe(1);
expect(renderSystem.getQueryEntities()).toContain(entity);
const renderComp = entity.getComponent(RenderableComponent);
if (renderComp) {
entity.removeComponent(renderComp);
}
expect(renderSystem.getRemovedCount()).toBe(1);
expect(renderSystem.getQueryEntities()).not.toContain(entity);
});
test('应该高效处理批量实体变化', () => {
const entities = [];
for (let i = 0; i < 100; i++) {
const entity = scene.createEntity(`entity${i}`);
entity.addComponent(new TransformComponent(i, i));
entity.addComponent(new RenderableComponent());
entities.push(entity);
}
expect(renderSystem.getAddedCount()).toBe(100);
expect(renderSystem.getQueryEntities().length).toBe(100);
scene.destroyEntities(entities);
expect(renderSystem.getRemovedCount()).toBe(100);
expect(renderSystem.getQueryEntities().length).toBe(0);
});
});
describe('性能对比', () => {
test('响应式查询应该避免每帧重复查询', () => {
for (let i = 0; i < 50; i++) {
const entity = scene.createEntity(`entity${i}`);
entity.addComponent(new TransformComponent(i, i));
entity.addComponent(new RenderableComponent());
}
expect(renderSystem.getAddedCount()).toBe(50);
const initialCount = renderSystem.getAddedCount();
for (let i = 0; i < 100; i++) {
scene.update();
}
expect(renderSystem.getAddedCount()).toBe(initialCount);
});
});
});