Cholmondely: Tagged as Oolite scripting

2025-08-11T15:19:39Z

Tagged as Oolite scripting

Wildeblood: /* See Also */

2025-08-08T08:08:47Z

‎See Also

Wildeblood: Punctuation

2025-08-08T07:55:32Z

Punctuation

Wildeblood: Page created. CORRECTIONS INVITED.

2025-08-08T07:53:12Z

Page created. CORRECTIONS INVITED.

New page

***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 <code>hud.plist</code> file using special selectors that begin with <code>drawCustom</code>. These dials reference data sources that are populated using JavaScript via the <code>player.ship.setCustomHUDDial</code> 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''': <code>{ selector = "drawCustomBar:"; data_source = "customFuelLevel"; ... }</code>

=== 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''': <code>{ selector = "drawCustomIndicator:"; data_source = "customDirection"; ... }</code>

=== 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''': <code>{ selector = "drawCustomLight:"; data_source = "customStatusLight"; ... }</code>

=== 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''': <code>{ selector = "drawCustomText:"; data_source = "playerShipName"; ... }</code>

=== 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''': <code>{ selector = "drawCustomImage:"; data_source = "customStatusIcon"; ... }</code>

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

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

=== 2. JavaScript Implementation ===

In your world script, set the data sources:

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

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

# Use Descriptive Data Source Names: Choose clear, descriptive names for your data sources to avoid conflicts with other OXPs.
# Initialize Data Sources: Set initial values for your data sources in appropriate event handlers (like <code>shipLaunchedFromStation</code> or <code>startUp</code>).
# Update Only When Necessary: For values that don't change frequently, update them only when needed rather than in every frame.
# Consider Performance: Avoid updating custom dials every frame unless absolutely necessary, as this can impact performance.
# 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 ==

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

== Related Methods ==

* <code>player.ship.setCustomHUDDial(key, value)</code>: Sets the value of a custom HUD dial


== See Also ==

* [[HUD Configuration]]
* [[Oolite Colour Specifiers]]
* [[JavaScript Reference]]

[[Category:OXP]]
[[Category:HUD]]
[[Category:JavaScript]]

← Older revision		Revision as of 07:55, 8 August 2025
Line 1:		Line 1:
−	~~*~~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.	+	'''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 ==		== Overview ==

@@ Line 135: / Line 135: @@
 [[Category:OXP]]
 [[Category:HUD]]
 [[Category:JavaScript]]

@@ Line 128: / Line 128: @@
 == See Also ==
-* [[HUD Configuration]]
+* [[HUD Customisation Guide]]
 * [[Oolite Colour Specifiers]]
-* [[JavaScript Reference]]
+* [[Oolite_JavaScript_Reference:_PlayerShip#setCustomHUDDial]]
 [[Category:OXP]]
 [[Category:HUD]]
 [[Category:JavaScript]]

Oolite Custom HUD Dials - Revision history

Cholmondely: Tagged as Oolite scripting

Wildeblood: /* See Also */

Wildeblood: Punctuation

Wildeblood: Page created. CORRECTIONS INVITED.