Armazenamento de dados

O DataStoreService permite que você armazene dados que precisam persistir entre sessões, como itens no inventário de um jogador ou pontos de habilidade.Armazenamentos de dados são consistentes por experiência, então qualquer lugar em uma experiência pode acessar e alterar os mesmos dados, incluindo locais em diferentes servidores.

Se você quiser adicionar controle de permissão granular aos seus armazenamentos de dados e acessá-los fora dos servidores do Studio ou do Roblox, você pode usar Abrir APIs de nuvem para armazenamentos de dados.

Para visualizar e monitorar todos os armazenamentos de dados em uma experiência através do Hub do Criador, use o Gerenciador de Armazenamentos de Dados.

Para dados temporários que você precisa atualizar ou acessar frequentemente, use armazenamentos de memória.

Habilitar acesso ao Studio

Por padrão, experiências testadas no Studio não podem acessar armazenamentos de dados, então você deve ativá-los primeiro.Acessar armazenamentos de dados no Studio pode ser perigoso para experiências ao vivo porque o Studio acessa os mesmos armazenamentos de dados que a aplicação do cliente.Para evitar substituir dados de produção, não ative essa configuração para experiências ao vivo.Em vez disso, habilite-o para uma versão de teste separada da experiência.

Para habilitar o acesso ao Studio em uma experiência publicada:

1. Abra Configurações do Jogo.
2. Navegue até Segurança .
3. Ative a opção Ativar acesso ao Studio aos Serviços de API .
4. Clique em Salvar .

Armazenamento de dados de acesso

Para acessar um armazenamento de dados dentro de uma experiência:

1. Adicione DataStoreService a um lado do servidor Script.
2. Use a função GetDataStore() e especifique o nome do armazenamento de dados que você deseja usar.Se o armazenamento de dados não existir, o Studio cria um quando você salva os dados da experiência pela primeira vez.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Criar dados

Um armazenamento de dados é essencialmente um dicionário, semelhante a uma tabela Luau.Um índice exclusivo de chave indexa cada valor no lojade dados, como uma chave exclusiva de Player.UserId ou uma string nomeada para uma promoção de experiência.

Para criar uma nova entrada, chame SetAsync() com o nome da chave e um valor.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, errorMessage = pcall(function()
	experienceStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

Atualizar dados

Para alterar qualquer valor armazenado em um lojade dados, chame UpdateAsync() com o nome da chave da entrada e uma função de retorno que define como você deseja atualizar a entrada.Este retorno de chamada toma o valor atual e retorna um novo valor com base na lógica que você define.Se o retorno do callback for nil, a operação de escrita é cancelada e o valor não é atualizado.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Uppercase Name:", updatedName)
end

Definir vs atualização

Use o conjunto para atualizar rapidamente uma chave específica. A função SetAsync():

• Pode causar inconsistência de dados se dois servidores tentarem definir a mesma chave ao mesmo tempo
• Só conta contra o limite de escrita

Use atualização para lidar com tentativas multiserver. A função UpdateAsync():

• Lê o valor da chave atual do servidor que o atualizou pela última vez antes de fazer quaisquer alterações
• É mais lento porque lê antes de escrever
• Conta contra ambos os limites de leitura e escrita

Ler dados

Para ler o valor de uma entrada de armazenamento de dados, chame GetAsync() com o nome da chave da entrada.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, currentExperience = pcall(function()
	return experienceStore:GetAsync("User_1234")
end)
if success then
	print(currentExperience)
end

Dados de incremento

Para incrementar um inteiro em um lojade dados, chame IncrementAsync() com o nome da chave da entrada e um número para quanto mudar o valor.IncrementAsync() é uma função de conveniência que permite que você evite chamar UpdateAsync() e aumente manualmente o integral.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, newExperience = pcall(function()
	return experienceStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newExperience)
end

Remover dados

Para remover uma entrada e retornar o valor associado à chave, chame RemoveAsync().

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

Metadados

Existem dois tipos de metadados associados a chaves:

• Definido pelo serviço : Metadados de leitura padrão, como o tempo de atualização mais recente e o tempo de criação. Cada objeto tem metadados definidos pelo serviço.
• Definido pelo usuário : Metadados personalizados para marcar e categorizar. Definido usando o objeto DataStoreSetOptions e a função SetMetadata().

Para gerenciar metadados, expanda as funções SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync() e RemoveAsync().

• SetAsync() aceita os argumentos opcionais terceiro e quarto:

  • Uma tabela de UserIds . Isso pode ajudar com a proteção de direitos autorais e rastreamento e remoção de propriedade intelectual.

  • Um ObjetoDataStoreSetOptions, onde você pode definir metadados personalizados usando a função SetMetadata().

    local DataStoreService = game:GetService("DataStoreService")
    
    local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["ExperienceElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        experienceStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync() , IncrementAsync() , e RemoveAsync() retornam um segundo valor no ObjetoDataStoreKeyInfo.Este segundo valor contém propriedades e funções definidas pelo serviço e para obter metadados definidos pelo usuário.

  • A função GetUserIds() recupera a tabela de UserIds que você passou para SetAsync() .
  • A função GetMetadata() recupera metadados definidos pelo usuário que você passou para SetAsync() através de SetMetadata() .
  • A propriedade Version recupera a versão da chave.
  • A propriedade CreatedTime recupera o tempo em que a chave foi criada, formatada como o número de milisegundos desde a época.
  • A propriedade UpdatedTime recupera a última vez que a chave foi atualizada, formatada como o número de milisegundos desde o épico.

  local DataStoreService = game:GetService("DataStoreService")
  
  local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
  
  local success, currentExperience, keyInfo = pcall(function()
      return experienceStore:GetAsync("User_1234")
  end)
  if success then
      print(currentExperience)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• A função de retorno de chamada de UpdateAsync() toma um parâmetro adicional no objeto DataStoreKeyInfo que descreve o estado atual da chave.Ele retorna o valor modificado, as chaves associadas a UserIds e os metadados da chave.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

Para limites ao definir metadados, veja os limites de metadados limites de metadados.

Armazenamentos de dados ordenados

Por padrão, os armazenamentos de dados não classificam seu conteúdo.Se você precisar obter dados de maneira ordenada, como em estatísticas de placares persistentes, chame GetOrderedDataStore() em vez de GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Armazenamentos de dados ordenados suportam as mesmas funções básicas que os armazenamentos de dados padrão, mais a função única GetSortedAsync() .Isso recupera múltiplas chaves classificadas com base em uma ordem de classificação específica, tamanho da página e valores mínimo/máximo.

O seguinte exemplo classifica os dados de personagens em páginas com três entradas, cada uma em ordem decrescente, e então percorre as páginas e exibe o nome e a idade de cada personagem.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popula o armazenamento de dados loja
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- Ordena os dados por ordem descendente em páginas de três entradas cada
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Obtém a página atual (primeira)
		local entries = pages:GetCurrentPage()
		-- Itera por todos os pares de chave-valor na página
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Verifica se a última página foi alcançada
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avanços para a próxima página
			pages:AdvanceToNextPageAsync()
		end
	end
end