Consultando Components

Aprenda a obter listas de entities que têm components em comum, para facilitar a verificação ou atualização delas.

Você pode consultar components com o método engine.getEntitiesWith(...components) para acompanhar todas as entities na scene que têm certos components.

Systems normalmente iteram sobre as entities nestas queries, realizando as mesmas operações em cada uma. Ter um grupo predefinido de entities válidas é uma ótima forma de poupar resources, especialmente para functions que rodam em cada tick do game loop. Se a cada tick o seu system tivesse de iterar sobre cada entity na scene à procura das que precisa, isso seria muito ineficiente.

Você pode acessar as entities em uma query da seguinte forma.

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

Required components

Ao fazer uma query, especifique quais components precisam estar presentes em cada entity que é adicionada ao grupo. Você pode listar quantos components quiser, a query só retornará entities que tenham todos os components listados.

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

💡 Dica: Se a sua query retorna entities com as quais você não precisa lidar, considere criar um component personalizado para atuar como um flag. Esse component não precisa ter nenhuma propriedade, mas pode ser usado para marcar um subgrupo específico de entities que você talvez queira tratar de forma diferente.

Use queries em um system

// Defina um System
function PhysicsSystem(dt: number) {

  // query para entities que incluem tanto um component Transform quanto um Physics
  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

  }
}

// Adicione o system ao engine
engine.addSystem(rotationSystem)

No exemplo acima, a PhysicsSystem function itera sobre as entities na query, que é executada em cada tick do game loop.

• Se a scene tiver várias ball entities, cada uma com um Posição e um Physics component, então elas serão tratadas, e sua posição será atualizada a cada tick.

• Se a sua scene também tiver outras entities, por exemplo um hoop e um scoreBoard que tenha apenas um Transform mas não um Physics component, então elas não serão afetadas por PhysicsSystem.

Lidar com as entities e components

O getEntitiesWith function retorna uma collection, que inclui referências a um conjunto de entities e também pode, opcionalmente, incluir referências aos components listados.

Usando a sintaxe mais simples, você obtém apenas uma lista de referências às entities correspondentes.

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

Enquanto itera por esta lista de entities, você pode então buscar versões somente leitura ou mutáveis dos seus components, usando .get ou getMutable.

for (const [entity] of engine.getEntitiesWith(Transform)) {
	// obter versão somente leitura
	const transformReadOnly = Transform.get(entity)

	// obter versão mutável
	const transformMutable = Transform.getMutable(entity)
}

Você também pode, opcionalmente, buscar referências para cada um dos components listados diretamente como parte da collection retornada pela query. Para fazer isso, basta declarar várias referências juntas, uma para cada component que você quer buscar. Adicionar essas referências é opcional, e você também não precisa declarar referências para todos os os components na query.

// retorna referências para a entity e o primeiro component listado
for (const [entity, component1] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// iterar sobre a lista de entities
}

// retorna referências para a entity e os dois primeiros components listados
for (const [entity, component1, component2] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// iterar sobre a lista de entities
}

📔 Nota: Essas referências são somente leitura. Para buscar versões mutáveis desses components, você precisa usar a .getMutable function referenciando a entity.

Você pode então se referir a essas referências enquanto itera pela collection de resultados; em cada entrada você terá acesso à entity e às referências correspondentes dos seus components.

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

Subscribe to changes

Um caso de uso comum é executar uma function apenas quando os dados de um determinado component mudam. Use a OnChange function para evitar ter de definir um system e de comparar explicitamente valores antigos com novos valores.