Composites

Genera un árbol de entities y components en tiempo de ejecución a partir de un archivo compuesto

A composite es un archivo que describe un árbol de entities y components. 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. Este archivo se carga automáticamente cuando empieza tu escena.

• Custom Items 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:

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.

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

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

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:

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

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),
  });
}

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

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 — los bloques de construcción que describe un composite.

• Custom Items — elementos reutilizables almacenados como composites.

• Smart Items - Advanced — genera composites sin código, usando la acción Spawn Entity.

• Archivos de escena — donde main.composite vive en tu proyecto de escena.