Persistent Data (ssk.persist.*)

This library provides a handy way to automatically save and restore (persist) data.

Currently this feature works on all platforms, excluding Apple TV.

Apple TV support will be added in the future. - The Roaming Gamer

Setting Default Values

The ssk.persist library lets you set 'default' values for any named field. This way, if you call get() for a named field before you set() it, you will get a valid value.

To set a defaut value for a field in a persistent data set, use this function:

ssk.persist.setDefault( fileName, fieldName, value [ , params ] )

fileName - Name of file to save persistent data in.
fieldName - Name of setting to set default for.
value - Value to set as default for fieldName.
params ({}) - Optional table of parameters.
- save (true) - Save immediately to file.
- base (system.DocumentsDirectory) - Base folder type for save file.

Setting and Getting Values

Use these functions set and get values respectively:

ssk.persist.set( fileName, fieldName, value [ , params ] )

ssk.persist.get( fileName, fieldName [ , params ] )

fileName - Name of file to save persistent data in.
fieldName - Name of setting to set default for.
value - Value to set as default for fieldName.
params ({}) - Optional table of parameters.
- save (true) - Save immediately to file.
- base (system.DocumentsDirectory) - Base folder type for save file.

Setting Secure Mode

If you wish, you can ask ssk.persist to use the ssk.security module when saving and loading data with this function:

ssk.persist.setSecure()

Just be sure you turn on secure mode before you first use the module. (See Complete Example below.)

Multiple Sets Allowed?

As you may have determined already, this module supports multiple separate data sets. Simply use different names for the fileName setting and your data will be separated into independent sets. (See Complete Example below.)

Data Caching

This library utilizes caching to speed up data accesses.

Whenever a persistent data set is mofified the following checks occur:

Is data cached?
- If not, load it from file or create blank record.
- Cache data in persist module.
Is there a value for the field user is accessing?
- If not, and if there is a default set,
  - Set field in cached copy to default
  - Return default value.
Did user set save parameter to false?
- If not, save cached data immediately

I will be modifying this slightly in the future to handle back to back set/setDefault calls with save set to true. This modification will prevent these saves from blocking and affecting frame rate.

Complete Persist Example

The following example shows a example usage with automatic secure mode enabling when on device.


-- Enable secure mode if on device, but use un-encoded saves when on the simulator
-- Tip: This makes checking your saves and hand-modifying them easy while testing in the simulator.
--
if( ssk.system.onDevice ) then
   ssk.persist.setSecure()
end

-- Set up two data sets with defaults
--
ssk.persist.setDefault( "iap.json", "disabled_ads", false , { save = false } )
ssk.persist.setDefault( "iap.json", "bought_extra_content", false )

ssk.persist.setDefault( "settings.json", "sound_enabled", true, { save = false } )
ssk.persist.setDefault( "settings.json", "last_score", 0 )

-- Check persistent data fields
print( "Ads disabled? ", ssk.persist.get( "iap.json", "disabled_ads") )

print( "Last Score: ", ssk.persist.get( "settings.json", "last_score" ) )

-- Set 'last score' to a random value
ssk.persist.set( "settings.json", "last_score", math.random(100, 10000) )

-- Check persistent data fields again
print( "Ads disabled? ", ssk.persist.get( "iap.json", "disabled_ads") )

print( "Last Score: ", ssk.persist.get( "settings.json", "last_score" ) )