Oolite JavaScript Reference: Mission

Properties

choice : String (read/write)

The most recently selected choice from the mission screen. The empty string "None" is used for no choice. Important: in future versions, null will be used to indicate no choice. A choice can be cleared by setting mission.choice = null. This clearing will trigger the missionChoiceWasReset handler.

Methods

runScreen

This method was added in Oolite test release 1.74.

runScreen(params: dict, callBack:function) 

This method replaces any previous ways of defining missionscreens. The individually parts of a missionscreen can be added by adding different keys to the directory.
title: String (pure text)
titleKey: String (Key in missiontext.plist)
music: String (filename of a music file)
overlay: String (filename of a picture used as overlay)
background: String (filename of a picture used as background)
model: String (Role of a ship that will be shown as rotating ship)
message: String (pure text)
messageKey: String (Key in missiontext.plist)
choicesKey: string (Key in missiontext.plist)

Some keys exclude each other, like a foreground an background picture. When both are defined, only one is used.

The callback function is a self defined function that called when the player makes a choice. Every runScreen can have its own callback function or you can use one single for all your callbacks

example:

		// Show the mission screen
		mission.runScreen({titleKey:"oolite_trumble_title", messageKey:"oolite_trumble_offer", background:"trumblebox.png", choicesKey:"oolite_trumble_offer_yesno"}, this.trumbleOffered);
	}
};


this.trumbleOffered = function(choice)
{
	if (choice == "OOLITE_TRUMBLE_YES")
	{
		missionVariables.trumbles = "TRUMBLE_BOUGHT";
		player.credits -= 30;
		player.ship.awardEquipment("EQ_TRUMBLE");
	}
	else
	{
		missionVariables.trumbles = "NOT_NOW";
	}
}

markSystem

function markSystem(systemNumbers : Number, ...)

Mark the listed systems on the long range chart; for example, mission.markSystem(4, 54, 222) will mark system numbers 4, 54, and 222. Note: eventually this will be deprecated for syntax along the lines of currentGalaxy.systems[4].marked = false;, but this form should continue to work.

unmarkSystem

function unmarkSystem(systemNumbers : Number, ...)

Remove the marks from the listed systems on the long range chart; for example, mission.unmarkSystem(4, 54) will unmark system numbers 4, and 54.

deprecated methods

The methods below were in use up to Oolite 1.73 and will be replaced in future

function addMessageTextKey(messageKey : String)

Sets the dictionary key for the mission screen text. "messageKey" is the key of an entry in missiontext.plist. Must be called after showMissionScreen.

function setBackgroundImage(backgroundImage : String)

Specifies a background image to be shown at the mission screen. "backgroundImage" is the filename of a picture in the "Images" folder. Must be called before showMissionScreen.

function setChoicesKey(choicesKey : String)

Specifies the choices to be shown at the mission screen. "choicesKey" is the key of an entry in missiontext.plist. Must be called after showMissionScreen.

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

Sets the dictionary key of the text to put on the manifest screen (usually short instructions for current missions. F5-F5). When not called from within the worldScript, the script name has to be specified additionally.

function setMusic(musicKey : String)

Specifies a music file to be played at the mission screen. "musicKey" is the filename of a music file in the "Music" folder. Must be called before showMissionScreen.

function showMissionScreen()

Shows the mission screen. Due to implementation details musicKey, backgroundImage and shipKey must be set before this method is called, but messageKey and choicesKey must be set after this method is called.

function showShipModel(shipKey : String)

Specifies a ship model to be displayed on the mission screen. "shipKey" is the role of a ship in shipData.plist. Must be called before showMissionScreen. (Open issue: why is this a method rather than a write-only property? --ahruman)

function runMissionScreen(messageKey : String, backgroundImage : String, choiceKey : String, shipKey : String, musicKey : String)

This is the recommended way to set up a missionscreen. It does all the setup or clearing of the Key's. Strictly spoken it is not a method but a JS routine that calls the appropriate methods in the right order. After setting up and showing the missionscreen it clears the keys. e.g. mission.runMissionScreen("myMessage", null, "myChoices") will display a missionscreen with "myMessage" and wil give the choices of "myChoices". Any previous defined background image as well as rotating ships and music, is cleared.