Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Data Stores and Services

DataStores: Saving and Loading Data in Roblox

Learn how Roblox DataStores store data between sessions, how keys and values work, why every call needs pcall, and how to test saving safely in Studio.

Everything in a running server disappears when the server shuts down: scores, coins, unlocked items, the level a player reached. If you want a player to find their progress next time, you must save it somewhere permanent. Roblox gives you this storage for free through DataStores: a cloud key-value database attached to your experience.

This lesson explains the core ideas and the three methods you need first. It also teaches the habit that separates reliable games from broken ones: always expect saving to fail. The Roblox code is shown read-only because the real service is not available on this site; the runnable examples are a JavaScript mock with the same shape, including simulated failures.

Keys and values

A DataStore is like a giant table of key and value pairs. The key is a string, the value is data. The common pattern is one key per player, built from the player's UserId:

Text
"Player_1234567"  ->  { coins = 120, level = 4, items = { "Sword", "Boots" } }

Rules to remember:

  • Use UserId, never the player's name, because names can change. Build keys like "Player_" .. player.UserId.
  • Values can be numbers, strings, booleans and tables of these. Tables may nest, but keys must be strings or consecutive numbers, not mixed. Instances, functions and Vector3 or Color3 values cannot be saved directly. Convert them to numbers or plain tables first.
  • Size limits apply to keys and values, and request limits apply per minute. They are documented by Roblox and can change, so check the current figures when you design your system.
  • DataStores work only on the server. A LocalScript cannot save, which is also why a cheater cannot edit saves.

Getting a DataStore

LUA
local DataStoreService = game:GetService("DataStoreService")
local playerStore = DataStoreService:GetDataStore("PlayerData")

The name "PlayerData" creates (or opens) a named store. If you change the name, you open a completely different, empty store, so pick one and keep it. Many developers append a version for deliberate resets while testing: "PlayerData_v1".

To test DataStores in Studio, open Game Settings, then Security, and turn on Enable Studio Access to API Services. The experience must also be published at least once, because DataStores belong to a published experience.

GetAsync, SetAsync and the need for pcall

The three basic methods are:

LUA
playerStore:SetAsync(key, value)   -- write (overwrites)
local value = playerStore:GetAsync(key)   -- read (nil if the key has never been saved)
playerStore:RemoveAsync(key)       -- delete

All of them contact Roblox's servers over the internet. Requests can fail because of a network error, an outage, or because you exceeded a rate limit. When a DataStore call fails it throws an error and would stop your script. You must catch it with pcall (protected call):

LUA
local success, result = pcall(function()
	return playerStore:GetAsync("Player_" .. player.UserId)
end)

if success then
	print("Loaded:", result)
else
	warn("Could not load data:", result) -- result holds the error message
end

pcall returns true plus the function's results when everything works, or false plus the error message when something fails. This is the Luau equivalent of try/catch.

The DataStore habits

Key by UserId Names can change. IDs never do.
Wrap in pcall Every call can fail.
Server only Clients cannot save or edit.
Enable Studio access Needed to test saving.

Never overwrite saved data with defaults after a failed load.

1 / 2

That last note is the most important rule in this chapter. If loading fails and you assume the player is new, then save the default data later, you erase a real player's progress. When a load fails, either retry or stop the player from saving.

A runnable DataStore mock

This mock behaves like a DataStore: asynchronous, returns nil for missing keys, and can fail at random. It uses a fixed pattern of failures, so the output is always the same.

JS A mock DataStore with pcall (JavaScript stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first load returns null (JavaScript's nil), which means the player has never been saved, which is different from a failed load. Distinguish those two cases in your own code.

Handling "new player" versus "failed load"

LUA
local success, data = pcall(function()
	return playerStore:GetAsync(key)
end)

if not success then
	-- network problem: do NOT treat as new, retry or kick with a message
elseif data == nil then
	-- never saved before: a brand new player, create default data
else
	-- returning player: use data
end

Three branches, three meanings. Writing them out makes the bug of overwriting good data almost impossible.

JS Three outcomes of a load

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What to save

Save as little as you need. Good candidates: currency, level, unlocked items, settings. Poor candidates: anything you can compute again, anything huge (inventory with thousands of entries should be compressed or split), and anything temporary such as a player's current position in a round.

Store identifiers, not instances. Save { "Sword", "Boots" } rather than the sword object, and look the tool up in ServerStorage when loading.

Add a version field (for example version = 1) to your table now. When you later change the data layout, you can read the old version and convert it. This tiny habit saves hours.

Common mistakes

  • Calling DataStore methods without pcall.
  • Saving in a LocalScript (it errors; saving is server-only).
  • Using player.Name in the key.
  • Treating a failed load as a new player and overwriting good data.
  • Trying to save Instances, Vector3, or tables with mixed key types.
  • Forgetting to enable Studio API access and thinking saving is broken.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What should you use to build a player's DataStore key?

    UserId never changes, while names and display names can.
  2. 2. What does GetAsync return for a key that has never been saved?

    A missing key returns nil, which usually means a brand new player.
  3. 3. Why must every DataStore call be wrapped in pcall?

    DataStore requests go over the internet and can fail. pcall catches the error so your script keeps running.
  4. 4. What is the most dangerous mistake after a failed load?

    Overwriting a real save with defaults destroys the player's progress. Retry or block saving instead.
  5. 5. Where can DataStores be used?

    DataStores are server-only, so clients cannot read or edit saves directly.

Summary

  • A DataStore is a cloud key-value store tied to your experience; key players by "Player_" .. UserId.
  • Use GetAsync, SetAsync and RemoveAsync on the server only, and wrap each call in pcall.
  • Separate three outcomes: failed load, new player (nil), and returning player.
  • Never save defaults over data after a failed load.
  • Save only plain data (numbers, strings, booleans, tables), add a version field, and enable Studio API access to test.

Next: Saving Player Data the Right Way