Composites

Genera un árbol de entities y components en runtime a partir de un archivo composite

Un composite es un archivo que describe un árbol de entities and components. En lugar de escribir código para crear cada entity una por una, puedes almacenar esa estructura en un archivo composite y generar todo con una sola llamada.

Puede que ya trabajes con composites sin darte cuenta:

• Cada scene tiene un main.composite archivo. Contiene todo lo que agregaste y configuraste visualmente en el Scene Editor. Este archivo se carga automáticamente cuando tu scene comienza.

• Custom Items se guardan como composite.json archivos. Cada Custom Item es un composite que puedes reutilizar en distintas scenes.

Esta página explica cómo generar un composite desde código en runtime, por ejemplo, para generar un Custom Item dinámicamente como parte de la lógica de tu scene.

Generar un composite

Generar un composite requiere dos pasos: cargar el archivo composite, luego generar lo. Cargar es asíncrono y generar es sincrónico, así que el patrón siempre es cargar y luego generar:

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

  // 1. Carga el composite desde su archivo
  await engine.getCompositeProvider().loadComposite(src);

  // 2. Genéralo: crea todas sus entities y components
  const barrel = engine.addEntityFromComposite(src);
  return barrel;
}

engine.getCompositeProvider().loadComposite(src) lee el archivo composite y lo carga en memoria. En una scene normal construida con @dcl/sdk, un composite provider ya está configurado para ti, y puedes acceder a él con engine.getCompositeProvider().

engine.addEntityFromComposite(src) luego crea todas las entities descritas en el composite, con todos sus components, y devuelve el 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 Acerca de generar entities.

📔 Nota: Debes cargar un composite antes de generarlo. engine.addEntityFromComposite() es sincrónico y solo puede generar un composite que ya esté cargado. Si lo llamas en un composite que no se ha cargado, lanza Composite "<src>" not found.. Si no se ha establecido ningún composite provider, lanza CompositeProvider has not been set..

loadComposite() es idempotente: indexa cada composite por su src cadena, así que volver a llamarlo con la misma ruta no vuelve a cargar el archivo; devuelve el composite ya cargado. Puedes llamarlo con seguridad antes de cada generación sin preocuparte por cargar el mismo archivo dos veces.

Coloca un composite generado

Pasa una transform opción a addEntityFromComposite() para colocar el composite generado en una posición, rotación o escala específicas. Este transform se aplica a la root entity.

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

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

  // Genera el composite en una posición específica
  engine.addEntityFromComposite(src, {
    transform: {
      position: Vector3.create(8, 0, 8),
    },
  });
}

Los campos de transform (position, rotation, y scale) son todos opcionales. Cualquier campo que omitas conserva el valor almacenado en el composite.

📔 Nota: El transform que pasas reemplaza el componente Transform existente de la root entity. Solo se ve afectada la root entity; las child entities mantienen sus posiciones relativas a la root.

Limitación actual: composites anidados

La generación funciona para composites autónomos y Custom Items. Un composite puede referenciar otro composite desde una de sus entities, pero la carga no no recorre esas referencias anidadas todavía.

Si la root de un composite generado referencia otro composite (cualquier cosa que no sea main.composite, el único composite incluido con tu scene), falla al instanciarse. Por ahora, mantén los composites que generes autónomos.

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.

• Scene Files — donde main.composite se encuentra en tu proyecto de scene.