Hud.plist

From Elite Wiki
Revision as of 20:24, 10 August 2015 by Cim (talk | contribs) (viewscreen_only: Note bug)

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' 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

In Oolite 1.81 and onwards 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

(Oolite 1.77 or later) 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:, 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

In Oolite 1.79 or later, 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*

From Oolite 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

(1.81 or later)

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.

labeled

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

(1.79 or later)

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

(1.81 or later)

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

In 1.79 or later 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.

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