Consultando Componentes

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

Você pode consultar componentes com o método engine.getEntitiesWith(...components) para acompanhar todas as entidades na cena que possuem certos componentes.

Sistemas normalmente iteram sobre as entidades nessas consultas, realizando as mesmas operações em cada uma. Ter um grupo pré-definido de entidades válidas é uma ótima maneira de economizar recursos, especialmente para funções que são executadas a cada tick do loop do jogo. Se a cada tick seu sistema tivesse que iterar por todas as entidades na cena procurando as que precisa, isso seria muito ineficiente.

Você pode acessar as entidades em uma consulta da seguinte forma.

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

Componentes obrigatórios

Ao fazer uma consulta, especifique quais componentes precisam estar presentes em cada entidade que for adicionada ao grupo. Você pode listar quantos componentes quiser; a consulta retornará apenas entidades que tenham todos os componentes listados.

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

💡 Tip: Se sua consulta retornar entidades com as quais você não precisa lidar, considere criar um componente personalizado para atuar como um sinalizador. Este componente não precisa ter nenhuma propriedade, mas pode ser usado para marcar um subgrupo específico de entidades que você pode querer tratar de forma diferente.

Usar consultas em um sistema

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

  // consultar entidades que incluem tanto um Transform quanto um 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

  }
}

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

No exemplo acima, a PhysicsSystem function itera sobre as entidades da consulta, que é executada a cada tick do loop do jogo.

• Se a cena tiver várias bola entidades, cada uma com um Position e um Física componente, então elas serão tratadas, e sua posição será atualizada a cada tick.

• Se sua cena também tiver outras entidades, por exemplo um arco e um placar que tenham apenas um Transform mas não um Física componente, então elas não serão afetadas por PhysicsSystem.

Lidando com as entidades e componentes

O getEntitiesWith a função retorna uma coleção, que inclui referências a um conjunto de entidades e também pode opcionalmente incluir referências aos componentes listados.

Usando a sintaxe mais simples, você busca apenas uma lista de referências às entidades correspondentes.

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

Ao iterar essa lista de entidades, você pode então buscar versões somente leitura ou mutáveis de seus componentes, 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 a cada um dos componentes listados diretamente como parte da coleção retornada pela consulta. Para fazer isso, simplesmente declare múltiplas referências juntas, uma para cada componente que você deseja buscar. Adicionar essas referências é opcional, e você também não precisa declarar referências para todos os componentes na consulta.

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

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

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

Você pode então se referir a essas referências enquanto itera sobre a coleção de resultados; em cada entrada você terá acesso à entidade e às suas respectivas referências de componentes.

for (const [entity, transformReadOnly] of engine.getEntitiesWith(Transform)) {
	console.log('id da entidade: ', entity)
	console.log('tem posição : ', transformReadOnly.position)
}

Inscrever-se em mudanças

Um caso de uso comum é executar uma função apenas caso os dados em certo componente mudem. Use a OnChange function para evitar ter que definir um system e ter que comparar explicitamente valores antigos com valores novos.