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

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 têm determinados components.

[Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) normalmente iteram sobre as entities nessas queries, realizando as mesmas operações em cada uma. Ter um grupo predefinido de entities válidas é uma ótima forma de economizar recursos, especialmente para functions que executam a cada tick do game loop. Se, a cada tick, o seu system tivesse de iterar sobre cada entity na scene procurando as que ele 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 necessá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 retornará apenas entities que tenham **todos os** um 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 component personalizado para atuar como um [sinalizador](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#components-as-flags). Esse component não precisa ter nenhuma property, mas pode ser usado para marcar um subgrupo específico de entities que você talvez queira tratar de forma diferente.
{% endhint %}

## Use queries em um System

```ts
// Defina um System
function PhysicsSystem(dt: number) {
	// query para entities que incluem tanto um 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 sobre as 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 uma `Physics` component, então elas serão tratadas, e sua position será atualizada a cada tick.
* Se a sua scene também tiver outras entities, por exemplo um *hoop* e uma *scoreBoard* que só têm um `Transform` mas não um `Physics` component, então elas não serão afetadas por `PhysicsSystem`.

## Lidando 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 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 read-only ou mutáveis de seus components, usando `.get` ou `getMutable`.

```ts
for (const [entity] of engine.getEntitiesWith(Transform)) {
	// obtenha a versão read-only
	const transformReadOnly = Transform.get(entity)

	// obtenha a 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 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 a *todos os* os 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" %}
**📔 Observação**: Estas referências são read-only. Para obter versões mutáveis desses components, você precisa usar a `.getMutable` function que referencia a entity.
{% endhint %}

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

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

## Inscreva-se nas alterações

Um caso de uso comum é executar uma function apenas se os dados de um determinado component mudarem. Use a [OnChange](/creator/content-creator-pt/scenes-sdk7/arquitetura/subscribe-to-changes.md) function para evitar ter de definir um system e de comparar explicitamente valores antigos com valores 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.