Mission API

Proposal

As the player completes missions throughout the game, there is a greater need to save and restore game state. One of the challenges is that a lot of state is held inside the Lua scripts where the state is not so easily saved and restored.

This proposal introduces a Mission API which allows content developers to save and retrieve state about missions in the game engine. This state will be saved and restored when the player restarts a game.

API Reference

Mission.getMeta('<mission-id>', '<meta-name>')

Retrieves the meta value of the mission's meta. The meta-name is unique on a per-mission basis. In other words, two different missions can have a meta of the same name.

Parameters

• <mission-id> - A unique identifier for the mission
• <meta-name> - The meta name whose value to retrieve.

Return Value

The value of the meta, or null if the meta has never been set

Example

```lua`` local numoftries = Mission.getMeta('covefe-mission', 'number-of-tries')

### `Mission.setMeta('<mission-id>', '<meta-name>', '<meta-value>')`

#### __Parameters__ 
* `<mission-id>` - A unique identifier for the mission
* `<meta-name>` - The meta name whose value to set
* `<meta-value>` - The value which to set the meta

#### __Return Value__
_None_

#### __Example__
```lua
Mission.setMeta('covefe-mission', 'numer-of-tries', x++)

Mission.getStatus('<mission-id>')

Parameters

• <mission-id> - A unique identifier for the mission

Return Value

The string value of mission-id's current status that was set with Mission.setStatus()

Example

local status = Mission.getStatus('covefe-mission')

Mission.setStatus('<mission-id>', '<status-string>')

Parameters

• <mission-id> - A unique identifier for the mission
• <status-string> - The string value to which to set the status

Return Value

None

Example

Mission.setStatus('covefe-mission', 'completed')

Usage

Suppose you want to design a mission where the player must retrieve two bags of a weed for an NPC named "Pie Man", and we want the make sure that if the player quits the game after finding one bag of weed that that accomplishment is restored when the player restarts the game. We can use the mission's "status" to track the progress of the mission.

(Note: All code samples may or may not compile, right now its only purpose is to show the idea)

function onPieMan_select(scene, item)
    local status = Mission.getStatus("pie-man-mission")
    if status == null
        Utils.showModal(scene, "Hey Tommy, find me two bags of weed and I'll pay you $500!")
        Mission.setStaus("sevan-mission", "started")
    else if status == "started"
        pieman_part1(scene)
    else if status == "first-completed"
        pieman_part2(scene)
    else if status == "completed"
        Utils.showModal(scene, "I'm still smoking all that weed you got me before, thanks man")
    end
end

function pieman_part1(scene)
    local hasbag = -- check if player has a bag of weed
    if hasbag then
        Utils.showModal(scene, "Thanks man! Can you find me another?")
        -- remove bag from players inventory 
        Mission.setStatus("sevan-mission", "first-bag-completed")
    else
        Utils.showModal(scene, "I'm still waiting for that first bag")
    end
end

function pieman_part2(scene)
    local hasbag = -- check if player has a bag of weed
    if /* player has a bag of weed */
        Utils.showModal(scene, "thanks, this is more weed than I'll ever need in my life!")
        -- give player $500
        Mission.setStatus("sevan-mission", "completed")
    else
        Utils.showModal(scene, "dont come back until you've brought me my second bag)
    end
end

Here you can see we've used Mission.getStatus() and Mission.setStatus() to track how far along tha player has progressed in getting the bags of weed for the NPC.

This API could be used for tracking the linear progress of a mission, but suppose we wanted a missiong where the player had to bring a bong and a bag of weed to an NPC, and it didn't matter in which order. In this case we could do something like:

function onSneasel_select(scene, item)
    local status = Mission.getStatus("sneasel-mission")
    if status == null
        Utils.showModal(scene, "Hey Tommy, find me some weed and a bong I'll pay you $500!")
        Mission.setStaus("sneasel-mission", "started")
    else if status == "started"
        sneasel_update(scene)
    else if status == "completed"
        Utils.showModal(scene, "Thanks for the weed and bong!")
    end
end

function sneasel_update(scene)
    local hasweed = -- check if player has a bag of weed
    local hasbong = -- check if player has a bong

    if hasweed then
        local weedCompelted = Mission.getMeta("sneasel-mission", "weed-completed")
        if ~weedCompleted then
            Utils.showModal(scene, "you found some weed, thanks!")
            Mission.setMeta("sneasel-mission", "weed-completed", true)
        end
    end

    if hasbong then
        local bongCompelted = Mission.getMeta("sneasel-mission", "bong-completed")
        if ~bongCompelted then
            Utils.showModal(scene, "you found a bong, thanks!")
            Mission.setMeta("sneasel-mission", "bong-completed", true)
        end
    end

    local weedMission = Mission.getMeta("sneasel-mission", "weed-completed")
    local bongMission = Mission.getMeta("sneasel-mission", "bong-completed")
    if weedMission and bongMission then
        Mission.setStaus("sneasel-mission", "completed")
    else if ~weedMission then
        Utils.showModal(scene, "can you find me some weed?")
    else
        Utils.showModal(scene, "can you find me a bong?")
    end
end

In this example it does not matter in which order you give the NPC the items. In this example that Mission.setMeta() API is used to store a boolean value, but it can also be used to store numeric and string values.

Notes

• In this design the return type of Mission.getMeta() is ambiguous. It may require additional calls to get a specific type (i.e. Mission.getMetaInt(), Mission.getMetaString(), etc).

• Mission.setStatus() and Mission.getStatus() may not even be required since the mission status could be stored as just another meta.