> 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-es/scenes-sdk7/arquitectura/querying-components.md).

# Consultando Components

Aprende cómo obtener listas de entidades que tienen Components en común, para facilitar su comprobación o actualización.

Puedes [consultar components](/creator/content-creator-es/scenes-sdk7/arquitectura/querying-components.md) con el método `engine.getEntitiesWith(...components)` para hacer seguimiento de todas las entities en la scene que tienen ciertos components.

[Systems](/creator/content-creator-es/scenes-sdk7/arquitectura/systems.md) normalmente recorren las entities en estas consultas, realizando las mismas operaciones sobre cada una. Tener un grupo predefinido de entities válidas es una excelente manera de ahorrar recursos, especialmente para funciones que se ejecutan en cada tick del game loop. Si en cada tick tu system tuviera que recorrer cada entity de la scene buscando las que necesita, sería muy ineficiente.

Puedes acceder a las entities de una consulta de la siguiente manera.

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

## Componentes requeridos

Al hacer una consulta, especifica qué components deben estar presentes en cada entity que se agregue al grupo. Puedes listar tantos components como quieras; la consulta solo devolverá entities que tengan **todos** de los components listados.

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

{% hint style="info" %}
**💡 Consejo**: Si tu consulta devuelve entities con las que no necesitas trabajar, considera crear un component personalizado que actúe como un [indicador](/creator/content-creator-es/scenes-sdk7/arquitectura/entities-components.md#components-as-flags). Este component no necesita tener ninguna property, pero puede usarse para marcar un subgrupo específico de entities al que quizá quieras tratar de forma diferente.
{% endhint %}

## Usa consultas en un system

```ts
// Define un System
function PhysicsSystem(dt: number) {
	// consulta entities que incluyan tanto un Transform como un 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
	}
}

// Agrega el system al engine
engine.addSystem(PhysicsSystem)
```

En el ejemplo anterior, la `PhysicsSystem` function recorre las entities de la consulta, que se ejecuta en cada tick del game loop.

* Si la scene tiene varias *ball* entities, cada una con un `Transform` y una `Physics` component, entonces se procesarán y su position se actualizará en cada tick.
* Si tu scene también tiene otras entities, por ejemplo un *hoop* y una *scoreBoard* que solo tienen un `Transform` pero no un `Physics` component, entonces no se verán afectadas por `PhysicsSystem`.

## Trabajando con las entities y components

El `getEntitiesWith` devuelve una colección que incluye referencias a un conjunto de entities y también puede incluir opcionalmente referencias a los components listados.

Usando la sintaxis más simple, obtienes solo una lista de referencias a las entities correspondientes.

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

Mientras recorres esta lista de entities, puedes obtener versiones de solo lectura o mutables de sus components, usando `.get` o `getMutable`.

```ts
for (const [entity] of engine.getEntitiesWith(Transform)) {
	//versión de solo lectura
	const transformReadOnly = Transform.get(entity)

	// versión mutable
	const transformMutable = Transform.getMutable(entity)
}
```

También puedes obtener opcionalmente referencias a cada uno de los components listados directamente como parte de la colección devuelta por la consulta. Para hacerlo, simplemente declara varias referencias juntas, una por cada component que quieras obtener. Agregar estas referencias es opcional, y tampoco necesitas declarar referencias a *todos* los components en la consulta.

```ts
// devuelve referencias a la entity y al primer component listado
for (const [entity, component1] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// recorre la lista de entities
}

// devuelve referencias a la entity y a los dos primeros components listados
for (const [entity, component1, component2] of engine.getEntitiesWith(
	MyCustomComponent1,
	MyCustomComponent2
)) {
	// recorre la lista de entities
}
```

{% hint style="warning" %}
**📔 Nota**: Estas referencias son de solo lectura. Para obtener versiones mutables de esos components, necesitas usar la `.getMutable` función que hace referencia a la entity.
{% endhint %}

Luego puedes referirte a estas referencias mientras recorres la colección de resultados; en cada entrada tendrás acceso a la entity y a las referencias de sus components correspondientes.

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

## Suscríbete a los cambios

Un caso de uso común es ejecutar una función solo cuando los datos de un cierto component cambian. Usa la [OnChange](/creator/content-creator-es/scenes-sdk7/arquitectura/subscribe-to-changes.md) función para evitar tener que definir un system y tener que comparar explícitamente los valores antiguos con los nuevos.


---

# 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-es/scenes-sdk7/arquitectura/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.