Intro to Progressbars

Progressbars allow you to display a value with respect to its minimum and maximum possible values. It is very commonly used for visually depicting hp, cooldown, stamina, or any other stat within a game.

Constructor

The constructor for progressbars is UIProgressBar (note the capital B), and its signature is as follows:

UIProgressBar(_id, _x, _y, _sprite_base, _sprite_progress, _value, _min_value, _max_value, _orientation=UI_ORIENTATION.HORIZONTAL, _relative_to=UI_DEFAULT_ANCHOR_POINT)

• id is the string ID.
• x and y are the offsets with respect to the anchor point. Note that, as directed in the Fundamentals page, your sprites should have its origin point set to top left, to allow for correct positioning in gooey.
• sprite_base is the sprite asset used to render the progressbar background, or "container".
• sprite_progress is the sprite asset used to render the actual progress, or the "container filling".
• value is the starting value for the progressbar.
• min_value and max_value are the minimum and maximum possible values for the depicted quantity.
• orientation is an optional argument that defines whether the progressbar is rendered horizontal, left to right (default) or vertical, down to up. This is defined using the UI_ORIENTATION enum.
• relative_to is the anchor point, as usual from the UI_RELATIVE_TO enum.

About progressbar sprites

Different from other gooey widgets, progressbars in gooey work only with fixed-size sprites. This means you need to have the base sprite and the progress sprite (if the behavior is set to REVEAL - more on that below) to the size you want.

Scaling at runtime

Should you need to scale these sprites at runtime (e.g. to respond to a change in UI scale), you can use the built-in sprite_scale helper function to do so, then assign the resulting scaled sprites to the progressbar.

Nine-sliced sprites and progressbars

Except for the STRETCH behavior for the progress sprite, gooey will not honor nine-sliced sprites. In fact, if you try to set a nine-sliced sprite to a base sprite (or a progress sprite on a behavior other than STRETCH), it will yield an error. Make sure to disable nine-slice for progressbar sprites, unless in the case mentioned.

Progressbar render behaviors

gooey includes three rendering behavior for progressbars. These are stored in the UI_PROGRESSBAR_RENDER_BEHAVIOR enum, and are explained as follows:

Behavior name	Description
REVEAL	The progress sprite will be rendered partially over the base sprite. The proportion that will be rendered corresponds to the value with respect to the progressbar range. This is the default behavior.
REPEAT	The progress sprite is repeatedly rendered as many times as the progressbar value, over the base sprite.
STRETCH	The progress sprite will be stretched (with nine-slice behavior) over the base sprite.

The REVEAL behavior

With this behavior, gooey represents the proportion of the total by proportionally rendering the progress sprite over the base sprite.

When you set UI_ORIENTATION to HORIZONTAL, the progress sprite is revealed left to right; when you set it to VERTICAL, the reveal is used bottom to top.

The base sprite and the progress sprite should be lined up. Many UI packs include both sprites of the same size. However, if this is not the case, you can modify the progress sprite offset using the setSpriteProgressAnchor method (as all offset methods, this expects a struct of the form {x=, y=}.

The REPEAT behavior

This behavior causes gooey to consider the progress sprite a repeatable "sticker" that you can use to depict a stat, such as health (the most ubiquitous example is a heart sprite).

When using this behavior, you can also set another sprite called the remaining progress sprite. This will cause gooey to paint the number of units remaining to reach the max value, next to the progress sprites. For example, if the player's max health is 5 and the current health is 3 (and the progressbar is configured with those values), if you set a remaining progress sprite of an empty gray heart, and a progress sprite of a filled red heart, this will cause gooey to always paint 5 hearts, but the first 3 of those will be filled and the remaining 2 will be empty.

You can also configure a custom unit if you want each "sticker" to represent a value greater than 1. For example, if the player has 100 max hp, you could set the unit to 10. This will cause gooey to render 10 hearts, and calculate the "filled hearts" based on the % of current hp out of that 100 (say the player has 70 hp, then 7 hearts will be filled).

The STRETCH behavior

This behavior works similar to REVEAL; however, the progress sprite will be stretched according to a nine-slice configuration. This allows your progress sprite to have borders (for example) that are always rendered no matter the proportion, or to be a square that is constantly repeated until the current value is reached (this will depend on the nine-slice configuration in the GameMaker IDE).

Example

For the interactive example, I'm using the following sprites for this example:

• Parzival's Hand-drawn UI - This is used for the REVEAL example
• Wenrexa's Free Casual UI - This is used for the STRETCH
• BDragon1727's Basic Pixel Health Bar and Scroll Bar - This is used for the REPEAT example

I want to create one progressbar for each behavior, to compare them. I will create them inside invisible panels to use as HUD. First, I will define three variables:

self.hp = 50;
self.min_hp = 0;
self.max_hp = 100;

The REVEAL code

Then, let's create the REVEAL progressbar first. The images I'm using are a border sprite and a greyscale fill sprite. The globe will "fill" according to the player's hp - this is a vertically oriented progressbar. Those are the same size and are lined up, so I'm just setting the blend value to red to display it as an hp "globe" (akin to the Diablo UI):

The code to create such progressbar is as follows. Note I'm binding the value of the player's current hp to the progressbar, as seen in the Bindings and Pre/Post-render Callbacks tutorial.

var _panel = new UIPanel("RevealPanel", 10, -10, 326, 326, undefined, UI_RELATIVE_TO.BOTTOM_LEFT);
_panel.setMovable(false).setResizable(false);

var _progressbar = new UIProgressBar("RevealProgressbar", 0, 0, spr_Globe_Border, spr_Globe_Fill, self.hp, self.min_hp, self.max_hp,UI_ORIENTATION.VERTICAL,UI_RELATIVE_TO.MIDDLE_CENTER);
_progressbar.setBinding(self,"hp");
_progressbar.setImageProgressBlend(#ff2222);
_panel.add(_progressbar);

The STRETCH code

I also want to create a STRETCH progressbar. Wenrexa's progress sprite has a nice border, so I set up nine-slicing on the sprite so it covers the curves of the "capsule":

After doing this, we can use these directly in the code:

var _panel = new UIPanel("StretchPanel", -10, 10, 332, 56, undefined, UI_RELATIVE_TO.TOP_RIGHT);
_panel.setMovable(false).setResizable(false);

var _progressbar = new UIProgressBar("StretchProgressbar", 0, 0, spr_Progressbar, spr_Progress, self.hp, self.min_hp, self.max_hp,UI_ORIENTATION.HORIZONTAL,UI_RELATIVE_TO.MIDDLE_CENTER);
_progressbar.setBinding(self,"hp");
_progressbar.setRenderProgressBehavior(UI_PROGRESSBAR_RENDER_BEHAVIOR.STRETCH);
_panel.add(_progressbar);

The REPEAT code

Finally, we can work on the REPEAT behavior progressbar. I will use BDragon1727' star icons (empty and full) for this one:

I want to make sure to use the remaining progress setting, to display empty stars. Note that, in this case, we are using the same sprite resource for both base and progress, and we are setting the frame index for each. Finally, we are setting the unit to 10 - this means in total 10 stars will be drawn, and gooey will calculate the % times 10:

var _panel = new UIPanel("RepeatPanel", 10, 10, 180, 18, undefined, UI_RELATIVE_TO.TOP_LEFT);
_panel.setMovable(false).setResizable(false);

var _progressbar = new UIProgressBar("RepeatProgressbar", 0, 0, undefined, spr_Star, self.hp, self.min_hp, self.max_hp,UI_ORIENTATION.HORIZONTAL,UI_RELATIVE_TO.TOP_LEFT);
_progressbar.setBinding(self,"hp");
_progressbar.setRenderProgressBehavior(UI_PROGRESSBAR_RENDER_BEHAVIOR.REPEAT);
_progressbar.setSpriteRemainingProgress(spr_Star).setImageRemainingProgress(0).setImageProgress(1).setProgressRepeatUnit(10);
_panel.add(_progressbar);

The result

This is the resulting interactive example. Use the +Left+ and +Right+ keys to increase or decrease player's health and see the progressbars reflect the change!

Not working?

Remember, if keyboard interaction is not working, make sure to click on the black bar just above the game canvas, to activate the iframe element - otherwise keys are processed by the site itself.