Cholmondely: Tagged as Oolite scripting

2025-08-11T15:18:39Z

Tagged as Oolite scripting

Wildeblood: /* Related Pages */

2025-08-08T08:16:57Z

‎Related Pages

Wildeblood: /* Related Pages */

2025-08-08T05:56:24Z

‎Related Pages

Wildeblood: /* Related Pages */

2025-08-07T11:39:59Z

‎Related Pages

Wildeblood: /* Related Pages */

2025-08-07T06:23:28Z

‎Related Pages

Wildeblood: Page created with analysis by GLM-4.5

2025-08-06T22:20:59Z

Page created with analysis by GLM-4.5

New page

The '''hud.plist''' file is a configuration file that defines the layout, appearance, and behavior of the Heads-Up Display (HUD) in Oolite. This powerful configuration file allows players and OXP developers to customize virtually every aspect of the in-game interface, from crosshair appearance to instrument placement, colors, and transparency.

== Overview ==
The HUD configuration file is structured as a property list (plist) with several main sections:
* Global settings - Overall HUD behavior and appearance
* Dials - Individual HUD elements (gauges, indicators, etc.)
* Legends - Text labels associated with dials
* Multi-function displays (MFDs) - Customizable information panels
* Message GUI - In-game message display settings
* Comm log GUI - Communications log settings

The file uses a coordinate system where (0,0) is the center of the screen. Positive x values move elements right, negative x values move them left. Positive y values move elements down, negative y values move them up.

== File Location ==
The main hud.plist file is located in the Oolite installation directory under <code>Resources/Config/</code>. OXPs can override this file by including their own hud.plist file.

== Global Settings ==
These settings control the overall behavior and appearance of the HUD.

{| class="wikitable"
|-
! Key !! Type !! Description
|-
| crosshair_scale || float || Scales the size of the crosshair. Larger values = bigger crosshair.
|-
| crosshair_width || float || Line thickness of the crosshair.
|-
| crosshair_color || string || Color of the crosshair (e.g., "greenColor", "redColor", or RGB tuples).
|-
| scanner_minimalistic || boolean || If yes, uses a simpler, cleaner scanner display.
|-
| scanner_non_linear || boolean || If yes, scanner zoom is non-linear (more sensitive near the center).
|-
| scanner_ultra_zoom || boolean || If yes, enables ultra zoom mode on the scanner.
|-
| allow_big_gui || boolean || If yes, allows larger GUI elements (not commonly used).
|-
| overall_alpha || float || Global transparency (0.0 = fully transparent, 1.0 = fully opaque).
|-
| cloak_indicator_on_status_light || boolean || If yes, shows cloak status on the status light.
|-
| reticle_target_sensitive || boolean || If yes, reticle changes color when over a target.
|}

Example:
<pre>
{
crosshair_scale = 32.0;
crosshair_width = 1.5;
crosshair_color = "greenColor";

scanner_minimalistic = no;
scanner_non_linear = no;
scanner_ultra_zoom = no;

allow_big_gui = no;
overall_alpha = 0.75;
cloak_indicator_on_status_light = yes;
reticle_target_sensitive = no;
</pre>

== Dials ==
The <code>dials</code> array lists all HUD elements, in drawing order. Each dial is a dictionary specifying its appearance, position, size, and behavior.

=== Common Dial Properties ===
{| class="wikitable"
|-
! Key !! Type !! Description
|-
| selector || string || Internal method that draws this dial (e.g., "drawScanner:").
|-
| equipment_required || string || Only show if this equipment is present (e.g., "EQ_ADVANCED_COMPASS").
|-
| x, y || int || Position on screen. Positive = right/down, negative = left/up from center.
|-
| y_origin || int || Vertical origin: -1 = bottom, 1 = top.
|-
| width, height || float || Size of the dial.
|-
| alpha || float || Transparency (0.0–1.0).
|-
| rgb_color || array || RGB color, e.g., (1.0, 0.0, 0.0) = red.
|-
| draw_surround || boolean || If yes, draws a border around the dial.
|-
| labelled || boolean || If yes, includes a text label (e.g., for energy gauge).
|}

=== Example Dials ===

==== Targeting Reticle ====
<pre>
{ // Targeting reticle
equipment_required = "EQ_SCANNER_SHOW_MISSILE_TARGET";
selector = "drawTargetReticle:";
// reticle_scale = 0.015625 /* 1/64 is default */
target_rgba = "greenColor";
target_sensitive_rgba = "redColor";
wormhole_rgba = "cyanColor";
},
</pre>
Only appears if missile targeting scanner is installed. Changes color based on target/wormhole.

==== Scanner ====
<pre>
{ // scanner
alpha = 1.0;
selector = "drawScanner:";
x = 0;
y = 68;
y_origin = -1;
height = 64.0;
width = 288.0;
rgb_color = (1.0, 0.0, 0.0);
},
</pre>
The main radar display. Positioned at (x=0, y=68) from bottom-center. Red by default.

==== Flight Control Bars ====
<pre>
{ // speed bar
draw_surround = yes;
height = 8;
selector = "drawSpeedBar:";
width = 80;
x = 200;
y = 95;
y_origin = -1;
},
{ // roll bar
draw_surround = yes;
height = 6;
selector = "drawRollBar:";
width = 80;
x = 200;
y = 80;
y_origin = -1;
},
{ // pitch bar
draw_surround = yes;
height = 6;
selector = "drawPitchBar:";
width = 80;
x = 200;
y = 70;
y_origin = -1;
},
{ // yaw bar
draw_surround = yes;
height = 8;
selector = "drawYawBar:";
width = 80;
x = 200;
y = -130;
},
</pre>
Horizontal/vertical flight indicators. Positioned at right side of screen. draw_surround adds a border.

==== Status Gauges ====
<pre>
{ // energy gauge
draw_surround = yes;
height = 48;
selector = "drawEnergyGauge:";
width = 80;
x = 200;
y = 35;
y_origin = -1;
labelled = yes;
},
{ // forward shield bar
draw_surround = yes;
height = 8;
selector = "drawForwardShieldBar:";
width = 80;
x = -200;
y = 94;
y_origin = -1;
},
{ // aft shield bar
draw_surround = yes;
height = 8;
selector = "drawAftShieldBar:";
width = 80;
x = -200;
y = 78;
y_origin = -1;
},
{ // fuel bar
height = 8;
selector = "drawFuelBar:";
width = 80;
x = -200;
y = 61;
y_origin = -1;
},
</pre>
Vertical/horizontal status bars. draw_surround adds a border. labelled includes a text label.

==== Specialty Indicators ====
<pre>
{ // missile display
height = 12;
selector = "drawMissileDisplay:";
spacing = 16;
width = 12;
x = -228;
y = 16;
y_origin = -1;
},
{ // status indicator light
height = 8;
selector = "drawStatusLight:";
width = 8;
x = -108;
y = 32;
y_origin = -1;
},
{ // ship's clock
height = 12;
selector = "drawClock:";
width = 12;
x = -41;
y = 18;
y_origin = -1;
},
</pre>
Small indicators for ship status, time, and armament. width/height control icon size.

== Legends ==
Legends are text labels, usually paired with dials. They are drawn ''before'' dials, so text appears behind the graphics.

=== Legend Properties ===
{| class="wikitable"
|-
! Key !! Type !! Description
|-
| text || string || The label to display.
|-
| align || int || Text alignment: 0 = left, 1 = center, 2 = right.
|-
| x, y || int || Position.
|-
| y_origin || int || -1 = from bottom, 1 = from top.
|-
| height, width || float || Font/label size.
|-
| with_dial || string || Links this label to a dial (for visibility/positioning).
|}

=== Example Legends ===
<pre>
legends = // these are drawn, in order, before the dials
(
// Left hand side
{
text = "FWD";
align = 1;
x = -245;
y = 86;
y_origin = -1;
height = 12;
width = 12;
with_dial = "drawForwardShieldBar:";
},
{ text = "AFT";
align = 1;
x = -245;
y = 70;
y_origin = -1;
height = 12;
width = 12;
with_dial = "drawAftShieldBar:";
},
{
text = "FUEL";
align = 1;
x = -245;
y = 55;
y_origin = -1;
height = 10;
width = 10;
with_dial = "drawFuelBar:";
},
// Right hand side
{
text = "SPD";
x = 242;
y = 86;
y_origin = -1;
height = 14;
width = 14;
with_dial = "drawSpeedBar:";
},
{
text = "ROLL";
x = 242;
y = 72;
y_origin = -1;
height = 12;
width = 12;
with_dial = "drawRollBar:";
},
);
</pre>

* "FWD"/"AFT": Labels for forward/aft shield bars.
* "FUEL"/"ALT"/"CT"/"LT": Fuel, altitude, cabin/weapon temperature.
* "SPD"/"ROLL"/"PITCH"/"YAW": Flight control indicators.
* with_dial ensures the label only appears if its dial is visible.

== Multi-function Displays (MFDs) ==
MFDs are customizable panels for extra info (e.g., cargo, manifest, map).

=== MFD Properties ===
{| class="wikitable"
|-
! Key !! Type !! Description
|-
| width, height || int || Size of the MFD panel.
|-
| x, y || int || Position. Negative = left/up from center.
|-
| y_origin || int || 1 = from top.
|}

You can define up to 12 MFDs. Position them where you like (e.g., left/right sides of screen). Players can cycle through MFD modes in-game.

=== Example MFDs ===
<pre>
multi_function_displays = // can have 1 to 12 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;
}
);
</pre>

== Message GUI ==
Controls the in-game message display (e.g., mission messages, alerts).

=== Message GUI Properties ===
{| class="wikitable"
|-
! Key !! Type !! Description
|-
| width, height || int || Panel size.
|-
| x, y || int || Position.
|-
| row_height || int || Height per message line.
|-
| permanent || boolean || If yes, always visible.
|-
| background_automatic || boolean || If yes, background auto-hides when no messages.
|-
| background_rgba || string || Background color + alpha (RGBA).
|-
| text_color || string || Default message text color.
|-
| text_comms_color || string || Comms message color.
|}

=== Example Message GUI ===
<pre>
message_gui = {
width = 252;
height = 140;
x = 128;
y = -60;
row_height = 14;
permanent = no;
background_automatic = yes;
// default background transparent
background_rgba = "0.0 0.05 0.45 0.0";
text_color = "yellowColor";
text_comms_color = "greenColor";
};
</pre>

== Comm Log GUI ==
The communications log (e.g., radio chatter, station messages).

=== Comm Log GUI Properties ===
{| class="wikitable"
|-
! Key !! Type !! Description
|-
| alpha || float/string || Transparency (can be a number or quoted string).
|-
| width, height || int || Panel size.
|-
| x, y || int || Position.
|-
| row_height || int || Line height.
|-
| permanent || boolean || If yes, always visible.
|-
| automatic || boolean || If yes, auto-hides when inactive.
|-
| background_rgba || string || Background color + alpha.
|}

=== Example Comm Log GUI ===
<pre>
comm_log_gui = {
alpha = "0.75";
width = 216;
height = 132;
x = -156;
y = -68;
row_height = 12;
permanent = no;
automatic = yes;
background_rgba = "0.0 0.05 0.45 0.5";
};
</pre>

== Best Practices ==
* '''Key Uniqueness:''' If modifying for an OXP, prefix custom keys (e.g., myoxp_dial_name).
* '''Testing:''' Use in-game debug console and logs to verify HUD changes.
* '''Performance:''' Avoid too many dials or overly complex layouts.
* '''Compatibility:''' Test with multiple screen resolutions and OXPs.
* '''Commenting:''' Annotate your own hud.plist for future reference and sharing.

== Related Pages ==
* [[Oolite Configuration Files]]
* [[OXP HowTo]]
* [[HUD Design]]
* [[Oolite Coordinate System]]
* [[Oolite Color Definitions]]

[[Category:Configuration]]
[[Category:Oolite Documentation]]
[[Category:HUD]]

@@ Line 438: / Line 438: @@
 == Related Pages ==
 * [[Fully Annotated HUD Configuration (hud.plist) File]]
-* [[OXP HowTo]]
+* [[Checklist for testing new hud.plist file]]
 * [[HUD Design]]
-* [[Oolite Coordinate System]]
+* [[Oolite HUD Positioning System]]
 * [[Oolite Colour Specifiers]]

@@ Line 446: / Line 446: @@
 [[Category:Configuration]]
 [[Category:Oolite Documentation]]
 [[Category:HUD]]

HUD Customisation Guide - Revision history

Cholmondely: Tagged as Oolite scripting

Wildeblood: /* Related Pages */

Wildeblood: /* Related Pages */

Wildeblood: /* Related Pages */

Wildeblood: /* Related Pages */

Wildeblood: Page created with analysis by GLM-4.5