Functions which allow the creation of many type of UI meters on screen without creating and injecting XML files.

This page lists functions added by the SUP NVSE Plugin

Bar

A HUD Bar is a UI structure which consists of 4 UI elements - "Meter" (image) "Frame" (Image), "Text" (Text element) and "ImageEx" (Additional image).

Each Bar has a name which is set upon its creation. Bars are tied to the calling mod, which means that different mods can have bars with the same names without conflicts.

Types of Bars:

There are 5 types of Bars:

• Type 0 - Horizontal Bar - Horizontal Meter.

• Type 1 - Vertical Bar - Vertical Meter..Vertical bars will work "upside-down" by default. To make a standart vertical meter you have to rotate elements of the bar by 180 degrees.

• Type 2 - Alpha Bar - Alpha Meter. (Picture is becoming transparent as value is closer to minimal)

• Type 3 - Text Bar - Text Meter - will output like this "Value/MaxValue", like "50/100" or simply "Value"

• Type 4 - Text Bar - Percentage - will output percentage text like this "N%", like "50%"

• Type 5 - Size bar - size meter - will increase\decrease in size according to current percentage.

You can set any DDS textures to "Meter" and "Frame" using HudBarSetTexture.

• For types (0-2), "Meter" is used as an actual Meter(types 0-2).
• For types (3-4), "Text" is used as an actual Meter.
• For any type of Meter, you can add "Frame" and "ImageEx" - they are additional images which can be used as addition to text (type 3-4), or serve as an actual frame for the meter (type 0-2).

Creating a HUD Bar:

Example esp and textures for this tutorial are avaiable for download on SUP NVSE Page.

Each bar has to be created with HudBarCreate command.

HudBarCreate "MyBar" 10 100 0 ; Creating type with Type of 0 at UI screen position - X:10,Y:100.

You've created bar named "MyBar". From now on when you want to tweak it - you will specify this name. At this moment Bar is empty and will not be displayed on-screen.

We've chosen type 0 - horizontal meter. Let's set up UI elements:

HudBarSetTexture "MyBar" 0 "SUPBARS/Line.dds" 1 ; Setting "SUPBARS/Line.dds" texture to Meter.
HudBarSetTexture "MyBar" 1 "SUPBARS/Frame.dds" 1 ; Setting "SUPBARS/Frame.dds" texture to Frame.

Now let's set up indent. Indent is the pixels between left border of the texture and the meter. It is used in SUP Bars to determine where exactly meter is located in texture. This is a must to calculate meter width\height properly. Look at the picture to see how to calculate indent. If your Meter doesn't have space between left border and meter - indent is not needed. Indent is also used for HudBarSetAutoPos which automatically calculates icon positions and it needs to know where exactly element is drawn on the picture. In our case indent is 30 pixels.

HudBarSetIndent "MyBar" 0 30

We've finished setting up textures. Now let's add text to your bar.

HudBarSetTextString "MyBar" 0 "My first Bar" ; Setting text to "My first Bar".

We're almost ready. Now after setting all visual element we can either set up element position using HudBarSetPos or use HudBarSetAutoPos which will try to resolve position automatically.

HudBarSetAutoPos "MyBar"

Now we can finally display the bar.

HudBarShowBar "MyBar" 1

And bar will be visible.

At this moment the only thing that remains is setting up a value. SUP HUD Bars gives you many ways to pass value to the Bar.

1)HudBarSetValuePercentage - Will pass percentage to the bar. For instance:

HudBarSetValuePercentage "MyBar" 0.5 ; Will set Bar value to 50% so Meter will be 50% full.

2)HudBarSetValueFloat - Will pass direct value to bar. This value will be calculated according to <ValueMax> which is set to the bar previously.

HudBarSetValueMax "MyBar" 100
HudBarSetValueFloat "MyBar" 50 ;; Meter will be 50% full which is calculated from formula Value/MaxValue.

3)HudBarSetValueScriptVar - Will "hook" script variable to Bar and Bar will automatically read this script variable accorind to fUpdateTimer(default is 0.1s for each bar).

HudBarSetValueScriptVar "MyBar" MyQuest.fMyVar; Bar will read the value of MyQuest.fMyVar(it can be an int or  a float).

This is useful for "Set and forget" bars. You don't have to set value to bar anymore, you can just set this variable.

4)HudBarSetValueUDF - Will "hook" UDF result to specified Bar.

HudBarSetValueUDF "barName" myUDF ;; Bar will call myUDF according to fUpdateTimer and will display it's result value.

Example UDF:

Scriptname myUDF
float fResult
begin function {}
  set fResult to PlayerRef.GetActorVelocity Z
  SetFunctionValue iResult ; Result of this function is fResult.
end

So in the end we have following script to set up a bar:

HudBarCreate "MyBar" 10 100 0 ; Creating type with Type of 0 at UI screen position - X:10,Y:100.
HudBarSetTexture "MyBar" 0 "SUPBARS/Line.dds" 1 ; Setting "SUPBARS/Line.dds" texture to Meter.
HudBarSetTexture "MyBar" 1 "SUPBARS/Frame.dds" 1 ; Setting "SUPBARS/Frame.dds" texture to Frame.
HudBarSetTextString "MyBar" 0 "My first Bar" ; Setting text to "My first Bar".
HudBarSetAutoPos "MyBar"
HudBarShowBar "MyBar" 1
HudBarSetValuePercentage "MyBar" 0.5 ; Will set Bar value to 50% so Meter will be 50% full.

If you've chosen to set bar value yourself you'll need to call "HudBarSetValuePercentage "MyBar" N" in your script. If you've chosen to use script variable or UDF - Bar will just work.

A couple of example script which set up different types of bars:

HudBarCreate "d" 10 150 0
HudBarSetValueFloat "d" 50
HudBarSetTextString "d" 0 ""My first Bar but BIGGER"
HudBarSetTexture "d" 1 "SUPBARS/Frame.dds" 0
HudBarSetTexture "d" 0 "SUPBARS/Line.dds" 0
HudBarSetIndent "d" 0 45
HudBarSetSize "d" 0 540 18
HudBarSetSize "d" 1 540 18 
HudBarSetZoom "d" 0 -1 
HudBarSetZoom "d" 1 -1 
HudBarSetAutoPos "d"
HudBarSetVisible "d" 1 1
HudBarShowBar "d" 1

This will create identical bar to example above but it will be bigger by 1.5x. Notice that we use HudBarSetSize to set bigger size for Meter and Frame and for this new size to work we set their "Zoom" value to -1. Also notice that Indent is now set to 45 which is(30x1.5).

HudBarCreate "a" 10 200 4
HudBarSetTexture "a" 1 "SUPBARS/Icon1.dds" 1
HudBarSetTextString "a" 1 "My Percentage Bar "
HudBarSetTextString "a" 2 " %"
HudBarSetVisible "a" 1 1
HudBarSetAutoPos "a"
HudBarShowBar "a" 1

This will create and icon and text value with postfix "%".

HudBarCreate "f" 10 400 2
HudBarSetValueFloat "f" 50
HudBarSetTextString "f" 0 "My Alpha bar "
HudBarSetTexture "f" 0 "SUPBARS/Icon1.dds" 1
HudBarSetAutoPos "f"
HudBarSetMeterTrait "f" 0 50
HudBarShowBar "f" 1

This will create "Alpha" type of bar - When value will be 100% - Icon will have alpha 255(default value). When value is 0% - icon will have 50 "alpha"(almost invisible, default is 0 - fully invisible). Inter-alpha will be calculated according to alphaMax and alphaMin difference.

HudBarCreate "g" 10 500 3
HudBarSetTexture "g" 1 "SUPBARS/Icon1.dds" 1
HudBarSetTextString "g" 1 "My custom scripted value bar "
HudBarSetVisible "g" 1 1
HudBarSetAutoPos "g"
HudBarShowBar "g" 1
HudBarSetValueScriptVar "g" myVar 0

Simple bar which would display myVar automatically.

HudBarCreate "e" 10 600 3
HudBarSetTexture "e" 1 "SUPBARS/Icon1.dds" 1
HudBarSetTextString "e" 1 "Player Inventory weight:"
HudBarSetTextString "e" 2 " wg"
HudBarSetVisible "e" 1 1
HudBarSetAutoPos "e"
HudBarSetMeterTrait "e" 2 1
HudBarSetValueMax "e" 210
HudBarShowBar "e" 1

Bar will show "Player Inventory weight:50/210 wg" in the game. 50(Value) and 210(MaxValue) are example values which are set by you in-game.

Managing a HUD Bar:

If you want to temporarily hide the bar - use HudBarShowBar. If you want to permanently destroy the bar - use HudBarDestroy. You should always destroy bars when they are no longer needed. One esp cannot affect HUD Bars from other esp(i.e. set value,destroy), however it can read values of bars from other mod using HudBarGetAllBars and then calling HudBarGetBarTrait with specified mod index.

For testing purposes - when you call any HB commands from console - First HUD Bar with matching name will be chosen.

To debug your HUD bars use HudBarGetDebugInfo and HudBarGetDebugInfoAll commands. All information about created bars during gamesession is written in "SUPNVSE.log" which is located in Fallout root folder. If you are unable to debug why your bar doesn't work by yourself - feel free to contact plugin author, providing clean esp with your bar and Debug log. Before that you need to make sure that your script actually gets executed in-game.

Bar Visibility:

You could tweak HUD Bar visibility conditions with built-in Bar traits using HudBarSetBarTrait.

1)iMenuTypeShow - Show Bar in gamemode\menumode.

2)iDisableControlMovement - 1- Will hide bar when player movement controls is disabled.

3)iDisableWhenSneaking - 1 - Will hide bar when player is sneaking, 2- Will make bar appear ONLY when player is sneaking.

4)iDisableWhenCombat - 1 - Will hide bar when player is in combat, 2- Will make bar appear ONLY in combat.

5)iDisableWhenAiming - Will hide bar when player is aiming(through Ironsight or Skope), 2 - Will make bar appear ONLY when aiming.

6)iDisableWhenWeaponOut - 1 - Will hide bar when player has their weapon out. 2- Will hide bar when player doesn't have weapon out.

7)iDisableWhenItemNotEquipped - Will hide bar when player doesn't have item (Weapon or Armor) equipped. Item is set via HudBarSetItem or HudBarSetFormList.

For instance - you want to make Bar display only when aiming with your custom gun.

HudBarSetBarTrait "BarName" 25 1
HudBarSetItem "BarName" WeapNV9mmPistol
HudBarSetBarTrait "BarName" 24 1

Or you want your bar only work when sneaking and not in combat

HudBarSetBarTrait "BarName" 22 2
HudBarSetBarTrait "BarName" 23 1

You want your bar to be hidden in menumode.

HudBarSetBarTrait "BarName" 0 1

Alternate icon size:

Textures can be different. In some of the actual drawn image is positioned in the middle of it, leaving space between texture frame and actual image.That's why I added option to add "Indent" value for each element. Indent will tell SUP HUD Bars system real size of the image so it can do better calculations with HudBarSetAutoPos function.

For horizontal or vertical meters(type 0-1) indent is mandatory. Setting indent for other UI elements is optional. You can see what size you need to specify for indent by looking at the picture on the right.

Example:

HudBarSetIndent "Name" 1 60

Also you can specify Alternate icon size which is the real icon size in px which is calculated from Indent to the border of actually drawn image. Setting alternate size can be done via HudBarSetSize command.

All Indent and Set size alt commands should be execute before SetAutoPos, otherwise, it won't be able to calculate properly. Depending on what icons you use you might not need setting indent or Alt size at all.