[Tutorial]How to use SaveData and GameData

[hacheipe399]

The handbook of SMBX2 MAGLx3 build doesn't have enough info on how to use the SaveData table. This is the new way to handle saved data through levels or episodes, it replaces the Data class in usage. We don't need any classes or special functions to store information on an episode, this table will save us a lot of headaches with this regard.

The begin
First of all, we need to declare the table. If you want data to be stored in a single level, then use the Level.filename() function for the table, this works only for luna.lua files. Then, we create a new variable to store the table, so we can use it later:

Code: Select all

SaveData[Level.filename()] = SaveData[Level.filename()] or {}
 local levelsave = SaveData[Level.filename()]

or if we want to save values to be available from anywhere of the episode, we just name our table with a simple string:

Code: Select all

SaveData["episode"] = SaveData["episode"] or {}
local globalsave = SaveData["episode"]

If we think about it, we can make multiple savetables with different names, store different data and use it on different levels we need them. Also, if we want to consult remotely the data from a particular level, let's say, level44, we can use SaveData["level44.lvl"] from outside.

Starting to use SaveData
To set a new value, we just write its name and set it a value, it can be a number, string, boolean or even another table:

Code: Select all

levelsave.n = 30

Be careful! All values you use are null at the start, so we need to initialize them:

Code: Select all

function onStart()
      if levelsave.n == nil then
         levelsave.n = 0
   end
end

Now we're good to go!
That's how typically I initialize values because of how I use them, but always initialize them at onStart() or before any of the lua events.

How can we use level data outside levels?
If we want to access a level's data from the worldmap (map.lua), we need to get the level object by using the Level instance functions (only within a loop). In the following example, we want the data from the level we stand on, so we check if we sat foot on some level and we print a value from it:

Code: Select all

function onTick()
  if world.levelObj ~= nil then
     local lev = world.levelObj
     for i,k in ipairs(Level.get()) do
          if k == lev then
              SaveData[k.filename] = SaveData[k.filename] or {}
              local levelsave = SaveData[k.filename]
              Text.print(tostring(levelsave.n), 3, 400, 400)
          end
     end
   end
end

If we want to use data related to the worldmap inside levels, it is better to put any values into a general table, not in a Level.filename() one.

What is GameData? How to use it?
GameData is a table like SaveData, but with a different behavior. SaveData values are stores permanently in an episode, but GameData values are erased when the game closes. The usage of GameData follows exactly the same logic of SaveData:

Code: Select all

GameData[Level.filename()] = GameData[Level.filename()] or {}
 
local gamesave = GameData[Level.filename()]

Data stored for a session is useful for things like one-time archievements, checkpoints, etc.
____________________
Comment below if you have any doubts or questions. See you later.