Resumo
Use o DataStoreService a partir de um Script de servidor: carregue os dados de cada jogador com GetAsync quando ele entra, guarde em uma tabela enquanto ele joga, e salve com UpdateAsync em um timer, quando ele sai (PlayerRemoving) e quando o servidor desliga (game:BindToClose). Envolva toda chamada em pcall e tente de novo algumas vezes quando falhar.
- Para testar no Studio, publique o jogo e ative File > Experience Settings > Security > Enable Studio Access to API Services, em um jogo de teste separado: o Studio usa os mesmos dados dos servidores publicados.
- Se os dados de um jogador falharem ao carregar, nunca salve esse jogador. Salvar os valores padrão sobrescreveria o progresso real dele.
- Salve uma tabela por jogador em uma chave como
User_12345, em um timer e não a cada mudança. - Para trocas ou itens pagos, adicione session locking para dois servidores não conseguirem salvar o mesmo jogador.
Nesta página
Antes de começar: ative o acesso do Studio em uma cópia de teste
Um jogo rodando no Studio não acessa data stores até você permitir. Permitir tem um detalhe que a documentação da Roblox aponta: o Studio passa a ler e gravar os mesmos data stores do jogo publicado, então um teste que zera as suas moedas no Studio zera também no jogo publicado, e um bug em código de teste pode estragar as chaves de jogadores de verdade.
- Faça uma cópia de teste. Salve o seu jogo em um arquivo, abra a cópia, escolha File > Publish to Roblox As e clique em Create new game. Não adicione como um place dentro do seu jogo publicado: todos os places de um jogo compartilham os mesmos data stores.
- Na cópia de teste, abra File > Experience Settings e vá em Security.
- Ative Enable Studio Access to API Services e clique em Save.
Chamadas de data store só funcionam em Scripts de servidor; um LocalScript que tenta recebe um erro, então os clientes não conseguem gravar dados salvos. Quando um botão deve mudar algo, o cliente pede ao servidor com um RemoteEvent e o servidor decide (veja o guia de RemoteEvents (em inglês)).
Como os data stores guardam os dados do jogador
Um data store é um conjunto nomeado de chaves e valores nos servidores da Roblox, compartilhado por todos os servidores e todos os places do seu jogo. DataStoreService:GetDataStore("PlayerData") devolve um.
As boas práticas da Roblox se resumem a um data store para os dados dos jogadores, uma chave por jogador, uma tabela em cada chave. Monte a chave a partir do UserId do jogador, como User_12345, nunca a partir do nome, que ele pode trocar. Um padrão fixo User_{UserId} também deixa o processamento automático de direito ao esquecimento da Roblox achar os dados de um jogador, se você configurar isso.
| Tipo | Salva? | Observações |
|---|---|---|
| Numbers, strings, booleans, buffers | Sim | As strings precisam ser UTF-8 válido. Não guarde inf nem nan. |
| Tabelas | Sim | Se tudo dentro delas também puder ser salvo. Uma tabela cujas chaves numéricas não começam em 1 (então o tamanho dela é 0) volta com essas chaves como strings. |
Instances, Vector3, CFrame, Color3 | Não | O salvamento dá erro ou guarda nil. Salve o nome de um item, ou uma posição como três números. |
Toda requisição é uma chamada pela internet que pode falhar, leva tempo e conta contra um orçamento por minuto. Por isso sistemas de salvamento confiáveis leem uma vez quando o jogador entra, guardam os dados em uma tabela no servidor enquanto ele joga, e gravam de volta de tempos em tempos.
GetAsync, SetAsync ou UpdateAsync: qual usar
| Método | O que faz | Use para |
|---|---|---|
GetAsync(key) | Lê o valor. O resultado fica em cache naquele servidor por 4 segundos. | Carregar os dados de um jogador |
SetAsync(key, value) | Sobrescreve o valor sem ler. Uma gravação. | Uma chave nova, ou um valor que não depende do antigo |
UpdateAsync(key, callback) | Lê o valor mais recente, passa para a sua callback e grava o que ela devolver. Uma leitura e uma gravação. | Salvar dados de jogadores, e qualquer chave que mais de um servidor pode gravar |
IncrementAsync(key, delta) | Soma um número inteiro a um número inteiro guardado. | Contadores |
RemoveAsync(key) | Apaga a chave e devolve o valor antigo. As versões anteriores ainda podem ser listadas e lidas. | Apagar os dados de um jogador |
O SetAsync grava às cegas: se dois servidores salvam a mesma chave quase ao mesmo tempo, a gravação mais recente vence, seja ela qual for. O UpdateAsync lê o valor atual antes e, se outro servidor gravar no meio, o Roblox roda a sua callback de novo com o valor novo. A Roblox recomenda usá-lo sempre que uma gravação depende do valor atual ou vários servidores podem gravar a chave, que é o caso dos dados de jogadores. A callback tem três regras:
- Ela não pode pausar: nada de
task.wait()nem de outras chamadas de data store dentro dela. - Ela pode rodar mais de uma vez, então deve só calcular o valor novo, nunca dar itens nem disparar eventos.
- Retornar
nilcancela a gravação. O módulo usa isso para não sobrescrever dados salvos por uma versão mais nova do jogo.
Passo 1: Crie o módulo PlayerData
Este ModuleScript é o único código que conversa com o data store. Ele carrega os dados de cada jogador quando ele entra, guarda em memória, salva a cada 180 segundos, quando ele sai e quando o servidor desliga, e se recusa a salvar quem teve os dados falhando ao carregar.
- No Explorer, passe o mouse sobre ServerScriptService, clique em + e insira um ModuleScript. Renomeie para
PlayerDatae troque o conteúdo pelo código abaixo. - Um ModuleScript só roda quando um script dá require nele. Insira um Script no ServerScriptService chamado
Maincom esta linha:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Outros scripts de servidor dão require do mesmo jeito. - Edite
DEFAULTSe o tipoDatapara combinar com o seu jogo, mantendo cada campo como number, string, boolean ou tabela.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: carrega os dados de cada jogador quando ele entra, guarda em memória,
-- e salva em um timer, quando ele sai e quando o servidor desliga.
-- Outros scripts de servidor usam PlayerData.Get(player) para ler e mudar os dados.
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- aumente quando o formato dos dados mudar, e adicione um passo em migrate()
local AUTOSAVE_SECONDS = 180
-- No Studio uma chamada que falha desiste na hora, então testar sem acesso a data store é rápido
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- dobra depois de cada falha: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- Com o que um jogador novo começa
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false se o carregamento falhou: dados padrão nunca podem substituir progresso real
}
-- Chamado dentro de cada pcall abaixo, então um jogo que ainda não foi publicado
-- (sem acesso a data store) ainda carrega os jogadores com dados padrão
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- salvamentos ainda rodando, por chave
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Dispara com o jogador quando os dados dele estão prontos. Chame PlayerData.Get(player) para a tabela:
-- uma tabela enviada por um BindableEvent chega como cópia, então mudá-la não mudaria nada.
PlayerData.Loaded = loadedEvent.Event
local function deepCopy(value: any): any
if type(value) ~= "table" then
return value
end
local copy = {}
for key, item in value do
copy[key] = deepCopy(item)
end
return copy
end
local function defaultData(): Data
local data = deepCopy(DEFAULTS) -- uma cópia nova, para os jogadores nunca dividirem uma tabela Inventory
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Leva os dados salvos até o schema atual. Devolve nil se não der para usá-los com segurança.
local function migrate(saved: any): Data?
if type(saved) ~= "table" then
return nil
end
local version = tonumber(saved.SchemaVersion) or 1
if version > SCHEMA_VERSION then
return nil -- salvo por uma versão mais nova do jogo: nunca carregue nem sobrescreva aqui
end
-- Um passo por mudança de schema, do mais antigo para o mais novo
if version < 2 then
-- Exemplo: a versão 1 chamava a moeda de Gold. Só copie quando Coins não existir,
-- para dados antigos que já têm Coins mas não têm SchemaVersion manterem o valor.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Adiciona os campos criados desde o último salvamento deste jogador, e troca valores do tipo errado
for field, default in DEFAULTS do
if type(saved[field]) ~= type(default) then
saved[field] = deepCopy(default)
end
end
saved.SchemaVersion = SCHEMA_VERSION
return saved
end
-- Roda uma chamada de data store em pcall. Se falhar, espera e tenta de novo, dobrando a
-- espera a cada vez e somando um pouco de aleatoriedade para os servidores não tentarem todos juntos.
local function withRetries(label: string, call: () -> any): (boolean, any)
for attempt = 1, MAX_ATTEMPTS do
local ok, result = pcall(call)
if ok then
return true, result
end
warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
if attempt < MAX_ATTEMPTS then
local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
task.wait(waitTime + math.random() * waitTime / 2)
end
end
return false, nil
end
local function save(session: Session): boolean
if not session.canSave then
return false
end
local key = session.key
pendingSaves[key] = (pendingSaves[key] or 0) + 1
local newerSchema = false
local ok = withRetries(`Save {key}`, function()
return store():UpdateAsync(key, function(current: any)
if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
newerSchema = true
return nil -- retornar nil cancela a gravação
end
-- Grava a tabela atual inteira, marcada com o UserId do jogador
return session.data, { session.userId }
end)
end)
local left = (pendingSaves[key] or 1) - 1
if left > 0 then
pendingSaves[key] = left
else
pendingSaves[key] = nil
end
if newerSchema then
session.canSave = false
warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
end
return ok and not newerSchema
end
local function startAutosave(player: Player, session: Session)
task.spawn(function()
-- Começa em um ponto aleatório do intervalo para os servidores não salvarem todos de uma vez
task.wait(math.random() * AUTOSAVE_SECONDS)
while sessions[player] == session do
save(session)
task.wait(AUTOSAVE_SECONDS)
end
end)
end
local function load(player: Player)
local key = "User_" .. player.UserId
-- Se este jogador acabou de sair deste servidor e voltou, deixa o último salvamento terminar antes
while pendingSaves[key] do
task.wait()
end
local ok, saved = withRetries(`Load {key}`, function()
return store():GetAsync(key)
end)
if player.Parent ~= Players then
return -- saiu enquanto carregava: nada mudou, então não há nada para salvar
end
local data: Data? = nil
if ok then
data = if saved == nil then defaultData() else migrate(saved)
end
local session: Session = {
key = key,
userId = player.UserId,
data = data or defaultData(),
canSave = data ~= nil,
}
if not session.canSave then
warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
end
sessions[player] = session
player:SetAttribute("DataLoaded", session.canSave) -- uma GUI pode ler isto e avisar o jogador
startAutosave(player, session)
loadedEvent:Fire(player)
end
local function endSession(player: Player)
local session = sessions[player]
if not session then
return
end
sessions[player] = nil -- para o loop de autosave e faz uma segunda chamada não fazer nada
save(session)
end
-- A tabela de dados ao vivo do jogador, ou nil até ela carregar. Mude só a partir de scripts de servidor.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True quando os dados do jogador carregaram e vão ser salvos. Confira antes de vender qualquer coisa.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Salva agora em vez de esperar o timer, para momentos que importam, como uma compra.
-- Pausa, e devolve true quando o salvamento deu certo.
function PlayerData.SaveNow(player: Player): boolean
local session = sessions[player]
return session ~= nil and save(session)
end
Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
task.spawn(load, player) -- jogadores que entraram antes de este módulo receber o primeiro require
end
game:BindToClose(function()
-- O servidor dá 30 segundos a estas funções, então salva todo mundo ao mesmo tempo
for player in sessions do
task.spawn(endSession, player)
end
-- Depois espera cada salvamento ainda rodando, incluindo os que o PlayerRemoving começou
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Depois que o jogo estiver publicado, mantenha o STORE_NAME e o padrão de chave User_ iguais. Mudar qualquer um dos dois aponta o módulo para chaves vazias, e todo jogador recomeça dos valores padrão.
Como o módulo mantém os dados seguros
Valores padrão e uma versão de schema
Um jogador novo recebe uma cópia nova de DEFAULTS. Precisa ser uma cópia: se todos os jogadores dividissem uma tabela Inventory, um item adicionado para um apareceria para todos.
Toda tabela salva carrega um SchemaVersion. Adicionar um campo não precisa mudar a versão, porque o migrate preenche os campos que faltam a partir dos padrões. Renomear ou reorganizar precisa: aumente SCHEMA_VERSION e adicione um passo, como o exemplo que renomeia Gold para Coins (em um jogo novo, apague o exemplo e comece em 1). Dados com uma versão maior que a do servidor vêm de uma versão mais nova que ainda está sendo lançada, então os servidores mais antigos não mexem neles.
Um carregamento que falhou nunca é salvo
Esta regra evita perdas totais. Se todas as tentativas de carregar falharem, o jogador joga com dados padrão, mas canSave fica false, então esses padrões nunca sobrescrevem o progresso real dele. O módulo também define um atributo DataLoaded como false, que o Passo 3 usa para avisar o jogador. O exemplo de referência da Roblox trata carregamentos que falham do mesmo jeito e sugere isso no lugar de expulsar; se você prefere expulsar, chame player:Kick() com uma mensagem no ponto em que o módulo avisa.
Novas tentativas com backoff
O withRetries envolve toda chamada em pcall. Depois de uma falha, ele espera 1, depois 2, depois 4 segundos, cada um mais até metade desse tempo de forma aleatória, e para depois de quatro tentativas (uma no Studio, para um jogo sem acesso a data store começar na hora). A aleatoriedade espalha as novas tentativas de muitos servidores depois de uma queda, e o limite mantém a espera em uns 10 segundos, dentro dos 30 segundos que um servidor tem para desligar. Como todo salvamento grava a tabela ao vivo inteira pelo UpdateAsync, uma nova tentativa que termina atrasada não consegue colocar dados velhos de volta.
Quando ele salva
| Quando | Por quê |
|---|---|
| A cada 180 segundos enquanto o jogador está no servidor | Limita a perda em um crash. O primeiro salvamento acontece em um ponto aleatório do intervalo para os servidores não salvarem todos de uma vez. O exemplo de referência da Roblox também usa 180 segundos. |
Quando o jogador sai (PlayerRemoving) | O salvamento final normal. A sessão é removida antes, então o autosave para. |
Quando o servidor desliga (game:BindToClose) | Todo mundo que ainda está no servidor é salvo de uma vez, e a função espera cada salvamento em andamento. O Roblox dá 30 segundos a ela. |
Quando você pede, com PlayerData.SaveNow(player) | Depois de algo que não pode se perder, como uma compra. |
Se um jogador volta ao mesmo servidor enquanto o salvamento final dele ainda está rodando, o carregamento novo espera esse salvamento terminar, então não consegue ler o valor mais antigo.
Passo 2: Leia e mude os dados a partir de outros scripts
Todo script de servidor que dá require no módulo divide as mesmas tabelas:
| Chamada | O que faz |
|---|---|
PlayerData.Get(player) | A tabela de dados ao vivo do jogador, ou nil até ela carregar. Mude os campos direto, como data.Coins += 10, e o próximo salvamento pega a mudança. |
PlayerData.Loaded | Dispara com o jogador quando os dados dele estão prontos, inclusive depois de um carregamento que falhou. Passa só o jogador, porque uma tabela enviada por um BindableEvent chega como cópia. |
PlayerData.CanSave(player) | false se o carregamento falhou. Confira antes de vender qualquer coisa: uma compra que não pode ser salva some quando o jogador sai. |
PlayerData.SaveNow(player) | Salva na hora e devolve true se deu certo. Pausa. |
O módulo é o único lugar em que os dados salvos vivem, e o leaderstats é só uma vitrine: monte-o como no guia de leaderboard, preencha a partir de PlayerData.Get(player) em uma função do Loaded, e atualize os dois quando um valor mudar. Nunca leia valores salvos de volta do leaderstats, e nunca deixe um segundo script salvar a mesma chave.
Um script que dá require no módulo depois que os jogadores já entraram perde o Loaded deles. Conecte a função, depois percorra também Players:GetPlayers() e trate qualquer jogador para quem PlayerData.Get(player) já devolve uma tabela.
Está substituindo um script de salvamento mais antigo, como o do guia de leaderboard? Os valores dele ficam no próprio data store e na própria chave, então este módulo começa todo mundo dos valores padrão. Antes do lançamento, aponte STORE_NAME e o prefixo User_ para os antigos (o migrate trata dados sem SchemaVersion como versão 1 e preenche os campos que faltam), ou copie os valores antigos, e depois remova o script antigo.
Os clientes nunca mudam estes dados direto. Um botão de loja dispara um RemoteEvent; o servidor confere CanSave, compara o preço com as Coins do jogador, muda a tabela e chama SaveNow. O guia de loja com GUI monta esse fluxo de compra no servidor.
Para um exemplo pronto de como adicionar campos, o guia de simulador de cliques adiciona PowerLevel e Rebirths a DEFAULTS e ao tipo Data, depois os muda na tabela que PlayerData.Get devolve. O migrate dá os campos novos aos jogadores com salvamentos antigos.
Passo 3: Avise o jogador quando os dados dele não carregaram
Um jogador cujos dados falharam ao carregar deve saber que esta sessão não vai ser salva, para poder entrar de novo em vez de jogar à toa. Este LocalScript observa o atributo DataLoaded e mostra uma faixa quando ele é false.
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local shown = false
local function showWarning()
if shown or player:GetAttribute("DataLoaded") ~= false then
return
end
shown = true
local gui = Instance.new("ScreenGui")
gui.Name = "DataWarning"
gui.ResetOnSpawn = false
local label = Instance.new("TextLabel")
label.AnchorPoint = Vector2.new(0.5, 0)
label.Position = UDim2.new(0.5, 0, 0, 12)
label.Size = UDim2.new(0.8, 0, 0, 48)
label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
label.TextColor3 = Color3.new(1, 1, 1)
label.TextScaled = true
label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
label.Parent = gui
gui.Parent = player:WaitForChild("PlayerGui")
end
-- O servidor define DataLoaded uma vez, depois de tentar carregar os dados deste jogador
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Passo 4: Teste o salvamento no Studio
Faça isto na cópia de teste, com o acesso do Studio ativado.
- Dê a você mesmo algo para salvar. Embaixo da linha do require no
Main, adicione:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Aperte Play. A janela Output (no menu Window, ou na aba Script) mostra o seu nome e 100 (na primeira vez), sem o aviso
Could not load. - Aperte Stop. Terminar o teste fecha o servidor, e o módulo salva você antes de fechar.
- Aperte Play de novo. O Output deve mostrar 200, 100 a mais que da última vez. Se mostrar o mesmo número de novo, o salvamento não deu certo: leia os avisos acima dele.
- Teste o caminho de falha. Desative o acesso do Studio e aperte Play. Depois de vários segundos de novas tentativas, o Output mostra
Could not load User_...e 100, e a faixa do Passo 3 aparece. Pare, ative o acesso de novo e aperte Play: o Output mostra 300, os seus 200 salvos mais 100, porque a sessão que falhou nunca foi salva por cima dos seus dados. - Remova a linha de teste do
Main.
Por que os dados dos jogadores se perdem
Estes são os jeitos mais comuns de um sistema de salvamento perder progresso. O módulo trata as quatro primeiras linhas e a linha do schema no código; as outras dependem do que você guarda e de como usa, e a última precisa de session locking.
| O que acontece | Resultado | Prevenção |
|---|---|---|
| Um carregamento falha e o script salva mesmo assim | Os valores padrão sobrescrevem o progresso real: uma perda total | Nunca salvar um jogador cujo carregamento falhou |
Salvar só no PlayerRemoving | Um crash ou um desligamento pula o salvamento | Autosave, mais um BindToClose que espera os salvamentos |
Sem pcall ou sem nova tentativa | Uma requisição que falha para o script ou perde o salvamento | pcall com algumas novas tentativas espaçadas |
| Salvar a cada mudança | As requisições entram em fila; quando uma fila tem 30, as novas são descartadas | Guardar os dados em memória e salvar em um timer |
| Salvar algo que um data store não consegue guardar | O salvamento dá erro, ou o valor volta como nil | Salvar numbers, strings, booleans e tabelas deles |
| Mudar o formato dos dados sem migração | Salvamentos antigos carregam nos campos errados | Uma versão de schema e um passo de migração |
| Dois scripts salvando a mesma chave | Cada salvamento sobrescreve os campos do outro | Um módulo é o dono da chave |
| Dois servidores com o mesmo jogador | O servidor com os dados mais velhos salva por último e sobrescreve o progresso mais novo | Session locking |
Session locking, "lock lost" e ProfileStore
Um jogador fica conectado a um servidor por vez, mas o salvamento final do servidor antigo ainda pode estar rodando quando ele entra em um novo: uma nova tentativa lenta, um teleporte ou uma volta rápida. Se o servidor novo carregar primeiro, ele fica com dados mais velhos, e quem salvar por último vence. A documentação da Roblox observa que, em jogos com trocas, essa brecha é uma fonte comum de duplicação de itens.
O session locking fecha essa brecha. Quando um servidor carrega a chave de um jogador, ele grava o próprio ID de trava nos metadados da chave na mesma chamada de UpdateAsync. Qualquer outro servidor que encontrar uma trava não expirada que não foi ele quem colocou não carrega nem salva a chave. O dono renova a trava a cada autosave e a remove no salvamento final; se ele parar de renovar, a trava expira e outro servidor pode pegá-la.
O que "lock lost" significa
Em um sistema com session locking, um servidor perdeu a trava quando outro servidor agora é dono da chave do jogador, porque a trava expirou ou foi tomada. A cópia dele pode estar desatualizada, então ele precisa parar de salvar aquele jogador; uma resposta comum é expulsá-lo com uma mensagem para ele se reconectar. Se você viu "lock lost" como jogador, isso vem do próprio sistema de salvamento daquele jogo, e só os desenvolvedores dele podem explicar.
Você precisa disso?
O módulo deste guia não trava sessões. Sem trava, o pior caso realista é um jogador perder o que ganhou no servidor antigo desde o último salvamento bem-sucedido dele, em uma disputa rara. Adicione a trava quando duplicação ou perda custariam algo de verdade para os jogadores: trocas, developer products, itens raros ou teleportes frequentes.
| Opção | O que é | Vale saber |
|---|---|---|
| O módulo deste guia | Carregamento, memória, novas tentativas, autosave, salvamento no desligamento e versões de schema, sem trava | Curto o bastante para ler inteiro e mudar |
| O exemplo de dados do jogador e compras da Roblox | Código de referência da Roblox com session locking, novas tentativas processadas em ordem por chave e tratamento de recibos de compra | A Roblox diz que ele não foi provado ao longo do tempo em um jogo popular e não deve ser usado como está sem testes extensos |
| ProfileStore | Um módulo grátis e open source da comunidade, sucessor do ProfileService, construído em volta de session locking e autosave | Não é feito pela Roblox. Levar um jogo que já existe para ele significa migrar os dados que você já salvou |
Para qualquer módulo de terceiros, a Roblox aconselha conferir quem é o dono, se ele é mantido e como você chegaria aos seus dados sem ele. A mesma documentação chama o DataStore2 de biblioteca legada que jogos novos não devem usar.
Limites dos data stores
Estes são os limites da documentação da Roblox em 30 de setembro de 2026. A Roblox os revisa, então confira a página de códigos de erro e limites (em inglês) antes de planejar em cima de um número exato.
| Tipo de requisição | Data stores padrão | Ordered data stores |
|---|---|---|
Leitura: GetAsync, a leitura no UpdateAsync | 60 + 40 × jogadores | 60 + 40 × jogadores |
Gravação: SetAsync, IncrementAsync, a gravação no UpdateAsync | 60 + 40 × jogadores | 30 + 5 × jogadores |
Listagem: ListKeysAsync, ou GetSortedAsync para ordered stores | 5 + 2 × jogadores | 5 + 2 × jogadores |
Remoção: RemoveAsync | 60 + 40 × jogadores | 30 + 5 × jogadores |
Com 20 jogadores, um servidor pode fazer 860 gravações padrão por minuto; o autosave deste módulo usa umas 7 delas, mais uma por jogador que sai. Salvar a cada moeda coletada é o que estoura um orçamento. Um segundo orçamento cobre o jogo inteiro e é dividido com o Open Cloud: 300 leituras por minuto mais 40 por jogador online, e 300 gravações mais 20 por jogador.
| Limite | Valor |
|---|---|
| Nome do data store, nome da chave, scope | 50 caracteres cada |
| Valor guardado em uma chave | 4.194.304 caracteres, medidos em JSON |
| Leituras de uma chave, somando todos os servidores | 25 MB por minuto |
| Gravações em uma chave, somando todos os servidores | 4 MB por minuto, com cada requisição arredondada para cima até o próximo KB |
| Requisições esperando | 30 por fila; além disso, as requisições falham com os erros 301 a 306 |
| Armazenamento do jogo inteiro | 500 MB mais 1 MB por usuário de todos os tempos |
Meça os dados de um jogador com #HttpService:JSONEncode(data), e veja o orçamento que sobra em um servidor ao vivo com DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Chamadas de GetAsync respondidas pelo cache de 4 segundos não contam. O modo Run do Studio tem limites próprios, talvez menores, então a Roblox sugere o Team Create para testar limites de requisições.
Versões e backups
Data stores padrão guardam o histórico para você. A primeira gravação em uma chave em cada hora UTC é mantida como uma versão, e as gravações seguintes naquela hora sobrescrevem umas às outras. Uma versão antiga expira 30 dias depois que uma gravação mais nova a substitui; a mais recente nunca expira. Ordered data stores não guardam versões.
Para voltar os dados de um jogador, abra o Data Stores Manager (Creations, o seu jogo, Configure > Data Stores Manager), selecione a chave dele, escolha uma versão anterior e clique em Revert, o que precisa de permissão de Edit. Faça isso com o jogador offline, senão o servidor com a sessão dele vai salvar a cópia dele por cima da reversão. A partir de um script de servidor, ListVersionsAsync e GetVersionAsync acham e leem uma versão antiga, que você então grava de volta como o valor atual.
Antes de publicar uma atualização que muda como os dados são salvos, a Roblox recomenda um snapshot com a API Snapshot Data Stores do Open Cloud (um por dia por jogo). Sem ele, um salvamento com bug às 3:30 UTC sobrescreve tudo o que foi gravado naquela chave desde as 3:00, porque cai na mesma versão da hora.
Erros comuns e como resolver
Os erros de data store aparecem na janela Output do Studio, e o módulo imprime um aviso com o texto de erro da Roblox a cada tentativa que falha. O guia de erros de script explica como ler o Output em geral.
StudioAccessToApisNotAllowed (erro 403)
"Can't write to DataStore from Studio because API access is not enabled." Publique o jogo, depois ative Enable Studio Access to API Services em File > Experience Settings > Security, na cópia de teste.
DataStore request was added to queue
O servidor está enviando requisições mais rápido que o orçamento dele, ou gravando a mesma chave com frequência demais, normalmente por salvar a cada mudança ou em um loop. Quando uma fila tem 30, as requisições novas falham com os erros 301 a 306. Guarde os dados em memória e salve em um timer.
CantStoreValue (erro 104), ou um campo volta como nil
A tabela tem algo que um data store não consegue salvar, como uma Instance, um Vector3 ou um Color3. Salve um nome, um ID ou números simples no lugar e recrie o objeto ao carregar.
ValueTooLarge (erro 105)
Uma chave guarda mais de 4.194.304 caracteres de JSON. Meça com #HttpService:JSONEncode(data), tire o que você consegue recriar, ou divida os dados entre algumas chaves fixas.
Sem erros, mas os dados não salvam
Procure o aviso Could not load do módulo: depois de um carregamento que falhou, ele se recusa a salvar, de propósito. Senão, o valor provavelmente foi mudado em um LocalScript, que nunca chega ao servidor, ou outro script salva a mesma chave.
Os dados zeram toda vez que eu entro de novo
A chave muda entre as sessões (montada a partir de player.Name, ou o STORE_NAME foi editado), o carregamento falha e você vê os padrões, ou nada dá require no módulo e ele nunca roda. Confira o Output e se o Main dá require em PlayerData.
Crie com o RoCode
Se você prefere não montar isso à mão, o RoCode pode construir dentro do jogo que você tem aberto. Ele é um agente de IA independente, não feito pela Roblox, que trabalha por meio de um plugin do Roblox Studio: escreve Luau que usa o DataStoreService como qualquer script e cria os scripts no seu Explorer. Ele nunca chama os seus data stores sozinho, mas com o plugin 3.9 ou mais recente pode apertar Play para um teste curto, em que os seus scripts rodam como em qualquer teste.
Adicione salvamento ao meu jogo: guarde Coins, Level e Inventory em um módulo PlayerData com autosave e salvamento no desligamento, e mostre Coins no leaderstats que eu já tenho.
- Pode procurar código de leaderstats e de DataStore que já existe com Search Scripts e Read Script, para ampliar o que você tem em vez de adicionar um segundo script de salvamento. Em um jogo grande, diga o nome do script ou da pasta na sua mensagem.
- Cria o ModuleScript e o Script que dá require nele com Create Script, ou muda os que você já tem com Edit Script
- Roda Check Script em cada script que escreveu: uma verificação de compilação dentro do Studio com uma lista curta de avisos, não uma verificação de tipos nem um teste
- Envia as mudanças em lotes, e cada lote é um ponto de desfazer no Studio
Você ainda ativa o Studio Access to API Services na sua cópia de teste: o RoCode não consegue mudar essa configuração. Com o plugin 3.9 ou mais recente, o teste curto dele lê os erros, e com o plugin 3.9.11 ou mais recente ele pode controlar um personagem de teste para conferir se o jogo funciona, mas ele confere só o que escolheu testar, então jogue você mesmo para conferir se Coins, Level e Inventory salvam e carregam. Se um salvamento falhar no seu teste, o Check Output consegue ler as linhas do Server do teste que você rodou. Salvar costuma vir depois que o loop principal funciona; fazer um jogo do Roblox com IA um sistema de cada vez mostra essa ordem. Como o RoCode se conecta ao Studio.
Perguntas frequentes
Como ativar o DataStore no Roblox Studio?
Publique o jogo, abra File > Experience Settings > Security, ative Enable Studio Access to API Services e clique em Save. Faça isso em um jogo de teste separado, porque o Studio passa a usar os mesmos data stores dos servidores publicados daquele jogo.
O Roblox salva os dados do jogador automaticamente?
Não. Nada sobre um jogador dura além da sessão a não ser que um script de servidor salve com o DataStoreService, e isso inclui o leaderstats.
Devo usar o ProfileStore ou o DataStoreService direto?
O ProfileStore também é construído em cima de data stores, então a pergunta é se você quer session locking escrito e mantido por outra pessoa. Para trocas, itens pagos ou teleportes frequentes, vale ter a trava, de uma biblioteca ou do exemplo de referência da Roblox. Para um jogo menor, um módulo como este é mais fácil de ler e mudar.
Como zerar ou apagar os dados de um jogador?
No Data Stores Manager, ache a chave e escolha Mark for Deletion, que você pode desfazer durante um período de espera, ou chame RemoveAsync na chave a partir de um script de servidor. Faça isso com o jogador offline, senão o próximo salvamento do servidor dele grava os dados de volta. Na cópia de teste, mudar o STORE_NAME começa todo mundo do zero; nunca faça isso em um jogo publicado.
Fontes e leitura extra
- Roblox Creator Docs: Data stores (em inglês). acesso no Studio, GetAsync, SetAsync, UpdateAsync, set vs update
- Roblox Creator Docs: Best practices for data stores (em inglês). uma chave por jogador, dados em memória, novas tentativas com backoff, módulos de terceiros
- Roblox Creator Docs: Data store error codes and limits (em inglês). códigos de erro, limites de requisições do servidor e do jogo, limites de tamanho, vazão e armazenamento
- Roblox Creator Docs: Versioning, listing and caching (em inglês). versões por hora, snapshots, o cache de 4 segundos, o que pode ser salvo
- Roblox Creator Docs: Implement player data and purchasing systems (em inglês). o exemplo de referência, session locking, carregamentos que falham, o autosave de 180 segundos
- Roblox Creator Docs: Data Stores Manager (em inglês). ver chaves, reverter versões, apagar dados
- Roblox Engine API: DataModel:BindToClose (em inglês). a janela de 30 segundos no desligamento
Como o código foi verificado: todo script desta página passa no verificador de tipos estrito do Luau com as definições da API do Roblox (luau-lsp, 12 de novembro de 2026). A verificação de tipos pega APIs com nome errado e tipos incorretos, não a lógica do jogo, então teste no Studio antes de publicar.