Compositos

Gere uma árvore de entities e components em runtime a partir de um arquivo composite

Um composite é um arquivo que descreve uma árvore de entities e components. Em vez de escrever código para criar cada entity individualmente, você pode armazenar essa estrutura em um arquivo composite e instanciar 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. Esse arquivo é carregado automaticamente quando sua scene começa.

• Custom Items são salvos como composite.json arquivos. Cada Custom Item é um composite que você pode reutilizar entre scenes.

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

Instanciar um composite

Instanciar um composite requer dois passos: carregar o arquivo composite, depois instanciar ele. O carregamento é assíncrono e a instanciação é síncrona, então o padrão é sempre carregar e depois instanciar:

export async function spawnBarrel() {
  const src = "barrel.composite";

  // 1. Carregue o composite a partir do seu arquivo
  await engine.getCompositeProvider().loadComposite(src);

  // 2. Instancie-o: cria todas as suas entities e components
  const barrel = engine.addEntityFromComposite(src);
  return barrel;
}

engine.getCompositeProvider().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 engine.getCompositeProvider().

engine.addEntityFromComposite(src) então cria todas as entities descritas no composite, com todos os seus components, e retorna a root entity da árvore instanciada. Use essa entity retornada para ler ou alterar components mais tarde, por exemplo, para reposicionar ou remover o item instanciado.

💡 Dica: Para fazer a mesma coisa sem escrever código, use a Spawn Entity action no Scene Editor. Veja Sobre instanciar entities.

📔 Nota: Você deve carregar um composite antes de instanciá-lo. engine.addEntityFromComposite() é síncrona e só pode instanciar um composite que já esteja carregado. Se você a chamar em um composite que ainda não foi carregado, ela lança Composite "<src>" not found.. Se nenhum composite provider tiver sido definido, ela lança CompositeProvider has not been set..

loadComposite() é idempotente: ela identifica cada composite pelo seu src string, então chamá-la novamente com o mesmo caminho não recarrega o arquivo; ela retorna o composite já carregado. Você pode chamá-la com segurança antes de cada instância, sem se preocupar em carregar o mesmo arquivo duas vezes.

Posicione um composite instanciado

Passe uma opção transform para addEntityFromComposite() para colocar o composite instanciado em uma posição, rotação ou escala específica. Esse transform é aplicado à root entity.

import { Vector3 } from "@dcl/sdk/math";

export async function spawnBarrel() {
  const src = "barrel.composite";
  await engine.getCompositeProvider().loadComposite(src);

  // Instancie o composite em uma posição específica
  engine.addEntityFromComposite(src, {
    transform: {
      position: Vector3.create(8, 0, 8),
    },
  });
}

Os campos de transform (position, rotation, e scale) são todos opcionais. Qualquer campo que você omitir mantém o valor armazenado no composite.

📔 Nota: O transform que você passar substitui o componente Transform existente da root entity. Apenas a root entity é afetada; as child entities mantêm suas posições relativas à root.

Limitação atual: composites aninhados

A instanciação funciona para composites autônomos e Custom Items. Um composite pode referenciar outro composite a partir de uma de suas entities, mas o carregamento não faz recursão nessas referências aninhadas ainda.

Se a root de um composite instanciado referenciar outro composite (qualquer coisa além de main.composite, o único composite incluído na sua cena), ele falha ao instanciar. Por enquanto, mantenha os composites que você instancia autônomos.

Páginas relacionadas

• Entities & Components — os blocos de construção que um composite descreve.

• Custom Items — itens reutilizáveis armazenados como composites.

• Smart Items - Avançado — instancie composites sem código, usando a ação Spawn Entity.

• Arquivos de cena — onde main.composite fica no seu projeto de cena.