Table of Contents

• Introduction
• Defining an interface
• Arrangement
  • Anchor/alignment
  • Position and size
• Active and visible conditions
• Interface elements
  • Points and boxes
  • Sprites, images, and outline
  • Labels, strings, and buttons
  • Bars and rings
  • Filled areas
  • Pointers
  • Values

Introduction

interface <name> [<anchor>]
	anchor [<anchor>]
	(active | visible) [if <condition>]
	point <name>
		from <x#> <y#> [<anchor>]
		[align [<anchor>]]
		[pad <x#> <y#>]
	box <name>
		from <x#> <y#> to <x#> <y#> [<anchor>]
		[align [<anchor>]]
		[pad <x#> <y#>]
	(sprite <sprite>) | (image | outline <name>)
		center <x#> <y#> [<anchor>]
		dimensions <x#> <y#>
		[colored]
	(label <text>) | (string <name>) | (button <key> <text>) | ("dynamic button" <key> <name>)
		from <x#> <y#> [<anchor>]
		[color <color>]
		width <width#>
		[truncate <truncation>]
		[align [<anchor>]]
		[pad <x#> <y#>]
	("wrapped label" <text>) | ("wrapped string" <name>) | ("wrapped button" <key> <text>) | ("wrapped dynamic button" <key> <name>)
		from <x#> <y#> [<anchor>]
		[color <color>]
		width <width#>
		[truncate <truncation>]
		[alignment <alignment>]
		[align [<anchor>]]
		[pad <x#> <y#>]
	(ring | bar) <name>
		center <x#> <y#> [<anchor>]
		dimensions <x#> <y#>
		[color <from color> [<to color>]]
		[size <size#>]
		[reversed]
		[start angle <angle#>]
		[span angle <angle#>>]
	pointer
		from <x#> <y#>
		to <x#> <y#>
		["orientation angle" <angle#>]
		["orientation vector" <x#> <y#>]
		[color <color>]
	fill
		from <x#> <y#> to <x#> <y#> [<anchor>]
		color <color>
	value <name> <value>
	list <name>
		<value#>
		...

Defining an Interface

interface <name> [<anchor>]

This marks the beginning of this interface definition and defines the name by which the game code can refer to this interface. If an interface with this name has previously been defined when this one is loaded, the previously loaded definition will be discarded, meaning plugins can completely override interface definitions. This line may optionally set an anchor. This is equivalent to the first line of the interface definition setting the same anchor point:

interface <name>
	anchor [<anchor>]

Arrangement

Anchor/alignment

All elements can be given an individual alignment, overriding the currently active global anchor for that element only. All elements can also be given a pad value, this defines amount of padding that will be added around the element when drawing it in its bounding box.

	anchor [<anchor>]

Sets the "origin" point. The coordinates of elements will be taken relative to that origin. The origin set by an anchor node is applied to all elements following that node until another anchor node or the end of the interface. Except for any elements which define their own anchor. If the node has no additional tokens beyond the first, then center is implicitly used and the origin set by this anchor will be the center of the screen, coordinates (0, 0). The <anchor> values take the form:

([(top | bottom)] [(left | right)] | center)

If only a vertical or horizontal alignment is provided, the center of that edge will be used:

Position and size

There are several different ways in which the position and size of an element can be defined. Each element need only make use of one:

from <x#> <y#> to <x#> <y#> [<anchor>]

The coordinates for opposing corners of the bounding box are given. An optional anchor override can also be included, which will be applied to both sets of coordinates if present.

from <x#> <y#> [<anchor>]
to <x#> <y#> [<anchor>]

Similar to the previous method, however since each of the two sets of coordinates is given separately, they can be given anchor overrides if desired.

from <x#> <y#> [<anchor>]
dimensions <x#> <y#>

The position of one corner is given, alongside the size of the box, instead of the opposite corner. The position of the opposite corner will be derived by adding the x and y values of the dimensions to the x and y of the from coordinate, respectively.

Dimensions can also be defined as two separate values:

width <width#>
height <height#>

Where width is equivalent to the dimensions x value ande height is equivalent to the y value.

center <x#> <y#> [<anchor>]
dimensions <x#> <y#>

The center coordinate gives the point at the center of the bounding box; the same distance from the left edge as to the right, and the same distance from the top edge as to the bottom.

Wherever any one of these methods of defining position and size is valid, any of the others may also be used instead.

Active and visible conditions

	(active | visible) [if <condition>]

These nodes mean subsequent elements will only be active or visible, respectively, if the given condition was set in the information passed to this interface object when it was drawn. They are not mutually exclusive: an element can be active and visible, inactive and visible, or inactive and invisible, however, and element cannot be active and invisible. The requirement will be applied to all subsequent elements until either the end of this interface definition, or until an overriding active or visible node. If a node only contains the token active or visible, with no condition, then any previous condition requirement in place will not apply to subsequent elements, until a new requirement is defined.

Interface elements

Points and boxes

The most basic type of element is the point:

	point <name>
		(center | from) <x#> <y#> [<anchor>]
		[align [<anchor>]]
		[pad <x#> <y#>]

This defines a coordinate which can be used by the game to as an anchor to draw complex graphics not defined in the interface. For example, the position of the radar is defined as a point.

	box <name>
		from <x#> <y#> to <x#> <y#> [<anchor>]
		[align [<anchor>]]
		[pad <x#> <y#>]
	box <name>
		from <x#> <y#> [<anchor>]
		to <x#> <y#> [<anchor>]
	box <name>
		from <x#> <y#> [<anchor>]
		dimensions <x#> <y#>
	box <name>
		center <x#> <y#> [<anchor>]
		dimensions <x#> <y#>
	box <name>
		center <x#> <y#> [<anchor>]
		width <width#>
		height <height#>
	box <name>
		from <x#> <y#> [<anchor>]
		width <width#>
		height <height#>

A box defines a rectangle on screen which can be used as the bounding area for the game to draw more complex items.

There are numerous different element types which can have additional child nodes unique to them:

Sprites, images, and outlines

	sprite <sprite>
		from <x#> <y#> to <x#> <y#> [<anchor>]
		[inactive <sprite>]
		[hover <sprite>]

Allows a sprite, with the path (within the images folder) given by <sprite>. It will only be drawn if its visible condition is met. Optional alternative inactive and hover sprites can also be defined to be drawn instead of the default if the active condition of this sprite is not met, or if it is met and the user's mouse is above the bounding box of this sprite, respectively.

	image <name>
		from <x#> <y#> to <x#> <y#> [<anchor>]

Provides a named box that can be given an image to be drawn by the game at runtime, only if the visible condition is met.

	outline <name>
		from <x#> <y#> to <x#> <y#> [<anchor>]
		[colored]

Similar to image, however, the OutlineShader will be used with the given sprite, instead of drawing the image directly. If the colored child node is present, then a custom color can be set by the game when the sprite to be outlined is set, otherwise, opaque white will be used.

Labels, strings, and buttons

	(label <text>) | (string <name>) | (button <key> <text>) | ("dynamic button" <key> <name>)
		from <x#> <y#> to <x#> <y#> [<anchor>]
		size <size#>
		color <color>
		inactive <color>
		hover <color>
		truncate (none | front | middle | back)

Defines a location for text to be drawn. In the case of a label, the given text will be drawn directly. With a string, a name is given, and the game sets the text at runtime, selecting this text location with that name. A button is similar to a label, except it also accepts a key token. The first character of this token will be sent as keyboard input if the bounding box for this button is clicked while it is visible and active. A dynamic button (v. 0.10.5) is a combination of a button and a string element. It has the functionality of a button, but its caption is retrieved at runtime.

Size defines the font size of the text. The vanilla game supports 14 and 18.

Color sets the named color that will be used for the text when it is visible and active. If no color is given, the following defaults will be used:

type	color name
color (active)	"active"
inactive	"inactive"
hover	"hover"

If color is defined but either the inactive or hover color is not, the undefined color will use the given active color.

Wrapped text elements

	("wrapped label" <text>) | ("wrapped string" <name>) | ("wrapped button" <key> <text>) | ("wrapped dynamic button" <key> <name>)
		from <x#> <y#> to <x#> <y#> [<anchor>]
		size <size#>
		color <color>
		inactive <color>
		hover <color>
		truncate (none | front | middle | back)
		alignment (left | center | right | justified)

Beginning with v. 0.10.13, every text element has its "wrapped" counterpart. The difference is that the text is wrapped at the width limit of the element. As for basic text elements, you can specify truncation of the text. Additionally, you can choose how the text should be aligned.

Bars and rings

	(bar | ring) <name>
		from <x#> <y#> to <x#> <y#> [<anchor>]
		color <from color> [<to color>]
		size <size#>
		[reversed]
		[start angle <angle#>]
		[span angle <angle#>>]

Defines a straight line (bar) or circular outline (ring) to be drawn with this interface. In the case of a ring, it will be drawn anti-clockwise around the center of its bounding box, with a radius equal to half the width of the bounding box. Beginning in v. 0.10.2, it is also possible to define the "start angle" and "span angle" for a ring. The "start angle" defines from how many degrees clockwise from a line straight up from the center the ring should start filling. The default value is 0, which corresponds to straight up. Values of greater than or equal to zero and less than 360 are allowed. The "span angle" defines how many degrees the ring should be drawn through when fully filled. The default, and maximum, value is 360, where the full ring will correspond to a full circle. The minimum value is 0, in which case, nothing is drawn. A bar will be drawn from the bottom right corner of its bounding box. At runtime, the game may only partially complete the bar or ring, or segment it, for example, the ship hull status ring, or the fuel bar. Beginning in v0.10.3, "reversed" can be used to invert the fill direction of a bar. A reversed bar will be filled from the top left corner. It is not currently possible to reverse a ring. The size determines the thickness of the bar or ring, the default value is 2. Bars can take a start and end color, and will interpolate between the two. If one color is given, the whole bar will be that color, and if no color is given, "active" will be used.

Filled areas

	fill <name>
		from <x#> <y#> to <x#> <y#> [<anchor>]
		color <color>

Defines an area to be filled with the specified color while drawing this interface. Prior to v. 0.10.17, the keyword for this element was "line". If no color is given, "medium" will be used.

Pointers

	pointer
		from <x#> <y#>
		to <x#> <y#>
		["orientation angle" <angle#>]
		["orientation vector" <x#> <y#>]
		[color <color>]

Define a pointer to be drawn with this interface. The orientation can either be given as an angle in degrees, counting clockwise with 0 being straight up, or a pair of values corresponding to the x and y components of a vector. If no orientation is given, the vector (0, -1) is used. If no color is given, "medium" will be used.

Values and lists

	value <name> <value#>

Stores a numerical value. This can be any real number, which the game can refer to using the given name.

	list <name>
		<value#>
		...

Stores a list of real numbers, which the game can refer to using the given name (v. 0.10.5).