Oolite Custom HUD Dials

Custom HUD dials allow OXP developers to create dynamic HUD elements that can display information controlled by JavaScript. This is particularly useful for displaying ship-specific information, mission data, or other dynamic content without requiring players to edit their HUD configuration files.

Overview

Custom dials are defined in the hud.plist file using special selectors that begin with drawCustom. These dials reference data sources that are populated using JavaScript via the player.ship.setCustomHUDDial method.

Custom Dial Types

There are five types of custom dials available, each expecting different types of data:

drawCustomBar

Displays a horizontal or vertical bar similar to the standard HUD bars (fuel, shields, etc.).

• Data Source: A number between 0 and 1
• Use Case: Displaying percentage-based values like fuel level, shield strength, etc.
• Example: { selector = "drawCustomBar:"; data_source = "customFuelLevel"; ... }

drawCustomIndicator

Displays an indicator that can move between two positions, similar to the pitch, roll and yaw indicators.

• Data Source: A number between -1 and 1
• Use Case: Showing directional information or relative values
• Example: { selector = "drawCustomIndicator:"; data_source = "customDirection"; ... }

drawCustomLight

Displays a colored light or indicator that can change color based on data.

• Data Source: Any valid color specifier (e.g., "greenColor" or [0.0,0.5,1.0,1.0])
• Use Case: Status indicators that change color based on conditions
• Example: { selector = "drawCustomLight:"; data_source = "customStatusLight"; ... }

drawCustomText

Displays text that can be dynamically updated.

• Data Source: A string
• Use Case: Displaying dynamic text information like ship name, mission status, etc.
• Example: { selector = "drawCustomText:"; data_source = "playerShipName"; ... }

drawCustomImage

Displays an image that can be dynamically changed.

• Data Source: A string, matching the filename of an image in the Images folder
• Use Case: Displaying dynamic icons or images based on game state
• Example: { selector = "drawCustomImage:"; data_source = "customStatusIcon"; ... }

Note: For drawCustomImage, width and height are optional. If set, images will be scaled to that size. If not set, images will appear at their natural size. The image will be centered on the x and y coordinates.

Implementation Example

1. HUD Configuration (hud.plist)

In your HUD file, define the custom dials in the dials section:

dials = (
    // Other dials...
    
    // Custom dial for ship name
    {
        selector = "drawCustomText:";
        data_source = "playerShipName";
        x = 32;
        y = -40;
        y_origin = 1;
        x_origin = -1;
        height = 20;
        width = 12;
        color = "cyanColor";
        alpha = 0.8;
    },
    
    // Custom dial for ship class
    {
        selector = "drawCustomText:";
        data_source = "playerShipClass";
        x = 38;
        y = -44;
        y_origin = 1;
        x_origin = -1;
        height = 8;
        width = 8;
        color = { red = 1.0; green = 0.0; blue = 0.5; alpha = 1.0; };
        alpha = 0.8;
    }
);

2. JavaScript Implementation

In your world script, set the data sources:

this.shipLaunchedFromStation = function () {
    var self = player.ship;
    self.setCustomHUDDial("playerShipName", self.shipUniqueName);
    self.setCustomHUDDial("playerShipClass", self.shipClassName.toUpperCase());
}

This example sets the ship name and class once when the player launches from a station. The values remain constant until the next time the event fires (i.e., after docking and launching again).

Best Practices

1. Use Descriptive Data Source Names: Choose clear, descriptive names for your data sources to avoid conflicts with other OXPs.
2. Initialize Data Sources: Set initial values for your data sources in appropriate event handlers (like shipLaunchedFromStation or startUp).
3. Update Only When Necessary: For values that don't change frequently, update them only when needed rather than in every frame.
4. Consider Performance: Avoid updating custom dials every frame unless absolutely necessary, as this can impact performance.
5. Provide Fallbacks: Consider what should happen if your JavaScript fails to set the data source. You might want to include default values or error handling.

Common Use Cases

1. Ship Information: Display ship name, class, or other ship-specific details
2. Mission Status: Show mission objectives or status messages
3. System Information: Display current system name, government type, etc.
4. Custom Gauges: Create specialized gauges for OXP-specific mechanics
5. Status Indicators: Show status of OXP-specific equipment or features

Related Methods

• player.ship.setCustomHUDDial(key, value): Sets the value of a custom HUD dial

See Also

• HUD Customisation Guide
• Oolite Colour Specifiers
• Oolite_JavaScript_Reference:_PlayerShip#setCustomHUDDial
• File:HUDDataShipName.oxz