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.

  1. Make sure your game is published (File > Publish to Roblox) to enable Studio access.

  2. From the Home tab, open the Game Settings window.

  3. In the Security section, turn on Enable Studio Access to API Services.

    alt

  4. 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.

  1. Create a new Script within ServerScriptService called GoldManager.

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


    1local DataStoreService = game:GetService("DataStoreService")
    2
  3. Call DataStoreService:GetDataStore() with the string "PlayerGold". This will access the PlayerGold data store if it already exists, or create it otherwise.


    1local DataStoreService = game:GetService("DataStoreService")
    2local goldStore = DataStoreService:GetDataStore("PlayerGold")
    3

Saving the 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 UserId or simply a named string for a game promo.

Player Data Example

Key Value

31250608

50

351675979

20

505306092

78000

Promo Examples

Key Value

ActiveSpecialEvent

SummerParty2

ActivePromoCode

BONUS123

CanAccessPartyPlace

true

To save player data in the data store:

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


    1local DataStoreService = game:GetService("DataStoreService")
    2local goldStore = DataStoreService:GetDataStore("PlayerGold")
    3
    4-- Data store key and value
    5local playerUserID = 505306092
    6local playerGold = 250
    7
  2. To save data into the PlayerGold data store, call SetAsync within a protected call, passing the key and value variables previously created.


    1local DataStoreService = game:GetService("DataStoreService")
    2local goldStore = DataStoreService:GetDataStore("PlayerGold")
    3
    4-- Data store key and value
    5local playerUserID = 505306092
    6local playerGold = 250
    7
    8-- Set data store key
    9local setSuccess, errorMessage = pcall(function()
    10 goldStore:SetAsync(playerUserID, playerGold)
    11end)
    12if not setSuccess then
    13 warn(errorMessage)
    14end
    15

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 12 and, if SetAsync() failed for any reason, errorMessage is displayed in the Output window.

Reading Data

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


    1local setSuccess, errorMessage = pcall(function()
    2 goldStore:SetAsync(playerUserID, playerGold)
    3end)
    4if not setSuccess then
    5 warn(errorMessage)
    6end
    7
    8-- Read data store key
    9local getSuccess, currentGold = pcall(function()
    10 return goldStore:GetAsync(playerUserID)
    11end)
    12if getSuccess then
    13 print(currentGold)
    14end
    15
  2. 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.

    alt

Sample Project

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

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

You can also edit the game in Studio and explore the enhanced GoldManager script which includes data auto-saving and more.