Class: QuerySystem

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:45

高性能实体查询系统

提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。

Example

typescript

// 查询所有包含Position和Velocity组件的实体
const movingEntities = querySystem.queryAll(PositionComponent, VelocityComponent);

// 查询特定标签的实体
const playerEntities = querySystem.queryByTag(PLAYER_TAG);

Constructors

Constructor

new QuerySystem(): QuerySystem

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:69

Returns

QuerySystem

Accessors

version

Get Signature

get version(): number

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:843

获取当前版本号（用于缓存失效）

Returns

number

Methods

setEntities()

setEntities(entities): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:86

设置实体列表并重建索引

当实体集合发生大规模变化时调用此方法。系统将重新构建所有索引以确保查询性能。

Parameters

entities

Entity[]

新的实体列表

Returns

void

addEntity()

addEntity(entity, deferCacheClear): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:102

添加单个实体到查询系统

将新实体添加到查询系统中，并自动更新相关索引。为了提高批量添加性能，可以延迟缓存清理。

Parameters

entity

Entity

要添加的实体

deferCacheClear

boolean = false

是否延迟缓存清理（用于批量操作）

Returns

void

addEntities()

addEntities(entities): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:130

批量添加实体

高效地批量添加多个实体，减少缓存清理次数。使用Set来避免O(n)的重复检查。

Parameters

entities

Entity[]

要添加的实体列表

Returns

void

addEntitiesUnchecked()

addEntitiesUnchecked(entities): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:164

批量添加实体（无重复检查版本）

假设所有实体都是新的，跳过重复检查以获得最大性能。仅在确保没有重复实体时使用。

Parameters

entities

Entity[]

要添加的实体列表

Returns

void

removeEntity()

removeEntity(entity): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:191

从查询系统移除实体

从查询系统中移除指定实体，并清理相关索引。

Parameters

entity

Entity

要移除的实体

Returns

void

updateEntity()

updateEntity(entity): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:223

更新实体在查询系统中的索引

当实体的组件组合发生变化时调用此方法，高效地更新实体在查询系统中的索引。

Parameters

entity

Entity

要更新的实体

Returns

void

queryAll()

queryAll(...componentTypes): QueryResult

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:342

查询包含所有指定组件的实体

返回同时包含所有指定组件类型的实体列表。内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。

Parameters

componentTypes

...ComponentType[]

要查询的组件类型列表

Returns

QueryResult

查询结果，包含匹配的实体和性能信息

Example

typescript

// 查询同时具有位置和速度组件的实体
const result = querySystem.queryAll(PositionComponent, VelocityComponent);
logger.info(`找到 ${result.count} 个移动实体`);

queryAny()

queryAny(...componentTypes): QueryResult

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:379

查询包含任意指定组件的实体

返回包含任意一个指定组件类型的实体列表。内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。

Parameters

componentTypes

...ComponentType[]

要查询的组件类型列表

Returns

QueryResult

查询结果，包含匹配的实体和性能信息

Example

typescript

// 查询具有武器或护甲组件的实体
const result = querySystem.queryAny(WeaponComponent, ArmorComponent);
logger.info(`找到 ${result.count} 个装备实体`);

queryNone()

queryNone(...componentTypes): QueryResult

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:416

查询不包含任何指定组件的实体

返回不包含任何指定组件类型的实体列表。内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。

Parameters

componentTypes

...ComponentType[]

要排除的组件类型列表

Returns

QueryResult

查询结果，包含匹配的实体和性能信息

Example

typescript

// 查询不具有AI和玩家控制组件的实体（如静态物体）
const result = querySystem.queryNone(AIComponent, PlayerControlComponent);
logger.info(`找到 ${result.count} 个静态实体`);

queryByTag()

queryByTag(tag): QueryResult

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:452

按标签查询实体

返回具有指定标签的所有实体。标签查询使用专用索引，具有很高的查询性能。

Parameters

tag

number

要查询的标签值

Returns

QueryResult

查询结果，包含匹配的实体和性能信息

Example

typescript

// 查询所有玩家实体
const players = querySystem.queryByTag(PLAYER_TAG);

queryByName()

queryByName(name): QueryResult

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:500

按名称查询实体

返回具有指定名称的所有实体。名称查询使用专用索引，适用于查找特定的命名实体。

Parameters

name

string

要查询的实体名称

Returns

QueryResult

查询结果，包含匹配的实体和性能信息

Example

typescript

// 查找名为"Player"的实体
const player = querySystem.queryByName("Player");

queryByComponent()

queryByComponent<T>(componentType): QueryResult

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:548

按单个组件类型查询实体

返回包含指定组件类型的所有实体。这是最基础的查询方法，具有最高的查询性能。

Type Parameters

T

T extends Component

Parameters

componentType

ComponentType<T>

要查询的组件类型

Returns

QueryResult

查询结果，包含匹配的实体和性能信息

Example

typescript

// 查询所有具有位置组件的实体
const entitiesWithPosition = querySystem.queryByComponent(PositionComponent);

clearCache()

clearCache(): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:702

清理查询缓存

用于外部调用清理缓存，通常在批量操作后使用。注意:此方法也会清理响应式查询缓存

Returns

void

createReactiveQuery()

createReactiveQuery(componentTypes, config?): ReactiveQuery

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:731

创建响应式查询

响应式查询会自动跟踪实体/组件的变化,并通过事件通知订阅者。适合需要实时响应实体变化的场景(如UI更新、AI系统等)。

Parameters

componentTypes

ComponentType[]

查询的组件类型列表

config?

ReactiveQueryConfig

可选的查询配置

Returns

ReactiveQuery

响应式查询实例

Example

typescript

const query = querySystem.createReactiveQuery([Position, Velocity], {
    enableBatchMode: true,
    batchDelay: 16
});

query.subscribe((change) => {
    if (change.type === ReactiveQueryChangeType.ADDED) {
        console.log('新实体:', change.entity);
    }
});

destroyReactiveQuery()

destroyReactiveQuery(query): void

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:778

销毁响应式查询

清理查询占用的资源,包括监听器和实体引用。销毁后的查询不应再被使用。

Parameters

query

ReactiveQuery

要销毁的响应式查询

Returns

void

Example

typescript

const query = querySystem.createReactiveQuery([Position, Velocity]);
// ... 使用查询
querySystem.destroyReactiveQuery(query);

getAllEntities()

getAllEntities(): readonly Entity[]

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:850

获取所有实体

Returns

readonly Entity[]

getStats()

getStats(): object

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:862

获取系统统计信息

返回查询系统的详细统计信息，包括实体数量、索引状态、查询性能统计等，用于性能监控和调试。

Returns

object

系统统计信息对象

entityCount

entityCount: number

indexStats

indexStats: object

indexStats.componentIndexSize

componentIndexSize: number

indexStats.tagIndexSize

tagIndexSize: number

indexStats.nameIndexSize

nameIndexSize: number

queryStats

queryStats: object

queryStats.totalQueries

totalQueries: number

queryStats.cacheHits

cacheHits: number

queryStats.indexHits

indexHits: number

queryStats.linearScans

linearScans: number

queryStats.archetypeHits

archetypeHits: number

queryStats.dirtyChecks

dirtyChecks: number

queryStats.cacheHitRate

cacheHitRate: string

optimizationStats

optimizationStats: object

optimizationStats.archetypeSystem

archetypeSystem: any

cacheStats

cacheStats: object

cacheStats.size

size: number

cacheStats.hitRate

hitRate: string

getEntityArchetype()

getEntityArchetype(entity): undefined | Archetype

Defined in: packages/core/src/ECS/Core/QuerySystem.ts:922

获取实体所属的原型信息

Parameters

entity

Entity

要查询的实体

Returns

undefined | Archetype

Class: QuerySystem ​

Example ​

Constructors ​

Constructor ​

Returns ​

Accessors ​

version ​

Get Signature ​

Returns ​

Methods ​

setEntities() ​

Parameters ​

entities ​

Returns ​

addEntity() ​

Parameters ​

entity ​

deferCacheClear ​

Returns ​

addEntities() ​

Parameters ​

entities ​

Returns ​

addEntitiesUnchecked() ​

Parameters ​

entities ​

Returns ​

removeEntity() ​

Parameters ​

entity ​

Returns ​

updateEntity() ​

Parameters ​

entity ​

Returns ​

queryAll() ​

Parameters ​

componentTypes ​

Returns ​

Example ​

queryAny() ​

Parameters ​

componentTypes ​

Returns ​

Example ​

queryNone() ​

Parameters ​

componentTypes ​

Returns ​

Example ​

queryByTag() ​

Parameters ​

tag ​

Returns ​

Example ​

queryByName() ​

Parameters ​

name ​

Returns ​

Example ​

queryByComponent() ​

Type Parameters ​

T ​

Parameters ​

componentType ​

Returns ​

Example ​

clearCache() ​

Returns ​

createReactiveQuery() ​

Parameters ​

componentTypes ​

config? ​

Returns ​

Example ​

destroyReactiveQuery() ​

Parameters ​

query ​

Returns ​

Example ​

Class: QuerySystem

Example

Constructors

Constructor

Returns

Accessors

version

Get Signature

Returns

Methods

setEntities()

Parameters

entities

Returns

addEntity()

Parameters

entity

deferCacheClear

Returns

addEntities()

Parameters

entities

Returns

addEntitiesUnchecked()

Parameters

entities

Returns

removeEntity()

Parameters

entity

Returns

updateEntity()

Parameters

entity

Returns

queryAll()

Parameters

componentTypes

Returns

Example

queryAny()

Parameters

componentTypes

Returns

Example

queryNone()

Parameters

componentTypes

Returns

Example

queryByTag()

Parameters

tag

Returns

Example

queryByName()

Parameters

name

Returns

Example

queryByComponent()

Type Parameters

T

Parameters

componentType

Returns

Example

clearCache()

Returns

createReactiveQuery()

Parameters

componentTypes

config?

Returns

Example

destroyReactiveQuery()

Parameters

query

Returns

Example