Hud.plist

hud.plist and hud-small.plist are two different HUDs used by Oolite. They provide Oolite with the information necessary to display the players hud.
The 'hud-small.plist' is used on ships like the Cobra MkI and the Adder, while the 'hud.plist' is the standard default Cobra MkIII hud. The main difference lies in their width. 'hud-small' is smaller (narrower) than 'hud', to help you imagine a smaller cockpit in a smaller ship.

allow_big_gui

This property was added in Oolite test release 1.81.

This is a statement that there is nothing in the lower part of the screen (-256 <= x <= -160 , -256 <= y <= 256) when GUI screens are being displayed. Currently this allows the mission screen to take up 27 text rows instead of 21, which previously required the HUD to be hidden entirely.

This setting is not validated by the game. Setting this to 'yes' when the HUD does in fact use that space may end up looking very messy.

The default value is no.

Example:

allow_big_gui = yes;

cloak_indicator_on_status_light

This key determines if the statuslight also should show the cloaked status.

Example:

cloak_indicator_on_status_light = yes;

crosshair_scale

Affects the size of the crosshair. (default 32.0)

Example:

crosshair_scale = 32.0;

crosshair_width

Affects the width of the crosshair. (default 1.5)

Example:

crosshair_width = 1.5;

crosshair_color

Affects the color of the crosshair. color can be a named color or any of the other Colour specifiers. (Default is greenColor)

Example:

crosshair_color= "greenColor";

crosshairs

This entry contains a directory with crosshairs that overrides those defined in the internal crosshairs.plist

Example:

crosshairs = {
WEAPON_BEAM_LASER =
	(
		(0.25, 0.25, 1.0,		0.75, 0.0, 0.50),
		(0.25, 0.25, -1.0,		0.75, 0.0, -0.50),
		(0.25, 1.0, 0.25,		0.75, 0.50, 0.0),
		(0.25, -1.0, 0.25,		0.75, -0.50, 0.0),
		(0.25, -0.25, 1.0,		0.75, 0.0, 0.50),
		(0.25, -0.25, -1.0,		0.75, 0.0, -0.50),
		(0.25, 1.0, -0.25,		0.75, 0.50, 0.0),
		(0.25, -1.0, -0.25,		0.75, -0.50, 0.0)
	);
}

crosshair_file

This property was added in Oolite test release 1.77.

This entry names an external crosshairs plist file that defines the default crosshairs for this HUD. If this is specified at the same time as the crosshairs property, then crosshair_file takes precedence.

dials

The dials are listed here as an array of individual dials. Each dial is a separate directory. Some examples are:

{
	"equipment_required" = "EQ_SCANNER_SHOW_MISSILE_TARGET";
	selector = "drawTargetReticle:";
},
{	// scanner
	selector	= "drawScanner:";
	alpha		= 1.0;
	x		= 0;
	y		= 60;
	y_origin	= -1;
	height		= 72.0;
	width		= 288.0;
	rgb_color	= (1.0, 0.0, 0.0);
},
{    // energy bars
	"draw_surround" = yes;
	height = 48;
	selector = "drawEnergyGauge:";
	width = 80;
	x = 200;
	y = 35;
	"y_origin" = "-1";
	labelled = yes;
	n_bars = 3;
}

selector

The selector is a hardcoded name, like: drawTargetReticle: (see STE), drawScanner:, drawScannerZoomIndicator:, drawStickSensitivityIndicator:, drawCompass:, drawAegis:, drawScoopStatus:, drawSpeedBar:, drawRollBar:, drawPitchBar:, drawYawBar:, drawEnergyGauge:, drawForwardShieldBar:, drawAftShieldBar:, drawYellowSurround:, drawGreenSurround:, drawFuelBar:, drawCabinTempBar:, drawWeaponTempBar:, drawAltitudeBar:, drawMissileDisplay:, drawStatusLight:, drawClock:, drawWeaponsOfflineText: or drawFPSInfoCounter:

1.79 also adds: drawWaypoints:, drawPrimedEquipment:, drawASCTarget:, drawWitchspaceDestination:

1.81 also adds: drawSurround: (like drawYellowSurround: but allows a "color" attribute to be specified), drawCustomBar:, drawCustomIndicator:, drawCustomText:, drawCustomLight:, drawCustomImage:

align

In 1.79, for the "drawASCTarget:" selector, right-aligns the text to the X coordinate rather than the standard left alignment.

alpha

alpha is the transpacency of the dial ranging from 0 to 1.

alert_conditions

This property was added in Oolite test release 1.79.

This controls which alert conditions the dial appears at. It is a number from 0 to 15, formed by adding together the numbers for the individual alert conditions - 1=docked, 2=green, 4=yellow, 8=red. For example, a dial which only appeared at yellow and red alert condition would have

alert_conditions = 12;

The default value, which reflects previous behaviour, is 15 (show at all conditions)

color*

This property was added in Oolite test release 1.79.

There are several color parameters - color, color_low, color_medium, color_high, color_critical, color_surround for influencing the following dials.

• drawSpeedBar: color_low, color_medium, color_high, color_surround
• drawRollBar/drawPitchBar/drawYawBar: color, color_surround
• drawEnergyGauge: color_low, color_medium, color_surround
• drawForwardShieldBar/drawAftShieldBar: color_low, color_medium, color_high, color_surround
• drawFuelBar: color_low, color_medium, color_high, color_surround
• drawCabinTempBar: color_low, color_medium, color_high, color_critical, color_surround
• drawAltitudeBar: color_low, color_medium, color_high, color_critical, color_surround
• drawCustomBar: color_low, color_medium, color_high, color_surround

In general, low, medium and high represent ranges of the size of the bar (with critical for particularly dangerous levels on some dials). On the fuel bar, 'medium' is used for the bar itself, while 'high' and 'low' are used for the distance marker for the current destination system.

All of these parameters accept any standard format of color specifier.

data_source

This property was added in Oolite test release 1.81.

The data key set with player.ship.setCustomHUDDial. Different custom selectors expect different values:

• drawCustomBar: - a number between 0 and 1
• drawCustomIndicator: - a number between -1 and 1
• drawCustomLight: - any valid colour specifier (e.g. "greenColor" or [0.0,0.5,1.0,1.0])
• drawCustomText: - a string
• drawCustomImage: - a string, matching the filename of an image in the Images folder. Note that width and height can but do not need to be set on this dial. If they are set, all images will be scaled to that size. If they are not set, images will appear at their natural size. The image, like legend images, will be centred on the x and y coordinates.

draw_surround

A box is drawn around the dial when set to 'yes'.

equipment_required

The dials is only drawn if the required equipment is present.

height

The height of the dial.

labelled

Adds bank numbers to the energy banks. Does nothing for other dials.

n_bars

For "drawEnergyGauge:", determines how many energy banks are drawn. Without this key, the system chops the total energy in banks with a minimum of 64 units for each bank. (more precisely: n_bars = integer(maxEnergy/64) )

For "drawPrimedEquipment:", if this is set to >1 (odd numbers may be better than even) also shows some previous and next primable equipment in the cycle.

Ignored for other dials.

rgb_color

Determines the color of some dials. Example:

rgb_color	= (1.0, 0.0, 0.0);

reticle_scale

This property was added in Oolite test release 1.79.

Determines the minimum proportion of the screen taken up by the targeting reticle in 'drawTargetReticle' and the waypoint indicator in 'drawWaypoints'. Does nothing for other dials

spacing

Determines spacing between the missile icons in the 'drawMissileDisplay'. Does nothing for other dials.

viewscreen_only

This property was added in Oolite test release 1.81.

If this is set to true, then the HUD dial will only be displayed when looking at space (internal or external view) and not on GUI screens such as the market or the charts. This should generally be set for any dial positioned with 'x' between -256 and +256 and 'y' between -160 and +256, as otherwise they will overlap the GUI text.

Note: in Oolite 1.82 and earlier there is a bug with the processing of this setting which mean that the only 'true' value which is accepted is '1' - 'yes' and 'true' will be incorrectly treated as 'false'. Use viewscreen_only = 1; for compatibility with both 1.82 and later versions.

x

x is the x-position of the dial on screen.

y

y is the y-position of the dial on screen.

x_origin

x_origin = 1.0 means that the x co-ordinate is interpreted relative to the right hand side of the screen. If x_origin is set to 0 or unspecified, then x is interpreted relative to the middle of the screen. x_origin = -1.0 means that the x co-ordinate is interpreted relative to the left hand side of the screen. N.B. it is preferable to define hud elements relative to the screen borders, so that hud elements fit better on all height/width ratio screens.

y_origin

y_origin = -1.0 means that y is relative to the screen bottom. If y_origin is set to 0 or unspecified, then y is interpreted relative to the middle of the screen , and similarly for y_origin. y_origin = 1.0 means that the y co-ordinate is interpreted relative to the top of the screen.

width

The width of the dial.

legends

The legends are listed here as an array of individual legends. Each legends is a separate directory. The legends looks for example like:

legends = (
 {
	text		= "FWD";
	align		= 1;
	x		= -245;
	y		= 86;
	y_origin	= -1;
	height		= 12;
	width		= 12;
	with_dial	= "drawForwardShieldBar:";
 }, 
 {
 	image		= "myImage.png";
 	x		= -164;
 	y		= 72;
 	y_origin	= 1;
 	height		= 40;
 	width		= 40;
 	alpha 		= 0.5;
 }
)

"text" is the text to be displayed, while "image" is a texture file to be shown. If both are specified, "image" is used.

"alpha", "viewscreen_only" (1.81 onwards), "x", "y", "x_origin" and "y_origin" have the same meaning as on the dials. "height" and "width" control the height and width of the text characters (and should generally be the same number). "align", on a text dial, can be set to 1 to right-align the text (as with the "drawASCTarget:" dial) from 1.79 onwards.

"with_dial" in 1.79 onwards indicates that this legend should only be shown if the corresponding dial is visible

In 1.81, the "color" property of a legend may be set. In previous versions text legends are always green.

multi_function_displays

This property was added in Oolite test release 1.79.

The multi-function displays are listed here as an array. Each entry is a dictionary of parameters

multi_function_displays = (
		{
			width = 198;
			height = 132;
			x = -156;
			y = -72;
			y_origin = 1;
		},
		{
			width = 198;
			height = 132;
			x = 156;
			y = -72;
			y_origin = 1;
		}
	);

In 1.81 or later the "color" property is also available to change them from green if this suits the HUD better.

Links

• Tabular text output for MFDs/mission screens (2016)

overall_alpha

The overall tranparency of the hud can be set with overall_alpha.

Example:

overall_alpha	= 0.75;

reticle_target_sensitive

This key determines if the reticle should become red when on-target.

Example:

reticle_target_sensitive = no;

comm_log_gui

Determines the location and the specifications of the comm_log_gui and contains a directory of keys.

Example:

"comm_log_gui" = {
	alpha = "0.75";
	width = 360;
	height = 100;
	x = 0;
	y = 180;
	row_height = 12;
	permanent = no;
	automatic = yes;
	background_rgba = "0.0 0.05 0.45 0.5";  // = default color
};

message_gui

Determines the location and the specifications of the message_gui and contains a directory of keys.

Example:

"message_gui" = {
	alpha = "0.75";
	width = 480;
	height = 160;
	x = 0;
	y = "-40";
	"row_height" = 16;
};

---

List of special features included in HUD OXPs

These are not necessarily included the HUD.plist itself and might need javascripting. Most modern HUDs are Dynamic, altering their display between green, yellow, red and docked conditions.

       Choice of layouts/colour - Dangerous HUD (fighter cockpit view, hauler cockpit view and glass only view, 6 colours) & Xenon HUD (2 colours)
       Gauges: Curved gauges - ChupacabraHUD
       Gauges: Round Dials - Vimana HUD
       Gauges: Pie Charts - Pie Chart Style HUDs
       Gauges: Numeric - Numeric Style HUDs
       Warning signs (eg. for low altitude/energy/shields/high temperature/on-coming missiles) - Vimana HUD, ChupacabraHUD
       Sun glare contrast for MFDs - Xenon HUD
       Pulsating scanner - Dangerous HUD
       Weapon Bays Missile Identifier - ChupacabraHUD
       Custom Missile Bay display - ChupacabraHUD
       Shield capacitors recharging display - ChupacabraHUD
       Ironhide armour status - Vimana HUD
       Current Location Display (with Current Risk Notifier) - Deeper Space HUD
       Persistent comms messages screen - ClearHUD
       Extra add-on modules (purchasable) with some of the functions of the Combat, Damage Report & Navigation MFD's - Vimana HUD
       Equipment Lights - Z-GrOovY MiLHUD, Vimana HUD, Deeper Space HUD & the Coluber HUDs (these lists are inevitably partial - there is so much equipment)
       Precision flight indicator (for controllers/joysticks only) - Vimana-X HUD, Fighter HUD (Oolite), MilSpec HUD OXP, Coluber HUD CH01 & JB's Dynamic HUD (included in compass).
       Sound effects - Dangerous HUD

Designing a HUD

It's easier than you think. Draw up your graphic, and then it's a matter of trial and error placing the gauges and readings. They all kinda fall into the format of an X-Y placing and a Height/Width value if needed. It's that simple. Placing them can be a pain in the butt of repetition and you work out values, but it's worth it when it all gets done and you launch for the first time and see your own HUD working.
Once you've done your graphics and hud.plist, you just need to assign that to a particular ship (if that's how you want it to work) ~ there's a "HUD" value in the shipdata.plist listing. Alternatively you just let it stand alone and the game will use it as default. Killer Wolf (2010)

Adding in HUD Selector compatibility allows for easy swapping of HUDs (say between 3 tweaked versions of your own which you wish to try out...)

• FrankenHUD Designing a HUD (2009)

Links

• Making HUDs (2010 - before the many recent changes)
• Yet another contribution to the collection of HUD´s (2011 - 5 pages of thread include many tweaks and explanations)
• HowToDo rather complex visualizations / GUI's? Complex stuff about HUDs (2013)

Specific Tweaks

• Change text color (Phkb, 2017)
• HUD design - colours (2013)
• (HUD Dev) drawCustomText: - multi line / line break possible? (Pleiadian, 2017)
• (HUD Dev) Display current system and tech level? (Pleiadian, 2017)
• (HUD Dev) Display speed in meters? (Pleiadian, 2017)
• A Vertical HUD? (gt52, 2016)
• Adding customised HUD dials (Norby, 2015)
• Adding a precision flying indicator (for controllers/joysticks) (Phkb, 2023)
• Moving MFDs and Message panels around your HUD posts by Diziet Sma & Spara (2014), and by Tricky (2014).
• Issues with 2 HUDs loaded (2013)
• Thread includes some issues with designing HUDs (2013)
• Moving the onscreen messages to the side (2011)
• Formatting text msgs on a HUD (2011)