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. Os armazenamentos de dados são consistentes por experiência, então qualquer local 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 Roblox, você pode usar Open Cloud APIs for Data Stores.

Para dados temporários que você precisa atualizar ou acessar com frequência, use armazenamento de memória.

Habilitando o 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, pois o Studio acessa os mesmos armazenamentos de dados que a aplicação do cliente. Para evitar sobrescrever dados de produção, não ative esta configuração para versões de teste separadas da experiência.

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

1. Vá para Início > Configurações do Jogo > Segurança .
2. Habilite a Habilitar o Acesso ao Studio a Serviços de API alternar.
3. Clique em Salvar .

Acessando Armazenamento de Dados

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

1. Adicionar DataStoreService a um servidor-side Script .
2. Use a função GetDataStore() GetDataStore() | GetDataStore() para especificar 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 seus dados de experiência pela primeira vez.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Criando Dados

Um armazenamento de dados é basicamente um dicionário, semelhante a uma tabela Lua. Um índice de chave único key armazena cada valor no lojade dados, como um Player.UserId único de um usuário ou uma string nomeada para um promo 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

Atualizando Dados

Para alterar qualquer valor armazenado em um lojade dados, chame Class.GlobalDataStore:UpdateAsync()|UpdateAsync() com o nome da chave da entrada e uma função de retorno que define como você deseja atualizar a entrada. Essa função de retorno leva o valor atual e retorna um novo valor com base na lógica que você define. Se a função de retorno retornar nil , a operação de gravação é

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

Configurar vs Atualizar

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

• Pode causar desconsistência de dados se dois servidores tentarem definir a mesma chave ao mesmo tempo
• Somente conta contra o limite de gravação

Use a atualização para lidar com tentativas de múltiplos servidores. A função UpdateAsync() :

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

Lendo Dados

Para ler o valor de uma entrada do 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

Incrementando Dados

Para incrementar um inteiro em um lojade dados, chame IncrementAsync() com o nome da chave da entrada e um número para quanto alterar o valor. IncrementAsync() é uma função de conveniência que permite que você não precise chamar Class.GlobalDataStore:UpdateAsync()|

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

Removendo 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:

• Metadados de serviço definidos : Metadados de leitura apenas, como a mais recente hora de atualização e hora de criação. Todos os objetos têm metadados de serviço.
• Usuário-definido : Metadados personalizados para a marcação e classificação. Definido usando o objeto DataStoreSetOptions e a função Class.DataStoreSetOptions:SetMetric()|SetMetric() .

Para gerenciar metadados, expanda as funções SetAsync(), UpdateAsync(), GetAsync(), 1> Class.GlobalDataStore:IncrementAsync()|IncrementAsync()1> e 4> Class

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

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

  • Um ObjetoDataStoreSetOptions, onde você pode definir metadados personalizados usando a função Class.DataStoreSetOptions:SetMetric()|SetMetric() .

    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 objeto 0> Class.DataStoreKeyInfo0>. Este segundo valor contém propriedades e funções de serviço para recuperar metadados de usuário.

  • A função GetUserIds() recupera a tabela de UserIds que você passou para SetAsync().
  • A função GetMetadata() recupera metadados personalizados que você passou para SetAsync() através de SetMetadata() .
  • A propriedade Version recupera a versão da chave.
  • A propriedade CreatedTime busca o tempo em que a chave foi criada, formatada como o número de milisegundos desde o épico.
  • A propriedade UpdatedTime busca 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() leva um parâmetro adicional no objeto DataStoreKeyInfo que descreve o estado atual do chave. Ele retorna o valor modificado, as chaves associadas com UserIds e o metadado 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, see Limites de Metadados .

Armazenamento de Dados Ordenado

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Armazéns de dados ordenados suportam as mesmas funções básicas que armazéns de dados padrão, mais a função única GetSortedAsync() . Isso recupera várias chaves sortidas com base em uma ordem de classificação específica, tamanho da página e valores mínimos/máximos.

O seguinte exemplo classifica os dados do personagem em páginas com três entradas, cada uma em ordem crescente, e em seguida,Loop através das páginas e saídas do nome e idade de cada personagem.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popula o lojade dados solicitado
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

-- Classifica 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 através de todos os pares de valor da chave 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