> 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-pt/scenes-sdk7/arquitetura/composites.md).

# Composites

Faça spawn de uma árvore de entities e components em runtime a partir de um arquivo composite

A *composite* é um arquivo que descreve uma árvore de [entities e components](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md). Em vez de escrever código para criar cada entity uma por uma, você pode armazenar essa estrutura em um arquivo composite e spawnar tudo com uma única chamada.

Talvez você já trabalhe com composites sem perceber:

* Toda scene tem um `main.composite` arquivo. Ele contém tudo o que você adicionou e configurou visualmente no [Scene Editor](/creator/content-creator-pt/scene-editor/comece/about-editor.md). Este arquivo é carregado automaticamente quando sua scene inicia.
* [Custom Items](/creator/content-creator-pt/scene-editor/interatividade/custom-items.md) são salvos como `composite.json` arquivos. Cada Custom Item é um composite que você pode reutilizar entre scenes.

Esta página aborda como spawnar um composite a partir do código em runtime, por exemplo, para spawnar um Custom Item dinamicamente como parte da lógica da sua scene.

## Spawnar um composite

Spawnar um composite leva dois passos: **carregar** o arquivo composite, depois **spawnar** ele. Carregar é assíncrono e spawnar é síncrono, então o padrão é sempre carregar e depois spawnar:

```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. Carregue o composite a partir do arquivo
  const resource = await provider.loadComposite(src);

  // 2. Spawn: cria todas as suas entities e components
  const barrel = Composite.instance(engine, resource, provider);
  return barrel;
}
```

`provider.loadComposite(src)` lê o arquivo composite e o carrega na memória. Em uma scene normal construída com `@dcl/sdk`, um composite provider já está configurado para você; você o acessa com a `getCompositeProvider()` function de `@dcl/sdk/ecs`.

`Composite.instance()` então cria todas as entities descritas no composite, com todos os seus components, e retorna a **root entity** da árvore spawnada. Use essa entity retornada para ler ou alterar components mais tarde, por exemplo para reposicionar ou remover o item spawnado.

{% hint style="info" %}
**💡 Dica**: Para fazer a mesma coisa sem escrever código, use a **Spawn Entity** action no Scene Editor. Veja [Sobre spawnar entities](/creator/content-creator-pt/scene-editor/interatividade/smart-items-advanced.md#about-spawning-entities).
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Você deve carregar um composite antes de spawná-lo. `Composite.instance()` é síncrono e só pode spawnar um composite que já esteja na memória. Apenas `main.composite` vem incluído na sua scene e está disponível desde o início; qualquer outro arquivo composite deve ser carregado com `loadComposite()` primeiro. Para verificar de forma síncrona se um composite já está disponível, use `provider.getCompositeOrNull(src)`.

`loadComposite()` é idempotente: ele indexa cada composite pela sua `src` string, então chamá-lo novamente com o mesmo path não recarrega o arquivo; ele retorna o composite já carregado. Você pode chamá-lo com segurança antes de cada spawn sem se preocupar em carregar o mesmo arquivo duas vezes.
{% endhint %}

### Spawn em uma entity existente

Por padrão `Composite.instance()` cria uma nova entity para conter a árvore spawnada. Passe um `rootEntity` nas opções para spawnar em uma entity que você já tem:

```ts
// Spawn o composite diretamente na raiz da scene, sem entity wrapper
const barrel = Composite.instance(engine, resource, provider, {
  rootEntity: engine.RootEntity,
})
```

## Posicionar um composite spawnado

Para colocar o composite spawnado em uma posição, rotação ou escala específicas, defina um `Transform` component na root entity retornada 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);

  // Spawn o composite em uma posição específica
  const barrel = Composite.instance(engine, resource, provider);
  Transform.createOrReplace(barrel, {
    position: Vector3.create(8, 0, 8),
  });
}
```

{% hint style="warning" %}
**📔 Nota**: `Transform.createOrReplace()` substitui o Transform component existente da root entity. Apenas a root entity é afetada; as child entities mantêm suas posições relativas à root.
{% endhint %}

## Limitação atual: nested composites

Spawnar funciona para composites autocontidos e Custom Items. Um composite pode referenciar outro composite a partir de uma de suas entities, mas `loadComposite()` faz **não** recursiona nessas referências aninhadas: ele apenas carrega o arquivo que você lhe passa.

Ao spawnar, `Composite.instance()` recursiona em referências aninhadas que já estão na memória. Se um nested composite não estiver carregado (qualquer coisa diferente de `main.composite`, o único composite incluído na sua scene), esse ramo registra um warning e é ignorado. Para spawnar um composite com referências aninhadas, chame `loadComposite()` primeiro para cada arquivo referenciado — ou, mais simples, mantenha os composites que você spawnar autocontidos.

## Páginas relacionadas

* [Entities & Components](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md) — os blocos de construção que um composite descreve.
* [Custom Items](/creator/content-creator-pt/scene-editor/interatividade/custom-items.md) — itens reutilizáveis armazenados como composites.
* [Smart Items - Avançado](/creator/content-creator-pt/scene-editor/interatividade/smart-items-advanced.md#about-spawning-entities) — spawn composites sem código, usando a ação Spawn Entity.
* [Arquivos da scene](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-files.md) — onde `main.composite` fica no seu projeto de scene.


---

# 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-pt/scenes-sdk7/arquitetura/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.