Hud gauges.tbl

This feature requires FreeSpace Open

Revision information.....

FSO Revision: 5211

Note: Please update the version when the page is updated. If your edit had nothing to do with new code entries then please do not edit the version

hud_gauges.tbl is used for modifying the elements of the HUD. It is as of now currently unfinished. Not all gauges can be modified. However, it can still be used to add custom gauges equivalent 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 hull 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 it the standard way to describe screen coordinates and 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.
  • #Custom Gauges
    • This is where all custom gauges (and their default attributes) are defined. This includes any child gauges you want to define.
  • #Main Gauges
    • Used to set the attributes of the Main HUD gauges, such as the escort list or the shield status display or any custom main gauge you have defined.
  • #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.

Table Contents

$Max Escort Ships:

FS2 Open 3.6.10:

• 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.
• Syntax: Integer, from 1 to 20

$Length Unit Multiplier:

FS2 Open 3.6.10:

• Defines the multiplier used for scaling the distances and speeds reported to the player in the game
• Syntax: Float

$Wireframe Targetbox:

FS2 Open, 3.6.12:

• Defines the default draw method for the targetbox
• Syntax: Integer
  • Options:

• 0 - Standard
• 1 - Wireframe
• 2 - Wireframe with textures

$Lock Wireframe Mode:

FS2 Open, 3.6.12:

• If set, prevents targetbox draw method from being changed during the gaming session. This can be used by modders to define an unchangable look for their mod.
• Syntax: Boolean

$Reticle Style:

FS2 Open 3.6.10:

• Selection for display type of the Reticle.
• Syntax: String
  • Options:

• FS1 - uses reticle1_fs1.ani
• FS2 - uses reticle1.ani

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

FS2 Open 3.6.10: *What the name of the custom gauge will be

• Syntax: String, 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. Only main gauges that can already be manipulated in this table or custom gauges that you defined can be used as a parent gauge.
  • Syntax: String, 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.
• 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. These tags are NOT additive.
• 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.
• If any later definition that matches has some settings missing that an earlier definition set, those will be overridden with defaults. The previous settings will NOT be used.

$Default:

FS2 Open 3.6.10:

• Defines what resolution coordinates 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:

FS2 Open 3.6.10:

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

FS2 Open 3.6.10:

• Where <Gauge name> is the name of the gauge (can be a custom gauge) you want to move, moves the upper-left corner of the gauge to the specified position.
• Syntax: ( Float FloatInteger )
• List of known supported retail gauges:

• Player Shield
• Target Shield
• Shield Mini
• Afterburner Energy
• Weapons Energy
• Escort List

• +Size:
  • Defines the size of the gauge; usually not needed, unless the gauge should be centered (see +Percentage below).
  • Size and Percentage must always be specifed together for size to have an effect.
  • Syntax: ( Integer Integer )

• +Percentage:
  • Moves the the gauge by the given percent (100.0 is 100%) of the screen size. If a size was specified (see +Size above) the center will be moved to this position. This is added onto the original coordinates given for the gauge. This means if you specify the coordinates (0 0) and as a percentage (50.0 50.0) the gauge's upper left corner will be positioned on the screen center.
  • If additionally you specified the size, then the gauge's center is positioned on the screen center. If you specified (5 5) as coordinates then the center is moved 5 to the right and 5 below the center of the screen.
  • Size and Percentage must always be specifed together for size to have an effect.
  • Syntax: ( Float Float )

• +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: Filename, 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: String, up to 32 characters, although the limit varies for retail gauges

• +Color:
  • What color the gauge's image or text should be.
  • Syntax: Three Integers, from 0 to 255; red, blue and green respectively

#Gauges

$Default:

FS2 Open 3.6.10:

• Defines what resolution coordinates 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 )

$Resolution:

FS2 Open 3.6.10:

• Defines the resolution for the draw data
  • Syntax: ( Integer Integer )

$Gauge:

FS2 Open 3.6.10:

• Defines the name of gauge
  • Syntax: String

• +Size:
  • Defines the size of the gauge; usually not needed, unless the gauge should be centered (see +Percentage below).
  • Size and Percentage must always be specifed together for size to have an effect.
  • Syntax: ( Integer Integer )

• +Percentage:
  • Moves the the gauge by the given percent (100.0 is 100%) of the screen size. If a size was specified (see +Size above) the center will be moved to this position. This is added onto the original coordinates given for the gauge. This means if you specify the coordinates (0 0) and as a percentage (50.0 50.0) the gauge's upper left corner will be positioned on the screen center.
  • If additionally you specified the size, then the gauge's center is positioned on the screen center. If you specified (5 5) as coordinates then the center is moved 5 to the right and 5 below the center of the screen.
  • Size and Percentage must always be specifed together for size to have an effect.
  • Syntax: ( Float Float )

• +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: Filename, 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: String, up to 32 characters, although the limit varies for retail gauges

• +Color:
  • What color the gauge's image or text should be.
  • Syntax: Three Integers, from 0 to 255; red, blue and green respectively

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

FS2 Open 3.6.10:

• Defines what ship class HUD attributes will apply to.
• Syntax: String, up to 32 characters

$Default:

FS2 Open 3.6.10:

• Defines what resolution coordinates 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:

FS2 Open 3.6.10:

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

FS2 Open 3.6.10:

• 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: ( Float FloatInteger )
• List of known supported retail gauges:

• Player Shield
• Target Shield
• Shield Mini
• Afterburner Energy
• Weapons Energy
• Escort List

• +Size:
  • Defines the size of the gauge; usually not needed, unless the gauge should be centered (see +Percentage below).
  • Size and Percentage must always be specifed together for size to have an effect. Their values cannot be inherited from the default gauges as their effect is calculated on the fly. They have to be specifed for each ship individually,
  • Syntax: ( Integer Integer )

• +Percentage:
  • Moves the the gauge by the given percent (100.0 is 100%) of the screen size. If a size was specified (see +Size above) the center will be moved to this position. This is added onto the original coordinates given for the gauge. This means if you specify the coordinates (0 0) and as a percentage (50.0 50.0) the gauge's upper left corner will be positioned on the screen center.
  • If additionally you specified the size, then the gauge's center is positioned on the screen center. If you specified (5 5) as coordinates then the center is moved 5 to the right and 5 below the center of the screen.
  • Size and Percentage must always be specifed together for size to have an effect. Their values cannot be inherited from the default gauges as their effect is calculated on the fly. They have to be specifed for each ship individually,
  • Syntax: ( Float Float )

• +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: Filename, 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: String, up to 32 characters, although the limit varies for retail gauges

• +Color:
  • What color the gauge's image or text should be.
  • Syntax: Three Integers, from 0 to 255; red, blue and green respectively

#Ship Gauges

$Ship:

FS2 Open 3.6.10:

• Defines the name of the ship
  • Syntax: String

$Default:

FS2 Open 3.6.10:

• Defines what resolution coordinates 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 )

$Resolution:

FS2 Open 3.6.10:

• Defines the resolution for the draw data
  • Syntax: ( Integer Integer )

$Gauge:

FS2 Open 3.6.10:

• Defines the name of gauge
  • Syntax: String

• +Size:
  • Defines the size of the gauge; usually not needed, unless the gauge should be centered (see +Percentage below).
  • Size and Percentage must always be specifed together for size to have an effect. Their values cannot be inherited from the default gauges as their effect is calculated on the fly. They have to be specifed for each ship individually,
  • Syntax: ( Integer Integer )

• +Percentage:
  • Moves the the gauge by the given percent (100.0 is 100%) of the screen size. If a size was specified (see +Size above) the center will be moved to this position. This is added onto the original coordinates given for the gauge. This means if you specify the coordinates (0 0) and as a percentage (50.0 50.0) the gauge's upper left corner will be positioned on the screen center.
  • If additionally you specified the size, then the gauge's center is positioned on the screen center. If you specified (5 5) as coordinates then the center is moved 5 to the right and 5 below the center of the screen.
  • Size and Percentage must always be specifed together for size to have an effect. Their values cannot be inherited from the default gauges as their effect is calculated on the fly. They have to be specifed for each ship individually,
  • Syntax: ( Float Float )

• +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: Filename, 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: String, up to 32 characters, although the limit varies for retail gauges

• +Color:
  • What color the gauge's image or text should be.
  • Syntax: Three Integers, from 0 to 255; red, blue and green respectively

Minimal Example

  $Max Escort Ships: 15

Example

• it runs, but not entirely sure if all of it is working properly; this is a copy-paste from somewhere else... someone please update

  $Max Escort Ships: 15
  
  #Custom Gauges
     $Name: MyParentGauge
        +Default1024x: 100
        +Default1024y: 100
        +Parent: 
     $Name: MyChildGauge
        +Default1024x: 10
        +Default1024y: 5
        +Parent: MyParentGauge
  #End

  #Main Gauges
     $Default:                  (1024 768)
        $Player Shield:         (694 670)
        $Target Shield:         (232 670)
        $MyParentGauge:         (100 100)
     $Resolution:               (1024 768)
        $Escort List:           (865 330)
            +Image: escort1
  #End

  #Gauges
     $Default:                   (1024 768)        
         $Gauge: MyParentGauge
            $MyChildGauge:       (347 219)
                +Image:          child_image
                +Color:          175 230 175
     $Resolution:                (1024 768)
         $Gauge: Escort List
            $Header Text:        (4 1)
                +Text: Monitoring
            $List:               (0 13)
            $Ship:               (0 11)
                +Image:          escort2
            $Last Ship:          (0 11)
                +Image:          escort3
            $Ship Name:          (4 0)
            $Ship Hull:          (116 0)
            $Ship Status:        (-11 0)
  #End

  #Ship Main Gauges
     $Ship: WhateverShip 107A
         $Default:               (1024 768)
            $Player Shield:      (694 670)
            $Target Shield:      (232 670)
            $MyParentGauge:      (100 100)
     $Ship: WhateverShip 105B
         $Default:               (1024 768)
            $Player Shield:      (694 623)
            $Target Shield:      (211 670)
            $MyParentGauge:      (100 150)
  #End

  #Ship Gauges
     $Ship: WhateverShip 107A
         $Default:               (1024 768)        
            $Gauge: MyParentGauge
                $MyChildGauge:   (347 219)
                    +Image:      child_image
                    +Color:      175 230 175
     $Ship: WhateverShip 105B
         $Default:               (1024 768)        
            $Gauge: MyParentGauge
                $MyChildGauge:   (347 219)
                    +Image:      child_image
                    +Color:      175 230 175
  #End