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.
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.
A partir da linha de comandos, execute o seguinte comando para o instalar no seu projeto em vez do branch padrão do SDK:
npm install --save-exact @dcl/sdk@auth-server @dcl/js-runtime@auth-server2. 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:
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 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:
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:
A sintaxe é idêntica à utilizada pela Multijogador sem servidor 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.
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:
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:
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 :
Consulte Scene Admin 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:
Componentes personalizados
Também pode aplicar validateBeforeChange() a componentes personalizados definidos pela cena.
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:
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.
Receber mensagens
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:
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:
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:
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.
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.
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.
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:
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:
Armazenamento do World — partilhado por todos os jogadores
Também pode gerir o armazenamento da cena através da linha de comandos, usando npx sdk-commands storage scene:
Armazenamento do jogador — por endereço da Wallet
Também pode gerir o armazenamento dos jogadores através da linha de comandos, usando npx sdk-commands storage player:
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.
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.
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), 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çãofreshapenas 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:
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.Para ler, liste todas as chaves da parte com
Storage.getValues({ prefix, offset }), página a página, até obterpagination.totalentradas, e combine-as pelo ID da linha.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, tem de ler todas as chaves da parte e eliminar os IDs duplicados.
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 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:
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.

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.
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: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
versiondesde 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: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 ou dos comandosnpx 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:
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:
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:
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.

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:
Também pode especificar um ambiente com a flag --target :
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:
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
✅ Prefira Components atómicos
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:
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
Promiseou umawaitdemorar 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 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 ).
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 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:
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:
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.Intdescodifica 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»-500moedas 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
0xseguido de 40 caracteres hexadecimais. Rejeite qualquer outro valor antes de este chegar aos seus mapas ou ao Storage.
Enviar mensagens antes da sincronização do estado
Os clientes têm de esperar que o estado seja sincronizado antes de interagir:
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.
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.
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:Verificar a sincronização de componentes no cliente, registando o número de entidades:
Depurar em produção
Utilize Scene Insights 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:
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 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:
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.
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:
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).
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
syncEntitye protegidos comvalidateBeforeChange.Alojamento: não é necessário implementar um servidor separadamente. O Multiplayer Server é implementado automaticamente juntamente com a Scene.
Atualizado