Saving Data

Games often need to store some amount of persistent data between sessions like a player's level, experience points, inventory items, gold/cash, and more.

This tutorial will show you how to create a basic data store, save sample data, and read the data back into a game session.

Enabling Studio Access

By default, games tested in Studio cannot access data stores, so you must first enable them.

Make sure your game is published to enable Studio access.
From the Home tab, open the Game Settings window.
In the Security section, turn on Enable Studio Access to API Services.
Click Save to register your changes.

Creating a Data Store

Data stores are identified by a unique name. In this example, a data store named PlayerGold will save each player's gold to persistent storage.

Create a new Script within ServerScriptService called GoldManager.

Data stores are managed by DataStoreService, so get the service on the first line.


local DataStoreService = game:GetService("DataStoreService")

Call DataStoreService:GetDataStore() with the string "PlayerGold". This will access the PlayerGold data store if it already exists, or create it otherwise.


local DataStoreService = game:GetService("DataStoreService")

local goldStore = DataStoreService:GetDataStore("PlayerGold")

A data store is essentially a dictionary, like a Lua table. Each value in the data store is indexed by a unique key, for instance the player's unique UserId or simply a named string for a game promo.

Key	Value
31250608	50
351675979	20
505306092	78000

To save player data in the data store:

Create a variable named playerUserID for the data store key. Then, use playerGold to store a player's starting gold amount.


local DataStoreService = game:GetService("DataStoreService")

local goldStore = DataStoreService:GetDataStore("PlayerGold")

-- Data store key and value
local playerUserID = 505306092
local playerGold = 250

To save data into the PlayerGold data store, call SetAsync within a protected call, passing the key and value variables previously created.


local DataStoreService = game:GetService("DataStoreService")

local goldStore = DataStoreService:GetDataStore("PlayerGold")

-- Data store key and value
local playerUserID = 505306092
local playerGold = 250

-- Set data store key
local setSuccess, errorMessage = pcall(function()
	goldStore:SetAsync(playerUserID, playerGold)
end)
if not setSuccess then
	warn(errorMessage)
end

Functions like SetAsync() are network calls that may occasionally fail. As shown above, pcall() is used to detect and handle when such failures occur.

In its most basic form, pcall() accepts a function and returns two values:

The status (boolean); this will be true if the function executed without errors, or false otherwise.
The return value of the function or an error message.

In the sample above, the status (setSuccess) is tested on line 13 and, if SetAsync() failed for any reason, errorMessage is displayed in the Output window.

Be careful to not send requests to data stores too often. Requests on a data store key are placed in a queue and, if the queue fills up, additional requests will be dropped.

A common mistake may be updating a player's gold data every time they collect a gold piece. Instead, store the player's gold in a variable and only update the data store occasionally, such as with a periodic auto-save and/or when the player leaves the game.

Reading Data

To read data from a data store, call GetAsync() with the desired key name.


local DataStoreService = game:GetService("DataStoreService")

local goldStore = DataStoreService:GetDataStore("PlayerGold")

-- Data store key and value
local playerUserID = 505306092
local playerGold = 250

-- Set data store key
local setSuccess, errorMessage = pcall(function()
	goldStore:SetAsync(playerUserID, playerGold)
end)
if not setSuccess then
	warn(errorMessage)
end

-- Read data store key
local getSuccess, currentGold = pcall(function()
	return goldStore:GetAsync(playerUserID)
end)
if getSuccess then
	print(currentGold)
end

To test the script, click Run and notice the currentGold value printed to the Output window. Note that it may take a couple seconds, as the functions must connect to data store servers.

Sample Project

Now that you understand basic data store usage, test it out in the Gold Rush sample game. You can also edit the game in Studio and explore the enhanced GoldManager script which includes data auto‑saving and more.