Oolite JavaScript Reference: Mission

Prototype: Object
Subtypes: none

The mission global object is used to run mission screens, and perform other actions related to mission scripting.

Properties

displayModel

displayModel : Ship

If currently running a mission screen with a model, the ship entity used to display the model. This can be animated by setting its position and orientation from a frame callback.

Methods

addMessageText

function addMessageText(message : String)

Appends text to the currently running mission screen.

markSystem

function markSystem(systemNumber : Number)

Mark a system on the long range chart. Multiple systems may be marked at once, as in mission.markSystem(4, 54, 222).

See also: unmarkSystem()

runScreen

runScreen(parameters : Object [, callback : Function [, this : Object]]) 

Present a mission screen.

The appearance of the mission screen is defined by the properties of the parameters object. The currently defined properties are:

• title : String
• titleKey : String (Key in missiontext.plist)
• music : String (name of a music file)
• overlay : guiTextureSpecifier (name of an image used as overlay)
• background : guiTextureSpecifier (name of a picture used as background)
• model : String (Role of a ship that will be shown as rotating ship)
• message : String
• messageKey : String (Key in missiontext.plist)
• spinModel: Boolean (If false, the model is shown from the top with no automatic animation.)
• choicesKey : String (Key in missiontext.plist)

Some of these are mutually exclusive; for instance, “title” overrides “titleKey”. See setScreenBackground() for a discussion of guiTextureSpecifier.

The callback function is a function that is called when the player makes a choice. Every runScreen can have its own specific callback function, or you can design a single function to handle multiple mission screens instead.

Example:
A simple mission screen:

mission.runScreen({
    title: "My first mission screen",
    message: "This am a mission screen wot is good",
    choicesKey: "me_firstmission_choices"
},
function (choice)
{
    if (choice === "1_YES")  player.commsMessage("Yay!");
    else if (choice === "2_NO")  player.commsMessage("Boo.");
    else  player.commsMessage("Whut?");
});

In missiontext.plist, you’ll need the following. The numbers are used because choices are sorted by key.

{
    "me_firstmission_choices" =
    {
        "1_YES" = "Yes.";
        "2_NO" = "No.";
        "3_MAYBE" = "Maybe.";
    };
}

The call does not have to be laid out as above. The parameters object can be manipulated in any way you want beforehand, and the callback function can be written out of line. For example, the following is equivalent:

var parameters = new Object();
parameters.title = "My first mission screen";
parameters.message = "This am";
parameters.choicesKey = "me_firstmission_choices";
parameters.message += " a mission screen wot is good";

function callback(choice)
{
    if (choice === "1_YES")  player.commsMessage("Yay!");
    else if (choice === "2_NO")  player.commsMessage("Boo.");
    else  player.commsMessage("Whut?");
}

mission.runScreen(parameters, callback);

This form is more complicated, and the ordering is less intuitive. However, it does allow you to make complex decisions about the parameters in code, and writing the callback out of line can be preferable if it’s long. It is recommended that you start out with the first approach, but keep in mind that there are other options if it becomes too limiting.

One warning: runScreen() will overwrite any existing missionscreen. The only safe place is using it inside a missionScreenOpportunity handler, because that handler only fires when it is allowed to show such a screen. When using the command at other places, first make sure with guiScreen != "GUI_SCREEN_MISSION" that there is currently no missionscreen on display by another oxp.

setInstructions

function setInstructions(instructions : String, [worldScriptName : String])

Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.

When not called from within a world script, the name of a world script must be specified so that Oolite knows which script the message belongs to. Clear the message by calling setInstructions(null).

It is recommended that setInstructions() is used only when you need to customise the text for a specific scenario. For static text, use setInstructionsKey() instead.

See also: setInstructionsKey()

setInstructionsKey

function setInstructionsKey(messageKey : String, [worldScript : String])

Like setInstructions(), but looks up the specified messageKey in missiontext.plist.

See also: setInstructions()

unmarkSystem

function unmarkSystem(systemNumbers : Number)

Remove a mark set with markSystem(). Multiple systems may be unmarked at once, as in mission.unmarkSystem(4, 54, 222).

See also: markSystem()