HUD Customisation Guide

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 Resources/Config/. 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.

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:

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

Dials

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

Common Dial Properties

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

{   // 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";
},

Only appears if missile targeting scanner is installed. Changes color based on target/wormhole.

Scanner

{   // 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);
},

The main radar display. Positioned at (x=0, y=68) from bottom-center. Red by default.

Flight Control Bars

{   // 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;
},

Horizontal/vertical flight indicators. Positioned at right side of screen. draw_surround adds a border.

Status Gauges

{   // 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;
},

Vertical/horizontal status bars. draw_surround adds a border. labelled includes a text label.

Specialty Indicators

{   // 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;
},

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

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

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:";
    },
);

• "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

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

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

Message GUI

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

Message GUI Properties

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

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

Comm Log GUI

The communications log (e.g., radio chatter, station messages).

Comm Log GUI Properties

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

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

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

• Fully Annotated HUD Configuration (hud.plist) File
• OXP HowTo
• HUD Design
• Oolite Coordinate System
• Oolite Color Definitions