Difference between revisions of "Oolite JavaScript Reference: Mission"

From Elite Wiki
m (→‎addMessageTextKey)
(Updated for 1.74.)
Line 1: Line 1:
−
== Properties ==
+
<small>'''Prototype:''' <code>Object</code></small><br />
−
 
+
<small>'''Subtypes:''' none
−
'''choice''' : String (read/write)
 
−
 
 
−
The most recently selected choice from the mission screen. The empty string <code>"None"</code> is used for no choice. '''Important:''' in future versions, <code>null</code> will be used to indicate no choice. A choice can be cleared by setting mission.choice = null. This clearing will trigger the missionChoiceWasReset handler. This property is deprecated since 1.74. The new runScreen method has its own private choice through a callBack function.
 
  
 +
The '''mission''' global object is used to run mission screens, and perform other actions related to mission scripting.
  
 
== Methods ==
 
== Methods ==
Line 11: Line 9:
 
  function '''addMessageText'''(message : String)
 
  function '''addMessageText'''(message : String)
  
−
Sets the additional text for the mission screen text.  Must be called '''''after''''' <code>runScreen</code> and adds code below any existing text.
+
Appends text to the currently running mission screen.
  
−
=== <code>addMessageTextKey</code> ===
+
=== <code>markSystem</code> ===
−
  function '''addMessageTextKey'''(messageKey : String)
+
  function '''markSystem'''(systemNumber : Number)
−
 
 
−
Sets the dictionary key in [[missiontext.plist]] for the mission screen text. "messageKey" is the key of an entry in missiontext.plist. Must be called '''''after''''' <code>runScreen</code>.
 
  
−
=== <code>markSystem</code> ===
+
Mark a system on the long range chart. (It is currently possible to mark multiple systems at once, as in <code>mission.markSystem(4, 54, 222)</code>, but this syntax ''may'' be deprecated for Oolite 1.75.)
−
function '''markSystem'''(systemNumbers : Number, ...)
 
  
−
Mark the listed systems on the long range chart; for example, <code>mission.markSystem(4, 54, 222)</code> will mark system numbers 4, 54, and 222. '''Note:''' eventually this will be deprecated for syntax along the lines of <code>currentGalaxy.systems[4].marked = false;</code>, but this form should continue to work.
+
'''See also:''' <code>[[#unmarkSystem|unmarkSystem()]]</code>
  
 
=== <code>runScreen</code> ===
 
=== <code>runScreen</code> ===
 
{{Oolite-method-added|1.74}}
 
{{Oolite-method-added|1.74}}
−
  '''runScreen(params: dict, callBack:function)'''  
+
  '''runScreen(parameters : Object [, callback : Function [, this : Object]])'''  
−
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.<br>
+
Present a mission screen.
−
'''title''': String (pure text)<br>
+
 
−
'''titleKey''': String (Key in missiontext.plist)<br>
+
The appearance of the mission screen is defined by the properties of the <code>parameters</code> object. The currently defined properties are:
−
'''music''': String (filename of a music file)<br>
+
* <code>title : String</code>
−
'''overlay''': String (filename of a picture used as overlay)<br>
+
* <code>titleKey : String</code> (Key in [[missiontext.plist]])
−
'''background''': String (filename of a picture used as background)<br>
+
* <code>music : String</code> (name of a music file)
−
'''model''': String (Role of a ship that will be shown as rotating ship)<br>
+
* <code>overlay : String</code> (name of an image used as overlay)
−
'''message''': String (pure text)<br>
+
* <code>background : String</code> (name of a picture used as background)
−
'''messageKey''': String (Key in missiontext.plist)<br>
+
* <code>model : String</code> (Role of a ship that will be shown as rotating ship)
−
'''choicesKey''': string (Key in missiontext.plist)<br>
+
* <code>message : String</code>
 +
* <code>messageKey : String</code> (Key in [[missiontext.plist]])
 +
* <code>choicesKey : String</code> (Key in [[missiontext.plist]])
 +
 
 +
Some of these are mutually exclusive; for instance, “title” oveerrides “titleKey”.
  
−
Some keys exclude each other, like a foreground and background picture. When both are defined, only one is used.
+
The callback function is a function that is 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.
  
−
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:'''<br>
 +
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.";
 +
    };
 +
}
  
−
example:
+
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:
−
// Show the mission screen
+
var parameters = new Object();
−
mission.runScreen({titleKey:"oolite_trumble_title", messageKey:"oolite_trumble_offer", background:"trumblebox.png", choicesKey:"oolite_trumble_offer_yesno"}, this.trumbleOffered);
+
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)
−
this.trumbleOffered = function(choice)
 
 
  {
 
  {
−
if (choice == "OOLITE_TRUMBLE_YES")
+
    if (choice === "1_YES") player.commsMessage("Yay!");
−
{
+
    else if (choice === "2_NO")  player.commsMessage("Boo.");
−
missionVariables.trumbles = "TRUMBLE_BOUGHT";
+
    else player.commsMessage("Whut?");
−
player.credits -= 30;
 
−
player.ship.awardEquipment("EQ_TRUMBLE");
 
−
}
 
−
else
 
−
{
 
−
missionVariables.trumbles = "NOT_NOW";
 
−
}
 
 
  }
 
  }
 +
 +
mission.runScreen(parameters, callback);
  
−
=== <code>setInstructionsKey</code> ===
+
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.
−
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).<br>
+
=== <code>setInstructions</code> ===
−
When not called from within the worldScript, the worldScript script name has to be specified additionally so Oolite knows to which worldScript the instruction belongs.
+
function '''setInstructions(instructions : String, [worldScriptName : String])'''
  
−
=== <code>unmarkSystem</code> ===
+
Specify a message to put on the Manifest screen (usually short instructions for current mission), under the title “Missions”.
−
function '''unmarkSystem'''(systemNumbers : Number, ...)
 
  
−
Remove the marks from the listed systems on the long range chart; for example, <code>mission.unmarkSystem(4, 54)</code> will unmark system numbers 4, and 54.
+
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 <code>setInstructions(null)</code>.
  
 +
It is recommended that <code>setInstructions()</code> is used only when you need to customise the text for a specific scenario. For static text, use <code>[[#setInstructionsKey|setInstructionsKey()]]</code> instead.
  
−
=== <code>deprecated methods</code> ===
+
'''See also:''' <code>[[#setInstructionsKey|setInstructionsKey()]]</code>
  
−
The methods below were in use up to Oolite 1.73 and will be replaced in future<br>
+
=== <code>setInstructionsKey</code> ===
 +
{{Oolite-method-added|1.74}}
 +
function '''setInstructionsKey(messageKey : String, [worldScript : String])'''
  
−
function '''setBackgroundImage'''(backgroundImage : String)
+
Like <code>[[#setInstructions|setInstructions()]]</code>, but looks up the specified <code>messageKey</code> in [[missiontext.plist]].
  
−
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''''' <code>showMissionScreen</code>.
+
'''See also:''' <code>[[#setInstructions|setInstructions()]]</code>
  
−
function '''setChoicesKey'''(choicesKey : String)
+
=== <code>unmarkSystem</code> ===
−
 
+
  function '''unmarkSystem'''(systemNumbers : Number)
−
Specifies the choices to be shown at the mission screen. "choicesKey" is the key of an entry in missiontext.plist. Must be called '''''after''''' <code>showMissionScreen</code>.
 
−
 
 
−
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''''' <code>showMissionScreen</code>.
 
−
 
 
−
function '''showMissionScreen'''()
 
−
 
 
−
Shows the mission screen. Due to implementation details <code>musicKey</code>, <code>backgroundImage</code> and <code>shipKey</code> must be set '''''before''''' this method is called, but <code>messageKey</code> and <code>choicesKey</code> 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''''' <code>showMissionScreen</code>. (Open issue: why is this a method rather than a write-only property? --[[User:Ahruman|ahruman]])
+
Remove a mark set with <code>[[#markSystem|markSystem()]]</code>. (It is currently possible to mark multiple systems at once, as in <code>mission.unmarkSystem(4, 54, 222)</code>, but this syntax ''may'' be deprecated for Oolite 1.75.)
  
−
function '''runMissionScreen'''(messageKey : String, backgroundImage : String, choiceKey : String, shipKey : String, musicKey : String)
+
'''See also:''' <code>[[#markSystem|markSystem()]]</code>
  
−
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. <code>mission.runMissionScreen("myMessage", null, "myChoices")</code> 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.
 
  
 
[[Category:Oolite scripting]]
 
[[Category:Oolite scripting]]

Revision as of 10:49, 18 June 2010

Prototype: Object
Subtypes: none

The mission global object is used to run mission screens, and perform other actions related to mission scripting.

Methods

addMessageText

function addMessageText(message : String)

Appends text to the currently running mission screen.

markSystem

function markSystem(systemNumber : Number)

Mark a system on the long range chart. (It is currently possible to mark multiple systems at once, as in mission.markSystem(4, 54, 222), but this syntax may be deprecated for Oolite 1.75.)

See also: unmarkSystem()

runScreen

This method was added in Oolite test release 1.74. 

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 : String (name of an image used as overlay)
  • background : String (name of a picture used as background)
  • model : String (Role of a ship that will be shown as rotating ship)
  • message : String
  • messageKey : String (Key in missiontext.plist)
  • choicesKey : String (Key in missiontext.plist)

Some of these are mutually exclusive; for instance, “title” oveerrides “titleKey”.

The callback function is a function that is 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:
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.

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

This method was added in Oolite test release 1.74. 

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(). (It is currently possible to mark multiple systems at once, as in mission.unmarkSystem(4, 54, 222), but this syntax may be deprecated for Oolite 1.75.)

See also: markSystem()

Retrieved from "https://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Mission&oldid=22504"