> 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 en tiempo de ejecución un árbol de entities y components a partir de un archivo composite

A *composite* es un archivo que describe un árbol de [entities y components](/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 y generar todo con una sola llamada.

Es posible 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/comenzar/about-editor.md). Este archivo se carga automáticamente cuando empieza tu escena.
* [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 explica 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 **generarlo** . Cargar es asíncrono y generar es sincrónico, así que el patrón siempre es cargar y luego 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. Cargar el composite desde su archivo
  const resource = await provider.loadComposite(src);

  // 2. Generarlo: 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; puedes acceder a él con la `getCompositeProvider()` función de `@dcl/sdk/ecs`.

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

{% hint style="info" %}
**💡 Consejo**: Para hacer lo mismo sin escribir código, usa la **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 sincrónico y solo puede generar un composite que ya esté en memoria. Solo `main.composite` está incluido con tu escena y disponible desde el inicio; cualquier otro archivo composite debe cargarse primero con `loadComposite()` Para comprobar de forma sincrónica si un composite ya está disponible, usa `provider.getCompositeOrNull(src)`.

`loadComposite()` es idempotente: indexa cada composite por su cadena `src` de modo que volver a llamarlo con la misma ruta no recarga 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 %}

### Generar sobre una entity existente

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

```ts
// Genera el composite directamente en la raíz de la escena, sin entity 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íficas, establece un `Transform` component en la root entity devuelta 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 Transform component existente de la root entity. Solo se ve afectada la root entity; las entidades hijas mantienen sus posiciones relativas a la raíz.
{% 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 **recorre** esas referencias anidadas: solo carga el archivo que le pasas.

Al generar, `Composite.instance()` recorre las referencias anidadas que ya están en memoria. Si un composite anidado no está cargado (cualquier cosa distinta de `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()` cada archivo referenciado primero — o, más sencillo, mantén autocontenidos los composites que generas.

## Páginas relacionadas

* [Entities & Components](/creator/content-creator-es/scenes-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) — elementos reutilizables almacenados como composites.
* [Smart Items - Advanced](/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.
* [Archivos de escena](/creator/content-creator-es/scenes-sdk7/tipos-de-proyectos/scene-files.md) — donde `main.composite` vive 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/scenes-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.