> 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/composites.md).

# Composites

Genera un árbol de entities y Components en tiempo de ejecución a partir de un archivo composite

Un *composite* es un archivo que describe un árbol de [Entities y Components](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/arquitectura/entities-components.md). En lugar de escribir código para crear cada Entity una por una, puedes guardar esa estructura en un archivo composite e instanciar todo con una sola llamada.

Es posible que ya trabajes con composites sin darte cuenta:

* Cada Scene tiene un archivo `main.composite` . Contiene todo lo que añadiste y configuraste visualmente en el [Scene Editor](https://docs.decentraland.org/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md). Este archivo se carga automáticamente cuando se inicia tu Scene.
* [Custom Items](https://docs.decentraland.org/creator/content-creator-es/scene-editor/interactividad/custom-items.md) se guardan como archivos `composite.json` . Cada Custom Item es un composite que puedes reutilizar en distintas Scenes.

Esta página explica cómo instanciar un composite desde el código en tiempo de ejecución, por ejemplo, para instanciar un Custom Item de forma dinámica como parte de la lógica de tu Scene.

## Instanciar un composite

Para instanciar un composite hay que seguir dos pasos: **cargar** el archivo composite y, después, **instanciarlo** . La carga es asíncrona y la instanciación es síncrona, así que el patrón siempre es cargar y luego instanciar:

```ts
import { engine, Composite, getCompositeProvider } from "@dcl/sdk/ecs";

export async function spawnBarrel() {
  const src = "barrel.composite";
  const provider = getCompositeProvider();
  if (!provider || !provider.loadComposite) return;

  // 1. Cargar el composite desde su archivo
  const resource = await provider.loadComposite(src);

  // 2. Instanciarlo: crea todas sus Entities y Components
  const barrel = Composite.instance(engine, resource, provider);
  return barrel;
}
```

`provider.loadComposite(src)` lee el archivo composite y lo carga en la memoria. En una Scene normal creada con `@dcl/sdk`, ya se configura un proveedor de composites; puedes acceder a él con la función `getCompositeProvider()` de `@dcl/sdk/ecs`.

`Composite.instance()` crea todas las Entities descritas en el composite, con todos sus Components, y devuelve la **Root Entity** del árbol instanciado. Usa esta Entity devuelta para leer o modificar Components más adelante, por ejemplo, para cambiar la posición del elemento instanciado o eliminarlo.

{% hint style="info" %}
**💡 Consejo**: Para hacer lo mismo sin escribir código, usa la acción **Spawn Entity** en el Scene Editor. Consulta [Acerca de la instanciación de Entities](https://docs.decentraland.org/creator/content-creator-es/scene-editor/interactividad/smart-items-advanced.md#about-spawning-entities).
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Debes cargar un composite antes de instanciarlo. `Composite.instance()` es síncrono y solo puede generar un composite que ya esté en memoria. Solo `main.composite` se incluye con tu escena y está disponible desde el inicio; cualquier otro archivo de composite debe cargarse primero con `loadComposite()` . Para comprobar de forma síncrona si un composite ya está disponible, usa `provider.getCompositeOrNull(src)`.

`loadComposite()` es idempotente: identifica cada composite mediante su cadena `src` , por lo que, si la llamas de nuevo con la misma ruta, no vuelve a cargar el archivo, sino que devuelve el composite que ya se había cargado. Puedes llamarla sin problemas antes de cada generación, sin preocuparte por cargar el mismo archivo dos veces.
{% endhint %}

### Generar en una entidad existente

De forma predeterminada, `Composite.instance()` crea una entidad nueva para contener el árbol generado. Pasa un `rootEntity` en las opciones para generar el árbol en una entidad que ya tengas:

```ts
// Genera el composite directamente en la raíz de la escena, sin una entidad contenedora
const barrel = Composite.instance(engine, resource, provider, {
  rootEntity: engine.RootEntity,
})
```

## Posicionar un composite generado

Para colocar el composite generado en una posición, rotación o escala específica, configura un componente `Transform` en la entidad raíz que devuelve `Composite.instance()`.

```ts
import { engine, Composite, getCompositeProvider, Transform } from "@dcl/sdk/ecs";
import { Vector3 } from "@dcl/sdk/math";

export async function spawnBarrel() {
  const src = "barrel.composite";
  const provider = getCompositeProvider();
  if (!provider || !provider.loadComposite) return;

  const resource = await provider.loadComposite(src);

  // Genera el composite en una posición específica
  const barrel = Composite.instance(engine, resource, provider);
  Transform.createOrReplace(barrel, {
    position: Vector3.create(8, 0, 8),
  });
}
```

{% hint style="warning" %}
**📔 Nota**: `Transform.createOrReplace()` reemplaza el componente Transform existente de la entidad raíz. Solo se ve afectada la entidad raíz; las entidades secundarias conservan sus posiciones relativas a la raíz.
{% endhint %}

## Limitación actual: composites anidados

La generación funciona con composites autocontenidos y Custom Items. Un composite puede hacer referencia a otro composite desde una de sus entidades, pero `loadComposite()` no **busca** de forma recursiva esas referencias anidadas: solo carga el archivo que se le pasa.

Al generar, `Composite.instance()` busca de forma recursiva las referencias anidadas que ya están en memoria. Si un composite anidado no está cargado (es decir, cualquier otro distinto de `main.composite`, el único composite incluido con tu escena), se registra una advertencia para esa rama y se omite. Para generar un composite con referencias anidadas, llama primero a `loadComposite()` para cada archivo referenciado. O, más sencillo, procura que los composites que generes sean autocontenidos.

## Páginas relacionadas

* [Entidades y componentes](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/arquitectura/entities-components.md) : los elementos básicos que describe un composite.
* [Custom Items](https://docs.decentraland.org/creator/content-creator-es/scene-editor/interactividad/custom-items.md) : elementos reutilizables almacenados como composites.
* [Smart Items - Avanzado](https://docs.decentraland.org/creator/content-creator-es/scene-editor/interactividad/smart-items-advanced.md#about-spawning-entities) — crea composites sin código mediante la acción Spawn Entity.
* [Archivos de Scene](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/tipos-de-proyectos/scene-files.md) — donde `main.composite` se encuentra en el proyecto de tu escena.


---

# 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/composites.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.
