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

# Consultando Components

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

[Systems](/creator/content-creator-es/escenas-sdk7/arquitectura/systems.md) normalmente iteran sobre las entities en estas queries, realizando las mismas operations en cada una. Tener un grupo predefinido de valid entities es una excelente manera de ahorrar resources, especialmente para funciones que se ejecutan en cada tick del game loop. Si en cada tick tu system tuviera que iterar sobre cada entity en la scene buscando las que necesita, sería muy ineficiente.

Puedes acceder a las entities en una query de la siguiente manera.

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

## Components requeridos

Al hacer una query, especifica qué components deben estar presentes en cada entity que se añada al group. Puedes listar tantos components como quieras; la query solo devolverá entities que tengan **todo** de los components listados.

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

{% hint style="info" %}
**💡 Consejo**: Si tu query devuelve entities con las que no necesitas trabajar, considera crear un custom component para actuar como un [flag](/creator/content-creator-es/escenas-sdk7/arquitectura/entities-components.md#components-as-flags). Este component no necesita tener ninguna property, pero puede usarse para marcar un subgroup específico de entities que quieras tratar de forma diferente.
{% endhint %}

## Usar queries en un System

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

// Añade el System al engine
engine.addSystem(PhysicsSystem)
```

En el ejemplo anterior, la `PhysicsSystem` función itera sobre las entities de la query, y se ejecuta en cada tick del game loop.

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

## Trabajar con las entities y components

El `getEntitiesWith` function devuelve una collection que incluye references a un conjunto de entities y también puede incluir opcionalmente references a los components listados.

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

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

Mientras iteras sobre 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)) {
	//obtener versión de solo lectura
	const transformReadOnly = Transform.get(entity)

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

Opcionalmente también puedes obtener references a cada uno de los components listados directamente como parte de la collection devuelta por la query. Para ello, solo declara múltiples references juntas, una para cada component que quieras obtener. Añadir estas references es opcional, y no necesitas declarar references a *todo* los components en la query tampoco.

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

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

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

Luego puedes referirte a estas references mientras iteras sobre la collection de resultados; en cada entrada tendrás acceso a la entity y a sus correspondientes component references.

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

## Suscribirse a los cambios

Un caso de uso común es ejecutar una function solo en caso de que los datos de cierto component cambien. Usa la [OnChange](/creator/content-creator-es/escenas-sdk7/arquitectura/subscribe-to-changes.md) function 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 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-es/escenas-sdk7/arquitectura/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.