Ao usar dados persistentes, você pode rastrear e salvar dados por jogador entre sessões de jogo. Isso abre uma variedade de modos de jogo progressivos em que os jogadores podem sair e depois voltar para retomar seus objetivos ou ver o mesmo estado do jogo de quando saíram.
Os dados persistentes funcionam armazenando dados de cada jogador individual, como perfil ou estatísticas, no Verse. Esses dados podem então ser atualizados quantas vezes o valor dos dados mudar. Como são persistentes, eles persistirão durante as sessões de jogo e estarão disponíveis sempre que o jogador estiver on-line no jogo.
Sobrevivência, Magnata, RPGs e Roguelites são alguns exemplos de modos de jogo que utilizam dados persistentes. Esses tipos de modos de jogo exigem que os jogadores acumulem itens que satisfazem metas de longo prazo que conduzem a experiência.
Use dados persistentes nos seus códigos Verse para armazenar informações que são salvas por jogador, por módulo. Implemente dados persistentes em modos de jogo nos quais você gostaria de manter os jogadores, incentivando a progressão contínua.
Para praticar a implementação da persistência por conta própria, consulte o Tutorial de Estatísticas persistentes dos jogadores.
Embora dados persistentes possam ser criados e usados em Verse, também existem dispositivos do Modo Criativo que têm funcionalidades básicas com suporte a dados persistentes. Consulte mais detalhes em Dispositivos de persistência.
O que significa persistência em Verse
Em Verse, uma variável definida em um módulo é global para qualquer instância do jogo em execução onde a variável está no escopo. Exceto para variáveis com escopo de módulo associadas à sessão, uma variável com escopo de módulo requer persistência, o armazenamento dos dados além do jogo atual. Por esse motivo, há restrições quanto aos tipos que podem ser usados no escopo de módulo.
Atualmente, você pode usar os seguintes tipos em um escopo de módulo:
| Tipos de escopo de módulo permitidos | Definição | Restrições |
|---|---|---|
| Dados de qualquer tipo representados por | Os dados são armazenados apenas durante a sessão atual e não persistem nas entre as rodadas subsequentes. |
| Dados de qualquer tipo representado por | O acesso aos dados persistentes do jogador só é permitido quando o jogador está no jogo atual. |
Se um jogador sair do jogo ou não estiver na sessão atual, você não poderá mais armazenar ou acessar os dados dele nessa sessão de jogo. Se o jogador retornar ou jogar o mesmo jogo novamente, você poderá acessar e atualizar seus dados.
Como criar dados persistentes em Verse
Você pode criar seus próprios dados persistentes para cada jogador. Esses dados podem ser continuamente atualizados, armazenados e recuperados sempre que os jogadores retornam ao jogo. Durante o pareamento, o jogo verificará se há dados persistentes do novo jogador. Se o jogador tiver dados persistentes disponíveis, estes serão carregados e disponibilizados para scripts Verse.
Se o jogador tiver dados persistentes para uma ilha e o carregamento de dados falhar, o jogador não poderá ingressar nessa ilha. Esta é uma medida de proteção que impedirá que dados persistentes sejam substituídos no caso de falha no carregamento de dados.
Para criar dados persistentes no código Verse, defina uma variável weak_map que usa o tipo player como chave e um tipo persistente como valor. Consulte a lista completa de tipos que podem ser persistentes em Tipos persistentes.
No exemplo a seguir, a variável global "weak_map" MySavedPlayerData usa o tipo "player" como chave e um inteiro como valor. Armazenar um integer para um jogador nessa variável significa que os dados persistirão durante as sessões de jogo e poderão ser acessados e atualizados a qualquer momento quando o jogador estiver no jogo.
var MySavedPlayerData:weak_map(player, int) = map{}
Depois de definir seus dados persistentes, você precisará inicializar os dados de cada jogador. Você pode fazer isso verificando se ainda não há dados armazenados para esse jogador e, em seguida, adicionando o jogador e um valor inicial a weak_map.
# Runs when the device is started in a running game
OnBegin<override>()<suspends>:void =
InitialSavedPlayerData:int = 0
Players := GetPlayspace().GetPlayers()
for (Player : Players):
if:
not MySavedPlayerData[Player]
set MySavedPlayerData[Player] = InitialSavedPlayerDataO exemplo anterior armazenou apenas um inteiro, mas você pode usar outros tipos, como classes e matrizes, para armazenar mais dados para cada jogador em weak_map. Consulte a lista completa de tipos que você pode usar em Tipos persistentes.
O exemplo em Verse a seguir mostra como você pode definir um perfil de jogador personalizado em uma classe que pode ser armazenada, atualizada e acessada posteriormente por um jogador. A classe player_profile_data armazena as informações de um jogador, como EXP ganho, seu ranque e as missões concluídas.
player_profile_data := class<final><persistable>:
Version:int = 0
Class:player_class = player_class.Villager
XP:int = 0
Rank:int = 0
CompletedQuestCount:int = 0
QuestHistory:[]string = array{}
var PlayerProfileDataMap:weak_map(player, player_profile_data) = map{}Há um limite para a quantidade de dados que você pode armazenar por jogador e por ilha. Sempre que você salvar dados, recomendamos usar a função "FitsInPlayerMap" para verificar como suas atualizações afetam o tamanho total. Consulte mais detalhes em Como testar se os dados persistentes estão dentro dos limites.
Agora que você sabe como criar seus próprios dados persistentes e inicializá-los para cada jogador, confira as práticas recomendadas para conhecer as maneiras recomendadas de trabalhar com dados persistentes em Verse.
Como modificar dados entre versões publicadas da sua Ilha
Depois de publicar a versão atual da sua ilha, se você fizer atualizações nos dados persistentes, todos os dados armazenados de uma versão anterior da ilha deverão ser compatíveis com versões posteriores da ilha.
Para garantir isso, uma verificação de compatibilidade com versões anteriores é executada no UEFN, e ocorrerá uma falha de compilação se o código Verse não for mais compatível com a versão publicada atualmente. Essa verificação de compatibilidade com versões anteriores é executada sempre que você:
Clique em Iniciar Sessão na barra de ferramentas do UEFN.
Clique em Enviar alterações ou Enviar alterações de Verse na barra de ferramentas do UEFN.
Como publicar sua Ilha pela primeira vez.
Como ativar uma nova versão pública da sua Ilha.
Essa verificação de retrocompatibilidade é essencialmente uma verificação do tipo de valor da variável weak_map com escopo de módulo. Para tipos simples como integers, o tipo não pode ser alterado após a publicação da ilha. Isso inclui structs, em que você não pode alterar a definição da estrutura após a publicação da Ilha.
Atualmente, o único tipo persistente ao qual você pode adicionar mais dados depois de publicar sua Ilha é o tipo class, desde que os novos campos tenham valores padrão. Isso significa que o carregamento dos dados salvos de uma versão anterior incluirá os novos campos e seus valores padrão. Confira mais detalhes para usar classes como dados persistentes nas melhores práticas.
Como restaurar dados persistentes para a sua Ilha
Se precisar forçar uma redefinição dos dados persistentes da sua Ilha, poderá fazer isso em Verse atribuindo um valor padrão para os dados persistentes no weak_map para o jogador quando ele entrar na Ilha.
Para saber se os dados do jogador já foram redefinidos, você pode incluir um valor de versão para sua classe e atualizá-lo com novas alterações como parte dos seus dados persistentes. Esta é uma das práticas recomendadas listadas abaixo. Não deixe de conferir as outras!
Tipos persistentes em Verse
Veja a seguir os tipos persistentes que você pode usar na variável weak_map com escopo de módulo:
| Tipo | Descrição |
|---|---|
Uma matriz será persistente se os seus tipos de elementos forem persistentes. | |
Valores de caracteres são persistentes. | |
Valores de caracteres são persistentes. | |
Uma classe é persistente quando:
| |
Valores de cores são persistentes. | |
Um enum é persistente quando definido com o especificador persistente. | |
Valores de float são persistentes. | |
Valores inteiros são persistentes. | |
Os valores de lógica são persistentes. | |
Um mapa é persistente quando os tipos de chave e valor são persistentes. | |
Uma opção é persistente se o seu valor for persistente. | |
Uma estrutura é persistente quando:
Não é possível alterar uma estrutura persistente depois de publicar sua ilha. Por esse motivo, recomendamos o uso de estruturas persistentes somente quando o esquema for constante. tupla | |
Uma tupla é persistente se cada tipo de elemento for persistente. | |
Os valores vector2 são persistentes. | |
Os valores vector2i são persistentes. | |
Os valores vector3 são persistentes. |
Como testar com dados persistentes
Se quiser testar o comportamento persistente dos dados antes de publicar a versão mais recente da sua Ilha, você pode definir o seguinte comportamento no seu dispositivo Configurações da Ilha para as configurações Comportamento de Persistência: Sessão de Teste e Comportamento de Persistência: Sessão de Edição:
| Comportamento de dados persistentes | Descrição |
|---|---|
Importar da Sessão Ativa | Importe dados de sessão dos dados ativos, se houver dados ativos disponíveis. Isso requer que a ilha tenha sido publicada e que o jogador tenha jogado na versão em tempo real dessa ilha. Se dados em tempo real estiverem disponíveis, os dados da sessão de teste serão propagados com uma cópia desses dados em tempo real. Isso pode ser muito útil para testar problemas com dados persistentes associados a alterações na lógica da sua ilha. |
Simular Novo Usuário | Inicia o jogador com novos dados persistentes, como se estivesse jogando na Ilha pela primeira vez. |
Os comportamentos Importar da Sessão Ativa e Simular Novo Usuário funcionam tanto para persistência em Verse quanto para dispositivos de persistência, como os dispositivos Ponto de Salvamento e Rastreador. Simular Novo Usuário executará a sessão com dados vazios para dispositivos de persistência e persistência em Verse sem alterar os dados ativos, enquanto Importar da Sessão Ativa carregará os dados persistentes de ambos se os dados ativos estiverem disponíveis.
As configurações de comportamento de dados de persistência são aplicadas durante o teste. Existem dois cenários diferentes em que você pode testar com dados persistentes:
Sessão de Edição: as configurações do comportamento dos dados de persistência são aplicadas quando você inicia uma sessão do UEFN. Isso significa que os dados persistentes podem persistir entre vários jogos em uma única sessão. Se você sair da sessão e reiniciar uma nova, os dados persistentes serão redefinidos, e as configurações de comportamento dos dados de persistência serão reaplicadas.
Sessão de Teste: as configurações de comportamento de dados de persistência são aplicadas quando você configura um teste no Portal do Criador quando um testador entra por meio de um código de teste ou de um código de link privado. As configurações de comportamento de dados de persistência são aplicadas apenas da primeira vez em que o jogador entra. Quando o jogador sair e entrar novamente no teste, seus dados persistirão durante as sessões, e as configurações de comportamento de dados de persistência não serão reaplicadas. Para redefinir os dados persistentes, você precisará criar um novo código de link de teste de jogo.
Para atualizações de ilha que afetam o modo como os dados persistentes são gerenciados e atualizados, recomendamos que você teste em ambos os cenários, iniciando uma sessão do UEFN e um teste que usa um código de link. Não se esqueça de testar as alterações feitas nos dados persistentes com dados em tempo real e dados simulados de novos usuários. Isso ajudará a garantir que suas atualizações funcionem tanto para os jogadores atuais da sua ilha quanto para os novos jogadores.
Efeitos da publicação de novas versões da sua ilha
Assim que sua Ilha for publicada, um registro persistente será criado para os jogadores quando seus dados forem armazenados em weak_map. Os dados serão então armazenados e carregados em quaisquer visitas subsequentes à sua ilha.
Se as novas versões da sua ilha forem publicadas, os dados persistentes serão automaticamente mesclados na nova versão. Consulte mais detalhes em Como modificar dados entre versões publicadas da sua Ilha.
Efeitos da reversão da sua Ilha publicada
Se você reverter a sua ilha para uma versão anterior por meio do Portal de Criadores, os dados persistentes de todos os usuários serão redefinidos.
Atualmente, não há suporte para notificar os jogadores de que seus dados foram afetados por uma reversão.
Isso fará com que as atualizações recentes dos dados do jogador sejam perdidas e pode até resultar em sua redefinição completa. Isso é válido mesmo que a reversão não inclua internamente alterações na lógica que pudessem afetar os dados persistentes.
Devido ao seu impacto nos dados persistentes, recomendamos usar a funcionalidade de reversão apenas como último recurso.
Limitações
A seguir estão as limitações para trabalhar com dados persistentes em Verse.
Tamanho máximo de objetos persistentes
Há um limite para a quantidade de dados que podem ser armazenados em um weak_map por jogador.
Um registro weak_map é a quantidade total de dados associados a um único elemento weak_map. Um único registro weak_map tem um tamanho máximo de dados de 256 quilobytes (kB) por pessoa.
Quando um valor de 'weak_map' é salvo, a quantidade total de memória necessária para salvar os dados é calculada.
Confira a seguir alguns exemplos de dados que ultrapassariam os limites de 256 kB:
Aproximadamente 24.000 valores
floatouint.Aproximadamente 200.000 caracteres de texto. Isso equivale a cerca de 60 páginas de texto em um romance médio.
Se você tentar salvar dados maiores que 256 kB para um registro de pessoa, o salvamento falhará, e erro de tempo de execução em Verse será exibido.
Você pode evitar falhas ao salvar usando a função auxiliar FitsInPlayerMap em Verse. A função FitsInPlayerMap consulta uma cópia do registro que você deseja salvar e verifica seu tamanho. Se o registro puder ser salvo, a chamada de função será bem-sucedida. Caso contrário, se o registro for muito grande, ele falhará.
A função FitsInPlayerMap é especialmente útil quando você está trabalhando com uma matriz dinâmica ou um mapa de dados e adicionando novos elementos a eles. Atualizar um int, float ou logic que estava anteriormente no registro persistente não alterará o tamanho do registro persistente.
Máximo de mapas fracos de jogadores persistentes por Ilha
Uma única ilha pode ter até quatro variáveis persistentes, ou seja, quatro variáveis weak_map com player como o tipo de chave. Esse requisito é aplicado pelo compilador do Verse.
Mapa fraco obrigatório com tipo classe
Pelo menos o valor de weak_map de uma variável persistente deverá ser uma classe se o limite máximo de variáveis persistentes for atingido. Isso garante que as variáveis possam ter mais dados adicionados posteriormente, ao mesmo tempo que atendem ao requisito de retrocompatibilidade nas publicações subsequentes da Ilha.