> 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/authoritative-servers.md).

# Multiplayer Server

Crie scenes multiplayer do Decentraland com um multiplayer server sem interface.

**📔 Nota**: O Multiplayer Server era anteriormente chamado de **Authoritative Server**. Só o nome mudou; a funcionalidade é a mesma. O branch do SDK a instalar continua a chamar-se `auth-server`, consulte [Configuração](#setup).

## Visão geral

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

É extremamente importante permitir que todos os jogadores vejam uma scene com o mesmo conteúdo e no mesmo estado, para que possam interagir de formas mais significativas. Sem isto, se um jogador abrir uma porta e entrar numa casa, os outros jogadores continuarão a ver a porta fechada e verão o primeiro jogador atravessá-la como se estivesse aberta.

O **Multiplayer Server** é um processo de servidor sem interface que executa o código da sua scene, valida as alterações de estado e transmite o resultado a todos os jogadores ligados. Segue uma arquitetura de servidor autoritativo: em vez de confiar que cada client comunique as suas próprias ações, o servidor funciona como a única fonte de verdade. Esta é a abordagem recomendada para sincronizar scenes multijogador.

O Multiplayer Server é ideal sempre que a equidade seja importante para as mecânicas do jogo, pois permite implementar validações anti-batota elaboradas que são executadas no servidor. Também pode armazenar chaves privadas e outras informações sensíveis no servidor, sem nunca precisar de as expor diretamente ao utilizador.

Ter um Multiplayer Server também resolve um problema real: numa configuração peer-to-peer, dois jogadores a controlar algo como uma plataforma flutuante podem gerar resultados contraditórios. Cada client define uma altura diferente para a plataforma e não há ninguém com autoridade para decidir qual é a correta. O Multiplayer Server processa cada alteração num único local, para que todos os clients cheguem ao mesmo estado.

Também lhe dá um local para **persistir dados entre sessões**: tabelas de classificação, progressão dos jogadores, conquistas desbloqueadas ou alterações ao ambiente, como portas abertas ou itens colocados. Quando os jogadores regressam, o mundo reflete o que aconteceu anteriormente.

A Decentraland aloja e implementa o servidor por si. Ao publicar a sua scene pelo processo habitual, publica também o servidor de forma integrada, sem passos adicionais nem custos de alojamento.

## Configuração

### 1. Instale a versão do SDK auth-server

As APIs nativas do Multiplayer Server (`isServer`, `registerMessages`, `Storage`, `EnvVar`, etc.) estão disponíveis num branch separado do SDK.

**No Creator Hub**, abra as definições da scene e selecione **Enable Multiplayer Server** na secção **Advanced** do separador **Settings** . O Creator Hub instala o SDK correto e configura o ficheiro `scene.json` por si. Consulte [Multiplayer Server nas definições da scene](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/configurar/scene-settings.md#multiplayer-server).

**A partir da linha de comandos**, execute o seguinte comando para o instalar no seu projeto em vez do branch padrão do SDK:

```bash
npm install --save-exact @dcl/sdk@auth-server @dcl/js-runtime@auth-server
```

{% hint style="warning" %}
**📔 Nota**: Mantenha `--save-exact`. Sem esta opção, o npm guarda um intervalo de versões, como `^7.x.y-...` em `package.json`, e a próxima versão normal do SDK também corresponde a esse intervalo. Uma execução posterior de `npm install` pode então substituir a compilação auth-server por uma versão normal, que não inclui APIs de servidor, impedindo que o código do servidor seja compilado.
{% endhint %}

### 2. Configurar scene.json

O Multiplayer Server é ativado pela flag `"authoritativeMultiplayer": true` em `scene.json`, ao nível da raiz. Não precisa de a adicionar manualmente: ao usar a branch auth-server do SDK, é adicionada automaticamente na primeira vez que compilar ou pré-visualizar a scene. Certifique-se apenas de que não a remove; sem esta flag, o servidor nunca é executado e `isServer()` devolve sempre *false*.

Opcionalmente, também pode adicionar o seguinte ao seu `scene.json` ao nível da raiz:

```json
{
  "logsPermissions": ["0xYourWalletAddress"]
}
```

Adicione `logsPermissions` para dar a estas wallets acesso aos registos e às métricas do servidor após a publicação. No Creator Hub, a lista **Acesso aos registos e armazenamento** nas definições da scene permite-lhe editar este campo. Os proprietários de Worlds e os colaboradores elegíveis para publicação também têm acesso, tal como os proprietários de Genesis City e os gestores de LAND delegados da parcela base da scene. Consulte [Informações da scene](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/scene-insights.md) para obter informações sobre permissões, início de sessão e comandos.

### 3. Executar a pré-visualização

Use o comando de pré-visualização habitual; não são necessários passos adicionais. Ao usar a branch auth-server do SDK, a pré-visualização inicia automaticamente uma versão local do Multiplayer Server em segundo plano.

A sessão local do servidor não está ligada à versão em produção, pelo que pode testar à vontade sem afetar os jogadores que estão na sua scene publicada.

## Ramificação entre servidor e cliente

O código da scene na pasta `src` do seu projeto é executado tanto no servidor como no cliente. Use a função `isServer()` para dividir os caminhos de execução:

```typescript
import { isServer } from "@dcl/sdk/network"
import { initServer } from "./server/server"
import { initClient } from "./client/setup"
import { setupUi } from "./client/ui"

function main() {
  if (isServer()) {
    // Apenas no servidor: lógica do jogo, validação, gestão do estado
    initServer()
    return
  } else {
    // Apenas no cliente: UI, gestão de entradas, envio de mensagens
    initClient()
    setupUi()
  }
}
```

O servidor executa a sua scene sem interface gráfica nem renderização. Tem acesso verificado a todas as posições dos jogadores, aos wearables e a outros dados através de `PlayerIdentityData` e é a única autoridade sobre o estado do jogo.

## Componentes sincronizados e validação

### Sincronizar Entities com todos os clientes

Use `syncEntity` para transmitir quaisquer alterações nos componentes indicados dessa Entity:

```typescript
import { isServer, syncEntity } from "@dcl/sdk/network"

if (isServer()) {
  syncEntity(
    entity,
    [Transform.componentId, GameState.componentId],
    /* enumId */ 1
  )
}
```

A sintaxe é idêntica à utilizada pela [Multijogador sem servidor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/serverless-multiplayer.md) funcionalidade, o que torna muito simples atualizar uma cena que utiliza esta arquitetura para o Multiplayer Server. Quando uma cena utiliza o Multiplayer Server, as atualizações de estado deixam de ser enviadas entre todos os jogadores; em vez disso, todas as atualizações de estado passam a ser encaminhadas e validadas pelo servidor.

{% hint style="warning" %}
**📔 Nota**: Com o Multiplayer Server, o padrão ideal é fazer com que apenas o servidor chame `syncEntity`. Assim, não precisa de se preocupar com a consistência dos IDs das entidades. Em vez disso, a entidade é instanciada e partilhada pelo servidor, e todos os clientes são sincronizados com essa instância. Proteja sempre essa chamada com `isServer()`. Isto é diferente do [Multijogador sem servidor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/serverless-multiplayer.md), em que cada cliente chama `syncEntity` por si próprio.
{% endhint %}

### Validar alterações

Utilize `validateBeforeChange()` para restringir quaisquer atualizações de estado num componente específico de uma entidade. Esta função permite executar uma função de validação personalizada, e as alterações só são aplicadas se o teste de validação for aprovado.

Se a validação devolver o valor *true*, a alteração é aceite e propagada a todos os jogadores. Se a validação devolver o valor *false*, a alteração é rejeitada. Uma alteração rejeitada não é transmitida aos outros jogadores e é revertida para o jogador que tentou efetuá-la.

#### Validar valores

O caso mais simples consiste em validar se o novo *valor* que está a ser escrito se encontra dentro de determinados parâmetros. Por exemplo, aceitar alterações a um `Transform` apenas quando a nova posição Y é superior a 0:

```typescript
import { engine, Transform } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const entity = engine.addEntity()
Transform.create(entity, { position: Vector3.create(10, 2, 10) })

if (isServer()) {
  Transform.validateBeforeChange(entity, (value) => {
    // Rejeita qualquer atualização que coloque a entidade em Y = 0 ou abaixo
    return value.newValue.position.y > 0
  })
}
```

Como `validateBeforeChange()` só tem utilidade no servidor, proteja sempre essa chamada com `isServer()`. No cliente, a chamada não tem qualquer utilidade.

Pode utilizar esta função para impedir alterações que contrariem a lógica do seu jogo, como mecanismo antibatota.

#### Validar a proximidade do jogador

Pode combinar `validateBeforeChange()` com posições dos jogadores verificadas pelo servidor para confirmar se um jogador está suficientemente perto de um objeto antes de permitir que interaja com ele. Por exemplo, quando um jogador tenta apanhar um objeto alterando o seu `Transform`, pode rejeitar a alteração se o objeto estiver a mais de 5 metros do jogador:

```typescript
import { engine, Transform, PlayerIdentityData } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"

const pickableEntity = engine.addEntity()
Transform.create(pickableEntity, { position: Vector3.create(8, 1, 8) })

if (isServer()) {
  Transform.validateBeforeChange(pickableEntity, (value) => {
    // Encontra o jogador que enviou esta alteração
    for (const [playerEntity, identity] of engine.getEntitiesWith(
      PlayerIdentityData
    )) {
      if (identity.address.toLowerCase() !== value.senderAddress.toLowerCase())
        continue

      const playerTransform = Transform.getOrNull(playerEntity)
      if (!playerTransform) return false

      // Obtém a posição atual do objeto, antes da alteração
      const objectTransform = Transform.getOrNull(pickableEntity)
      if (!objectTransform) return false

      const distance = Vector3.distance(
        playerTransform.position,
        objectTransform.position
      )

      // Só permite a alteração se o jogador estiver a menos de 5 metros
      return distance <= 5
    }

    // Remetente não encontrado entre os jogadores ligados — rejeitar
    return false
  })
}
```

Este padrão é útil como mecanismo anti-cheat: impede os jogadores de atravessarem a cena para apanhar objetos com os quais não deveriam poder interagir.

#### Permitir alterações apenas por administradores

Também pode validar com base em *quem* está a enviar a alteração. Cada valor recebido inclui um campo `senderAddress` com o endereço da wallet do remetente. Use-o para permitir alterações apenas por determinados jogadores. Por exemplo, para permitir que apenas os administradores da cena modifiquem um componente `VideoPlayer`  :

```typescript
import { engine, VideoPlayer } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { isPreview } from "@dcl/asset-packs/dist/admin-toolkit-ui/fetch-utils"
import { getSceneAdmins } from "@dcl/asset-packs/dist/admin-toolkit-ui/ModerationControl/api"

// Cache de endereços de wallet dos administradores, atualizado a partir da lista de administradores da cena
let adminAddresses = new Set<string>()

async function updateAdminAddresses() {
  if (isPreview()) return
  try {
    const [error, response] = await getSceneAdmins()
    if (error) {
      console.error("[SERVER] Error fetching admin list:", error)
      adminAddresses = new Set()
      return
    }
    adminAddresses = new Set(
      (response ?? []).map((admin) => admin.admin.toLowerCase())
    )
    console.log(
      "[SERVER] Updated admin addresses cache:",
      Array.from(adminAddresses)
    )
  } catch (error) {
    console.error("[SERVER] Error updating admin addresses:", error)
    adminAddresses = new Set()
  }
}

export async function main() {
  const videoEntity = engine.addEntity()
  VideoPlayer.create(videoEntity, { src: "videos/intro.mp4" })

  if (isServer()) {
    // Preenche a cache antes de configurar a validação
    await updateAdminAddresses()

    VideoPlayer.validateBeforeChange(videoEntity, (value) => {
      // Permitir sempre alterações durante a execução em modo de pré-visualização, para facilitar os testes locais
      if (isPreview()) return true

      const senderAddress = value.senderAddress.toLowerCase()
      if (!adminAddresses.has(senderAddress)) {
        console.log(
          "[SERVER] Unauthorized VideoPlayer change blocked from:",
          senderAddress
        )
        return false
      }
      return true
    })
  }
}
```

Consulte [Scene Admin](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/operar-ao-vivo/scene-admin.md) para obter mais contexto sobre como os jogadores se tornam administradores de uma scene.

#### Envie intenções, nunca resultados

Sempre que houver pontuações, prémios ou recursos partilhados em jogo, estruture as mensagens do cliente em torno do que o jogador está **a tentar fazer**, e não em torno do resultado. Um cliente envia `claimPoint` ou `harvest`. Nunca envia "a minha pontuação agora é 40".

O servidor verifica então a mensagem: quem a enviou, se o jogo está numa fase que a permite, se o jogador está suficientemente perto e se ainda há algo para reclamar. Só então calcula o novo valor e grava-o. O servidor é o único responsável por escrever o estado do jogo.

Um cliente que pode definir a própria pontuação pode definir qualquer pontuação.

#### Permita alterações apenas pelo servidor

A abordagem mais rigorosa é aceitar apenas escritas originadas pelo próprio servidor, rejeitando qualquer alteração proveniente de um cliente. Este é o padrão indicado para estados que devem ser totalmente autoritativos: pontuações, fase do jogo, Entities geradas, etc.

Cada valor recebido inclui um campo `senderAddress` Quando o remetente é o servidor, este campo corresponde à constante `AUTH_SERVER_PEER_ID`, exportada por `@dcl/sdk/network/message-bus-sync`.

O exemplo abaixo define um pequeno auxiliar `protectServerEntity()` que aplica esta verificação a um ou mais Components numa determinada Entity. É uma forma prática de proteger vários Components (como `Transform` e `GltfContainer`) numa única chamada:

```typescript
import { engine, Entity, Transform, GltfContainer } from "@dcl/sdk/ecs"
import { Vector3 } from "@dcl/sdk/math"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

type ComponentWithValidation = {
  validateBeforeChange: (
    entity: Entity,
    cb: (value: { senderAddress: string }) => boolean
  ) => void
}

function protectServerEntity(
  entity: Entity,
  components: ComponentWithValidation[]
) {
  for (const component of components) {
    component.validateBeforeChange(entity, (value) => {
      return value.senderAddress === AUTH_SERVER_PEER_ID
    })
  }
}

if (isServer()) {
  // Depois de criar uma Entity gerida pelo servidor:
  const entity = engine.addEntity()
  Transform.create(entity, { position: Vector3.create(10, 5, 10) })
  GltfContainer.create(entity, { src: "assets/model.glb" })
  protectServerEntity(entity, [Transform, GltfContainer])
}
```

{% hint style="warning" %}
**📔 Nota**: Chame sempre `protectServerEntity()` dentro de um bloco `isServer()` . Ele envolve `validateBeforeChange()`, que só faz sentido no servidor — chamá-lo num cliente gera erros.
{% endhint %}

#### Componentes personalizados

Também pode aplicar `validateBeforeChange()` a componentes personalizados definidos pela cena.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

export const GameState = engine.defineComponent("game:State", {
  phase: Schemas.String,
  score: Schemas.Int,
  timeRemaining: Schemas.Int,
})

// Só o servidor pode modificar este componente
if (isServer()) {
  GameState.validateBeforeChange((value) => {
    return value.senderAddress === AUTH_SERVER_PEER_ID
  })
}
```

## Mensagens

Os componentes sincronizados são ótimos para estados que todos os jogadores devem ver continuamente: coisas como posições, pontuações ou a fase do jogo. Mas nem tudo se encaixa nesse modelo. Às vezes, um jogador só precisa dizer ao servidor «Cliquei neste botão» ou «Quero entrar no jogo», e o servidor precisa responder com uma resposta pontual, como «A ronda começou» ou «Aqui estão as suas estatísticas». Estes são eventos, não estados contínuos.

É para isso que servem as mensagens. Use `registerMessages()` para comunicação tipada e validada por esquema entre clientes e o servidor. As mensagens são enviadas sem esperar resposta: um cliente envia uma ao servidor, o servidor processa-a e, opcionalmente, envia uma de volta. Por si só, não criam diretamente nenhum estado persistente.

### Definir mensagens

Defina todas as mensagens num ficheiro partilhado que tanto o servidor como o cliente importam. Assim, ambos os lados estão sempre de acordo sobre as mensagens existentes e os dados que transportam. Cada mensagem é um `Schemas.Map` que descreve os respetivos dados:

```typescript
import { Schemas } from "@dcl/sdk/ecs"
import { registerMessages } from "@dcl/sdk/network"

export const Messages = {
  // Cliente → Servidor
  playerReady: Schemas.Map({ displayName: Schemas.String }),
  playerAction: Schemas.Map({ action: Schemas.String, targetId: Schemas.Int }),
  giveCoins: Schemas.Map({ to: Schemas.String, amount: Schemas.Int }),

  // Servidor → Cliente
  gameStarted: Schemas.Map({ roundNumber: Schemas.Int }),
  gameEnded: Schemas.Map({ winnerId: Schemas.String }),
}

export const room = registerMessages(Messages)
```

{% hint style="warning" %}
**📔 Nota**: Chame `registerMessages()` uma única vez, no nível superior de um módulo partilhado, como no exemplo acima. Assim, é executado quando o módulo é carregado pela primeira vez, tanto no servidor como no cliente. Não o chame condicionalmente nem dentro de funções; ambos os lados têm de registar sempre as mesmas mensagens.
{% endhint %}

### Enviar mensagens

Os clientes só podem enviar mensagens para o servidor. Não existe comunicação direta entre clientes. O servidor pode transmitir para todos os clientes ou direcionar mensagens a jogadores específicos através do respetivo endereço.

```typescript
import { room } from "./shared/messages"

// Cliente → Servidor (transmissão; o servidor recebe a mensagem)
room.send("playerReady", { displayName: "Alice" })

// Servidor → todos os clientes
room.send("gameStarted", { roundNumber: 1 })

// Servidor → um cliente específico (por endereço da carteira)
room.send("gameEnded", { winnerId: "Alice" }, { to: [playerAddress] })
```

{% hint style="warning" %}
**📔 Nota**: As mensagens têm um tamanho máximo de cerca de 13 KB. Mensagens maiores são descartadas silenciosamente pelo transporte, sem gerar qualquer erro. Mantenha os payloads pequenos; se precisar partilhar dados maiores, divida-os em várias mensagens ou use componentes sincronizados.
{% endhint %}

### Receber mensagens

```typescript
import { room } from "./shared/messages"

// O cliente recebe do servidor
room.onMessage("gameStarted", (data) => {
  console.log(`Round ${data.roundNumber} started!`)
})

// O servidor recebe do cliente
room.onMessage("playerReady", (data, context) => {
  if (!context) return
  const senderAddress = context.from // verified wallet address
  console.log(`[Server] ${data.displayName} is ready (${senderAddress})`)
})
```

No servidor, cada mensagem recebida inclui um objeto `context` com o endereço verificado da carteira do remetente. Use-o para identificar qual jogador enviou a mensagem (nunca confie numa identidade declarada pelo próprio no payload).

`context.from` é recebido exatamente como a rede o reporta, sem alterações entre maiúsculas e minúsculas. Converta-o para minúsculas uma única vez (`context.from.toLowerCase()`) e use esse valor em todos os mapas, conjuntos e chamadas a Storage, para que os dados de um jogador não acabem divididos entre duas chaves.

### Aguardar a sincronização do estado antes de enviar

Os clientes devem aguardar até que o estado da cena esteja sincronizado antes de enviar a primeira mensagem, para evitar condições de corrida ao entrar:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"
import { room } from "./shared/messages"

engine.addSystem(() => {
  if (!isStateSyncronized()) return

  // Agora é seguro enviar mensagens
  room.send("playerReady", { displayName: "Alice" })
})
```

{% hint style="info" %}
**💡 Sugestão**: `isStateSyncronized()` apenas indica que o estado do cliente está sincronizado; não garante que o servidor tenha concluído a inicialização. Para uma verificação de prontidão mais robusta, peça ao servidor que transmita uma mensagem «ready» ou de heartbeat e faça com que os clientes a aguardem antes de enviar mensagens de jogo.
{% endhint %}

### Tipos de esquema disponíveis

Todos os payloads de mensagens e os componentes personalizados usam `Schemas` para a serialização binária. Aqui está uma referência rápida dos tipos disponíveis:

```typescript
import { Schemas } from "@dcl/sdk/ecs"

// Tipos básicos
Schemas.String // "hello"
Schemas.Int // 42
Schemas.Float // 3.14
Schemas.Boolean // true / false
Schemas.Int64 // Date.now()

// Tipos de vetor
Schemas.Vector3 // { x: 1, y: 2, z: 3 }
Schemas.Quaternion // { x, y, z, w }

// Tipos complexos
Schemas.Array(Schemas.String) // ["a", "b", "c"]
Schemas.Entity // Entity reference
Schemas.Optional(Schemas.String) // "hello" or undefined
Schemas.Optional(Schemas.Int) // 42 or undefined

// Objetos aninhados
Schemas.Map({
  name: Schemas.String,
  health: Schemas.Int,
  position: Schemas.Vector3,
  playerId: Schemas.Optional(Schemas.String),
})
```

{% hint style="warning" %}
**📔 Nota**: Messages *tem de* ser definido com `Schemas.Map(...)`. Não pode enviar objetos JavaScript simples, pois a serialização binária irá falhar.
{% endhint %}

## Leitura das posições dos jogadores no servidor

O servidor pode ler as posições **verificadas** dos jogadores; os clientes não podem falsificá-las. Esta é a base do sistema anti-batota baseado na posição:

```typescript
import { engine, PlayerIdentityData, Transform } from "@dcl/sdk/ecs"

engine.addSystem(() => {
  for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
    const transform = Transform.getOrNull(entity)
    if (!transform) continue

    const address = identity.address
    const position = transform.position
    // Esta posição é verificada pelo servidor — nunca confie na posição comunicada pelo cliente
  }
})
```

{% hint style="warning" %}
**📔 Nota**: Utilize sempre `PlayerIdentityData` + `Transform` no servidor para obter as posições dos jogadores. Nunca confie nos valores comunicados pelo próprio cliente.
{% endhint %}

## Armazenamento de dados

Persista os dados entre reinícios do servidor. O armazenamento é **exclusivo do servidor**, proteja sempre as chamadas com `isServer()`. O servidor pode escrever e ler estes dados.

```typescript
import { Storage } from "@dcl/sdk/server"
```

Os dados podem ser armazenados em dois níveis:

* **World**: utilize esta opção para dados relevantes para todos os jogadores, como tabelas de classificação ou alterações persistentes ao ambiente.
* **Player**: utilize esta opção para dados específicos de cada jogador, como guardar o progresso ou as preferências desse jogador.

{% hint style="info" %}
**💡 Dica**: os valores do armazenamento são JSON. Pode armazenar um número, uma string, um array ou um objeto simples tal como estão e voltar a lê-los com o mesmo valor. Não precisa de `JSON.stringify()` nem de `JSON.parse()`. Há duas exceções: um `Date` é armazenado como texto ISO (`"2026-10-27T13:05:12.000Z"`) e as propriedades de objetos definidas como `undefined` são descartadas. Um valor que tenha guardado anteriormente com `JSON.stringify()` é uma string, pelo que será lido novamente como essa string.

Durante o desenvolvimento local, os dados são escritos em `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json`.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Como as chamadas de Storage comunicam problemas:

* `Storage.set()` e `Storage.player.set()` são resolvidas com um valor **booleano**. `false` significa que o valor não foi **persistido** , por exemplo, após um erro de rede ou quando demasiados pedidos são executados ao mesmo tempo (ver abaixo). Verifique sempre o resultado: um `false` descartado significa que os dados não foram guardados, sem qualquer aviso.
* `set()` gera um `TypeError` quando o valor não pode ser armazenado como JSON sem alterações: `undefined`, `NaN` ou `Infinity`, uma função, um `Map` ou um `Set`, entre outros. Para remover uma chave, use `delete()`.
* `get()` é resolvido com o valor armazenado ou com `null` apenas quando a chave não existe. Se a leitura falhar, é gerado um erro, por isso uma falha nunca é confundida com uma chave inexistente.
* As variantes de `delete()` geram um erro se o pedido falhar. São resolvidas com `false` apenas quando a chave não existia.
  {% endhint %}

### Guarde nos pontos de controlo, não a cada alteração

Storage é uma persistência duradoura para dados que têm de sobreviver a reinícios do servidor e a novas implementações. Não é um armazenamento de dados em tempo real. Mantenha o estado de jogo em curso na memória do servidor. É mais rápido e é o padrão adequado para um servidor. Escreva em Storage apenas quando for realmente necessário, em pontos de controlo significativos.

{% hint style="warning" %}
**⚠️ Aviso**: O runtime do servidor permite um máximo de **40 chamadas ao host em curso** ao mesmo tempo, partilhadas por *tudo* o que a cena pede ao runtime para fazer: cada pedido de Storage, `signedFetch`e outras APIs do runtime contam para o mesmo limite. As chamadas excedentes **não são colocadas em fila**. São rejeitadas imediatamente com um erro `too many concurrent host calls` . O SDK captura a rejeição e resolve o `Storage.set` promise a `false` em vez de lançar um erro. Se o seu código descartar esse valor booleano, a falha ao guardar passa despercebida e os dados persistidos ficam desatualizados ou perdem-se. Verifique o resultado de cada gravação (consulte a Nota acima).
{% endhint %}

Bons momentos para persistir os dados:

* Fim do jogo ou de uma ronda.
* Um jogador sai.
* Uma gravação periódica com debounce (por exemplo, uma vez a cada 30 segundos), não uma vez por frame.

Persista apenas os dados que têm de sobreviver a um reinício ou a uma nova implementação. Tudo o resto pode ficar na memória.

O exemplo abaixo mantém as pontuações na memória e só as grava num ponto de controlo, em vez de o fazer a cada ponto marcado:

```typescript
import { Storage } from "@dcl/sdk/server"

// O estado de trabalho fica na memória e é atualizado a cada evento
const scores: Record<string, number> = {}

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  // Não há chamadas a Storage aqui — apenas atualização da memória
}

// Persista apenas num ponto de controlo, como quando um jogador sai
async function onPlayerLeave(address: string) {
  const saved = await Storage.player.set(address, "score", scores[address] ?? 0)
  if (!saved) {
    // A gravação não foi persistida — mantenha o valor na memória e tente novamente mais tarde
    console.error(`Failed to save score for ${address}`)
  }
}
```

Para cenas com muitos jogadores em simultâneo, uma abordagem mais robusta acompanha as chaves com alterações ainda não guardadas (um «conjunto de alterações pendentes») e tenta novamente as gravações falhadas na próxima descarga:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// Estado de trabalho na memória, atualizado a cada evento
const scores: Record<string, number> = {}
const dirty = new Set<string>()

function onPointScored(address: string) {
  scores[address] = (scores[address] ?? 0) + 1
  dirty.add(address) // Marcar para descarga posterior; não há chamadas a Storage aqui
}

// Descarregar periodicamente as chaves com alterações pendentes (por exemplo, a cada ~30 s) e nos pontos de controlo
async function flush() {
  for (const address of dirty) {
    const ok = await Storage.player.set(address, "score", scores[address])
    if (ok) {
      dirty.delete(address) // Guardado com sucesso
    }
    // Se ok for false, a chave continua com alterações pendentes e será novamente tentada na próxima descarga
  }
}

// Executar a descarga com um temporizador usando um acumulador dt
let flushTimer = 0
engine.addSystem((dt) => {
  flushTimer += dt
  if (flushTimer > 30) {
    flushTimer = 0
    flush()
  }
})
```

### Armazenamento do World — partilhado por todos os jogadores

```typescript
import { Storage } from "@dcl/sdk/server"

type Entry = { name: string; score: number }

// Gravar — set() resolve para false se o valor NÃO tiver sido persistido
const ok = await Storage.set("leaderboard", [
  { name: "Alice", score: 100 },
  { name: "Bob", score: 85 },
])
if (!ok) {
  console.error("Failed to save leaderboard — retry later")
}

// Ler: null quando a chave não existe
const leaderboard = (await Storage.get<Entry[]>("leaderboard")) ?? []

// Eliminar
await Storage.delete("leaderboard")
```

Também pode gerir o armazenamento da cena através da linha de comandos, usando `npx sdk-commands storage scene`:

```bash
# Definir um valor
npx sdk-commands storage scene set high_score --value 100

# Obter um valor
npx sdk-commands storage scene get high_score

# Eliminar um valor
npx sdk-commands storage scene delete high_score

# Eliminar todos os dados de armazenamento da cena
npx sdk-commands storage scene clear --confirm
```

### Armazenamento do jogador — por endereço da Wallet

```typescript
import { Storage } from "@dcl/sdk/server"

type Progress = { level: number; coins: number }

// Gravar — set() resolve para false se o valor NÃO tiver sido persistido
const ok = await Storage.player.set(playerAddress, "progress", {
  level: 5,
  coins: 250,
})
if (!ok) {
  console.error(`Failed to save progress for ${playerAddress} — retry later`)
}

// Ler: null quando este jogador não tem progresso guardado
const progress = (await Storage.player.get<Progress>(playerAddress, "progress")) ?? { level: 1, coins: 0 }

// Eliminar
await Storage.player.delete(playerAddress, "progress")
```

Também pode gerir o armazenamento dos jogadores através da linha de comandos, usando `npx sdk-commands storage player`:

```bash
# Definir um valor para um jogador específico
npx sdk-commands storage player set level --value 10 --address 0x1234...

# Obter um valor para um jogador específico
npx sdk-commands storage player get level --address 0x1234...

# Eliminar um valor para um jogador específico
npx sdk-commands storage player delete level --address 0x1234...

# Eliminar todos os dados de um jogador específico
npx sdk-commands storage player clear --address 0x1234... --confirm

# Eliminar todos os dados dos jogadores (todos os jogadores)
npx sdk-commands storage player clear --confirm
```

Cada valor da cena pode ter até 512 KB, e todos os valores da cena de um World partilham 10 MB. Cada valor de jogador pode ter até 100 KB, com 1 MB por jogador.

{% hint style="warning" %}
**📔 Nota**: Não existe forma de listar os jogadores que têm dados armazenados. `Storage.player.getValues(address, { prefix, offset })` lista as chaves de um jogador que já conhece, mas nem o SDK, nem os comandos `storage player` nem a [IU de armazenamento](#access-stored-data) listam os endereços dos jogadores. Se precisar de percorrer todos os seus jogadores, por exemplo, para migrar os respetivos dados guardados ou criar uma tabela de classificação, mantenha também o seu próprio índice de endereços numa chave da cena.
{% endhint %}

### Carregar um ficheiro guardado sem o substituir

Nunca atribua dados predefinidos quando um jogador entra e depois os guarde: se os dados guardados desse jogador existirem, mas ainda não tiverem sido carregados, os valores predefinidos irão substituí-los. Leia primeiro e crie os valores predefinidos apenas quando `get()` devolver `null`. Se a leitura gerar um erro, não carregue os dados do jogador e tente novamente mais tarde.

```typescript
import { Storage } from "@dcl/sdk/server"

type Save = { coins: number }
const saves: Record<string, Save> = {}

async function loadOrCreate(address: string): Promise<Save> {
  if (saves[address]) return saves[address] // Already loaded
  // Lança um erro se a leitura falhar, para que uma falha nunca resulte numa nova gravação
  const stored = await Storage.player.get<Save>(address, "save")
  saves[address] = stored ?? { coins: 0 } // Usa os valores predefinidos apenas quando não existe uma gravação
  return saves[address]
}
```

Chame-a dentro de um `try/catch` no seu handler de entrada. Se lançar um erro, informe o cliente para que possa tentar novamente e ignore as ações desse jogador até que os dados guardados sejam carregados.

### Progresso enquanto não há ninguém na cena

Não mantenha um temporizador em execução para coisas que crescem ao longo do tempo, como colheitas, energia ou o reabastecimento de uma loja. O Multiplayer Server para alguns minutos depois de o último jogador sair (consulte [Aguarde o arranque do servidor](#wait-for-the-server-to-start-up)), por isso o temporizador também para. Em vez disso, guarde a hora da última atualização do progresso. Quando um jogador regressar, calcule o progresso com base no tempo decorrido e atualize a hora guardada.

Use o `Date.now()` do servidor para este efeito; nunca use uma hora enviada por um cliente: um jogador pode adiantar o relógio para saltar a espera.

### Evite perder dados durante gravações concorrentes

O Storage não permite atualizar uma chave apenas se ninguém a tiver alterado desde que a leu (não existe «compare-and-set»). Por isso, se ler uma chave, alterar o valor e voltar a gravá-lo, pode perder dados:

* Duas instâncias do servidor podem gravar ao mesmo tempo. Isto acontece quando uma versão antiga e uma nova da sua cena se sobrepõem durante uma nova implementação.
* Uma leitura pode devolver um valor mais antigo do que o último gravado. O Storage já disponibilizou um valor antigo de uma chave durante uma hora ou mais, mesmo com `Storage.get(key, { fresh: true })`, e após reinícios do servidor. A opção `fresh` apenas ignora a própria cache do SDK.
* Uma listagem com `Storage.getValues()` também pode estar desatualizada: pode omitir uma chave gravada recentemente ou continuar a mostrar uma chave que eliminou.

Para dados que só aumentam, como um registo de resultados ou comentários dos jogadores, use este padrão em vez de reescrever uma única chave:

1. Grave cada snapshot numa **nova chave** ordenada por hora e que não possa colidir, por exemplo `results-1-20261027-130512-k3fz`: um prefixo, um número de parte, a hora UTC e alguns caracteres aleatórios.
2. Para ler, liste todas as chaves da parte com `Storage.getValues({ prefix, offset })`, página a página, até obter `pagination.total` entradas, e combine-as pelo ID da linha.
3. Grave as linhas combinadas numa nova chave. Leia essa chave novamente e, apenas se corresponder, elimine as chaves combinadas. Nunca elimine uma chave que outro processo de gravação ainda possa alterar com base nas suas próprias leituras.

Assim, uma condição de corrida deixa uma chave extra, que será combinada na gravação seguinte, em vez de perder uma linha. Qualquer pessoa que leia os dados, incluindo você ao transferi-los da [interface de armazenamento](#access-stored-data), tem de ler todas as chaves da parte e eliminar os IDs duplicados.

```typescript
import { Storage } from "@dcl/sdk/server"

type Row = { id: string; text: string }
const PREFIX = "results-1-"

// Todas as chaves que começam pelo prefixo, da mais antiga para a mais recente
async function listAll(prefix: string) {
  const entries: { key: string; value: unknown }[] = []
  for (;;) {
    const page = await Storage.getValues({ prefix, offset: entries.length })
    entries.push(...page.data)
    if (page.data.length === 0 || entries.length >= page.pagination.total) break
  }
  return entries.sort((a, b) => (a.key < b.key ? -1 : 1))
}

async function appendRows(newRows: Row[]): Promise<boolean> {
  const versions = await listAll(PREFIX)
  // Combinar pelo ID da linha; o primeiro encontrado prevalece
  const rows = new Map<string, Row>()
  for (const { value } of versions) for (const row of value as Row[]) if (!rows.has(row.id)) rows.set(row.id, row)
  for (const row of newRows) if (!rows.has(row.id)) rows.set(row.id, row)
  const merged = [...rows.values()]

  // Uma nova chave de cada vez: hora UTC mais caracteres aleatórios
  // "2026-10-27T13:05:12.123Z" torna-se "20261027-130512"
  const stamp = new Date().toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-")
  const key = `${PREFIX}${stamp}-${Math.random().toString(36).slice(2, 6)}`
  if (!(await Storage.set(key, merged))) return false // Não foi guardado; tente novamente mais tarde

  // Eliminar as chaves combinadas apenas depois de confirmar que a nova pode ser lida
  const check = await Storage.get<Row[]>(key, { fresh: true })
  if (JSON.stringify(check) !== JSON.stringify(merged)) return true
  for (const version of versions) {
    try {
      await Storage.delete(version.key)
    } catch {
      // Mantido: a próxima escrita irá combiná-lo novamente
    }
  }
  return true
}
```

Um valor pode ter, no máximo, 512 KB. Por isso, comece uma nova parte (`results-2-`) antes de uma parte se aproximar desse limite. O exemplo [Scene Feedback](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0%2C-1-scene-feedback) usa este padrão nos respetivos ficheiros CSV e passa para uma nova parte aos 400 KB.

### Aceder aos dados armazenados

Pode ver e editar os dados armazenados ativos no seu servidor através da interface de armazenamento, acedendo a esta ligação:

[decentraland.org/storage](https://decentraland.org/storage)

No caso de um World, também pode aceder a esta página através do Creator Hub. Abra a página **Manage** , clique nos três pontos no cartão do World e selecione **View Storage**.

Aí, pode ver uma lista de todos os Worlds e terrenos onde pode publicar cenas.

Abra a sua cena e, em seguida, o separador **Scene** ou **Player** .

No separador **Scene** , verá uma lista de todas as variáveis armazenadas. A partir daqui, pode editar ou remover qualquer uma delas clicando no ícone do lápis ou do caixote do lixo.

![Activate stream](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-bbb302fbdb29f57fdcff7bf62fc6608838a06d44%2Fscene-data.webp?alt=media)

No separador **Player** , verá uma lista de todos os jogadores com dados armazenados no seu servidor. Pode pesquisá-los por endereço ou nome e, em seguida, consultar todos os dados associados. Também pode editar ou remover estes dados clicando no ícone do lápis ou do caixote do lixo.

### Alterar a estrutura dos dados

Os dados armazenados em produção **não são apagados quando publica uma nova versão da sua cena**. Isto é ótimo para tabelas de classificação, progresso dos jogadores e alterações persistentes ao ambiente que os jogadores esperam que se mantenham mesmo após pequenas atualizações à sua cena.

Por outro lado, os dados existentes no armazenamento foram escritos por uma versão anterior do seu código. Se o novo código esperar uma estrutura diferente, a análise ou leitura desses dados antigos pode falhar de formas subtis. Um campo cujo nome foi alterado estará em falta. Um campo que antes era uma string e agora é um objeto irá gerar um erro quando tentar aceder a uma propriedade. Um jogador que não inicia sessão há meses pode carregar dados anteriores a uma estrutura que o seu código já não sabe tratar.

{% hint style="warning" %}
**📔 Nota**: As alterações ao esquema não afetam apenas a primeira leitura após uma publicação. Os dados armazenados permanecem até serem substituídos ou eliminados, por isso um valor num formato antigo pode surgir a qualquer momento, muitas vezes quando regressa um jogador de quem já se tinha esquecido.
{% endhint %}

#### Práticas recomendadas

* *Leia sempre de forma defensiva*. Trate tudo o que vem do armazenamento como entrada não confiável, mesmo que tenha sido você a escrevê-lo. O tipo que passa para `get<T>()` não é verificado, por isso confirme se os campos existem e têm o tipo correto antes de os ler, e tenha um valor predefinido adequado caso não existam:

  ```typescript
  import { Storage } from "@dcl/sdk/server"

  const saved = await Storage.player.get<any>(playerAddress, "progress")
  const progress = {
    level: typeof saved?.level === "number" ? saved.level : 1,
    coins: typeof saved?.coins === "number" ? saved.coins : 0,
  }
  ```
* *Adicione campos; não os renomeie nem remova*. A alteração de esquema mais segura é aditiva: introduza um novo campo com um valor predefinido e não altere os campos existentes. Os dados antigos simplesmente não terão o novo campo, algo que a análise defensiva já contempla. Renomear um campo faz com que todos os registos antigos deixem de funcionar.
* *Crie versões para os objetos armazenados*. Inclua um campo `version` desde o primeiro dia. Ao ler os dados, escolha o procedimento com base na versão e migre as estruturas mais antigas para a atual antes de as usar. Assim, o resto do código pode continuar a trabalhar com uma única estrutura atual:

  ```typescript
  type ProgressV2 = { version: 2; level: number; coins: number; xp: number }

  function migrate(raw: any): ProgressV2 {
    const version = raw?.version ?? 1
    if (version === 1) {
      // v1 não tinha o campo xp — usar o valor predefinido
      return {
        version: 2,
        level: raw.level ?? 1,
        coins: raw.coins ?? 0,
        xp: 0,
      }
    }
    return raw as ProgressV2
  }
  ```
* *Grave novamente o valor migrado*. Depois de atualizar um registo em memória, guarde-o novamente para que a leitura seguinte já encontre o novo formato. Com o tempo, isto reduz o conjunto de registos com a estrutura antiga sem ser necessário executar um script de migração de uma só vez.
* *Para alterações incompatíveis, use uma nova chave*. Se a nova estrutura for realmente incompatível e a migração não compensar, grave os dados numa nova chave de armazenamento (por exemplo, `progress_v2`) e ignore a antiga. A chave antiga permanece inofensivamente no armazenamento e evita qualquer fluxo de leitura que tenha de a interpretar. Pode limpar as chaves antigas mais tarde através da [interface de armazenamento](https://decentraland.org/storage) ou dos comandos `npx sdk-commands storage` .
* *Teste com dados reais de produção*. Antes de implementar uma alteração estrutural, obtenha alguns registos reais na interface de armazenamento e teste o novo código de análise com eles. Os casos-limite que causam problemas são, geralmente, registos cuja existência desconhecia.
* *Mantenha uma saída de emergência*. Tenha em conta que pode editar ou eliminar registos individuais na interface de armazenamento ou através de `npx sdk-commands storage`. Se um jogador ficar bloqueado num estado inválido após uma alteração de esquema, pode corrigir o respetivo registo diretamente, sem voltar a publicar.

## Variáveis de ambiente

Configure a sua scene sem codificar valores diretamente no código. As variáveis de ambiente são úteis para dados sensíveis e também para sinalizadores de funcionalidades ou parâmetros que podem ser alterados facilmente sem voltar a publicar a sua scene.

As variáveis de ambiente estão disponíveis **apenas no servidor**. Proteja o acesso a elas com `isServer()`. O servidor pode ler as variáveis de ambiente, mas não pode alterar os respetivos valores.

`EnvVar.get()` devolve um `Promise<string>` e é resolvida como uma string vazia quando a variável não está definida. Por isso, forneça sempre um valor alternativo para os valores em falta:

```typescript
import { EnvVar } from "@dcl/sdk/server"
import { isServer } from "@dcl/sdk/network"

export async function main() {
  if (!isServer()) return

  const maxPlayers = parseInt((await EnvVar.get("MAX_PLAYERS")) || "4")
  const gameDuration = parseInt((await EnvVar.get("GAME_DURATION")) || "300")
  const debugMode = ((await EnvVar.get("DEBUG")) || "false") === "true"
}
```

### Dados sensíveis

As variáveis de ambiente são especialmente úteis para armazenar chaves privadas, códigos para resgatar recompensas e outros dados sensíveis cuja exposição no código compilado da Scene pública seria arriscada.

Pode armazenar chaves privadas no armazenamento do servidor e fazer com que apenas o servidor as leia com `isServer()`. Assim, os dados sensíveis nunca passam pelo dispositivo do jogador.

### Desenvolvimento local

Para utilizar variáveis de ambiente ao executar o projeto localmente, crie um ficheiro `.env` na raiz do projeto:

```
MAX_PLAYERS=8
GAME_DURATION=300
DEBUG=true
```

Importante: adicione `.env` ao seu ficheiro `.gitignore`, para que estes valores potencialmente sensíveis nunca sejam carregados para os servidores de conteúdo públicos.

### Alterar variáveis de ambiente

A forma mais fácil de alterar os valores das variáveis de ambiente é através da UI de armazenamento.

Pode aceder aos dados armazenados pelo armazenamento da Scene através desta ligação:

[decentraland.org/storage](https://decentraland.org/storage)

No caso de um World, também pode aceder a esta página através do Creator Hub. Abra a página **Manage** , clique nos três pontos no cartão do World e selecione **View Storage**.

Aí, pode ver uma lista de todos os Worlds e terrenos onde pode publicar cenas.

Abra a Scene e, em seguida, o separador **Ambiente** . Deverá ver todas as variáveis de ambiente do projeto.

![Activate stream](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-766c8433de10c67980a737242d867ad3c4fb5948%2Fenvironment-variables.webp?alt=media)

Tenha em atenção que não pode ler os valores destas variáveis de ambiente (para proteger os dados sensíveis), mas pode eliminá-las ou substituí-las. Basta clicar no ícone do lápis ou do caixote do lixo.

Também pode gerir as variáveis de ambiente através da linha de comandos, usando `npx sdk-commands storage env`:

```bash
# Definir uma variável
npx sdk-commands storage env set MAX_PLAYERS --value 8

# Eliminar uma variável
npx sdk-commands storage env delete OLD_VAR

# Eliminar todas as variáveis de ambiente
npx sdk-commands storage env clear --confirm
```

Também pode especificar um ambiente com a flag `--target` :

```bash
# Implementar no ambiente de staging
npx sdk-commands storage env set MY_KEY --value my_value --target https://storage.decentraland.zone

# Implementar num servidor de desenvolvimento local
npx sdk-commands storage env set MY_KEY --value my_value --target http://localhost:8000
```

As variáveis de ambiente implementadas têm precedência sobre os valores de `.env` .

## Estrutura de projeto recomendada

Separar o código do server, do client e o código partilhado mantém a base de código legível à medida que cresce:

```
src/
├── index.ts              # Ponto de entrada — ramo isServer()
├── client/
│   ├── setup.ts          # Gestores de Input, emissores de mensagens
│   └── ui.tsx            # UI React ECS (lê o estado sincronizado)
├── server/
│   ├── server.ts         # Game loop, gestores de mensagens, alterações de estado
│   └── gameState.ts      # Funções auxiliares para o estado do server
└── shared/
    ├── schemas.ts        # Definições de Component + validateBeforeChange
    └── messages.ts       # registerMessages() — importado por ambos os lados
```

{% hint style="info" %}
**💡 Dica**: mantém todas as chamadas a `registerMessages()` e as definições de Component personalizadas em `shared/`. Tanto o server como o client importam a partir daí, garantindo que estão sempre de acordo quanto aos schemas das mensagens.
{% endhint %}

## Práticas recomendadas de desempenho

Cada alteração a um Component envia os dados *inteiros* do Component pela rede. Isto é diferente do que faz o Colyseus, que envia apenas as diferenças. Tenha isto em conta ao conceber Components personalizados. A solução ideal pode ser armazenar os dados em Components separados, com base na frequência com que mudam.

### ❌ Evite Components monolíticos

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// MAU — alterar a pontuação também envia o array de posições
const GameState = engine.defineComponent("GameState", {
  playerAScore: Schemas.Int,
  playerBScore: Schemas.Int,
  timer: Schemas.Int,
  playerPositions: Schemas.Array(Schemas.Vector3), // payload grande
})
```

### ✅ Prefira Components atómicos

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"

// BOM — cada atualização é pequena e independente
const PlayerScore = engine.defineComponent("PlayerScore", {
  playerA: Schemas.Int,
  playerB: Schemas.Int,
})

const GameTimer = engine.defineComponent("GameTimer", {
  secondsLeft: Schemas.Int,
})
```

*Regra geral*: agrupe os campos que mudam em conjunto e com uma frequência semelhante. Separe os dados que mudam rapidamente (temporizadores, posições) dos que mudam lentamente (pontuações, configuração).

### Limite a frequência das mensagens

Evite enviar mensagens em todos os frames. Sempre que possível, agrupe ou limite a frequência:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { room } from "./shared/messages"

let lastSend = 0
engine.addSystem((dt) => {
  lastSend += dt
  if (lastSend > 0.1) {
    // a cada 100 ms
    room.send("position", transform.position)
    lastSend = 0
  }
})
```

Por exemplo, se o server controlar um temporizador de contagem decrescente, não é necessário enviar atualizações a todos os jogadores a cada segundo. O melhor é cada client calcular a passagem do tempo por si próprio, enquanto o server transmite o estado atual a cada 30 segundos, aproximadamente, para garantir a consistência.

## Limites de recursos do server

O Multiplayer Server executa cada scene num isolate isolado, com limites rígidos de recursos. Ultrapassar esses limites pode fazer com que os dados sejam descartados sem aviso ou que o server seja terminado para todos os jogadores na scene. Por isso, conceba a sua scene de forma a manter-se bem dentro desses limites.

### Memória

O isolate tem um **256 MB** de memória. Se este limite for excedido, o isolate é eliminado e o servidor é encerrado para todos os jogadores ligados. Mantenha o estado de trabalho reduzido e elimine os dados por jogador quando os jogadores saírem.

### CPU

Cada turno de execução tem um limite de tempo real:

* **Execução síncrona**: 10 segundos por turno. Um ciclo sem limite que exceda este tempo termina o isolate.
* **Conclusão do turno assíncrono**: 60 segundos. Se uma cadeia de `Promise` ou um `await` demorar mais do que este tempo a resolver, o isolate é terminado.

Distribua o trabalho pesado por vários ticks usando um acumulador `dt` em `engine.addSystem()`. Nunca execute ciclos síncronos sem limite no servidor.

### Taxa de mensagens recebidas

Cada peer ligado pode enviar até aproximadamente **300 mensagens por 1 000 ms**. Os frames de dados em excesso são descartados (não ficam em fila). Nunca envie mensagens do cliente em todos os frames. Consulte [Melhores práticas de desempenho](#performance-best-practices) para conhecer padrões de limitação da taxa.

### Tamanho da mensagem

* Os pacotes recebidos têm um limite de **128 KB** por pacote. Os pacotes demasiado grandes são totalmente descartados.
* As mensagens da Scene para o comms têm um limite de aproximadamente **30 KB**. Para a camada de transporte prática, mantenha as mensagens sincronizadas bem abaixo de **13 KB** (consulte a secção [Messages](#messages) ).

### Pedidos externos

As chamadas `signedFetch` concorrentes têm um limite de **32** em curso. Os pedidos adicionais ficam em fila até haver um lugar disponível. Cada tentativa de fetch tem um tempo limite de **15 segundos** . As respostas de fetch têm um limite de **10 MB**. As ligações WebSocket estão limitadas a **32** sockets simultâneos, com um tamanho máximo de mensagem de **1 MB** por mensagem.

### Chamadas ao host em curso

O limite de 40 chamadas descrito em [Armazenamento de dados](#data-storage) aplica-se a todas as chamadas ao host em todo o isolate, incluindo Storage, `signedFetch`, e outras APIs de runtime. As chamadas excedentes são rejeitadas imediatamente e não são colocadas em fila.

## Erros comuns

### Esquecer a validação de estado exclusivo do servidor

Sem `validateBeforeChange`, os clientes podem escrever em qualquer componente:

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { isServer } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"

// ❌ MAU — os clientes podem fazer batota
const Score = engine.defineComponent("Score", { value: Schemas.Int })

// ✅ BOM — apenas o servidor
if (isServer()) {
  Score.validateBeforeChange((v) => v.senderAddress === AUTH_SERVER_PEER_ID)
}
```

### Confiar em valores fornecidos pelo cliente

Nunca deixe um cliente definir os próprios valores de dados importantes, como saúde, pontuação ou posição:

```typescript
import { room } from "./shared/messages"

// ❌ MAU
room.onMessage("setHealth", (data) => {
  player.health = data.health // o cliente controla o valor!
})

// ✅ BOM — o servidor calcula o resultado
room.onMessage("takeDamage", (data) => {
  const damage = calculateDamage(data.source)
  player.health = Math.max(0, player.health - damage)
})
```

### Confiar em montantes e endereços nas mensagens

Uma mensagem de um cliente é um pedido, não um facto. Verifique todos os campos antes de os utilizar:

* **Montantes**: `Schemas.Int` descodifica o valor como um número inteiro de 32 bits, mas este ainda pode ser zero ou negativo. Rejeite montantes iguais ou inferiores a zero, caso contrário um jogador poderá «enviar» `-500` moedas e recebê-las em vez disso. Verifique também se o remetente tem saldo suficiente.
* **Endereços**: um endereço de carteira enviado pelo cliente tem de ser `0x` seguido de 40 caracteres hexadecimais. Rejeite qualquer outro valor antes de este chegar aos seus mapas ou ao Storage.

```typescript
import { room } from "./shared/messages"

const ADDRESS = /^0x[0-9a-f]{40}$/
const balances: Record<string, number> = {}

room.onMessage("giveCoins", (data, context) => {
  if (!context) return
  const from = context.from.toLowerCase()
  const to = String(data.to).toLowerCase()
  if (!ADDRESS.test(to) || to === from) return
  if (!Number.isInteger(data.amount) || data.amount <= 0) return // Rejeita valores negativos e zero
  if ((balances[from] ?? 0) < data.amount) return // Moedas insuficientes
  balances[from] -= data.amount
  balances[to] = (balances[to] ?? 0) + data.amount
})
```

### Enviar mensagens antes da sincronização do estado

Os clientes têm de esperar que o estado seja sincronizado antes de interagir:

```typescript
import { engine } from "@dcl/sdk/ecs"
import { isStateSyncronized } from "@dcl/sdk/network"

engine.addSystem(() => {
  if (!isStateSyncronized()) return
  // seguro para enviar mensagens
})
```

### Aguarde que o servidor arranque

O servidor só está ativo enquanto houver pelo menos um jogador na Scene. Depois de o último jogador sair, o servidor permanece ativo durante cerca de dois minutos e, em seguida, encerra. Na visita seguinte, é iniciada uma nova instância a frio, o que demora aproximadamente **15 segundos em produção**. A Preview local inicia o servidor instantaneamente, pelo que os problemas de arranque a frio quase sempre só surgem após a publicação.

O código da sua Scene deve estar preparado para esperar que o servidor fique disponível. As mensagens enviadas antes de o servidor terminar o arranque perdem-se silenciosamente. Enquanto espera, mostre ao jogador uma mensagem a indicar que o servidor está a iniciar e adicione uma lógica de repetição aos pedidos iniciais ao servidor.

{% hint style="info" %}
**Sugestão:** Uma forma fiável de detetar se o servidor está pronto é através de um heartbeat: faça com que o servidor escreva `Date.now()` para um campo de componente sincronizado a cada 2 segundos, e fazer com que o cliente registe quando viu a última alteração do valor. Se não chegar nenhuma alteração no prazo de 6 segundos, considere que o servidor está offline. Isto é mais robusto do que `isStateSyncronized()`, que apenas confirma que o transporte está ligado, não que o servidor está em execução.
{% endhint %}

## Exemplo completo

Um contador multijogador mínimo: clique num botão e o servidor incrementa uma pontuação sincronizada. O servidor persiste o contador em `Storage` para que o valor seja preservado quando o servidor reiniciar. Lembre-se de que o servidor encerra quando não há jogadores na cena, pelo que, sem armazenamento, a contagem seria reposta a zero sempre que a cena ficasse sem jogadores.

```typescript
import { engine, Schemas } from "@dcl/sdk/ecs"
import { registerMessages, isServer, syncEntity } from "@dcl/sdk/network"
import { AUTH_SERVER_PEER_ID } from "@dcl/sdk/network/message-bus-sync"
import { pointerEventsSystem } from "@dcl/sdk/ecs"
import { Storage } from "@dcl/sdk/server"

// 1. Define as mensagens (partilhadas)
const Messages = {
  increment: Schemas.Map({}),
  stateUpdate: Schemas.Map({
    count: Schemas.Int,
    lastPlayer: Schemas.String,
  }),
}

// 2. Define um componente exclusivo do servidor (partilhado)
const Counter = engine.defineComponent("Counter", {
  value: Schemas.Int,
  lastPlayer: Schemas.String,
})

// 3. Cria a sala
const room = registerMessages(Messages)

export async function main() {
  if (isServer()) {
    // === SERVIDOR ===

    // Só o servidor pode modificar este componente
    Counter.validateBeforeChange(
      (v) => v.senderAddress === AUTH_SERVER_PEER_ID
    )

    // Restaura o contador a partir do armazenamento, caso o servidor tenha reiniciado
    let initialCount = 0
    let initialPlayer = "none"
    let loaded = false
    try {
      initialCount = (await Storage.get<number>("counter")) ?? 0
      initialPlayer = (await Storage.get<string>("lastPlayer")) ?? "none"
      loaded = true
    } catch (error) {
      console.log("[Server] Could not load the counter:", error)
    }

    const counterEntity = engine.addEntity()
    syncEntity(counterEntity, [Counter.componentId], 1)
    Counter.create(counterEntity, {
      value: initialCount,
      lastPlayer: initialPlayer,
    })

    room.onMessage("increment", async (_data, context) => {
      if (!context) return
      if (!loaded) return // Nunca guardar por cima de um contador que não foi carregado
      const from = context.from.toLowerCase()
      const counter = Counter.getMutable(counterEntity)
      counter.value += 1
      counter.lastPlayer = from

      // Persiste no armazenamento para que o valor seja preservado quando o servidor reiniciar
      const saved =
        (await Storage.set("counter", counter.value)) &&
        (await Storage.set("lastPlayer", from))
      if (!saved) console.log("[Server] Counter not saved, the next click saves it again")

      room.send("stateUpdate", {
        count: counter.value,
        lastPlayer: from,
      })
    })
  } else {
    // === CLIENT ===
    const button = engine.addEntity()
    // ... add Transform, MeshRenderer, etc.

    pointerEventsSystem.onPointerDown(button, () => {
      room.send("increment", {})
    })

    room.onMessage("stateUpdate", (data) => {
      console.log(`Count: ${data.count} (last click by ${data.lastPlayer})`)
    })
  }
}
```

## Testar localmente

A pré-visualização padrão trata de tudo. Ao utilizar o ramo auth-server do SDK, o servidor local é iniciado automaticamente em segundo plano, juntamente com a pré-visualização do cliente.

Para testar interações multijogador localmente, abra a pré-visualização em duas janelas separadas; cada janela é tratada como um jogador diferente. Ligue cada janela com um endereço diferente. Ambos os clientes ligam-se à mesma instância do servidor local.

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.

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`

### Sugestões de depuração

* *Adicione um prefixo aos seus registos* com `[SERVER]` ou `[CLIENT]` para os distinguir no terminal:

  ```typescript
  import { isServer } from "@dcl/sdk/network"

  if (isServer()) {
    console.log("[SERVER] Starting...")
  } else {
    console.log("[CLIENT] Starting...")
  }
  ```
* *Verificar a sincronização de componentes* no cliente, registando o número de entidades:

  ```typescript
  import { engine } from "@dcl/sdk/ecs"

  engine.addSystem(() => {
    const entities = Array.from(engine.getEntitiesWith(MyComponent))
    console.log("[CLIENT] Synced entities:", entities.length)
  })
  ```

## Depurar em produção

Utilize [Scene Insights](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/scene-insights.md) para pesquisar registos de servidor publicados, acompanhá-los em tempo real e obter métricas de CPU, memória e outras. Os registos e as métricas são conservados durante **7 dias**, mesmo após reinícios e novas implementações.

Atualize para a versão mais recente do `auth-server` SDK e, em seguida, execute estes comandos a partir do projeto da sua cena:

```bash
npx sdk-commands scene-insights login
npx sdk-commands scene-insights tail
```

Inicie sessão no navegador com uma carteira autorizada. A sessão só de leitura é reutilizada nos comandos seguintes durante um máximo de 12 horas. Prima **Ctrl+C** para deixar de acompanhar os registos.

O guia [Scene Insights](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/scene-insights.md) abrange pesquisas históricas, seleção de cenas, permissões de acesso, métricas, depuração assistida por IA e limites de recolha.

### Ver dados de armazenamento

Pode aceder aos dados armazenados pelo armazenamento da Scene através desta ligação:

[decentraland.org/storage](https://decentraland.org/storage)

No caso de um World, também pode aceder a esta página através do Creator Hub. Abra a página **Manage** , clique nos três pontos no cartão do World e selecione **View Storage**.

Aí, pode ver uma lista de todos os Worlds e terrenos onde pode publicar cenas.

Abra o mundo ou os dados do jogador para ver as informações armazenadas em cada um.

Por exemplo, se um jogador específico tiver um problema ao jogar na sua cena, pode procurar esse jogador pelo endereço e ver que dados estão armazenados para ele, de modo a compreender a situação. Talvez tenha encontrado um caso extremo que o levou a ficar com dados contraditórios. Pode até apagar ou editar os dados desse jogador nesta página para o restabelecer num estado estável.

## Controlo de versões

Cada versão publicada da sua cena recebe um ID hash exclusivo, e cada hash está associado à sua própria instância de servidor. Isto significa que o código do cliente e o código do servidor são sempre atualizados em conjunto; nunca há um período em que um cliente com lógica antiga comunica com um servidor com lógica nova (ou vice-versa).

Quando publica uma atualização:

* *Os jogadores que já estão na cena* continuam a ver a versão antiga da cena até saírem e voltarem a entrar. Os respetivos clientes permanecem ligados à instância do servidor correspondente ao hash antigo.
* *Os novos jogadores que chegam* após a atualização carregam a nova versão da cena e ligam-se à nova instância do servidor.

Isto garante que o estado do cliente e do servidor nunca fica dessincronizado devido a uma alteração de esquema ou à mudança do nome de um Component. Uma atualização nunca pode interromper a sessão de um jogador que já esteja na sua Scene.

A contrapartida é que, durante um curto período logo após um deploy, os jogadores podem ficar distribuídos por duas instâncias de servidor diferentes. Um jogador que já estava na Scene e outro que acabou de chegar podem não se ver nem conseguir interagir através da Scene, apesar de estarem na mesma Scene, até os jogadores da instância mais antiga saírem e voltarem a entrar.

{% hint style="info" %}
**💡 Dica**: Os dados armazenados através do serviço [Storage](#data-storage) (como classificações, progresso dos jogadores ou alterações persistentes ao ambiente) *não* são apagados entre versões. Os dados de Storage são persistidos ao nível da localização e partilhados entre todas as instâncias de servidor que apontam para a mesma Scene, pelo que as novas versões retomam exatamente de onde a versão anterior parou.
{% endhint %}

## Migrar do Colyseus

Se tiver uma Scene existente criada com Colyseus, a tabela abaixo associa padrões comuns do Colyseus aos respetivos equivalentes no SDK7:

| Colyseus                             | Servidor Multiplayer do SDK7                            |
| ------------------------------------ | ------------------------------------------------------- |
| `room.send(type, data)`              | `room.send(type, data)` — mesma API                     |
| `room.onMessage(type, cb)`           | `room.onMessage(type, cb)` — mesma API                  |
| `room.state.players` (esquema)       | `syncEntity` + Components personalizados                |
| Serialização JSON                    | Serialização binária (automática através de `Schemas`)  |
| Aplicação de servidor separada       | A mesma base de código — `isServer()` ramificação       |
| Alojamento de servidor personalizado | Integrado: o Preview executa o servidor automaticamente |

Principais diferenças a ter em conta:

* *Serialização*: o Colyseus envia diferenças em JSON; o SDK envia o Component completo a cada alteração. Mantenha os Components pequenos (consulte [Práticas recomendadas de desempenho](#performance-best-practices)).
* *Modelo de estado*: o Colyseus utiliza uma árvore de estado mutável com diferenças calculadas automaticamente. O SDK utiliza Components ECS sincronizados através de `syncEntity` e protegidos com `validateBeforeChange`.
* *Alojamento*: não é necessário implementar um servidor separadamente. O Multiplayer Server é implementado automaticamente juntamente com a Scene.


---

# 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/authoritative-servers.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.
