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 course 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 (File > Publish to Roblox) 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
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.
Player Data Example
Create a variable named
playerUserIDfor the data store key. Then, use
playerGoldto 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
PlayerGolddata store, call
SetAsyncwithin 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,
pcallis used to detect and handle when such failures occur.
In its most basic form,
pcallaccepts 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 12 and, if
SetAsyncfailed for any reason,
errorMessageis 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.
To read data from a data store, call GetAsync with the desired key name.
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
currentGoldvalue printed to the Output window. Note that it may take a couple seconds, as the functions must connect to data store servers.
Now that you understand basic data store usage, test it out in a sample game.
You can also edit the game in Studio and explore the enhanced GoldManager script which includes data auto-saving and more.