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

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

To change the "Exit Screen" away from the default, you can use this code

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)
• Alaric's unfinished Torus-field-monitor OXZ contains Javascript for formatting MFD's - and for making text flow. See his alaric-oxp-utilities.js file:

"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;
}