> 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/rede/serverless-multiplayer.md).

# Multiplayer sem Servidor

Sincronize o estado da scene entre jogadores.

Decentraland executa as scenes localmente na instância do Explorer de cada jogador. Por predefinição, os jogadores conseguem ver-se e interagir diretamente, mas cada jogador interage com o ambiente de forma independente. Por predefinição, as alterações ao ambiente não são partilhadas entre os jogadores.

É extremamente importante que os jogadores vejam o mesmo conteúdo no mesmo estado, para poderem interagir de formas mais significativas.

Há três formas de sincronizar o estado da scene, para que todos os jogadores vejam o mesmo:

* **Marcar uma Entity como sincronizada**: A opção mais fácil. Consulte [Marcar uma Entity como sincronizada](#mark-an-entity-as-synced)
* **Enviar mensagens explícitas do MessageBus**: Envie e ouça manualmente mensagens específicas. Consulte [Enviar mensagens explícitas do MessageBus](#send-explicit-messagebus-messages)
* **Usar um servidor multiplayer**: Consulte [Servidor multiplayer](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/authoritative-servers.md). O servidor valida todas as alterações de estado e é a única fonte de verdade. Requer mais configuração, mas é altamente recomendado quando os jogadores têm incentivos para explorar a sua scene.

As duas primeiras opções são abordadas neste documento. São mais simples, pois não requerem um servidor. A desvantagem é que dependem mais da velocidade da ligação dos jogadores, e o estado da scene não persiste quando todos os jogadores saem da scene.

## Marcar uma Entity como sincronizada

No [Creator Hub](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md), marque uma Entity como sincronizada adicionando-lhe um **componente Multiplayer** . Este inclui uma caixa de seleção para cada um dos outros componentes da Entity, permitindo-lhe selecionar quais devem ser atualizados.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-3c4e9da9a4f012190b0cfd80e26ad80580ab9ba7%2Fmultiplayer-component.webp?alt=media)

Para marcar uma Entity como sincronizada através de código, use a função `syncEntity` :

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

export function main() {
  const doorEntity = engine.addEntity();

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

{% hint style="warning" %}
**📔 Nota**: Chame sempre `syncEntity()` dentro da função `main()` ou numa função executada posteriormente `main()` (como um callback ou um sistema). Chamá-la no nível superior de um ficheiro gera um erro, porque, nessa altura, o perfil do jogador ainda não foi inicializado.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: No multiplayer sem servidor, cada cliente chama `syncEntity` por conta própria. Se atualizar para um [Servidor multiplayer](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/authoritative-servers.md), o padrão muda: só o servidor deve chamar `syncEntity`, com a condição `isServer()`. Os clientes devem evitar declarar a sincronização de Entities partilhadas, a menos que tenham sido criadas pelo cliente.
{% endhint %}

A função `syncEntity` aceita os seguintes parâmetros:

* **entityId**: Uma referência à Entity a sincronizar
* **componentIds**: Uma lista dos componentes dessa Entity que devem ser sincronizados. É uma matriz que pode conter tantos componentes quantos forem necessários. Todos os valores devem ser `componentId` propriedades.
* **entityEnumId**: (opcional) Um ID exclusivo que é usado de forma consistente por todos os jogadores. Consulte [Sobre o ID de enumeração](#about-the-enum-id).

Nem todas as entidades ou componentes precisam de sincronização. Elementos estáticos, como uma árvore que permanece no mesmo sítio, não precisam de ser sincronizados. Nas entidades que sincroniza, só devem ser sincronizados os componentes que mudam ao longo do tempo. Por exemplo, se um cubo mudar de cor quando lhe clicam, só deve sincronizar o componente Material, e não o MeshRenderer ou o Transform, uma vez que estes nunca mudam.

{% hint style="info" %}
**💡 Sugestão**: Se os dados que pretende partilhar não existirem como componente, defina um [componente personalizado](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) que contenha esses dados.
{% endhint %}

### Sobre o ID de enumeração

O **entityEnumId** de uma entidade tem de ser exclusivo. Não está relacionado com o entityId local atribuído por `engine.addEntity()`, que é gerado automaticamente e pode variar entre jogadores que executam a mesma cena. O entityEnumId de uma entidade tem de ser definido explicitamente no código e ser exclusivo.

Definir este ID explicitamente é importante para evitar inconsistências caso uma condição de corrida faça com que uma parte da cena seja carregada antes de outra. Talvez, para o jogador A, a porta na cena seja a entidade *512*, mas, para o jogador B, essa mesma porta seja a entidade *513*. Nesse caso, se o jogador A abrir a porta, o jogador B verá o edifício inteiro a mover-se.

{% hint style="info" %}
**💡 Sugestão**: Crie uma enumeração na sua cena para manter referências claras a cada ID sincronizável da cena.

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

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

export function main() {
  syncEntity(
    doorEntity,
    [Transform.componentId, Animator.componentId],
    EntityEnumId.DOOR
  );
}
```

Aqui, a enumeração EntityEnumId é utilizada para identificar entidades com um identificador exclusivo, garantindo que todos os clientes reconhecem a entidade modificada, independentemente da ordem de criação.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Evite utilizar números superiores a **8001** se a sua cena também incluir Smart Items. Os itens criados pelo [Creator Hub](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md) com um componente Multiplayer utilizam IDs atribuídos automaticamente a partir de 8001. Qualquer ID inferior a 8001 pode ser atribuído em segurança às entidades sincronizadas.
{% endhint %}

**Entidades criadas por um jogador**

Se uma entidade for criada como resultado de uma interação do jogador e tiver de ser sincronizada com outros jogadores, não precisa de um entityEnumId. Pode utilizar `syncEntity()` passando apenas a entidade e a lista de componentes. É atribuído automaticamente, nos bastidores, um valor exclusivo para entityEnumId.

Todas as entidades instanciadas no início da cena têm de ter um ID atribuído manualmente. Isto garante que todos os jogadores utilizam o mesmo ID para cada entidade. Quando um único jogador é responsável por instanciar uma entidade, não são necessários IDs explícitos. Os outros jogadores recebem atualizações sobre essa nova entidade com um ID já atribuído, pelo que não há risco de incompatibilidade entre IDs.

Por exemplo, numa cena de uma luta de bolas de neve, sempre que um jogador lança uma bola de neve, instancia uma nova entidade que é sincronizada com os outros jogadores. A bola de neve não precisa de um entityEnumId exclusivo.

```ts
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]);
}
```

### Entidades subordinadas <a href="#parented-entities" id="parented-entities"></a>

O elemento principal de uma entidade é normalmente definido através da propriedade `parent` no `Transform` componente. No entanto, esta propriedade aponta para o ID da entidade local do elemento principal, que pode variar. Consulte [Sobre o ID do enum](#about-the-enum-id). Para entidades principais que precisam de ser sincronizadas, ou que tenham elementos subordinados que precisam de ser sincronizados, use a `parentEntity()` função em vez da `Transform`.

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

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

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

  parentEntity(child, parent);
}
```

Tenha em conta que tanto o elemento principal como o subordinado são sincronizados com `syncEntity`, para que todos os jogadores tenham uma compreensão comum dos IDs utilizados por ambas as entidades. Isto é necessário mesmo que nunca seja preciso alterar os componentes do elemento principal. Neste exemplo, `syncEntity` inclui uma matriz vazia de componentes, para evitar sincronizar componentes desnecessários.

{% hint style="warning" %}
**📔 Nota**: Se uma entidade tiver um elemento principal definido tanto por `parentEntity()` como pela propriedade `parent` no componente `Transform` , a propriedade no componente `Transform` é ignorada.
{% endhint %}

Quando as entidades são definidas como elementos subordinados através da função `parentEntity()` , também pode utilizar as seguintes funções auxiliares:

* **removeParent()**: Anula os efeitos de `parentEntity()`. É necessário passar apenas a entidade subordinada. A nova entidade principal da entidade passa a ser a entidade raiz da cena. A entidade principal original não é removida da cena.
* **getParent()**: Devolve a entidade principal da entidade que passou.
* **getChildren()**: Devolve a lista dos elementos subordinados da entidade que passou, como iterável.
* **getFirstChild()**: Devolve o primeiro elemento subordinado da lista da entidade que passou.

```ts
import {
  syncEntity,
  parentEntity,
  getParent,
  getFirstChild,
  getChildren,
  removeParent,
} from "@dcl/sdk/network";

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

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

  // define parent como elemento principal
  parentEntity(child, parent);

  // getParent
  const getParentResult = getParent(child);
  // devolve o elemento principal

  // getFirstChild
  const getFirstChildResult = getFirstChild(parent);
  // devolve o filho

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

  // remove o pai do filho
  removeParent(child);
}
```

## Verificar o estado de sincronização

Quando um jogador entra numa cena, pode ainda não estar sincronizado com os outros jogadores que se encontram nas proximidades. Se o jogador começar a alterar o estado do jogo antes de estar sincronizado, isso pode causar problemas no jogo. Recomendamos que verifique sempre se o jogador está sincronizado antes de lhe permitir alterar qualquer elemento da cena.

Se um jogador sair dos parcels da cena, também ficará dessincronizado com a cena enquanto permanecer no exterior. Por isso, é importante que os sistemas da cena também tratem este cenário, uma vez que a cena continua a ser executada enquanto o jogador estiver nas proximidades. Quando o jogador voltar a entrar, será atualizado automaticamente com quaisquer alterações ao estado da cena.

Pode verificar se o estado da cena está atualmente sincronizado para um jogador através da função `isStateSyncronized()` Esta função devolve um valor booleano, que é verdadeiro se o jogador já estiver sincronizado com a cena.

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

const isConnected = isStateSyncronized();
```

Por exemplo, pode incluir esta verificação num sistema e bloquear qualquer interação se esta função devolver false.

```ts
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 mensagens explícitas do MessageBus

{% hint style="warning" %}
**📔 Nota**: A API `MessageBus` está marcada como obsoleta no SDK e poderá ser removida numa versão futura. Na maioria dos casos de utilização, prefira [marcar as entidades como sincronizadas](#mark-an-entity-as-synced).
{% endhint %}

**Iniciar um message bus**

Crie um objeto message bus para gerir os métodos necessários para enviar e receber mensagens entre jogadores.

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

const sceneMessageBus = new MessageBus();
```

**Enviar mensagens**

Utilize o comando `.emit` do message bus para enviar uma mensagem a todos os outros jogadores na cena.

```ts
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: "Clique" },
  },
  function () {
    sceneMessageBus.emit("box1Clicked", {});
  }
);
```

Cada mensagem pode conter um payload como segundo argumento. O payload é do tipo `Object`, e pode conter quaisquer dados relevantes que pretenda enviar.

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

const sceneMessageBus = new MessageBus();

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

{% hint style="info" %}
**💡 Sugestão**: Se precisar de incluir numa única mensagem dados de mais do que uma variável, crie um tipo personalizado para reunir todos estes dados num único objeto.
{% endhint %}

**Receber mensagens**

Para processar mensagens de todos os outros jogadores nessa cena, utilize `.on`. Ao utilizar esta função, fornece uma string de mensagem e define uma função a executar. Sempre que chega uma mensagem com uma string correspondente, a função indicada é executada uma vez.

```ts
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);
});
```

{% hint style="warning" %}
**📔 Nota**: As mensagens enviadas por um jogador também são recebidas por esse mesmo jogador. O método `.on` não consegue distinguir entre uma mensagem emitida por esse mesmo jogador e uma mensagem emitida por outros jogadores.
{% endhint %}

**Exemplo completo de MessageBus**

Este exemplo utiliza um bus de mensagens para enviar uma nova mensagem sempre que se clica no cubo principal, gerando um novo cubo numa posição aleatória. A mensagem inclui a posição do novo cubo, para que todos os jogadores vejam estes novos cubos nas mesmas posições.

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

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

// Cube factory
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);

  // When a cube is clicked, send message to spawn another one
  pointerEventsSystem.onPointerDown(
    {
      entity: meshEntity,
      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;
}

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

// define type of data
type NewBoxPosition = {
  position: { x: number; y: number; z: number };
};

// on spawn message, create new cube
sceneMessageBus.on("spawn", (info: NewBoxPosition) => {
  createCube(info.position.x, info.position.y, info.position.z);
});
```

## Testar uma cena multijogador localmente

Se iniciar uma pré-visualização da Scene e a abrir em duas (ou mais) janelas diferentes do Explorer, cada janela aberta será interpretada como um jogador separado, e um servidor de comunicação simulado manterá estes jogadores sincronizados.

Interaja com a Scene numa janela e, em seguida, mude para a outra para ver que os efeitos dessa interação também são visíveis aí.

No Creator Hub, ative **Multi-Instance Preview** no submenu **Desktop Client** de **Play Options**, depois clique novamente no botão **Play** para abrir uma segunda janela do Explorer do Decentraland. Tem de iniciar sessão nas duas janelas com endereços diferentes. As mesmas sessões permanecerão abertas quando a cena for recarregada.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-10d53f215e20e8cf603bbf578d0b33df738d058f%2Fpreview-button.webp?alt=media)

Em alternativa, pode abrir uma segunda janela do Explorer da Decentraland escrevendo o seguinte num URL do browser:

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

## Cenas para um único jogador

Se a sua cena estiver implementada num [Decentraland World](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/publicacao/publishing-options.md#decentraland-worlds), pode torná-la numa cena para um único jogador. Os jogadores não se verão uns aos outros, não poderão conversar nem ver os efeitos das ações uns dos outros.

Para isso, configure o ficheiro `scene.json` da cena para definir **fixedAdapter** como `offline:offline`. A cena não terá qualquer Communication Service, e cada utilizador que entrar nesse World estará sempre sozinho.

**Exemplo:**

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


---

# 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/rede/serverless-multiplayer.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.
