View source for ROBLOX Scripting How To: Data Persistence

Welcome to one of the first of many to come guides from ROBLOX on cool new scripting features!

In this guide I'll be showing you how to use Data Persistence in your place. As a general warning, you'll probably want to be a least somewhat proficient at scripting; in other words, this shouldn't be your first script. It's not extremely difficult, though, so don't put off learning it! It's a great feature that'll majorly enhance your game!


== '''What is Data Persistence?''' ==

Have you created a game that players earn money in? That has checkpoints (like an obby) or maybe you've made a building place where people make their own creation, or maybe another type of place- It doesn't matter! Data Persistence will probably come in '''very''' handy with any place!


These are all great examples of places that can benefit from Data Persistence.  Data Persistence is the ability to save some data (like a number, or a string, or a brick) for a player in your game, so when they come back you can load in what they had last time they visited your place (such as the amount of money they earned, or a level they gained, etc.)



== '''How do I use Data Persistence?''' ==

Persistence is completely done via Lua, with calls on the individual player to save/load a piece of data for a particular place, as this is a Per User Per Place (PUPP) paradigm.  In simpler terms, this means for each place, each player can have saved data.  The model for this data is key/value pairs, with the key being a string you specify (more on this in the example code), and the value is determined by the call.


The following are our current calls for saving different types of data, and each of these calls can be found under Player. Due to this, you can not save/load from players not in the same server as the script executing the function call.

[[SaveBoolean]]([[String]] key, [[Bool]] value)

[[SaveNumber]]([[String]] key, [[Number]] value)

[[SaveString]]([[String]] key, [[String]] value)

[[SaveInstance]]([[String]] key, [[Instance]] value)


All of these calls do essentially the same thing, except they each will save different types of data, in accordance with the call name.  Let's look at the arguments we pass these functions:

'''[[String]] key -''' Think of this as a literal key that you would use to unlock a door.  Whatever you call this key - "Money", "Experience", maybe even "Pink Elephant" will be the key for loading (unlocking) any data you save later.

'''Value -''' this is the actual thing that you want to save for the player.  What this is depends on the functions you call, if you call SaveBoolean(), you'll want to use a [[Boolean]] (true/false) value.  If you use some data type other than the one specified by the function, you will get an error!


For each save function, we have a corresponding load function:

[[LoadBoolean]]([[String]] key)

[[LoadNumber]]([[String]] key)

[[LoadString]]([[String]] key)

[[LoadInstance]]([[String]] key)


If you use the same key you defined while saving a value from above, you will now get the same value you saved returned from each of these functions.



== '''Things to be Aware Of''' ==


=== '''What is save/load [[Instance]] all about?''' ===

These functions will save any object that can be placed under workspace (including all of the object’s descendants), which also brings up a key point:
'''All of the save functions have a data cap on how large the saves can be''', if this cap is reached no new data will be saved to that particular key (we believe the size of each to be sufficient currently, but if we see a need to raise it in the future, we will consider raising).


=== '''What's with this [[Player]].[[DataReady]] stuff?''' ===

This is a very important part of data persistence, which will we show more of in the Examples below.  On the Player object there is now a read-only [[Boolean]] value called [[DataReady]].  This value indicates whether the player is ready to have save/load functions called on him or her.  When a player initially joins a game, [[DataReady]] is false.  After a few seconds, [[DataReady]] will typically become true (at this point you can freely call save/load functions).  The best way to determine when [[DataReady]] goes from false to true is to use the [[WaitForDataReady]] function:

<pre>
player:WaitForDataReady()
</pre>

This function will wait until [[DataReady]] on player is true. Note: if [[DataReady]] never becomes true, we will sit and wait indefinitely on this property, effectively stopping the script from executing.


=== '''Why you should use [[pcall]] with Data Persistence''' ===

If you're not familiar with [[pcall]], you definitely will be after using persistence.  [[Pcall]] stands for "protected call", and rightfully so.  '''Any code executed inside of a pcall will not cause a script to crash'''.  Rather, the pcall will return with the error message the failed code has output.  Why is this important in respect to Data Persistence?  '''You should always wrap your save/load calls in a pcall''', just in case the call fails, you can handle the error in your script and continue on.  Here is an example:

<pre>
local playerScore
if not pcall(function() playerScore = player:LoadNumber("Score") end) then
   playerScore = 0
end
</pre>

The above code tries to load a number into playerScore with the key "Score" on the player object.  If for some reason we can't load the number (maybe we have never saved something to the key "Score", maybe Data Persistence goes down in the middle of the game, etc.), we can now recover by checking if the [[pcall]] succeeds.  In this example, if we fail we just assign a player score of 0 and allow the script to keep running.

== '''Examples''' ==

=== '''Loading example''' ===

The first place that used persistence was [http://www.roblox.com/Welcome-to-ROBLOX-Building-item?id=41324860 Welcome to ROBLOX Building], so naturally we thought it would be a good piece of example code.  Models that players build are saved, so when they come back they can continue to build on their creations.  Consider the following code snippet:

<pre>
player:WaitForDataReady()

local savedBuildingArea
local success = pcall(function() savedBuildingArea = player:LoadInstance("PlayerArea") end)

if not success or savedBuildingArea == nil or not savedBuildingArea:FindFirstChild("BasePlate") then
   createNewPlayerArea(area)
else
   local offset = area.BasePlate.CFrame.p - savedBuildingArea.BasePlate.CFrame.p
   area.BasePlate.Parent = nil
   savedBuildingArea:TranslateBy(offset)
   savedBuildingArea.Parent = area
   savedBuildingArea:MakeJoints()
end
</pre>



First we call ":WaitForDataReady()" - If you've not read the above guide on this, it basically just waits until the player is ready to have data loaded and saved. Next, we try to load in a key titled “PlayerArea” for our particular player.  Putting this in a [[pcall]] is a good idea, if we get an error (maybe this is the player’s first visit to your place, see Things to be Aware Of for more info) we can handle that situation. If we fail at loading "PlayerArea", our script then creates a new playerArea.  Otherwise, if we succeed in loading a previous playerArea, we set it up for use by the player.


=== Saving example ===

<pre>
function removePlayer(player)
   if not pcall(function() player:SaveInstance("PlayerArea", takenAreas.PlayerArea) end) then
      print("error saving")
   end
end

game.Players.PlayerRemoving:connect(function(player)
   removePlayer(player)
end)
</pre>


The above script simply tries to save an [[Instance]] "takenAreas.PlayerArea" to the key “PlayerArea” for the player simply called “player” when he or she leaves the game (typically it is good practice to only save when a player leaves your game, saves done in game don't actually get pushed out until the player leaves, thus saving in the middle of playing doesn't do much).  Once again we do this with a [[pcall]], just in case persistence isn’t working properly we can handle the error.  Saving for bools, numbers and strings work the same way, except it will throw an error if you try to pass the functions anything except for the type they specify respectively.


I hope that was pretty straightforward, if you have any questions please feel free to send Jeditkacheff a Private Message on ROBLOX [http://www.roblox.com/My/PrivateMessage.aspx?RecipientID=7210880 here].  

It may also be a good idea to post on the Scripting Helpers forum [http://www.roblox.com/Forum/ShowForum.aspx?ForumID=20 here]. 

Happy persisting!

==See Also==
'''Tutorials'''
*[[Data_Persistence]]
*[[Data Persistence Tutorial]]
*[[How To Efficiently Use Data Persistence]]

'''Methods'''
*[[LoadBoolean (Method)]]
*[[LoadNumber (Method)]]
*[[LoadString (Method)]]
*[[LoadInstance (Method)]]
*[[SaveBoolean (Method)]]
*[[SaveNumber (Method)]]
*[[SaveString (Method)]]
*[[SaveInstance (Method)]]