Mission Lifetime

Creation

Every time that the player lands on a planet, several "potential" missions are created and stored in a global table named availableMissions.

	availableMissionsTypes = {"ReturnAmbassador", "DestroyPirate", "CollectArtifacts"}
	availableMissions = {} -- This is a global variable
	...
	for i = 1,4 do
		local missionType = choose(availableMissionsTypes)
		availableMissions[i] = _G[missionType].Create()
		...
	end

Notice that the availableMissions are being Created by the "Create" function that I tried to explain before. At this point the mission is just the missionTable, there is no c++ representation (or even knowledge) of this mission. Once the player lands on a new planet, the availableMissions array is reinitialized, removing all references to the missionTables which the Lua garbage collector will later free.

Acceptance

If the player clicks on one of the "Accept" buttons, the Button will run this string:

	string.format("PLAYER:AcceptMission(%q, availableMissions[%d])", missionType, i)

This gets formatted as something like:

	PLAYER:AcceptMission("ReturnAmbassador", availableMissions[1])

The c++ end of this function is AI_Lua::ShipAcceptMission?. In here, the missionType and missionTable are validated to ensure that the mission was written correctly. Then, if everything looks good, a new Mission is created on the heap and passed to the player's AcceptMission? function. The missionTable also gets moved from the stack to Lua's global registry (look up LUA_REGISTRYINDEX).

	if( Mission::ValidateMission( missionType, missionTable, 0 ) ) {
		Mission *mission = new Mission( missionType, missionTable );
		player->AcceptMission( mission );
	}

Life

Every tick after this, the player will check if that mission has completed by calling it's Update function. If the Mission has completed, then the Mission object on the heap is deleted. The Mission destructor should destroy the missionTable by removing it from Lua's global registry.

Aborting

The player can also choose to abort a mission. This calls:

     PLAYER:RejectMission( "The Mission's Name" )

Saving and Loading

Whenever the game is saved (whenever the player leaves a planet), the mission is converted into an XML Node and saved in the saved-games.xml file. This required a conversion between arbitrary lua tables and XML that was only written recently. The converter doesn't produce the most beautiful XML code, but the goal here is to make it easy for modders to create creative missions and not to create pretty XML tables. The XML converter also can't handle lua functions as first class objects.

Whenever the game starts, all missions in the saved-games.xml get recreated as Lua tables. When a particular player is Loaded, each of that players missions are "Accepted" again. This probably needs to be fixed to add a "Load" function to each missionType. Work in progress.