Saving Data – Introduction

5 min

DataStoreService saves data that persists between game sessions, for example a player’s gold/cash, experience points, or items in their inventory. Saved data is accessible from any place in a game and also between servers.

Enabling Studio Access

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

From the Home tab, open the Game Settings window. If your game is not published, you’ll be prompted to do so.

In the Security section, turn on Enable Studio Access to API Services.
Click Save to register your changes.

Be careful when accessing data stores through Studio for a live game with an active player base. Studio accesses the same data stores as the live game, so it's recommended that you access data stores in a separate test version of the game.

Accessing Data Stores

Data stores are initially created and accessed by a unique name. For example, a data store named PlayerGold can store each player’s gold during and between game sessions.

Create a new Script within ServerScriptService called DataStoreTest.

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

				
					Accessing a Data Store
				
					Expected Output
				
					Expand
					
			local DataStoreService = game:GetService("DataStoreService")
		
				Copy Code
			
				Light Theme

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

				
					Accessing a Data Store
				
					Expected Output
				
					Expand
					
			local DataStoreService = game:GetService("DataStoreService")
local goldStore = DataStoreService:GetDataStore("PlayerGold")
		
				Copy Code
			
				Light Theme

Sorted Data »

Data returned by DataStoreService/GetDataStore|GetDataStore() is not sorted. This isn’t a concern when reading specific individual keys, but sorted data fetched via DataStoreService/GetOrderedDataStore|GetOrderedDataStore() is essential for user interfaces like persistent leaderboards.

Saving Data

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 Player/UserId|UserId or simply a named string.

Player Data

Game Data

Key	Value
31250608	50
351675979	20
505306092	78000

Key	Value
ActiveSpecialEvent	SummerParty2
ActivePromoCode	BONUS123
CanAccessPartyPlace	true

To save data into the PlayerGold data store, call GlobalDataStore/SetAsync|SetAsync() with the key and a value:

				
					Save to Data Store
				
					Expected Output
				
					Expand
					
			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
		
				Copy Code
			
				Light Theme

Functions like GlobalDataStore/SetAsync|SetAsync() which access a data store's contents are network calls that may occasionally fail. As illustrated above, you should always wrap these calls in pcall() to catch and handle errors. See articles/Datastore Errors|here for more details on error handling.

Requests on a data store key are placed in a queue. If too many requests to the same key are made quickly, the queue can fill up and additional requests will be dropped. So, instead of updating a player's gold every time they collect a gold piece, store the player's gold in a table and only update the data store every so often, such as when the player leaves (Players/PlayerRemoving|Players.PlayerRemoving event).

Reading Data

To read data from a data store, call GlobalDataStore/GetAsync|GetAsync() with the desired key name:

				
					Read From Data Store
				
					Expected Output
				
					Expand
					
			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
		
				Copy Code
			
				Light Theme

Testing

Once you’ve finished the script, the PlayerGold data store can be tested.

Click the Run button.

If everything is correct, the playerGold value should be printed to the Output window. Note that it may take a few seconds, as the functions must connect to data store servers.

Sample Place

Now that you understand basic data store usage, test it out in a sample place.

Gold Rush

Gather as many gold chunks as you can to set a personal record that will persist between game sessions.

Tags:

data
data store
player data
game data

Saving Data – Introduction

Saving Data – Introduction

Enabling Studio Access

Accessing Data Stores

Sorted Data »

Saving Data

Reading Data

Testing

Sample Place

Gold Rush

Related Articles

Data Store Errors and Limits