To Enable the Script:
1) Find and download the latest SaveAndLoadUtils.lua file
2) Copy SaveAndLoadUtils.lua to the map's data_XXX\Common\scripts
3) Edit the data_XXX\Common\mission.req and add SaveAndLoadUtils to its scripts section
4) In the mission script (example: data_XXX\Common\scripts\XXX\XXXg_con.lua), add ScriptCB_DoFile("SaveAndLoadUtils") near the other ScriptCB_DoFiles at the top of the file
5) Thats it!
To Save Data:
1) Enable the script (see above)
2) Pick a name for the file. This tutorial will use the name 'tutorialSaveExample'. It is important that one picks a longer, unique name. If someone picks 'sav' and someone else picks 'saving-xxx-data', then whenever 'sav' is saved, the 'saving-xxx-data' file will be deleted! Any file starting with name will be deleted before saving the new file. Choose the file names wisely. It is recommended not to end the name with a number. Code:[code]local filename = "tutorialSaveExample"[/code]3) Create a function. This function should take a string as an argument/parameter. The function will be called when the save operation is finished. If the string is nil, then the saved worked. If the string is not nil, then the saved failed and the string is the error message. It is extremely important that the saving function isn't called twice before this 'callback' function is called. If it is called twice, the game has a very high chance of crashing. This function is optional, but recommended. This tutorial will use the following function:[code]local callback = function(message)
--output the info to debug log
print("Save result:", message)
if message == nil then
--show a 'Save Game Done' ingame message
ShowMessageText("common.save")
ShowMessageText("ifs.freeform.done")
else
--show a 'Save Game Skip' ingame message
ShowMessageText("common.save")
ShowMessageText("ifs.freeform.skip")
end
end[/code]5) In order to save data, one must have data to save. The data must be contained in a single table. Other then that, its up to the modder to decide the format of that table and what it contains. This tutorial will use the following table:[code]local data = {
team1Points = GetTeamPoints(1),
team2Points = GetTeamPoints(2),
gameTime = ScriptCB_GetMissionTime(),
"Some other random data",
{
"This is a string inside a table, which is inside the 'data' table",
6,
"more random stuff"
},
"confused yet?",
"boo!",
}[/code]6) Now that one has the file name, the callback function, and the data, it's time to save. Saving generally has around a six second delay to complete. However, the function will return instantly. This is why it is important to use the callback function. One can think of the callback function as being similar to using the OnTimerElapse() after starting a timer with StartTimer(). A map should not end during this delay period. There are two main side effects for saving (and loading). First, a player's screen may flicker twice during the saving (and loading). This is due to the game quickly entering and exiting two shell screens during the process. Second, any stored metagame state is cleared. If one does not know what that means, then it most likely won't be a problem. Calling the saving function/method with the tutorial's variables looks like this:[code]util_saveDataToDisk( data, filename, callback )[/code]If one didn't have a callback function, the code would look like:[code]util_saveDataToDisk( data, filename )[/code]7) Thats it!
To Load Data:
1) Enable the script (see above)
2) Have some data saved using the 'To Save Data' steps (see above)
3) Loading data is done in a similar fashion to saving data. One must have the file name and should have the callback function. All the conditions that apply to saving data also apply to loading data. The main different is that the callback function takes a table as a second parameter. This table is the loaded data, if the load worked. Instead of making everyone reread the same info, I'll just show you the loading code:[code]local filename = "tutorialSaveExample"
local callback = function(message, data)
--output the info to debug log
print("Load result: msg, data:", message, data)
if message == nil then
--show a 'Load Game Done' ingame message
ShowMessageText("common.load")
ShowMessageText("ifs.freeform.done")
else
--show a 'Load Game Skip' ingame message
ShowMessageText("common.load")
ShowMessageText("ifs.freeform.skip")
end
end
util_loadDataFromDisk( filename, callback )[/code]
To Delete Saved Data:
*) Note: This section is a quick addition to the tutorial. It is not as polished as the rest of the tutorial. Follow this section (an the other ones too) at your own risk.
1) The util_sendSavedMetagameFileList() function gets a list of the saved metagame files (where the data is stored), then forwards that list to a given function.
2) The util_deleteRelatedMetagames() function takes a filename and the list of saved metagame files. It then goes through and deletes all metagame files whose file names begin with the given filename.
3) The code to use util_sendSavedMetagameFileList() and util_deleteRelatedMetagames() together in order to delete all 'tutorialSaveExample' saves:[code]util_sendSavedMetagameFileList( function(filelist, maxSaves)
util_deleteRelatedMetagames("tutorialSaveExample", filelist)
end, false)[/code]
Other Info:
* There is a map (SAV) that goes along with this tutorial. The tutorial map is a timed version of a modified Conquest. When the timer is up, the teams' points are saved to a file. When the map restarts, the teams' scores are reloaded.
* The code in this tutorial may be untested. Assuming I made no typos when writing it, it should work.
