Hud gauges.tbl

hud_gauges.tbl (Originally direct paste from FSDoc 2004.12.19, continuing to clean up. Please, somebody who knows more about this table, or just Wiki standards, fix my mistakes!)

IMPORTANT: The information in this section is how hud_gauges.tbl should work. Some things may not work as this guide says they should; in that case, e-mail me (WMCoolmon) or send me a PM via the Forums.

hud_gauges.tbl is used for modifying the elements of the HUD. It is as of now currently unfinished. However, it can still be used to add custom gauges equivelant to something like the wingman status display.

Gauge system overview

• Many of the gauges in Freespace 2 are made up of individual images and text. To allow easy editing, these have been broken up into main gauges and child gauges. Main gauges (aka parent gauges) are a standalone part of the HUD, and may be one gauge or a collection of gauges. Child gauges are gauges that are dependant upon another gauge's position.
• For example, in the center of the screen of Freespace 2, there is a gauge that tells you your target's hud strength and shield status. The text is a child gauge, and the shield quadrant is a child gauge. Both of these together make up the main gauge. So, to move both to the corner, you would simply change the position of the main gauge.
• Finally, all coordinates are measured in pixels from the upper-left corner of the screen. (100 50) is 100 pixels to the right and 50 pixels down; this may seem unnatural at first, but is easy to get used to.

Sections overview

• hud_gauges.tbl contains six sections, the most of any table in Freespace. They are:
  • Miscellaneous variables
    • All miscellaneous variables go at the top of the hud_gauges.tbl file. Currently, the only variable here is the number of escort ships.
  • #Custom Gauges
    • This is where all custom gauges (and their default attributes) are defined.
  • #Main Gauges
    • Used to set the attributes of the main HUD gauges, such as the escort list or the shield status display.
  • #Gauges
    • Used to set individual child gauges' attributes
  • #Ship Main Gauges
    • Same as the #Main Gauges section, except it's used for overrides to the gauges for specific ships
  • #Ship Gauges
    • Again, this is the same as the #Gauges section, except for individual ship overrides

Miscellaneous variables

• All miscellaneous variables are defined at the top of hud_gauges.tbl. The complete list is as follows:

$Max Escort Ships: <integer up to 20>

• Sets the number of escort ships shown in the list. Entries more than 16 will cause the list to overflow into the weapons list under a resolution of 1024x768.

#Custom Gauges

• Custom Gauges are easy to use, and incredibly powerful with the hud-set SEXPs. Initially, they are completely blank; in order to see them you must set their text or image variable in one of the Gauges sections. In order to define a new custom gauge, only the name field is needed:

$Name:

• What the name of the custom gauge will be
• Syntax: <string of up to 32 characters>

• +Default640x:
  • The Default X coordinate of the gauge in 640x480
  • Syntax: <integer>

• +Default640y:
  • The Default Y coordinate in 640x480
  • Syntax: <integer>

• +Default1024x:
  • The Default X coordinate in 1024x768
  • Syntax: <integer>

• +Default1024y:
  • The Default Y coordinate in 1024x768
  • Syntax: <integer>

• +Parent:
  • The parent gauge of the new custom gauge.
  • Syntax: <string of up to 32 characters>

#Main Gauges

• Each list of main gauge definitions can start with one of two strings - $Resolution and $Default. A list started with $Resolution will only be used if the resolution FreeSpace 2 is started in is exactly the same as $Resolution. $Default lists will be loaded regardless of the resolution. Finally, all tags are additive, so you can define some HUD gauges in a resolution tag and others in another and both will be loaded, provided the tags match up to the current resolution.
• In other words, a list starting with $Resolution: (1024 768) will only be used in 1024 768. However, a list starting with $Default: (640 480) will be scaled to any resolution, regardless of what the current resolution is.
• To have gauges be an absolute distance from the upper-left corner of the screen, regardless of resolution, use $Default: (0 0).
• Finally, gauges are loaded from first to last in the listing of resolution-specific and default gauge lists, so if any valid gauge settings are defined more than once, the last setting will be used. This means that $Default lists should always come first, so that resolution-specific settings will override them, rather than the other way around.

IMPORTANT: Only $Default or $Resolution may be defined, NOT both.

$Default:

• Defines what resolution cooridinates are given in and scale them to the current resolution appropriately. If (0 0) is given, coordinates are assumed to be absolute numbers of pixels from the upper-left corner of the screen no matter what resolution is used in fs2_open.
• Syntax: (<integer> <integer>)
  • Tip: Set to (100 100) to set coordinates using percentages.

$Resolution:

• Tells fs2_open that coordinates are for the specified resolution and that resolution only. These will not be used or scaled if the resolution fs2_open is started in is different.
• Syntax: (<integer> <integer>)

$<Gauge name>:

• Where <Gauge name> is the name of the gauge you want to move, moves the upper-left corner of the gauge to the specified position.
• Syntax: (<floating-point> <floating-point>)

• +Size:
  • Defines the size of the gauge; usually not needed, unless the gauge should be centered (see +Percentage below).
  • Syntax: (<integer> <integer>)

• +Percentage:
  • Moves the center of the gauge by the given percent. Added onto the original coordinates given for the gauge.
  • Syntax: (<floating-point> <floating-point>)

• +Image:
  • What image or animation the gauge should use. If set for a custom gauge, this image will always be displayed at the gauge's coordinates unless a SEXP is called.
  • Syntax: <animation filename of up to 32 characters>

• +Text:
  • What text the gauge should use. If set for a custom gauge, the text will always be shown unless a SEXP is used.
  • Syntax: <Text of up to 32 characters, although the limit varies for retail gauges>

• +Color:
  • What color the gauge's image or text should be.
  • Syntax: <red value from 0-255> <green value from 0-255> <blue value from 0-255>

#Ship Main Gauges

Basically the same as the #Main Gauges Section, the Ship Main Gauges adds a new variable - $Ship. This defines which ship the specified changes will apply to. So, if you set $Ship as "GTF Ulysses", whenever the player flies the Ulysses, s/he will see the HUD changes. IMPORTANT: Only $Default or $Resolution may be defined, NOT both.

$Ship:

• Defines what ship class HUD attributes will apply to.
• Syntax: <string of up to 32 characters

$Default:

• Defines what resolution cooridinates are given in and scale them to the current resolution appropriately. If (0 0) is given, coordinates are assumed to be absolute numbers of pixels from the upper-left corner of the screen no matter what resolution is used in fs2_open.
• Syntax: (<integer> <integer>)
  • Tip: Set to (100 100) to set coordinates using percentages.

$Resolution:

• Tells fs2_open that coordinates are for the specified resolution and that resolution only. These will not be used or scaled if the resolution fs2_open is started in is different.
• Syntax: (<integer> <integer>)

$<Gauge name>:

• Where <Gauge name> is the name of the gauge you want to move, moves the upper-left corner of the gauge to the specified position.
• Syntax: (<floating-point> <floating-point>)

• +Size:
  • Defines the size of the gauge; usually not needed, unless the gauge should be centered (see +Percentage below).
  • Syntax: (<integer> <integer>)

• +Percentage:
  • Moves the center of the gauge by the given percent. Added onto the original coordinates given for the gauge.
  • Syntax: (<floating-point> <floating-point>)

• +Image:
  • What image or animation the gauge should use. If set for a custom gauge, this image will always be displayed at the gauge's coordinates unless a SEXP is called.
  • Syntax: <animation filename of up to 32 characters>

• +Text:
  • What text the gauge should use. If set for a custom gauge, the text will always be shown unless a SEXP is used.
  • Syntax: <Text of up to 32 characters, although the limit varies for retail gauges>

• +Color:
  • What color the gauge's image or text should be.
  • Syntax: <red value from 0-255> <green value from 0-255> <blue value from 0-255>