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.

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

This method was added in Oolite test release 1.77.

function markedSystems()

Returns an object with a key for each script (named with the script's "this.name" property) which is marking at least one system. The value of the key is an array containing the system IDs of the systems marked by that script.

The special key "__oolite_legacy_destinations" is used for systems which were marked by the legacy script engine or were marked in a save game generated in 1.76 or earlier, for which the source of the mark is unknown. For compatibility, any call to unmarkSystem() will also remove the system from the list in "__oolite_legacy_destinations", if it is present.

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. In 1.77, each world script has a separate list of marked systems, and items marked from one script cannot be unmarked by another script. A moderately common pattern is to wish to mark a system from a world script and then unmark it from a ship script (perhaps in the shipDied handler). To do this, create a wrapper function in the world script that originally set the mark

// in world script
this._unmarkSystem = function(id)
{
  mission.unmarkSystem(id);
}

and call it from the ship script

// in ship script
this.shipDied = function(whom, why)
{ 
  worldScripts["my script"]._unmarkSystem(system.ID);
}

See also: markSystem()