> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md).

# Consultando Components

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

Pode [consultar componentes](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md) com o método `engine.getEntitiesWith(...components)` para acompanhar todas as entidades da cena que têm determinados componentes.

[Os Systems](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) normalmente iteram pelas entidades dessas consultas, realizando as mesmas operações em cada uma. Ter um grupo predefinido de entidades válidas é uma ótima maneira de economizar recursos, especialmente em funções executadas a cada tick do loop do jogo. Se, a cada tick, o seu System tivesse de iterar por todas as entidades da cena para encontrar as de que precisa, isso seria muito ineficiente.

Pode aceder às entidades de uma consulta da seguinte forma.

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

## Componentes obrigatórios

Ao fazer uma consulta, especifique quais componentes têm de estar presentes em cada entidade adicionada ao grupo. Pode listar quantos componentes quiser; a consulta só retornará entidades que tenham **todos** os componentes listados.

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

{% hint style="info" %}
**💡 Dica**: Se a consulta retornar entidades com as quais não precisa de lidar, considere criar um componente personalizado para servir de [indicador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md#components-as-flags). Este componente não precisa de ter propriedades, mas pode ser usado para marcar um subgrupo específico de entidades que talvez queira tratar de forma diferente.
{% endhint %}

## Usar consultas num System

```ts
// Definir um System
function PhysicsSystem(dt: number) {
	// consultar entidades que incluem os componentes Transform e 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
	}
}

// Adicionar o System ao engine
engine.addSystem(PhysicsSystem)
```

No exemplo acima, a função `PhysicsSystem` itera pelas entidades da consulta, que é executada a cada tick do loop do jogo.

* Se a cena tiver várias entidades *bola* , cada uma com um `Transform` e um componente `Physics` , elas serão processadas e a sua posição será atualizada a cada tick.
* Se a sua cena também tiver outras entidades, por exemplo um *aro* e um *painelDePontuação* que tenham apenas um componente `Transform` mas não um componente `Physics` componente, não serão afetados por `PhysicsSystem`.

## Lidar com as entidades e os componentes

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

Com a sintaxe mais simples, obtém apenas uma lista de referências às entidades correspondentes.

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

Ao percorrer esta lista de entidades, pode obter versões só de leitura ou mutáveis dos respetivos componentes usando `.get` ou `getMutable`.

```ts
for (const [entity] of engine.getEntitiesWith(Transform)) {
	//obter versão só de leitura
	const transformReadOnly = Transform.get(entity)

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

Opcionalmente, também pode obter referências a cada um dos componentes indicados diretamente como parte da coleção devolvida pela consulta. Para isso, basta declarar várias referências em conjunto, uma para cada componente que pretende obter. A inclusão destas referências é opcional e não precisa de declarar referências a *todos* os componentes da consulta.

```ts
// devolve referências à entidade e ao primeiro componente indicado
for (const [entity, component1] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// percorrer a lista de entidades
}

// devolve referências à entidade e aos dois primeiros componentes indicados
for (const [entity, component1, component2] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// percorrer a lista de entidades
}
```

{% hint style="warning" %}
**📔 Nota**: Estas referências são só de leitura. Para obter versões mutáveis desses componentes, tem de usar a função `.getMutable` que faz referência à entidade.
{% endhint %}

Pode então usar estas referências ao percorrer a coleção de resultados. Em cada entrada, terá acesso à entidade e às referências aos componentes correspondentes.

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

## Subscrever alterações

Um caso de utilização comum é executar uma função apenas quando os dados de um determinado componente são alterados. Use a função [OnChange](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/subscribe-to-changes.md) para evitar ter de definir um sistema e comparar explicitamente os valores antigos com os novos.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
