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

# Composites

Un *composite* es un archivo que describe un árbol de [entities y components](/creator/content-creator-es/escenas-sdk7/arquitectura/entities-components.md). En lugar de escribir código para crear cada entity una por una, puedes almacenar esa estructura en un archivo composite y generar todo con una sola llamada.

Puede que ya trabajes con composites sin darte cuenta:

* Toda escena tiene un `main.composite` archivo. Contiene todo lo que agregaste y configuraste visualmente en el [Scene Editor](/creator/content-creator-es/scene-editor/empezar/about-editor.md)Scene Editor
* [Custom Items](/creator/content-creator-es/scene-editor/interactividad/custom-items.md) se guardan como `composite.json` archivos. Cada Custom Item es un composite que puedes reutilizar en distintas escenas.

Esta página cubre cómo generar un composite desde código en tiempo de ejecución, por ejemplo para generar un Custom Item dinámicamente como parte de la lógica de tu escena.

## Generar un composite

Generar un composite requiere dos pasos: **cargar** el archivo composite, luego **generar** lo. Cargar es asíncrono y generar es síncrono, así que el patrón es siempre cargar-then-generar:

```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. Carga el composite desde su archivo
  const resource = await provider.loadComposite(src);

  // 2. Genera esto: 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 memoria. En una escena normal creada con `@dcl/sdk`, ya tienes configurado un composite provider, y puedes acceder a él con la `getCompositeProvider()` función de `@dcl/sdk/ecs`.

`Composite.instance()` entonces crea todas las entities descritas en el composite, con todos sus components, y devuelve el **root entity** del árbol generado. Usa esta entity devuelta para leer o cambiar components más adelante, por ejemplo para reposicionar o eliminar el item generado.

{% hint style="info" %}
**💡 Consejo**: Para hacer lo mismo sin escribir código, usa el **Spawn Entity** acción en el Scene Editor. Consulta [Sobre la generación de entities](/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 generarlo. `Composite.instance()` es síncrono y solo puede generar un composite que ya está en memoria. Solo `main.composite` viene incluido con tu escena y está disponible desde el inicio; cualquier otro archivo composite debe cargarse con `loadComposite()` primero. Para comprobar de forma síncrona si un composite ya está disponible, usa `provider.getCompositeOrNull(src)`.

`loadComposite()` es idempotente: indexa cada composite por su `src` string, así que volver a llamarlo con la misma ruta no vuelve a cargar el archivo, sino que devuelve el composite ya cargado. Puedes llamarlo con seguridad antes de cada generación sin preocuparte por cargar el mismo archivo dos veces.
{% endhint %}

## Posiciona un composite generado

Para colocar el composite generado en una posición, rotación o escala específicas, establece un `Transform` component en el root entity devuelto por `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 root entity. Solo la root entity se ve afectada; las child entities mantienen sus posiciones relativas a la root.
{% endhint %}

## Limitación actual: composites anidados

La generación funciona para composites autocontenidos y Custom Items. Un composite puede referenciar otro composite desde una de sus entities, pero `loadComposite()` no **no** recursa en esas referencias anidadas: solo carga el archivo que le pasas.

Al generar, `Composite.instance()` recursa en referencias anidadas que ya están en memoria. Si un composite anidado no está cargado (cualquier cosa excepto `main.composite`, el único composite incluido con tu escena), esa rama registra una advertencia y se omite. Para generar un composite con referencias anidadas, llama a `loadComposite()` primero para cada archivo referenciado — o, más simple, mantén los composites que generas autocontenidos.

## Páginas relacionadas

* [Entities & Components](/creator/content-creator-es/escenas-sdk7/arquitectura/entities-components.md) — los bloques de construcción que describe un composite.
* [Custom Items](/creator/content-creator-es/scene-editor/interactividad/custom-items.md) — items reutilizables almacenados como composites.
* [Smart Items - Avanzado](/creator/content-creator-es/scene-editor/interactividad/smart-items-advanced.md#about-spawning-entities) — genera composites sin código, usando la acción Spawn Entity.
* [Scene Files](/creator/content-creator-es/escenas-sdk7/tipos-de-proyectos/scene-files.md) — donde `main.composite` reside en tu proyecto de 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 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/composites.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.