Boss Bars Plus

Current Version: Beta 04c
Status: Hotfixed (Patch 1.5), Pending feedback on stability
Latest file: BossBars+ b04c
Changelog: Quick link

Introduction

Where did the idea for this library originate? It was noted that Blizzards existing boss bar functions were very restricted, not allowing much control over how it was displayed. It didn't feel like enough, so the idea came up to create a boss bar library that is much more flexible than the vanilla one. After a year of development on and off, It is finally complete. I look forward to seeing what the rest of the community can do with the tools that are provided here.

How to use

1) Copy the BossBars+ vX.X folder into your script.

2) BossBars+ and its dependencies are Library files, thus they must be placed at the top of your script.

3a) Open the 'Core' folder to view Galaxy functions available (Advanced)

3b) Open the 'GUI Core Extension' folder to view the GUI functions/actions available

If you downloaded the BossBarPlus_vX.X.SC2Map file, you will find examples of how to make use of it's functions.

Note that all functions have helpful hints to help you if you get stuck.

4) Additional steps

BossBarsPlus is dependent on QuickLib A03c & GXML B02c

If already have a copy of either of these libraries, please remove them to avoid duplicate constants/functions declaration conflicts

5) Run the map to view the available examples to get a brief idea of how to use the library.

Features

Pre-allocated memory for up to 100 boss bars
High level of customizability, entire look can be modified
May be used in both Galaxy and GUI
Supports HP, Shields and Energy
Smoothly animated bars when units are damaged or regenerating
Boss bar label may be set as a string or text (Player names)
Automatic updates when units are set as the boss (Auto-portraits can be disabled)
Optimized to contribute minimal map size increase in large projects
Optimized to contribute minimal processing overhead
Open source, modify at your leisure, but remember to give credit! :)

Function List

Core functions

bbNew:
Creates a new boss bar and returns the boss bar identifier as an integer. This is a function and must be directly called into a variable to work.
bbLastCreated:
Returns the boss bar identifier of the last created boss bar.
bbDestroy:
Destroys a boss bar by its identifier, freeing up allocated memory for the boss bars.
bbMove:
Moves the boss bar to the selected x and y offset according to a chosen anchor.
bbShow:
Shows the boss bar to all players in the player group set by bbSetGroup
bbLock:
Locks the boss bar to the unit it is currently bonded to. This feature is intended for use with revivable heroes that should not have their units replaced
bbAutoPortrait:
Enables/disables auto-portrait detection for specific boss bar. Useful for preventing debug error messages when where the boss does not have a portrait model.
bbSetSize:
Sets the size of the boss bar dialog
bbSetLabel:
Sets the title of the boss bar dialog as a string
bbSetTextLabel:
Sets the title of the boss bar dialog as text. If text styles and/or colors are set, they will override bbSetStyleDC and/or bbSetColorDC.

Note: This function was created specially for setting the boss bar title to player names, which are always detected as text.

bbSetRace:
Sets the race of the boss bar dialog. This is the only function that has the option of selecting which player groups view which race. Three themes are available: c_Terr, c_Prot and c_Zerg
bbSetBoss:
Sets the boss of the boss bar and updates it as necessary
bbSetGroup:
Sets the playergroup that that boss bar is visible to

Advanced functions

Note: All these functions make use of boss bar dialog item constants. The full list of boss bar dialog item constants can be viewed either in the Core folder (c_bb) or the GUI Core Extension/Constants folder

bbShowDC:
Shows/hides the selected boss bar dialog item
bbSetSizeDC:
Sets the size of the selected boss bar dialog item
bbSetPosDC:
Sets the position of the selected boss bar dialog item, with a fixed anchor to the top left of the holding dialog.
bbSetStyleDC:
Sets the text style of any of the label dialog items: c_Label, c_HPLabel, c_SPLabel, c_EPLabel

Note: An image displaying most of the text styles can be exported from the imported assets attached inside the map (F9). Credits goes to whomever created that image (It wasn't me)

bbSetColorDC:
Sets the color of any of the dialog item elements as a hex value with the following format: RRGGBBAA. Where alpha is the opacity of the dialog item.
bbSetImageDC:
Sets the image of the selected boss bar dialog item element. This function works for all the elements except c_Label. c_HPLabel, c_SPLabel, c_EPLabel can have their images changed, however, they are border dialog items and thus only border image types will display correctly.

Any image path should work so long as the image exists. For vanilla assets, a shortcut is available, whereby you can encapsulate any image name between "Assets\ \Textures\ \" and ".dds". (The Asset(string s) function seen in Example 1 in the map)

Note: You can browse for all the available images by opening the console (Alt+ tilde) and typing 'browse'. Look under the assets and textures folder.

bbSetImageTypeDC:
Sets the image type of the selected boss bar dialog item element. This function works for all boss bar elements except labels. This function was implemented to make it easier to use custom boss bar images (Normal image type), as many of Blizzards assets are cut up in strange ways.

Note: The image types referred here are the same as in blizzard natives.

Examples

Examples on library usage can be found in the .SC2map download

Known Caveats

Units with unidentical Unit Type and Model actor references will bug. This will require feedback on the 'broken' units to completely fix, as I would not be able to scan all the data just to find all the differences.
Boss bar needs to be manually refreshed if a unit with no Shield/Energy gains Shield/Energy capacity via a behavior or other means.
GUI code needs some cleanup

Got feedback?/Found a bug?

Feel free to report it to guan.chuan.siong@gmail.com with the subject title Boss Bar Library or make a post in here

[Library] Boss Bars Advanced