ECS Framework API / QuerySystem
Class: QuerySystem
Defined in: ECS/Core/QuerySystem.ts:79
高性能实体查询系统
提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。
Example
// 查询所有包含Position和Velocity组件的实体
const movingEntities = querySystem.queryAll(PositionComponent, VelocityComponent);
// 查询特定标签的实体
const playerEntities = querySystem.queryByTag(PLAYER_TAG);Constructors
Constructor
new QuerySystem():
QuerySystem
Defined in: ECS/Core/QuerySystem.ts:107
Returns
QuerySystem
Accessors
version
Get Signature
get version():
number
Defined in: ECS/Core/QuerySystem.ts:935
获取当前版本号（用于缓存失效）
Returns
number
Methods
setEntities()
setEntities(
entities):void
Defined in: ECS/Core/QuerySystem.ts:130
设置实体列表并重建索引
当实体集合发生大规模变化时调用此方法。 系统将重新构建所有索引以确保查询性能。
Parameters
entities
Entity[]
新的实体列表
Returns
void
addEntity()
addEntity(
entity,deferCacheClear):void
Defined in: ECS/Core/QuerySystem.ts:145
添加单个实体到查询系统
将新实体添加到查询系统中，并自动更新相关索引。 为了提高批量添加性能，可以延迟缓存清理。
Parameters
entity
要添加的实体
deferCacheClear
boolean = false
是否延迟缓存清理（用于批量操作）
Returns
void
addEntities()
addEntities(
entities):void
Defined in: ECS/Core/QuerySystem.ts:172
批量添加实体
高效地批量添加多个实体，减少缓存清理次数。 使用Set来避免O(n)的重复检查。
Parameters
entities
Entity[]
要添加的实体列表
Returns
void
addEntitiesUnchecked()
addEntitiesUnchecked(
entities):void
Defined in: ECS/Core/QuerySystem.ts:207
批量添加实体（无重复检查版本）
假设所有实体都是新的，跳过重复检查以获得最大性能。 仅在确保没有重复实体时使用。
Parameters
entities
Entity[]
要添加的实体列表
Returns
void
removeEntity()
removeEntity(
entity):void
Defined in: ECS/Core/QuerySystem.ts:235
从查询系统移除实体
从查询系统中移除指定实体，并清理相关索引。
Parameters
entity
要移除的实体
Returns
void
updateEntity()
updateEntity(
entity):void
Defined in: ECS/Core/QuerySystem.ts:258
更新实体在查询系统中的索引
当实体的组件组合发生变化时调用此方法，高效地更新实体在查询系统中的索引。
Parameters
entity
要更新的实体
Returns
void
queryAll()
queryAll(...
componentTypes):QueryResult
Defined in: ECS/Core/QuerySystem.ts:434
查询包含所有指定组件的实体
返回同时包含所有指定组件类型的实体列表。 系统会自动选择最高效的查询策略，包括索引查找和缓存机制。
Parameters
componentTypes
...ComponentType[]
要查询的组件类型列表
Returns
QueryResult
查询结果，包含匹配的实体和性能信息
Example
// 查询同时具有位置和速度组件的实体
const result = querySystem.queryAll(PositionComponent, VelocityComponent);
logger.info(`找到 ${result.count} 个移动实体`);queryAny()
queryAny(...
componentTypes):QueryResult
Defined in: ECS/Core/QuerySystem.ts:546
查询包含任意指定组件的实体
返回包含任意一个指定组件类型的实体列表。 使用集合合并算法确保高效的查询性能。
Parameters
componentTypes
...ComponentType[]
要查询的组件类型列表
Returns
QueryResult
查询结果，包含匹配的实体和性能信息
Example
// 查询具有武器或护甲组件的实体
const result = querySystem.queryAny(WeaponComponent, ArmorComponent);
logger.info(`找到 ${result.count} 个装备实体`);queryNone()
queryNone(...
componentTypes):QueryResult
Defined in: ECS/Core/QuerySystem.ts:604
查询不包含任何指定组件的实体
返回不包含任何指定组件类型的实体列表。 适用于排除特定类型实体的查询场景。
Parameters
componentTypes
...ComponentType[]
要排除的组件类型列表
Returns
QueryResult
查询结果，包含匹配的实体和性能信息
Example
// 查询不具有AI和玩家控制组件的实体（如静态物体）
const result = querySystem.queryNone(AIComponent, PlayerControlComponent);
logger.info(`找到 ${result.count} 个静态实体`);queryByTag()
queryByTag(
tag):QueryResult
Defined in: ECS/Core/QuerySystem.ts:652
按标签查询实体
返回具有指定标签的所有实体。 标签查询使用专用索引，具有很高的查询性能。
Parameters
tag
number
要查询的标签值
Returns
QueryResult
查询结果，包含匹配的实体和性能信息
Example
// 查询所有玩家实体
const players = querySystem.queryByTag(PLAYER_TAG);queryByName()
queryByName(
name):QueryResult
Defined in: ECS/Core/QuerySystem.ts:700
按名称查询实体
返回具有指定名称的所有实体。 名称查询使用专用索引，适用于查找特定的命名实体。
Parameters
name
string
要查询的实体名称
Returns
QueryResult
查询结果，包含匹配的实体和性能信息
Example
// 查找名为"Player"的实体
const player = querySystem.queryByName("Player");queryByComponent()
queryByComponent<
T>(componentType):QueryResult
Defined in: ECS/Core/QuerySystem.ts:748
按单个组件类型查询实体
返回包含指定组件类型的所有实体。 这是最基础的查询方法，具有最高的查询性能。
Type Parameters
T
T extends Component
Parameters
componentType
ComponentType<T>
要查询的组件类型
Returns
QueryResult
查询结果，包含匹配的实体和性能信息
Example
// 查询所有具有位置组件的实体
const entitiesWithPosition = querySystem.queryByComponent(PositionComponent);clearCache()
clearCache():
void
Defined in: ECS/Core/QuerySystem.ts:883
清理查询缓存
用于外部调用清理缓存，通常在批量操作后使用。
Returns
void
getAllEntities()
getAllEntities(): readonly
Entity[]
Defined in: ECS/Core/QuerySystem.ts:942
获取所有实体
Returns
readonly Entity[]
getStats()
getStats():
object
Defined in: ECS/Core/QuerySystem.ts:954
获取系统统计信息
返回查询系统的详细统计信息，包括实体数量、索引状态、 查询性能统计等，用于性能监控和调试。
Returns
object
系统统计信息对象
entityCount
entityCount:
number
indexStats
indexStats:
object
indexStats.maskIndexSize
maskIndexSize:
number
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.componentIndex
componentIndex:
any
optimizationStats.archetypeSystem
archetypeSystem:
any
cacheStats
cacheStats:
object
cacheStats.size
size:
number
cacheStats.hitRate
hitRate:
string
getEntityArchetype()
getEntityArchetype(
entity):undefined|Archetype
Defined in: ECS/Core/QuerySystem.ts:1014
获取实体所属的原型信息
Parameters
entity
要查询的实体
Returns
undefined | Archetype