Consultar Components

Saiba como 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 tenham certos components.

Systems normalmente iteram pelas entities nessas queries, realizando as mesmas operações em cada uma. Ter um grupo predefinido de entities válidas é uma ótima maneira de economizar recursos, especialmente para funções que executam a cada tick do game loop. Se a cada tick o seu system tivesse que iterar por cada entity na Scene procurando as que precisa, isso seria muito ineficiente.

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

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

Components obrigatórios

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

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

💡 Dica: Se a sua query retornar entities com as quais você não precisa lidar, considere criar um componente customizado para agir como um sinalizador. 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.

Usar queries em um System

// Defina um System
function PhysicsSystem(dt: number) {
	// query por entities que incluam tanto um component Transform quanto um 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
	}
}

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

No exemplo acima, a PhysicsSystem function itera pelas entities da query, que é executada a cada tick do game loop.

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

• Se a sua Scene também tiver outras entities, por exemplo uma hoop e um scoreBoard que tenham 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 incluir opcionalmente referências aos components listados.

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

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

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

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

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

Você também pode, opcionalmente, obter referências a 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ê quiser obter. Adicionar essas referências é opcional, e você não precisa declarar referências aos todos components na query também.

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

// retorna referências à entity e aos 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 obter 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 de components correspondentes.

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

Subscrever alterações

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