> 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).

# Compostos

Spawn de uma árvore de entities e components em runtime a partir de um arquivo composto

Um *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 fazer spawn de tudo isso 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/primeiros-passos/about-editor.md)Scene Editor
* [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 mostra como fazer spawn de um composite a partir de código em runtime, por exemplo para fazer spawn de um Custom Item dinamicamente como parte da lógica da sua scene.

## Fazer spawn de um composite

Fazer spawn de um composite leva duas etapas: **carregar** o arquivo composite, depois **fazer spawn** dele. O carregamento é assíncrono e o spawn é síncrono, então o padrão é sempre carregar e depois fazer spawn:

```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 seu arquivo
  const resource = await provider.loadComposite(src);

  // 2. Faça spawn dele: 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`Scene Editor `getCompositeProvider()` função de `@dcl/sdk/ecs`.

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

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

{% hint style="warning" %}
**📔 Observação**: Você deve carregar um composite antes de fazer spawn dele. `Composite.instance()` é síncrono e só pode fazer spawn de um composite que já esteja na memória. Apenas `main.composite` vem incluído com 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 %}

### Fazer spawn em uma entity existente

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

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

## Posicionar um composite em spawn

Para colocar o composite em spawn 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);

  // Faça spawn do 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" %}
**📔 Observação**: `Transform.createOrReplace()` substitui o component Transform existente da root entity. Apenas a root entity é afetada; as child entities mantêm suas posições relativas à root.
{% endhint %}

## Limitação atual: composites aninhados

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

Ao fazer spawn, `Composite.instance()` recorre a referências aninhadas que já estão na memória. Se um composite aninhado não estiver carregado (qualquer coisa diferente de `main.composite`, o único composite incluído com sua scene), esse ramo registra um aviso e é ignorado. Para fazer spawn de um composite com referências aninhadas, chame `loadComposite()` primeiro para cada arquivo referenciado — ou, mais simples, mantenha os composites que você faz spawn 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) — faça spawn de 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` main.composite vive no projeto da sua 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 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-pt/scenes-sdk7/arquitetura/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.