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. Uses role to identify ship, so be sure to use a unique role if you want a specific ship to be showed.

markedSystems

This property was added in Oolite test release 1.77.

markedSystems : Array (read-only)

An array of the objects currently being used to mark systems. The objects will have the same properties as those used by markSystem and unmarkSystem.

Methods

addMessageText

function addMessageText(message : String)

Appends text to the currently running mission screen. Can also be used to add text to other screens like the system data (F7) screen.

addMessageTextKey

function addMessageTextKey(messageKey : String)

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

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). In 1.76 and earlier a system cannot be marked twice, so:

mission.markSystem(7);
mission.markSystem(7);
mission.unmarkSystem(7);

will leave the system unmarked.

In 1.77 or later, the parameters may be objects instead of numbers. This allows control over the marker's appearance, and allows multiple markers to be placed on the same system. The object takes the following parameters:

• system : The system ID. This is the only required parameter.
• name : A string identifying the group this marker belongs to (which may be the script's name, or something more specific). If omitted, which is not recommended, this defaults to "__oolite_legacy_destinations" which is also used for marking with numbers and marking carried out by legacy scripts.
• markerColor : A string specifying a colour. e.g. "redColor" or "1.0 0.5 0.0". If omitted, "redColor" will be used.
• markerScale : A number between 0.5 and 2.0 specifying the relative size of the marker. Defaults to 1.0.
• markerShape : A string describing the shape of the marker. Valid values are MARKER_X, MARKER_PLUS, MARKER_SQUARE and MARKER_DIAMOND. If this value is invalid or omitted, MARKER_X will be used.

Multiple markers may be placed on the same system, provided that they have different names. If a marker with the same system and name already exists, it will be replaced.

mission.markSystem({
   system: 55,
   name: "my_oxp",
   markerColor: "cyanColor",
   markerScale: 1.5,
   markerShape: "MARKER_DIAMOND"
});

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)
• modelPersonality : Int (1.77 or later, the entityPersonality assigned to the model. If unspecified, or in 1.76 or earlier, a random personality is used)
• 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)
• initialChoicesKey : String (1.77 or later, the key from choicesKey which is initially selected)

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).

In 1.76 and earlier versions, any script can unmark a system, regardless of which script marked it or how many times it was previously marked.

In 1.77, each marker has a name, and if a system has multiple markers each marker must be removed separately. Parameters in 1.77 may be numbers or objects. Numbers remove the "__oolite_legacy_destinations" markers. Objects are the same format as in markSystem and remove the marker of the corresponding name (the marker style options are ignored when unmarking). In 1.77, this function will return true if all requested markers existed and were removed, or false if any of the requested markers did not exist.

See also: markSystem()