Home > @esengine/ecs-framework-monorepo > QuerySystem

QuerySystem class

高性能实体查询系统

提供快速的实体查询功能，支持按组件类型、标签、名称等多种方式查询实体。 系统采用多级索引和智能缓存机制，确保在大量实体场景下的查询性能。

主要特性： - 支持单组件和多组件查询 - 自动索引管理和缓存优化 - WebAssembly计算加速（如果可用） - 详细的性能统计信息

Signature:

export declare class QuerySystem

Example

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

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

Constructors

Constructor	Modifiers	Description
(constructor)()		Constructs a new instance of the QuerySystem class

Properties

Property	Modifiers	Type	Description
version	readonly	number	获取当前版本号（用于缓存失效）

Methods

Method	Modifiers	Description
addEntities(entities)		批量添加实体 高效地批量添加多个实体，减少缓存清理次数。 使用Set来避免O(n)的重复检查。
addEntitiesUnchecked(entities)		批量添加实体（无重复检查版本） 假设所有实体都是新的，跳过重复检查以获得最大性能。 仅在确保没有重复实体时使用。
addEntity(entity, deferCacheClear)		添加单个实体到查询系统 将新实体添加到查询系统中，并自动更新相关索引。 为了提高批量添加性能，可以延迟缓存清理。
batchUpdateComponents(updates)		批量更新实体组件 对大量实体进行批量组件更新操作。
beginFrame()		开始新的帧
clearCache()		公共方法：清理查询缓存 用于外部调用清理缓存，通常在批量操作后使用。
configureDirtyTracking(batchSize, maxProcessingTime)		配置脏标记系统
endFrame()		结束当前帧
getAllEntities()		获取所有实体
getEntityArchetype(entity)		获取实体所属的原型信息
getStats()		获取系统统计信息 返回查询系统的详细统计信息，包括实体数量、索引状态、 查询性能统计等，用于性能监控和调试。
markEntityDirty(entity, componentTypes)		标记实体组件已修改（用于脏标记追踪）
optimizePerformance()		手动触发性能优化
queryAll(componentTypes)		查询包含所有指定组件的实体 返回同时包含所有指定组件类型的实体列表。 系统会自动选择最高效的查询策略，包括索引查找和缓存机制。
queryAny(componentTypes)		查询包含任意指定组件的实体 返回包含任意一个指定组件类型的实体列表。 使用集合合并算法确保高效的查询性能。
queryByComponent(componentType)		按单个组件类型查询实体 返回包含指定组件类型的所有实体。 这是最基础的查询方法，具有最高的查询性能。
queryByName(name)		按名称查询实体 返回具有指定名称的所有实体。 名称查询使用专用索引，适用于查找特定的命名实体。
queryByTag(tag)		按标签查询实体 返回具有指定标签的所有实体。 标签查询使用专用索引，具有很高的查询性能。
queryNone(componentTypes)		查询不包含任何指定组件的实体 返回不包含任何指定组件类型的实体列表。 适用于排除特定类型实体的查询场景。
removeEntity(entity)		从查询系统移除实体 从查询系统中移除指定实体，并清理相关索引。
setEntities(entities)		设置实体列表并重建索引 当实体集合发生大规模变化时调用此方法。 系统将重新构建所有索引以确保查询性能。