Mission screen

Mission screens started off as screens which allow the player to interface with NPCs in a mission.oxp but also allow other sorts of "communication" as in the conversation overheard in the bar in the Hints OXP.

They can have backdrops, changes in text and allow choices for the player.

The text can be placed in a descriptions.plist, details about it in a script.js

Text

Several spacial characters are used in determining the layout of the text, just as in Wiki.

   \" Enables the use of colons.
   \\n Insert a hard Enter.

In XML:

   \n Inserts a hard Enter.

See Missiontext.plist for more complexity (eg random names, naming current system etc)

Character '31' (hex:1F, octal:037) is a narrow 'hair-space'. Custom font OXPs should ensure that this character is blank and has the same narrow width as the core font definition, as it is used to allow an equivalent to 'tab stops' in mission text.

% codes

Here are the % codes that can be used inside description strings and what each one does:

Code:

•  %H is replaced with <planetName>. If systemName is nil, a planet name is retrieved through -[Universe getSystemName:], treating <seed> as a system seed.
  
•  %I is equivalent to "%H[planetname-derivative-suffix]".
  
•  %N is replaced with a random "alien" name using the planet name digraphs. If used more than once in the same string, it will produce the same name on each occurence.
•  %R is like %N but, due to a bug, misses some possibilities. Deprecated.
•  %JNNN, where NNN is a three-digit integer, is replaced with the name of system ID NNN in the current galaxy.
•  %GNNNNNN, where NNNNNN is a six-digit integer, is replaced with the name of system ID NNN (first triplet) in the specified galaxy (second triplet).
•  %% is replaced with %.
•  %[ is replaced with [.
•  %] is replaced with ].

From String expansion

Colour

Choices can be non-yellow (have a look at the various contracts interfaces in 1.77) but there is a more fundamental limitation of the current UI code that all text on a particular line has to be the same colour. Cim (2013)

Code for Colour change

Alignment

There is no obvious way to do this, but Ocz managed some version of right alignment for his First Finance OXP

Tabular layout

When you need to get something in the form of a table or columns, you can use padText-like functions to adjust the padding of the desired width to labels and data, and then concatenate them into one line, just keep in mind that max row length is 32 em.

var pad1em = this._padTextLeft("", 1);
var tableHeader = this._padTextLeft("#", 3) + pad1em + 
    this._padTextRight("Item", 11) + pad1em +
    this._padTextAround("Remaining, pcs.", 7) + pad1em +
    this._padTextAround("Price, ₢ ", 7) + pad1em;

var tableRows = Array(this.$items.length);
for(var i = 0; i < this.$items.length; i++) {
    var item = this.$items[i];
    tableRows[i] = this._padTextLeft(i + 1, 3) + pad1em + 
    this._padTextRight(item.name, 11) + pad1em +
    this._padTextAround(item.quantity, 7) + pad1em +
    this._padTextLeft(formatCredits(item.price), 7) + pad1em;
}

// Concatenate them in one string if you want to display 
// the table as "message" on the mission screen
var table = tableHeader + "\n" + tableRows.join("\n") + "\n\n";

Alaric's unfinished Torus-field-monitor OXZ contains handy function to help format text in tabular layout for use in mission screens/MFDs.

See his alaric-oxp-utilities.js file:     Show code

"use strict";

this.name        = "alaric-oxp-utilities";
this.author      = "Alaric";
this.copyright   = "2016 Alaric";
this.description = "General helper functions for OXPs";
this.licence     = "CC BY-NC-SA 3.0 AU";
this.version	 = "1.0";

/**
* Trims a length of text to fit in the available width. If the text is truncated, 
* an ellipse (U+2026) will be appended unless <ellipses> is false. If <ellipses>
* is omitted from the call, it defaults to true.
*
* text				- The text to trim
* emDisplayWidth	- The available width, in Em, to display the text
* ellipses			- optional (default: true)
*
* Returns the new, trimmed, string.
*/
this._trimTextToFitWidth = function(text, emDisplayWidth, ellipses)
{
	var font = defaultFont;
	var chPadding = String.fromCharCode(31);
	var ellipsesText = "\u2026";
	var emEllipsesText = font.measureString(ellipsesText);
	var emPaddingText = font.measureString(chPadding);
		
	var chWidth = [0, text.length];
	var emWidth = [font.measureString(text), 0];

	// use default for ellipses if not supplied
	if (ellipses === null || ellipses === undefined) ellipses = true;
	
	// if the text already fits, just return it.
	if (emWidth[0] <= emDisplayWidth) return text;
	
	// if the display width is too short for ellipses, disable ellipses
	if (emEllipsesText >= emDisplayWidth) ellipses = false;

	// subtract ellipses with from display width if ellipses is true
	emDisplayWidth -= (ellipses) ? emEllipsesText : 0;
		
	while (chWidth[0] != chWidth[1])
	{
		// get Em width of text at length midway between chWidth[0] and chWidth[1]
		var chPivot = Math.ceil((chWidth[0] + chWidth[1]) / 2);
		var emPivot = font.measureString(text.substring(0, chPivot)); 

		// update for next split point based on the text being too long or too short
		var flagDirection = (emPivot <= emDisplayWidth) ? 0 : 1;

		chWidth[flagDirection] = chPivot - flagDirection;
		emWidth[flagDirection] = emPivot;
	}

	// At this point, chWidth[0] and emWidth[0] contain the trimmed width in
	// characters and Em respectively. Return the text, appending ellipses if 
	// <ellipses> is true. The space for ellipses has already been accounted
	// for.

	return (ellipses) 
		? text.substring(0, chWidth[0]) + ellipsesText
		: text.substring(0, chWidth[0])
		;
}


/*
* Builds tabular (columns aligned) text for use in mission screens/MFDs.
*
* Input to the function is provided by an array of 'rows'. Each row is, itself, an array of
* objects with the following properties:
*
* Required properties:
*	text:	The text to display in this column
*	width:	The width of the column in em. Text will be truncated if too long.
*
* Optional properties:
*	alignment:	LEFT, RIGHT or CENTER. Default: LEFT
*	elipses:	Display elipses for truncated text? Default: true.
*  blink:		
*
* Multiple rows are deliniated by '\n'. No '\n' is appended to the last row.
*
*/
this._buildTabularText = function(rows)
{
	var padCharacter = String.fromCharCode(31);
	var padWidth = defaultFont.measureString(padCharacter);
	var tabularText = "";
	var row;
	
	for (row = 0; row < rows.length; ++row)
	{
		if (row > 0) tabularText += "\n";
	
		var i;
		
		var currentEm0 = 0;
		var currentEm1 = 0;
		var columns = rows[row];
		var rowText = "";

		for (i = 0; i < columns.length; ++i)
		{
		
			currentEm0 = defaultFont.measureString(rowText);
			var leading = (currentEm1 - currentEm0);
			currentEm1 = currentEm1 + columns[i].width;
						
			var text = this._trimTextToFitWidth(columns[i].text, currentEm1 - currentEm0, columns[i].ellipses);
			var width = defaultFont.measureString(text);
			
		
			var padding = (currentEm1 - currentEm0) - width;

			switch ((columns[i].alignment !== undefined) ? columns[i].alignment : "LEFT")
			{
				
				case "LEFT" : padding = 0; break;
				case "RIGHT" : leading = 0; break;
 				case "CENTER" : padding = padding / 2; break;					

				default:
					log(this.name, "invalid alignment '" + columns[i].alignment + "'");
					padding = 0; break;

			}

			padding = Math.floor((leading + padding) / padWidth);
			
			rowText += (padding >= 1) 
				? new Array(padding).join(padCharacter) + text 
				: text
				;
		}
	
		tabularText += rowText;
	}

	return tabularText;
}

You can use it like this:     Show example

var rows = [
        [ /* header */
            { width: 32, alignment: "CENTER", text: "Fleet status" }
        ],

        [ /* line spacer */
        ],

        [ /* row 1 */

            { width: 1.5, text: "" },	// spacer
            { width: 20.5, alignment: "LEFT", text: "Ship" },
            { width: 10,   alignment: "RIGHT", text: "Maintenance" }
        ],
        [ /* row 2 */
            { width:   1, alignment: "RIGHT", text: "1" },
            { width: 0.5, alignment: "RIGHT", text: "" },	// spacer
            { width:  28, alignment: "LEFT", text: "Cobra Mk III" },
            { width: 2.5, alignment: "RIGHT", text: "10%" }
        ],

        [ /* row 3 */
            { width:   1, alignment: "RIGHT", text: "2" },
            { width: 0.5, alignment: "RIGHT", text: "" },	// spacer
            { width:  28, text: "Krait" },
            { width: 2.5, alignment: "RIGHT", text: "7%" }
        ],

        [ /* row 4 */
            { width:   1, alignment: "RIGHT", text: "3" },
            { width: 0.5, alignment: "RIGHT", text: "" },	// spacer
            { width:  28, alignment: "LEFT", text: "Unrealisticly long ship class name that happens to be not so long for mission screen" },
            { width: 2.5, alignment: "RIGHT", text: "100%" }
        ],

        [ /* row 5 */
            { width:   1, alignment: "RIGHT", text: "4" },
            { width: 0.5, alignment: "RIGHT", text: "" },	// spacer
            { width:  28, alignment: "LEFT", text: "Unrealisticly long name without ellipses that happens to be not so long for mission screen", ellipses: false },
            { width: 2.5, alignment: "RIGHT", text: "100%" }
        ],

        [
        ],

        [
            { width: 32, alignment: "CENTER", text: "Next enemy grooup encounter in 4 hours" }
        ]
    ]
		
);

var utils = worldScripts["alaric-oxp-utilities"]; // Get world script object if you copied entire file to your OXP
var messageText = utils._buildTabularText(rows); // or use this._buildTabularText(rows), if you copied just that funtions in your world script

mission.runScreen({
    title: "Statistics",
    screenID: "oxpname-stats-fleet"
    message: messageText
});

Backdrop

This is managed from within the script.js file:

background: ""the_file_name_of_the_image_you_want_to_display_must_be_in_the_images_folder.png",

or you can use overlay instead of background (less conflicts with other oxp's such as XenonUI which also tend to specify a background)

Problems with Backdrop

These can be prevented from appearing by other oxp's such as XenonUI which also create backdrops for the docked screens.

Using overlay helps, but also see Phkb's comments here (for Dark Side solutions) and here (using Library config).

Exit Screen

By default, when the mission screen ends, the game returns to the status screen (F5), but this behavior can be changed. In most cases you can just provide the exitScreen parameter to the mission.runScreen call, but if if the exit screen depends on the player's choice, you need change the exit screen in the mission screen callback by setting mission.exitScreen. Outside of a callback function, the value of this is almost meaningless, and setting it has no useful effect.

The example below uses both ways:     Show Example

this._runMissionScreen = function _runMissionScreen() 
{
    mission.runScreen(
        {
            title: "Exit Screen Example",
            exitScreen: "GUI_SCREEN_MARKET", // <-- The first way 
            choices: {
                "01_INTERFACES": "Do nothing",
                "02_CHART": "Set mission.exitScreen to \"GUI_SCREEN_SHORT_RANGE_CHART\"",
                "03_SYSDATA": "Set mission.exitScreen to \"GUI_SCREEN_SYSTEM_DATA\"",
                "04_INVALID": "Set mission.exitScreen to \"INVALID VALUE\"",
            }
        },
        this._missionScreenCallback.bind(this)
    );
    // The mission.exitScreen variable is set to the value 
    // of the exitScreen parameter of the function call above
    mission.addMessageText("Current exit screen is " + mission.exitScreen + ".");
};

this._missionScreenCallback = function _missionScreenCallback(choice) 
{
    // The choice is null when player interrupts the mission screen (e.g., presses F1 )
    if (choice === "01_INTERFACES" || choice === null) {
        // Do nothing - the exit screen will be as specified in runScreen call
    }
    else if (choice === "02_CHART") {
        mission.exitScreen = "GUI_SCREEN_SHORT_RANGE_CHART"; // <-- The second way
    }
    else if (choice === "03_SYSDATA") {
        mission.exitScreen = "GUI_SCREEN_SYSTEM_DATA";
    }
    else if (choice === "04_INVALID") {
        mission.exitScreen = "INVALID VALUE"; // The exit screen will be reset to default
    }
};

// Add interface to F4 page for docked station
this.startUpComplete = function startUpComplete() 
{
    player.ship.dockedStation.setInterface("example_exit_screen",
        {
            title: "Show exitScreen example screen",
            summary: "This is an example interface definition.",
            category: "AAA",
            callback: this._runMissionScreen.bind(this)
        }
    );
};

Svengali's Library & CCL

These two oxp's allow for more complex interractions. See the deprecated CCL's never used Cutscene, as well as the current Library OXP's "Music" and "Demos".

Links

• Creating a mission screen for textual messages (2021)
• Changing text colour (2022)
• New Line in mission.runScreen? (2017)
• Tabular text output for MFDs/mission screens (2016)