Surviving a reload

When a game is saved, a script is responsible for informing Pioneer exactly which of its data need to be saved. If nothing is specified, nothing will be saved at all. Similarly, after a game is loaded, a script is responsible for restoring all of its saved data; re-creating bulletin board adverts, the player's mission details, and any run-time state.

Here is a simple form. If a new game is started, you will see this on every bulletin board that you visit:

local Event = require 'Event'

local onChat = function (form, ref, option)
    form:Clear()
    form:SetMessage("Hello!")
end

local onCreateBB = function (station)
    station:AddAdvert('Click here for a greeting', onChat)
end

Event.Register("onCreateBB", onCreateBB)

If, however, you save the game, then reload, you will not see it on any bulletin board that had been created in the current system before you saved. onCreateBB will be triggered for any subsequently created bulletin boards, but not for those that already existed. It isn't appropriate to have scripts create new adverts just because a player has loaded; instead, it's the responsibility of the script to tell Pioneer what to save, and to use those saved data to restore all adverts after the game is loaded. The same goes for player missions, and any working data that the script is using.

There are two things we need to do to achieve all of this.

• We need to track everything that the script is doing.
• We need to be able to pack this away for saving, and bring it back after loading.

Tracking everything that we are doing

Any local table that is declared in file scope is visible to the entire script, without affecting any other scripts. Essential data should be kept in such tables.

Tracking adverts

It's important to be able to re-create an advert, so part of the process of making one should be storing that information. Your script will need to make a note of in which station the advert was placed, which flavour was used (if you have flavours), the face data that was used on the form and any unique information that was used, such as specific mission details, reward, etc. The simplest way to keep all of this together is in a table, gathering up the variables by name into keys of the same name:

local advert = {
    station = station,
    flavour = flavour,     -- This will be a table
    facedata = facedata, -- This will be a table
    target = target,
    destination = destination,
    reward = reward,
}

Remember, the AddAdvert() method takes three arguments: The advert text, the onChat function and the onDelete function. It also returns a unique number, which lends itself nicely to storing the information away. That same unique number is passed to the onChat function, allowing onChat to check that stored information.

The onDelete() function (again, we call it that by convention only) also accepts this reference as its argument, and is called whenever an advert is destroyed, whether that destruction be explicit (RemoveAdvert()) or implicit (the player hyperspaces away).

So, we can track adverts that have been created, and stop tracking any that have gone away. I'll do that using the reference returned by AddAdvert() as the key to a file-scoped local table:

local all_flavours = Translate:GetFlavours('TestModule')
local all_adverts = {}

local onChat = function (form, ref, option)
    form:Clear()
    form:SetFace(all_adverts[ref].facedata)
    form:SetMessage(all_adverts[ref].flavour.title)
end

local onDelete = function (advert_ref)
    all_adverts[advert_ref] = nil
end

local onCreateBB = function (station)
    local flavour = all_flavours[Engine.rand:Integer(1,#all_flavours)]
    advert_ref = station:AddAdvert(flavour.title,onChat,onDelete)
    local female = Engine.rand:Integer(1) == 1
    all_adverts[advert_ref] = {
        station = station,
        flavour = flavour,
        facedata = {
            female = female,
            name = NameGen.FullName(female),
            seed = Engine.rand:Integer()
        }
    }
end

Event.Register("onCreateBB", onCreateBB)

Tracking missions

This is less of a challenge. Whenever Player.AddMission() is called, it returns a reference to the mission. That reference can be stored in a file-local table, and that table can be iterated through, and Player.GetMission() called on each one. We can wrap these functions up:

local missionrefs = {}

local AddMission = function(mission)
    table.insert(missionrefs,Game.player:AddMission(mission))
    return missionrefs[#missionrefs]
end

local RemoveMission = function(mref)
    for i,m in ipairs(missionrefs) do
        if m == mref then
            table.remove(missionrefs,i)
        end
    end
    Game.player:RemoveMission(mref)
end

Now, instead of calling Game.player:AddMission() and Game.Player:RemoveMission(), we just directly call our local functions, AddMission() and RemoveMission(). They will send their argument on to the instance in Game.player, and also store or remove the mission ref in the missionrefs table. There is now a record of which missions belong to this script.

Serializing: Packing away for saving and loading

The Serializer object provides one method: Register. It takes three arguments. The first is a name; a simple string with which to uniquely identify this script. It's probably sensible to re-use the name that was used for the Translate object's flavour methods. The second argument is the name of a function which will return a single table. The third argument is a function that will accept a single table.

The second argument is your serializer function. The third is your unserializer function. By convention, we name these serialize and unserialize.

serialize must return a table. This table must contain everything that you need to store to get your script working after a reload. It will be run when the player saves the game. The table can contain any pure-lua types, and SystemPath, Body and SceneGraph.ModelSkin core types, anything else will explode, like a ShipDef/EquipDef or a StarSystem.

unserialize accepts a table, and does something with it. It will be run by the serializer after the game is loaded, immediately before the onGameStart event is triggered. It is passed the data that serialize returned at save time.

The most common way to deal with this is as follows (and this is very cut down):

local table_stuff_this_script_uses = {}
local loaded_data

-- The rest of the script goes here!

local onGameStart
    if loaded_data then
        for k,v in loaded_data.table_stuff_this_script_uses do
            table_stuff_this_script_uses[k] = v
        end
        loaded_data = nil
    else
        -- New game; do other stuff here perhaps
    end
end

local serialize = function ()
    return {table_stuff_this_script_uses = table_stuff_this_script_uses}
end

local unserialize = function (data)
    loaded_data = data
end

Event.Register("onGameStart", onGameStart)
Serializer:Register("TestModule", serialize, unserialize)

Now, combining that with the examples above, we get the following, which will save and load both the adverts and the missions that the script created:

local Event = require 'Event'
local Serializer = require 'Serializer'

local ads = {}

local onChat = function (form, ref, option)
    local ad = ads[ref]
    form:Clear()
    form:SetMessage(ad.bodytext)
end

local onDelete = function (ref)
	ads[ref] = nil
end

-- when we enter a system the BBS is created and this function is called
local onCreateBB = function (station)

	local ad = {
		headline = 'Click here for a greeting',
		bodytext = "Hello!",
		station  = station
	}

	-- create one per BBS
	local ref = station:AddAdvert({
		description = ad.headline,
		onChat      = onChat,
		onDelete    = onDelete}
    )
    ads[ref] = ad
end

local loaded_data

local onGameStart = function ()
	ads = {}

	if not loaded_data or not loaded_data.ads then return end

	for k,ad in pairs(loaded_data.ads or {}) do
		local ref = ad.station:AddAdvert({
			description = ad.headline,
			onChat      = onChat,
			onDelete    = onDelete})
		ads[ref] = ad
	end

	loaded_data = nil
end

local serialize = function ()
	return { ads = ads }
end

local unserialize = function (data)
	loaded_data = data
end

Event.Register("onCreateBB", onCreateBB)
Event.Register("onGameStart", onGameStart)

Serializer:Register("message", serialize, unserialize)

Although the example is functional, it has been coded with brevity alone in mind. I would not recommend using this as the basis for a mission without at least completely rewriting onChat(), and possibly tidying up the temporary loop variable names.

The codedoc is complete and accurate, and the scripts provided with Pioneer are good examples themselves. The API is extensive, but if you find that there are additonal things you would like to be able to do, or information you would like from Pioneer, the dev team are willing to extend the API to accommodate script writers. Simply create a new issue on the Github issue tracker.

Help is also always available on the Pioneer forum on SpaceSimCentral.com, and many of the dev team can be found on IRC at all hours.