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 with a defined 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(), markedSystems

runShipLibrary

This method was added in Oolite test release 1.81.

function runShipLibrary()

Display the ship library based on shiplibrary.plist, including processing of condition scripts.

This is mainly useful for scenarios which override the standard scripts.

runScreen

function 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 (This property was added in Oolite test release 1.77., special background layer)
• model : String (Role of a ship that will be shown as rotating ship)
• modelPersonality : Int (This property was added in Oolite test release 1.77., 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 (This property was added in Oolite test release 1.77., Object describing advanced choices)
• choicesKey : String (Key in missiontext.plist)
• initialChoicesKey : String (This property was added in Oolite test release 1.77., the key from choicesKey which is initially selected)
• allowInterrupt : Boolean (This property was added in Oolite test release 1.77.. 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 (This property was added in Oolite test release 1.77., 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" (F5). Not all GUI screens are selectable for this: only those reachable with function keys F3 to F8. This property can be changed with exitScreen)
• screenID : String (This property was added in Oolite test release 1.77., an optional string which can be read later from mission.screenID)
• textEntry : Boolean (This property was added in Oolite test release 1.79., 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.)
• customChartZoom : decimal (This property was added in Oolite test release 1.87., zoom level of the 'CUSTOM_CHART' backgroundSpecial map)
• customChartCentre: Vector3D (This property was added in Oolite test release 1.87., centre position of the 'CUSTOM_CHART' backgroundSpecial map, using the internal coordinate system. The z component is always zero. Discouraged in favour of customChartCentreInLY)
• customChartCentreLY: Vector3D (This property was added in Oolite test release 1.87., centre position of the 'CUSTOM_CHART' backgroundSpecial map, in LY. e.g. for Lave: (8, 34.6, 0). The z component is always zero.)
• registerKeys: dictionary (This property was added in Oolite test release 1.91., allows additional keys to be defined for the mission screen. Example: registerKeys:{"key1":[{key:"g",mod1:true}]} would register the Ctrl+g key press.)

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)

See also: Screenbackgrounds.plist

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 (in such case callback function will be called with null argument).

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.

In 1.87 or later, 'backgroundSpecial' has these additional special string values:

• SHORT_RANGE_CHART_SHORTEST: As SHORT_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.
• SHORT_RANGE_CHART_QUICKEST: As SHORT_RANGE_CHART, but if the player has a working Advanced Navigational Array then the quickest route to their current destination system will be displayed.
• CUSTOM_CHART: Displays a chart where zoom and centre position can be customised using the 'customChartZoom' and 'customChartCentreInLY' properties. The first 18 lines of the mission text will overlap the chart if used.
• CUSTOM_CHART_SHORTEST: As CUSTOM_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.
• CUSTOM_CHART_QUICKEST: As CUSTOM_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 four 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";
      unselectable = false;
      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.

Using registerKeys in runScreen callbacks (1.91 and later)

When a mission screen has been defined with extra keys using the registerKeys option, an additional parameter will be passed to the callback: keyPress. This parameter will contain the key ID defined in the registerKeys option, allowing the code to know what key was pressed.

Example

 this.myFunction = function() {
   mission.runScreen({
       screenID: "oolite-registerkeys-example",
       title: "RegisterKeys Example",
       allowInterrupt: true,
       choices: {default:{text:"Press ESC to return",color:"greenColor"}},
       message: "Use arrow keys to change values",
       registerKeys: {"left":[{key:"arrowLeft"}],"right":[{key:"arrowRight"}], "up":[{key:"arrowUp"}], "down":[{key:"arrowDown"}], "esc":[{key:"escape"}]}
   }, this.$runScreenHandler, this);
 }

 this.$runScreenHandler = function(choice, keyPress) {
   switch (keyPress) {
       case "left":
           // do something when the left arrow is pressed
           break;
       case "right":
           // do something when the right arrow is pressed
           break;
       case "up":
           // do something when the up arrow is pressed
           break;
       case "down":
           // do something when the down arrow is pressed
           break;
       case "esc":
           // do something when the esc key is pressed
           return;
   }
 }

In this example, all four arrow keys have been defined as extra keys, along with the Esc key.

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

Note: the "\n" token does not provide a line break (verified in v1.9).

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.

In Oolite 1.81 onwards, the following variant is available

This method was added in Oolite test release 1.81.

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

If this version is used, the first array element will be a heading on the Manifest screen, and the remaining elements will be entered underneath it, rather than being entered under the "Missions" heading.

Example:

mission.setInstructions(["Ship Companion:", expandMissionText ("myoxp_currentpet"),...]);

This will display Ship Companion: in yellow text on the F5F5 screen, and beneath it will show the expanded value of the key "myoxp_currentpet" from the missiontext.plist associated with the calling world script. If not called from a world script, the worldScriptName (this.name from the script) must be provided also:

mission.setInstructions(["Ship companion:", expandMissionText ("myoxp_currentpet"),...], "myoxp's script name");

Note that because the first parameter is now an array, the line(s) to be added must be enclosed in brackets and comma separated. Also note the optional use of expandMissionText() to retrieve text from missiontext.plist. It is also possible to construct the array before calling setInstructions, for example:

if(myoxp_petslist.length == 0) {
  mission.setInstructions(null); // clear any text previously displayed by this world script on the F5F5 screen
} else {
  var textArray = [];
  textArray.push("Ship Companion" + (myoxp_petslist.length > 1 ? "s:" : ":")); // "Ship Companion:" or "Ship Companions:" if more than one
  var i = myoxp_petslist.length - 1; // pointer to last entry in myoxp_petslist
  while(i--) { // for each pet in the list, starting from the bottom (probably newest to oldest)
    textArray.push(myoxp_petslist[i].name); // add the name of the pet to the text we will show on the F5F5 screen
  }
  mission.setInstructions(textArray); // our pets list will now be visible on the F5F5 screen until further notice (the next time we call setInstructions or one of its variants, it will replace this)
}

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) : Boolean

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 method will return true if all requested markers existed and were removed, or false if any of the requested markers did not exist.

See also: markedSystems

Links

• Missiontext.plist
• OXP mission offering
• Mission variable
• Mission screen
• Order of mission texts on the F5F5 manifest screen (2012)

• For ideas, see here: Gamemastery 101 - try the "Three Clue Rule" for example.

Other Missions

• Oolite Missions - reference: summaries of other missions
• List of Planets used in OXPs - reference to see which systems are used by other oxp's
• Script.oos - possible reason for really old missions no longer working (pre- v.1.70)