> 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

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

[Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) normalmente iteram sobre as entities nestas queries, realizando as mesmas operações em cada uma. Ter um grupo predefinido de entities válidas é uma ótima forma de poupar resources, especialmente para functions que rodam em cada tick do game loop. Se a cada tick o seu system tivesse de iterar sobre cada entity na scene à procura das 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)) {
	//...
}
```

## Required components

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

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

{% hint style="info" %}
**💡 Dica**: Se a sua query retorna entities com as quais você não precisa lidar, considere criar um component personalizado para atuar como um [flag](/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 %}

## Use queries em um system

```ts
// Defina um System
function PhysicsSystem(dt: number) {

  // query para entities que incluem tanto um component Transform quanto um Physics
  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

  }
}

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

```

No exemplo acima, a `PhysicsSystem` function itera sobre as entities na query, que é executada em cada tick do game loop.

* Se a scene tiver várias *ball* entities, cada uma com um `Posição` e um `Physics` component, então elas serão tratadas, e sua posição será atualizada a cada tick.
* Se a sua scene também tiver outras entities, por exemplo um *hoop* e um *scoreBoard* que tenha 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, opcionalmente, incluir referências aos components listados.

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

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

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

```ts
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 para 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ê quer buscar. Adicionar essas referências é opcional, e você também não precisa declarar referências para *todos os* os components na query.

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

// retorna referências para a entity e os 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 buscar 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 correspondentes dos seus components.

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

## Subscribe to changes

Um caso de uso comum é executar uma function apenas quando os dados de um determinado component mudam. 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 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:

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

The question should be specific, self-contained, and written in natural language.
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.