View source for User:Ben

== '''ROBLOX Scripting How-To: Data Persistence''' ==


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.


Now with that out of the way, let's start with the basics: '''What is Data Persistence?'''

Have you created a game that players earn money in? That has checkpoints (like an obby)? Maybe you've made a building place where people make their own creations.


These are all great examples of that 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.)



So, now the next question: '''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:

[[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 as follows:

function waitForProperty(instance, name)

while not instance[name] do

instance.Changed:wait()

end

end

waitForProperty(player,"DataReady")

This waitForProperty() function will wait until DataReady on player is true.  This solution is much more optimal than polling, as it relies on events, which use less processing power.


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



== '''Examples''' ==



This is currently being employed by blazing man beta.  Models that players build are saved, so when they come back they can continue to build on their creations.  Consider the following code snippet:

function waitForProperty(instance, name)
	while not instance[name] do
		instance.Changed:wait()
	end
end

waitForProperty(player,"DataReady")

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

if not err 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


Walkthrough
So, why are we waiting for this property in Player called DataReady? Under each player is a bool called “DataReady”, when this property is true, this means persistent data is ready to be saved or loaded for that player.

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) we can handle that situation. 


Maybe it would make more sense to talk about saving data?  The following is the corresponding save mechanism for the above example:

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)

Walkthrough:
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.  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 pm me (jeditkacheff).  Happy persisting!