> 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

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

Você pode [consultar components](/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md) com o método `engine.getEntitiesWith(...components)` para acompanhar todas as entities na Scene que tenham certos components.

[Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) 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.

```ts
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.

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

{% hint style="info" %}
**💡 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](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#components-as-flags). 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.
{% endhint %}

## Usar queries em um System

```ts
// 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.

```ts
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`.

```ts
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.

```ts
// 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
}
```

{% hint style="warning" %}
**📔 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.
{% endhint %}

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.

```ts
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](/creator/content-creator-pt/scenes-sdk7/arquitetura/subscribe-to-changes.md) function para evitar ter que definir um system e ter que comparar explicitamente valores antigos com novos valores.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.