Multiplayer sin servidor

Sincroniza el estado de la escena entre jugadores.

Decentraland ejecuta las Scenes localmente en la instancia de un jugador del explorer. De forma predeterminada, los jugadores pueden verse entre sí e interactuar directamente, pero cada jugador interactúa con el entorno de manera independiente. Los cambios en el entorno no se comparten entre jugadores por defecto.

Ver el mismo contenido en el mismo estado es extremadamente importante para que los jugadores interactúen de maneras más significativas.

Hay tres formas de sincronizar el estado de la Scene, para que todos los jugadores vean lo mismo:

• Marcar una entity como sincronizada: La opción más fácil. Ver Marcar una entity como sincronizada

• Enviar mensajes explícitos de MessageBus: Enviar y escuchar manualmente mensajes específicos. Ver Enviar mensajes explícitos de MessageBus

• Usar un Authoritative Server: Ver Authoritative Servers. El server valida todos los cambios de estado y es la única fuente de verdad. Requiere más configuración, pero se recomienda encarecidamente cuando los jugadores tienen incentivos para explotar tu Scene.

Las dos primeras opciones se cubren en este documento. Son más simples, ya que no requieren server. La desventaja es que dependes más de las velocidades de conexión del jugador, y el estado de la Scene no se mantiene cuando todos los jugadores salen de la Scene.

Marcar una Entity como sincronizada

En el Creator Hub, marca una entity como sincronizada añadiéndole un componente Multiplayer . Incluye una casilla para cada uno de los demás componentes de la entity, lo que te permite seleccionar cuáles actualizar.

Para marcar una entity como sincronizada mediante código, usa la syncEntity function:

import { syncEntity } from "@dcl/sdk/network";

const doorEntity = engine.addEntity();

syncEntity(doorEntity, [Transform.componentId, Animator.componentId], 1);

📔 Nota: En el multiplayer sin server, cada client llama a syncEntity por su cuenta. Si actualizas a un Authoritative Server, el patrón cambia: solo el server debería llamar a syncEntity, protegido por isServer(). Los clients deberían evitar declarar la sincronización de entities compartidas, a menos que hayan sido creadas por el client.

El syncEntity function recibe las siguientes entradas:

• entityId: Una referencia a la entity que se va a sincronizar

• componentIds: Una lista de los componentes que necesitan sincronizarse de esa entity. Es un array que puede contener tantas entities como sea necesario. Todos los valores deben ser propiedades de componentId .

• entityEnumId: (opcional) Un id único que se usa de forma consistente por todos los jugadores, ver About enum id.

No todas las entities o componentes necesitan sincronizarse. Los elementos estáticos, como un árbol que permanece en el mismo lugar, no requieren sincronización. En las entities que sí sincronizas, solo deben sincronizarse los componentes que cambian con el tiempo. Por ejemplo, si un cubo cambia de color al hacer click, solo deberías sincronizar el componente Material, no el MeshRenderer ni el Transform, ya que esos nunca cambiarán.

💡 Consejo: Si los datos que quieres compartir no existen como componente, define un componente personalizado que contenga esos datos.

Acerca del enum id

El entityEnumId de una entity debe ser único. No está relacionado con el entityId local asignado por engine.addEntity(), que se genera automáticamente y puede variar entre los jugadores que ejecutan la misma Scene. El entityEnumId de una entity debe definirse explícitamente en el código y ser único.

Establecer explícitamente este ID es importante para evitar inconsistencias si una condición de carrera hace que una parte de la Scene cargue antes que otra. Quizá para el jugador A la puerta de la Scene sea la entity 512, pero para el jugador B esa misma puerta es la entity 513. En ese caso, si el jugador A abre la puerta, el jugador B ve en su lugar que todo el edificio se mueve.

💡 Consejo: Crea un enum en tu Scene, para mantener referencias claras a cada id sincronizable en tu Scene.

import { syncEntity } from "@dcl/sdk/network";

enum EntityEnumId {
  DOOR = 1,
  DRAW_BRIDGE = 2,
  ELEVATOR = 3,
}

syncEntity(
  doorEntity,
  [Transform.componentId, Animator.componentId],
  EntityEnumId.DOOR
);

Aquí el enum EntityEnumId se usa para etiquetar entities con un identificador único, asegurando que cada client reconozca la entity modificada, independientemente del orden de creación.

📔 Nota: Evita usar números mayores que 8001 si tu Scene también incluye Smart Items. Los Items que son creados por el Creator Hub con un componente Multiplayer usarán IDs asignados automáticamente a partir de 8001. Cualquier ID menor que 8001 es seguro para asignar a tus entities sincronizadas.

Entities creadas por un jugador

Si una entity se crea como resultado de la interacción de un jugador, y esta entity debe sincronizarse con otros jugadores, la entity no necesita un entityEnumId. Puedes usar syncEntity() pasando solo la entity y la lista de componentes. Un valor único para entityEnumId se asigna automáticamente entre bastidores.

Todas las entities instanciadas al iniciar la Scene necesitan tener un ID asignado manualmente. Eso es para garantizar que todos los jugadores usen el mismo ID en cada una. Cuando un solo jugador está a cargo de instanciar una entity, no se necesitan IDs explícitos. Los demás jugadores reciben actualizaciones sobre esta nueva entity con un ID ya asignado, por lo que no hay riesgo de desajustes de IDs.

Por ejemplo, en una Scene de pelea de bolas de nieve, cada vez que un jugador lanza una bola de nieve, está instanciando una nueva entity que se sincroniza con otros jugadores. La bola de nieve no necesita un entityEnumId único.

import { syncEntity } from "@dcl/sdk/network";

function onThrow() {
  const ball = engine.addEntity();
  Transform.create(ball, {});
  GLTFContainer.create(ball, { src: "assets/snowBall.glb" });
  syncEntity(ball, [Transform.componentId, GLTFContainer.componentId]);
}

Entities parentadas

El padre de una entity normalmente se define mediante parent propiedad en el Transform component. Sin embargo, esta propiedad apunta al entity id local del padre, que podría variar, ver About enum id. Para parentar entities que necesitan sincronizarse, o que tienen hijos que necesitan sincronizarse, usa la parentEntity() function en lugar de la Transform.

import { syncEntity, parentEntity } from "@dcl/sdk/network";

const parent = engine.addEntity();
Transform.create(parent, { position: somePosition });
syncEntity(parent, []);

const child: Entity = engine.addEntity();
syncEntity(child, [Transform.componentId]);

parentEntity(child, parent);

Ten en cuenta que tanto el padre como el hijo se sincronizan con syncEntity, así que todos los jugadores tienen una comprensión común de qué ids usan ambas entities. Esto es necesario incluso si los componentes del padre quizá nunca necesiten cambiar. En este ejemplo, la syncEntity incluye un array vacío de componentes, para evitar sincronizar componentes innecesarios.

📔 Nota: Si una entity tiene como padre tanto el parentEntity() como también el parent propiedad en el Transform component, la propiedad en el Transform component se ignora.

Cuando las entities se parentan mediante la parentEntity() function, también puedes hacer uso de las siguientes funciones auxiliares:

• removeParent(): Deshace los efectos de parentEntity(). Requiere que pases solo la entity hija. El nuevo padre de la entity pasa a ser la root entity de la Scene. La entity padre original no se elimina de la Scene.

• getParent(): Devuelve la entity padre de una entity que hayas pasado.

• getChildren(): Devuelve la lista de hijos de la entity que hayas pasado, como un iterable.

• getFirstChild(): Devuelve el primer hijo de la lista de la entity que hayas pasado.

import { syncEntity, parentEntity } from "@dcl/sdk/network";

const parent = engine.addEntity();
Transform.create(parent, { position: somePosition });
syncEntity(parent, []);

const child: Entity = engine.addEntity();
syncEntity(child, [Transform.componentId]);

// establece parent como padre
parentEntity(child, parent);

// getParent
const getParentResult = getParent(child);
// devuelve parent

// getFirstChild
const getFirstChildResult = getFirstChild(parent);
// devuelve child

// getChildren
const getChildrenResult = Array.from(getChildren(parent));
// devuelve [child]

// quita el padre de child
removeParent(child);

Comprueba el estado de sincronización

Cuando un jugador acaba de cargar en una Scene, es posible que todavía no esté sincronizado con los otros jugadores que lo rodean. Si el jugador empieza a alterar el estado del juego antes de estar sincronizado, esto podría causar problemas en tu juego. Recomendamos comprobar siempre que un jugador esté sincronizado antes de permitirle editar cualquier cosa de la Scene.

Si un jugador sale de los parcels de la Scene, también quedará fuera de sincronización con la Scene mientras permanezca fuera. Por eso también es importante que los systems de la Scene manejen ese escenario, ya que la Scene sigue ejecutándose mientras el jugador esté cerca. Cuando el jugador vuelva a entrar, se le actualizará automáticamente con cualquier cambio del estado de la Scene.

Puedes comprobar si el estado de la Scene está sincronizado actualmente para un jugador mediante la isStateSyncronized() function. Esta function devuelve un boolean, que es true si el jugador ya está sincronizado con la Scene.

import { isStateSyncronized } from "@dcl/sdk/network";

const isConnected = isStateSyncronized();

Por ejemplo, podrías incluir esta comprobación en un system y bloquear cualquier interacción si esta function devuelve false.

import { isStateSyncronized } from "@dcl/sdk/network";

engine.addSystem(() => {
  if (isStateSyncronized() && !button.enabled) {
    console.log("Enable Start Game");
    button.enable();
  }

  if (!isStateSyncronized() && button.enabled) {
    console.log(`Disable Start Game.`);
    button.disable();
  }
});

Enviar mensajes explícitos de MessageBus

Iniciar un message bus

Crea un objeto message bus para gestionar los métodos necesarios para enviar y recibir mensajes entre jugadores.

import { MessageBus } from "@dcl/sdk/message-bus";

const sceneMessageBus = new MessageBus();

Enviar mensajes

Usa la .emit command del message bus para enviar un mensaje a todos los demás jugadores de la Scene.

import { MessageBus } from "@dcl/sdk/message-bus";

const sceneMessageBus = new MessageBus();

const myEntity = engine.addEntity();
MeshRenderer.setBox(myEntity);
MeshCollider.setBox(myEntity);

pointerEventsSystem.onPointerDown(
  {
    entity: myEntity,
    opts: { button: InputAction.IA_PRIMARY, hoverText: "Click" },
  },
  function () {
    sceneMessageBus.emit("box1Clicked", {});
  }
);

Cada mensaje puede contener un payload como segundo argumento. El payload es de tipo Object, y puede contener cualquier dato relevante que quieras enviar.

import { MessageBus } from "@dcl/sdk/message-bus";

const sceneMessageBus = new MessageBus();

sceneMessageBus.emit("spawn", { position: { x: 10, y: 2, z: 10 } });

💡 Consejo: Si necesitas que un solo mensaje incluya datos de más de una variable, crea un tipo personalizado para guardar todos esos datos en un solo objeto.

Recibir mensajes

Para manejar mensajes de todos los demás jugadores en esa Scene, usa .on. Al usar esta function, proporcionas una cadena de mensaje y defines una function que se ejecutará. Cada vez que llega un mensaje con una cadena coincidente, la function dada se ejecuta una vez.

import { MessageBus } from "@dcl/sdk/message-bus";

const sceneMessageBus = new MessageBus();

type NewBoxPosition = {
  position: { x: number; y: number; z: number };
};

sceneMessageBus.on("spawn", (info: NewBoxPosition) => {
  const myEntity = engine.addEntity();
  Transform.create(myEntity, {
    position: { x: info.position.x, y: info.position.y, z: info.position.z },
  });
  MeshRenderer.setBox(myEntity);
  MeshCollider.setBox(myEntity);
});

📔 Nota: Los mensajes enviados por un jugador también son recibidos por ese mismo jugador. El .on method no puede distinguir entre un mensaje emitido por ese mismo jugador y un mensaje emitido por otros jugadores.

Ejemplo completo de MessageBus

Este ejemplo usa un message bus para enviar un nuevo mensaje cada vez que se hace click en el cubo principal, generando un nuevo cubo en una posición aleatoria. El mensaje incluye la posición del nuevo cubo, de modo que todos los jugadores vean estos nuevos cubos en las mismas posiciones.

import { MessageBus } from "@dcl/sdk/message-bus";

/// --- Crear message bus ---
const sceneMessageBus = new MessageBus();

// Fábrica de cubos
function createCube(x: number, y: number, z: number): Entity {
  const meshEntity = engine.addEntity();
  Transform.create(meshEntity, { position: { x, y, z } });
  MeshRenderer.setBox(meshEntity);
  MeshCollider.setBox(meshEntity);

  // Cuando se hace click en un cubo, enviar un mensaje para generar otro
  pointerEventsSystem.onPointerDown(
    {
      entity: myEntity,
      opts: { button: InputAction.IA_PRIMARY, hoverText: "Press E to spawn" },
    },
    function () {
      sceneMessageBus.emit("spawn", {
        position: {
          x: 1 + Math.random() * 8,
          y: Math.random() * 8,
          z: 1 + Math.random() * 8,
        },
      });
    }
  );

  return meshEntity;
}

// Inicio
createCube(8, 1, 8);

// definir tipo de datos
type NewBoxPosition = {
  position: { x: number; y: number; z: number };
};

// al recibir el mensaje spawn, crear un nuevo cubo
sceneMessageBus.on("spawn", (info: NewBoxPosition) => {
  createCube(info.position.x, info.position.y, info.position.z);
});

Probar localmente una escena multijugador

Si lanzas una vista previa de la escena y la abres en dos (o más) ventanas de Explorer diferentes, cada ventana abierta se interpretará como un jugador distinto, y un servidor de comunicaciones simulado mantendrá a estos jugadores sincronizados.

Interactúa con la escena en una ventana y luego cambia a la otra para ver que los efectos de esa interacción también son visibles allí.

Usando Creator Hub, haz clic en el botón Preview una segunda vez, y eso abrirá una segunda ventana del explorer de Decentraland. Debes conectarte en ambas ventanas con direcciones diferentes. Las mismas sesiones permanecerán abiertas mientras la escena se recarga.

Como alternativa, puedes abrir una segunda ventana de Explorer de Decentraland escribiendo lo siguiente en una URL del navegador:

decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&multi-instance=true

Escenas de un solo jugador

Si tu Scene se despliega en un Decentraland World, puedes convertirla en una Scene de un solo jugador. Los jugadores no se verán entre sí, no podrán chatear ni ver los efectos de las acciones de los demás.

Para hacer esto, configura el scene.json archivo de la Scene para establecer el fixedAdapter a offline:offline. La Scene no tendrá ningún Communication Service en absoluto y cada usuario que entre en ese World siempre estará solo.

Ejemplo:

{
  "worldConfiguration": {
    "name": "my-name.dcl.eth",
    "fixedAdapter": "offline:offline"
  }
}