Consulta de componentes

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

Puedes consultar components con el método engine.getEntitiesWith(...components) para hacer un seguimiento de todas las entidades en la escena que tengan ciertos componentes.

Systems típicamente iterar sobre las entidades en estas consultas, realizando las mismas operaciones en cada una. Tener un grupo predefinido de entidades válidas es una gran manera de ahorrar recursos, especialmente para funciones que se ejecutan en cada tick del bucle de juego. Si en cada tick tu sistema tuviera que iterar por cada entidad en la escena buscando las que necesita, sería muy ineficiente.

Puedes acceder a las entidades en una consulta de la siguiente manera.

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

Componentes requeridos

Al hacer una consulta, especifica qué componentes deben estar presentes en cada entidad que se añada al grupo. Puedes listar tantos componentes como quieras, la consulta solo devolverá entidades que tengan todos los componentes listados.

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

💡 Consejo: Si tu consulta devuelve entidades con las que no necesitas tratar, considera crear un componente personalizado para actuar como un indicador. Este componente no necesita tener propiedades en él, pero puede usarse para marcar un subgrupo específico de entidades que podrías querer tratar de manera diferente.

Usar consultas en un sistema

// Definir un System
function PhysicsSystem(dt: number) {

  // consulta entidades que incluyen tanto un Transform como un Physics component
  for (const [entity] of engine.getEntitiesWith(Transform, Physics)) {
    const transform = Transform.getMutable(entity)
	cons vel = Physics.get(entity).velocity
	position.x += vel.x
	position.y += vel.y
	position.z += vel.z

  }
}

// Añadir el system al engine
engine.addSystem(rotationSystem)

En el ejemplo anterior, la PhysicsSystem function itera sobre las entidades en la consulta, que se ejecuta en cada tick del bucle de juego.

• Si la escena tiene varias bola entidades, cada una con un Position y un Física component, entonces serán manejadas, y su posición se actualizará en cada tick.

• Si tu escena también tiene otras entidades, por ejemplo un aro y un marcador que solo tienen un Transform pero no un Física component, entonces no se verán afectadas por PhysicsSystem.

Tratar con las entidades y componentes

El getEntitiesWith la función devuelve una colección, que incluye referencias a un conjunto de entidades y que también opcionalmente puede incluir referencias a los componentes listados.

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

const [entity] of engine.getEntitiesWith(myComponent, myOtherComponent)

Mientras iteras sobre esta lista de entidades, puedes entonces obtener versiones de solo lectura o mutables de sus componentes, usando .get u 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 referencias a cada uno de los componentes listados directamente como parte de la colección devuelta por la consulta. Para hacer esto, simplemente declara múltiples referencias juntas, una por cada componente que quieras obtener. Añadir estas referencias es opcional, y no necesitas declarar referencias a todos los componentes en la consulta tampoco.

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

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

📔 Nota: Estas referencias son de solo lectura. Para obtener versiones mutables de esos componentes, necesitas usar la .getMutable función referenciando la entidad.

Entonces puedes referirte a estas referencias mientras iteras sobre la colección de resultados; en cada entrada tendrás acceso a la entidad y a sus referencias de componentes correspondientes.

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

Suscribirse a cambios

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