查询组件

了解如何获取具有共同组件的实体列表，从而更轻松地检查或更新它们。

你可以 查询组件 使用该方法 engine.getEntitiesWith(...components) 以跟踪场景中所有具有特定组件的实体。

系统 系统通常会遍历这些查询中的实体，并对每个实体执行相同的操作。预先定义一组有效实体是节省资源的好方法，尤其适用于每个游戏循环 tick 都会运行的函数。如果每个 tick 你的系统都必须遍历场景中的每一个实体来查找所需的实体，那将非常低效。

你可以通过以下方式访问查询中的实体。

for (const [entity] of engine.getEntitiesWith(Transform)) {
	//...
}

所需组件

在创建查询时，指定添加到该组中的每个实体都需要包含哪些组件。你可以列出任意多个组件，查询只会返回具有 所有 所列组件中的组件。

for (const [entity] of engine.getEntitiesWith(
	Transform,
	Physics,
	NextPosition
)) {
	//...
}

💡 提示：如果你的查询返回了你不需要处理的实体，可以考虑创建一个自定义组件作为 标记。这个组件不需要包含任何属性，但可用于标记你可能希望区别处理的特定实体子组。

在系统中使用查询

// 定义一个系统
function PhysicsSystem(dt: number) {
	// 查询同时包含 Transform 和 Physics 组件的实体
	for (const [entity] of engine.getEntitiesWith(Transform, Physics)) {
		const transform = Transform.getMutable(entity)
		const vel = Physics.get(entity).velocity
		transform.position.x += vel.x
		transform.position.y += vel.y
		transform.position.z += vel.z
	}
}

// 将系统添加到引擎中
engine.addSystem(PhysicsSystem)

在上面的示例中， PhysicsSystem 函数会遍历查询中的实体，该查询会在游戏循环的每个 tick 中执行。

• 如果场景中有多个 球 实体，每个实体都有一个 Transform 和一个 Physics 组件，那么它们会被处理，并且其位置会在每个 tick 中更新。

• 如果你的场景中还有其他实体，例如一个 篮筐 和一个 记分板 只有一个 Transform 但没有一个 Physics 组件，那么它们将不会受到 PhysicsSystem.

处理实体和组件

该 getEntitiesWith 函数返回一个集合，其中包含一组实体的引用，并且还可以选择性地包含所列组件的引用。

使用最简单的语法，你只会获取对应实体的引用列表。

for (const [entity] of engine.getEntitiesWith(myComponent, myOtherComponent)) {
	//...
}

在遍历这个实体列表时，你可以通过使用 .get 或 getMutable.

for (const [entity] of engine.getEntitiesWith(Transform)) {
	// 获取只读版本
	const transformReadOnly = Transform.get(entity)

	// 获取可变版本
	const transformMutable = Transform.getMutable(entity)
}

你也可以选择直接从查询返回的集合中获取所列每个组件的引用。为此，只需将多个引用一并声明，每个你想获取的组件对应一个引用。添加这些引用是可选的，而且你不 所有 需要声明对查询中的组件的引用。

// 返回实体和第一个列出的组件的引用
for (const [entity, component1] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// 遍历实体列表
}

// 返回实体和前两个列出的组件的引用
for (const [entity, component1, component2] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// 遍历实体列表
}

📔 注意：这些引用是只读的。要获取这些组件的可变版本，你需要使用 .getMutable 引用该实体的函数。

然后你可以在遍历结果集合时引用这些引用，在每个条目中你都可以访问实体及其对应的组件引用。

for (const [entity, transformReadOnly] of engine.getEntitiesWith(Transform)) {
	console.log('实体 ID：', entity)
	console.log('具有位置：', transformReadOnly.position)
}

订阅更改

一个常见的用例是，仅在某个组件中的数据发生变化时才运行函数。使用 OnChange 函数，避免定义系统并显式比较旧值和新值。