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.

exitScreen

This property was added in Oolite test release 1.77.

exitScreen : guiScreen (read/write)

This can be used to set a new exit screen for the current mission screen. Outside of a callback function, the value of this is meaningless, and setting it has no useful effect.

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.

screenID

This property was added in Oolite test release 1.77.

screenID : String (read-only)

If there is currently a mission screen running, and it defined a screenID, then that screenID. Otherwise, this is null.

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)
• backgroundSpecial: String (1.77 or later, special background layer)
• 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.)
• choices: Object (1.77 or later. Object describing choices)
• choicesKey : String (Key in missiontext.plist)
• initialChoicesKey : String (1.77 or later, the key from choicesKey which is initially selected)
• allowInterrupt : Boolean (1.77 or later. If true (default: false), the mission screen can be interrupted with function keys, which does not call the callback function. Mainly intended for interfaces.)
• exitScreen : guiScreen (1.77 or later, a GUI screen to exit on. If omitted, an invalid value is given, or the player is not docked, this will revert to "GUI_SCREEN_STATUS". Not all GUI screens are selectable for this: only those reachable with function keys F3 to F8)
• screenID : String (1.77 or later, an optional string which can be read later from mission.screenID
• textEntry : Boolean (1.79 or later, if it's true, then you get the text prompt and 'choices' and 'choicesKey' are ignored. Whatever's typed there gets passed as the parameter to the callback function. The ship registry code has a simple example.)

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

There are 21 lines available for display of the message and choices combined. (In 1.77, this is extended to 27 lines if the player's HUD is hidden)

runScreen callbacks

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. The optional this parameter will be used as the this property of the mission screen callback. It is usually unnecessary to specify this, but if you intend the function which calls runScreen to be called from a different script, and the callback references this, you will need to use it.

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.

In 1.77, if allowInterrupt is set to true, it is possible that the callback function will not be called. It should therefore only be set for mission screens which can safely be interrupted without the callback. Regardless of this setting, all mission screens may be interrupted by the player launching from the station, and this possibility should be considered.

runScreen special backgrounds (1.77 or later only)

In 1.77 or later, 'backgroundSpecial' may be given the following special string values:

• SHORT_RANGE_CHART: Uses the short range chart (as if the player had pressed F6). The first 18 lines of the mission text will overlap the chart if used.
• LONG_RANGE_CHART: Uses the current long range chart (as if the player had pressed F6 twice). The first 16 lines of the mission text will overlap the chart if used.
• LONG_RANGE_CHART_SHORTEST: As LONG_RANGE_CHART, but if the player has a working Advanced Navigational Array then the shortest (fewest jumps, not necessarily shortest distance) route to their current destination system will be displayed.
• LONG_RANGE_CHART_QUICKEST: As LONG_RANGE_CHART, but if the player has a working Advanced Navigational Array then the quickest route to their current destination system will be displayed.

With all special chart backgrounds, changes made to destination system, or to markers, will be updated immediately. These backgrounds will be displayed above the 'background' (if any) but below everything else.

Advanced choices (1.77 or later only)

In 1.77 or later, choices may be set either with the 'choicesKey' parameter from missiontext.plist as before, or with the 'choices' parameter. (If both are set, 'choicesKey' will be ignored) Example

var options = {
   "01_AGREE" : "Take the job",
   "02_DECLINE" : "Politely decline"
};
if (player.bounty == 0) // only clean players have this option
{
   options["03_REPORT"] = "Call the police";
}

mission.runScreen({
   // title, message, etc.
   choices: options
},function(choice) {
   // choice handling
});

This is useful where the options available (perhaps depending on the player's ship or equipment, or on previous events in the mission) may vary in a complex fashion, to avoid the need to have a separate missiontext.plist entry for every possibility.

The value (either in choicesKey's missiontext entry or choices) may either be a text string as in previous versions, or an object itself. If it is an object, it can take three parameters:

• 'text' is the displayed text for this key.
• 'alignment' can be 'LEFT', 'RIGHT' or 'CENTER' (the default).
• 'unselectable' can be true or false (the default for non-blank text). Unselectable rows are printed, but are skipped when moving through the options. This can be useful for keeping a consistent interface.
• 'color' can be any color specification (e.g. "orangeColor"). The default is "yellowColor", or "darkGrayColor" for unselectable rows.

For example (missiontext.plist):

"my_choice_1" = {
   "01_AGREE" = {
      text = "Take the job";
      alignment = "LEFT";
      color = "greenColor";
   };
   // more options
};

In 1.77, the behaviour for choices which have no text is slightly changed. These will now leave a blank and unselectable line in the option list.

Safe usage of runScreen

One warning: runScreen() will overwrite any existing missionscreen or GUI screen. The only safe place is using it inside a missionScreenOpportunity handler or the callback function from a previous mission screen (or in 1.77 onwards, inside an interface callback function), 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.

Known issues

From Oolite 1.79, only the A-Z, a-z, 0-9 and (space) characters may be reliably entered in the 'textEntry' field. A wider selection, for boring internal reasons, is available on the Mac, and is hoped to also be available on other platforms in later releases.

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