HUD Configurations

The following entries are used on the HUD system, but have not been grouped with any particular gauge.

$Load Retail Configuration:

Optional. If yes, any gauge missing from the HUD gauge definitions below will be loaded using the retail defaults.

If no, any missing (default) gauge will prompt an error.

Syntax: Boolean

$Color:

Optional. Sets the default HUD color for all gauges.

Syntax: (Integer Red, Integer Green, Integer Blue)

Valid Values: all values from 0 to 255

$Font:

Optional. Sets the font type to use for the HUD. This can either be a string or a number. A string references a font with a specific name while a number references a font with a specific index in the fonts table. The number option is deprecated and is only there for backwards-compatibility. Use the name if possible.

$Max Directives:

Optional. Sets the default maximum number of directives displayed simultaneously.

Syntax: Integer maximum number of directives

Valid Values: Any positive number

Default Value: 5

$Max Escort Ships:

Optional. Sets the default maximum number of escort ships to be shown in the escort list.

Syntax: Integer

Valid Values: Any positive number

Warning:
Entries more than 16 will cause the list to overflow into the weapons list for resolutions lower than 1024x768.

$Length Unit Multiplier:

Optional. Sets the multiplier to applied to the reported distances. For example, if the multiplier is 0.5, then the distance reported to the player will (or at least should) be 0.5 x actual distance.

Syntax: Float

Valid Values: Any positive number

$Speed Unit Multiplier:

Optional. Analogous to $Length Unit Multiplier, this sets the multiplier to be applied to all speeds reported to the player. For example, if the multiplier is 0.5, the the speed reported to the player will (or at least should) be 0.5 x actual speed.

$Wireframe Targetbox:

2 - Standard with proper lighting (i.e. lit the same as the actual target)

FS2 Open, 3.6.16:

3 - Untextured with full bright lighting (i.e. drawn with a single flat color)

$Targetbox Shader Effect:

FS2 Open, 3.6.16:

Optional. If set, defines a unique ID for a shader effect to be used when rendering a ship for the targeting box. The ID will be passed to the main shader as in #Ship_Effects, but a table entry for the effect is not needed.

Syntax: Integer

Valid Values: Any positive number

$Lock Wireframe Mode:

Optional. If set, prevents targetbox draw method from being changed during the gaming session.

Syntax: Boolean

$Scale Gauges:

FS2 Open, 3.7.2:

Optional. If set, all gauges will use this value as the default for scaling individual gauge sizes (i.e. doesn't affect gauges that use Position:, and doesn't affect the values of Offset:. In addition, if "$Load Retail Configuration:" is true then all unspecified retail gauges will use this value.

If not set, defaults to yes.

Syntax: Boolean

$Force Scaling Above:

FS2 Open, 3.7.4:

Optional. If gauge scaling is disabled, then gauges will be scaled as though the base resolution were this resolution or the real base resolution, whichever is greater.

Use this to disable scaling at lower resolutions while preventing gauges from getting too small at higher resolutions.

To disable this feature, use (-1, -1).

Syntax: (Integer width, Integer height)

$Reticle Style:

Optional. Defines which aiming reticle to use.

Syntax: String

Valid Values:

FS1 - uses reticle1_fs1.ani

FS2 - uses reticle1.ani

#Gauge Config

The following entries define default gauge appearance and behavior. Each gauge has the option of overriding these options.

$Ship:

Deprecated and superceded by $Ships in FSO revision 9208. If defined, the following config data will only be used if the player ship is of the supplied ship class. Can be defined multiple times within a #Gauge config group to allow unique HUD configurations per ship class.

If not defined, all following config data will be applied to all ships.

Syntax: String, ship class name

$Ships:

Optional. Can be used to define a list of ships the hud definition that follows will be applied to. Can be defined multiple times within a #Gauge config group to allow unique HUD configurations per ship class.

If not defined, all following config data will be applied to all ships.

$Color:

$Font:

$Base:

Required. Defines the base resolution for this HUD configuration, upon which other gauge options (such as Position: / Origin: / Offset:) will use as its coordinate system.

Syntax: (Integer width, Integer height)

Valid Values: All supported resolutions (?)

$Scale Gauges:

FS2 Open, 3.7.2:

Optional. If set, will configure gauges Scaling behaviour for gauges in this #Gauge Config section. i.e. overriding the default, or the value specified at the top of the file. Individual gauges can override this setting.

Syntax: Boolean

$Force Scaling Above:

FS2 Open, 3.7.4:

Optional. If gauge scaling is disabled, then gauges will be scaled as though the base resolution were this resolution or the real base resolution, whichever is greater.

Use this to disable scaling at lower resolutions while preventing gauges from getting too small at higher resolutions.

To disable this feature, use (-1, -1).

Syntax: (Integer width, Integer height)

$Required Aspect:

Optional. If set, this configuration will only be loaded for the specified aspect ratios.

Used as a filter when there are multiple $Base: resolutions in the table

Syntax: String

Valid Values:

"Full Screen" (4:3, aspect ratio < 1.5)

"Wide Screen" (16:9, 16:10, or similar, aspect ratio >= 1.5)

$Min:

Optional. Minimum resolution for this config. Any resolution lower than specified will not use this configuration.

Used as a filter when there are multiple $Base: resolutions in the table

Syntax: (Integer width, Integer height)

Valid Values: All supported resolutions (?)

$Max:

Optional. Maximum resolution for this config. Any resolution higher than specified will not use this configuration.

Used as a filter when there are multiple $Base: resolutions in the table

Syntax: (Integer width, Integer height)

Valid Values: All supported resolutions (?)

$Gauges:

Following entries define gauge-specific behavior. For the most part, each gauge has its own overrides that, if not defined, would otherwise use the global values.

Since many gauges have the same configuration options, each gauge entry has a list of valid sub-entries. Unless stated otherwise, these options must be defined in the same order as they are shown, starting from the top and ending at the bottom.

Filename: (needs animation with 4 frames, 3rd is without auto-match-speed enabled, 4th is with... and frames 0 & 1 are not used, done this way because retail fs2 uses the same animation file for the auto speed & auto targeting gauges)

+Objective notify:

Adds a Objective notifier gauge. This gauge alerts the player when receiving a new objective, or when an objective has been completed or failed. Additionally, this gauge alerts the player when entering subspace, and when a Red Alert mission orders are being received (prior to a forced subspace jump).

Gauge Type:

Slew:

Optional. Determines whether or not this gauge is affected by afterburner shaking or similar effects. If set to "true", the gauge will not follow the player's head movements when using TrackIR/padlock. i.e. should be used for gauges like the gunsight/leadsight.

Max Width:

Line Height:

Optional. Determines the distance between line origins. (i.g. for a 12pt Font, there are needs to be at least 12 pixels between the bottom of one line and the next, otherwise the text will overlap each)

Lock Filename:

Filename for the background graphic for this gauge

Syntax: Filename

Needs to be an ani with a least 2 frames. The 1st frame is "no warning", the rest of the frames are cycled through when a warning is active. Frames cycle twice as fast when a lock has been acquired, compared to when a lock is being acquired.