Querying Components

Aprende cómo obtener listas de entities que tienen components en común, para facilitar su comprobación o actualización.

Puedes consultar components con el método engine.getEntitiesWith(...components) para llevar un seguimiento de todas las entities en la scene que tengan ciertos components.

Systems normalmente iteran sobre las entities en estas queries, realizando las mismas operations en cada una. Tener un grupo predefinido de valid entities es una excelente manera de ahorrar resources, especialmente para funciones que se ejecutan en cada tick del game loop. Si en cada tick tu system tuviera que iterar sobre cada entity en la scene buscando las que necesita, sería muy ineficiente.

Puedes acceder a las entities en una query de la siguiente manera.

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

Components requeridos

Al hacer una query, especifica qué components deben estar presentes en cada entity que se añada al group. Puedes listar tantos components como quieras; la query solo devolverá entities que tengan todo de los components listados.

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

💡 Consejo: Si tu query devuelve entities con las que no necesitas trabajar, considera crear un custom component para actuar como un flag. Este component no necesita tener ninguna property, pero puede usarse para marcar un subgroup específico de entities que quieras tratar de forma diferente.

Usar queries en un System

// Define un System
function PhysicsSystem(dt: number) {
	// consulta entities que incluyan tanto un component Transform como un component 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
	}
}

// Añade el System al engine
engine.addSystem(PhysicsSystem)

En el ejemplo anterior, la PhysicsSystem función itera sobre las entities de la query, y se ejecuta en cada tick del game loop.

• Si la scene tiene varias ball entities, cada una con un Transform y un Physics component, entonces se procesarán, y su posición se actualizará en cada tick.

• Si tu scene también tiene otras entities, por ejemplo una hoop y un scoreBoard que solo tienen un Transform pero no un Physics component, entonces no se verán afectadas por PhysicsSystem.

Trabajar con las entities y components

El getEntitiesWith function devuelve una collection que incluye references a un conjunto de entities y también puede incluir opcionalmente references a los components listados.

Usando la sintaxis más simple, obtienes solo una lista de references a las entities correspondientes.

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

Mientras iteras sobre esta lista de entities, puedes obtener versiones de solo lectura o mutables de sus components, usando .get o getMutable.

for (const [entity] of engine.getEntitiesWith(Transform)) {
	//obtener versión de solo lectura
	const transformReadOnly = Transform.get(entity)

	// obtener versión mutable
	const transformMutable = Transform.getMutable(entity)
}

Opcionalmente también puedes obtener references a cada uno de los components listados directamente como parte de la collection devuelta por la query. Para ello, solo declara múltiples references juntas, una para cada component que quieras obtener. Añadir estas references es opcional, y no necesitas declarar references a todo los components en la query tampoco.

// devuelve references a la entity y al primer component listado
for (const [entity, component1] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// iterar sobre la lista de entities
}

// devuelve references a la entity y a los dos primeros components listados
for (const [entity, component1, component2] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// iterar sobre la lista de entities
}

📔 Nota: Estas references son de solo lectura. Para obtener versiones mutables de esos components, necesitas usar la .getMutable function que hace referencia a la entity.

Luego puedes referirte a estas references mientras iteras sobre la collection de resultados; en cada entrada tendrás acceso a la entity y a sus correspondientes component references.

for (const [entity, transformReadOnly] of engine.getEntitiesWith(Transform)) {
	console.log('id de la entity: ', entity)
	console.log('tiene position: ', transformReadOnly.position)
}

Suscribirse a los cambios

Un caso de uso común es ejecutar una function solo en caso de que los datos de cierto component cambien. Usa la OnChange function para evitar tener que definir un System y tener que comparar explícitamente los valores antiguos con los nuevos.