FlixelBar
View sourceclass
org.flixelgdx.util.FlixelBar
A UI bar for progress, health, stamina, experience, cooldowns, loading, or any value mapped to a numeric range. It extends FlixelSprite so you can add instances to a FlixelSpriteGroup, use sprite transforms (position, scale, rotation, tint, alpha) with the rest of your HUD, and rely on the same camera and lifecycle rules as other sprites.
Rendering: The bar draws custom geometry with a shared white-pixel texture and optional TextureRegion backgrounds and fills. It does not use FlixelSprite.loadGraphic(FileHandle); those entry points are blocked so a bar never accidentally shows a loaded texture on top of the bar UI.
Value and range: You set a logical range with FlixelBar.setRange(float, float) and either FlixelBar.setValue(float) or FlixelBar.setTrack(FloatSupplier) so the fill updates each frame. Use FlixelBar.setMaxSupplier(FloatSupplier) when the maximum changes at runtime (for example leveling systems) without calling setRange manually.
Fill direction: BarFillDirection controls whether the fill grows left-to-right, right-to-left, top-to-bottom, or bottom-to-top.
Smoothing: FlixelBar.setLerp(float) applies frame-rate independent smoothing to the displayed value so the bar can lag slightly behind the target, similar to camera follow smoothing in FlixelCamera.
Appearance: Solid colors, custom empty and filled regions, optional two-color gradients, optional border, and threshold-based fill colors with optional color smoothing when the fill percent drops. Optional overlay text is set with FlixelBar.setText(CharSequence); pass a reused FlixelString for allocation-free live labels (see that method for why).
Screen space: With FlixelBar.setScreenSpace(boolean) true, the bar is offset by the current draw camera scroll so it stays fixed on screen while the world moves.
Constructors
FlixelBar(float, float, float, float)
Creates a bar at the given world position with the given hitbox size. No texture is loaded on the sprite; all visuals come from the bar configuration API.
Parameters:
| Name | Description |
|---|---|
x | Left edge in world space (or screen-anchored space if FlixelBar.setScreenSpace(boolean) is used). |
y | Top edge (Flixel convention: Y down). |
width | Bar width in pixels; used as the drawable width and for gradient resolution hints. |
height | Bar height in pixels. |
Fields
DEFAULT_MIN
DEFAULT_MAX
text
The text object used to display the overlay text.
Methods
loadGraphic(Texture, int, int)
makeGraphic(int, int, Color)
setScreenSpace(boolean)
When true, each draw adds the current Flixel.getDrawCamera() scroll to the bar position so the bar stays fixed on the monitor while the camera moves. When false, the bar uses normal sprite coordinates (moves with the world).
Parameters:
| Name | Description |
|---|---|
screenSpace | true to pin to the viewport in screen space; false for world space. |
Returns: this for chaining.
setFillDirection(BarFillDirection)
Sets which edge of the bar is the fill origin and which axis the fill grows along. Changing this may rebuild the internal gradient texture if a gradient is enabled.
Parameters:
| Name | Description |
|---|---|
direction | One of BarFillDirection; must not be null. |
Returns: this for chaining.
getFillDirection()
setRange(float, float)
Sets the inclusive logical range [min, max] used to map FlixelBar.getValue() to fill percent. If max is less than min, the two are swapped. Current and displayed values are clamped into the new range.
Parameters:
| Name | Description |
|---|---|
min | Lower bound of the value range (for example 0 for health). |
max | Upper bound (for example max HP). Must define a positive span after ordering for a non-zero fill. |
Returns: this for chaining.
getMin()
getMax()
setMaxSupplier(FloatSupplier)
Supplies a new maximum each frame (for example current max HP from a stats object). When non-null, FlixelBar.update(float) calls FlixelBar.setRange(float, float) with the current minimum and the supplied max so the bar stays consistent when max changes without manual range updates.
Parameters:
| Name | Description |
|---|---|
maxSupplier | null to use only FlixelBar.setRange(float, float); otherwise polled each update. |
Returns: this for chaining.
getMaxSupplier()
setValue(float)
Sets the target value when not using FlixelBar.setTrack(FloatSupplier). Ignored while a track supplier is set. If FlixelBar.getLerp() is 1, the displayed value snaps immediately; otherwise the displayed value catches up in FlixelBar.update(float).
Parameters:
| Name | Description |
|---|---|
value | Logical value clamped to the current FlixelBar.setRange(float, float). |
Returns: this for chaining.
getValue()
getDisplayedValue()
setTrack(FloatSupplier)
When non-null, FlixelBar.update(float) sets the target value from FloatSupplier.getAsFloat() each frame (for example player::getHealth). When null, FlixelBar.setValue(float) drives the bar. Primitive supplier avoids boxing.
Parameters:
| Name | Description |
|---|---|
supplier | null for manual values; otherwise the polled value source. |
Returns: this for chaining.
getTrack()
setLerp(float)
Smoothing factor for the value animation: 1 means the displayed fill matches the target immediately; values between 0 and 1 apply exponential smoothing scaled by elapsed time and target framerate (same idea as camera follow lerp in FlixelCamera). This is separate from FlixelBar.setThresholdSmoothing(float, boolean) which only affects threshold colors.
Parameters:
| Name | Description |
|---|---|
lerp | Smoothing amount in [0, 1]; clamped if out of range. |
Returns: this for chaining.
getLerp()
setEmptyColor(Color)
Sets the tint for the empty (background) strip when no FlixelBar.setEmptyGraphic(TextureRegion) is set. Clears any empty graphic region so the bar uses solid color for the background again.
Parameters:
| Name | Description |
|---|---|
c | libGDX color; not null. |
Returns: this for chaining.
setEmptyColor(FlixelColor)
Same as FlixelBar.setEmptyColor(Color) using a FlixelColor object.
Parameters:
| Name | Description |
|---|---|
c | Engine color wrapper; not null. |
Returns: this for chaining.
setFilledColor(Color)
Sets the tint for the filled portion when no FlixelBar.setFilledGraphic(TextureRegion) or gradient is used, unless threshold coloring overrides the fill color. Clears any filled graphic region.
Parameters:
| Name | Description |
|---|---|
c | LibGDX color; not null. |
Returns: this for chaining.
setFilledColor(FlixelColor)
Same as FlixelBar.setFilledColor(Color) using FlixelColor.
Parameters:
| Name | Description |
|---|---|
c | Engine color wrapper; not null. |
Returns: this for chaining.
setEmptyGraphic(TextureRegion)
Uses a texture region for the full empty background stretched to the bar size. Set null to fall back to FlixelBar.setEmptyColor(Color).
Parameters:
| Name | Description |
|---|---|
region | Empty-bar art, or null for solid FlixelBar.setEmptyColor(Color). |
Returns: this for chaining.
setFilledGraphic(TextureRegion)
Uses a texture region for the fill; the bar crops UVs so only a fraction matching the current percent is shown. Set null to use FlixelBar.setFilledColor(Color) or FlixelBar.setGradient(Color, Color).
Parameters:
| Name | Description |
|---|---|
region | Fill art, or null for color or gradient fill. |
Returns: this for chaining.
setGradient(Color, Color)
Enables a two-color linear gradient for the filled portion along the fill axis. Either argument null disables the gradient and restores solid or textured fill. Rebuilds an internal gradient texture when size or FlixelBar.setFillDirection(BarFillDirection) changes.
Use this if you need something like a health bar, where at the start of the bar the color is green, and at the end of the bar the color is red.
Parameters:
| Name | Description |
|---|---|
start | Color at the start of the gradient axis (left or bottom of the fill direction). |
end | Color at the end of the gradient axis. |
Returns: this for chaining.
setGradient(FlixelColor, FlixelColor)
Same as FlixelBar.setGradient(Color, Color) using FlixelColor.
Parameters:
| Name | Description |
|---|---|
start | Start color, or null to help disable the gradient. |
end | End color, or null to help disable the gradient. |
Returns: this for chaining.
setBorder(Color, float)
Draws a simple axis-aligned frame by tinting four rectangles. Pass null color or non-positive thickness to draw no border (or use FlixelBar.clearBorder()).
Parameters:
| Name | Description |
|---|---|
color | Border tint; null clears the border. |
thickness | Width of each border strip in pixels; values below zero are clamped to zero. |
Returns: this for chaining.
clearBorder()
Removes the border drawn by FlixelBar.setBorder(Color, float).
Returns: this for chaining.
setThresholdColors(Color, Color, float)
Convenience for two-stop threshold coloring: from lowColor at lowPercent up to fullColor at 100% fill. Replaces any previous threshold stops from FlixelBar.setThresholdStops(Collection<? extends ThresholdStop>).
Parameters:
| Name | Description |
|---|---|
fullColor | Color used when fill percent is at or above the top stop (full bar). |
lowColor | Color blended in below lowPercent. |
lowPercent | Fill fraction in [0,1] where the low color applies; clamped if out of range. |
Returns: this for chaining.
setThresholdStops(Collection<? extends ThresholdStop>)
Replaces threshold stops from a Collection. Values are copied into an internal Array and sorted by percent. Null entries are skipped.
For List implementations that also implement RandomAccess, copying uses index loops and avoids iterator allocation on this (typically rare) call. For a libGDX Array, use FlixelBar.setThresholdStops(Array<ThresholdStop>).
Parameters:
| Name | Description |
|---|---|
stops | Non-null collection; may be empty to clear thresholds. |
Returns: this for chaining.
setThresholdStops(Array<ThresholdStop>)
Same as FlixelBar.setThresholdStops(Collection<? extends ThresholdStop>) but reads stops from a libGDX Array by index (no iterator on the source).
Parameters:
| Name | Description |
|---|---|
stops | Non-null libGDX array; null entries are skipped. |
Returns: this for chaining.
clearThresholds()
Disables threshold-based fill coloring so the bar uses FlixelBar.setFilledColor(Color) or gradient only.
Returns: this for chaining.
setThresholdSmoothing(float)
Same as FlixelBar.setThresholdSmoothing(float, boolean) with decrease-only smoothing enabled.
Parameters:
| Name | Description |
|---|---|
lerp | Smoothing factor in [0,1] for threshold color transitions. |
Returns: this for chaining.
setThresholdSmoothing(float, boolean)
When lerp is below 1, the displayed threshold color eases toward the target color each frame. If onDecreaseOnly is true, smoothing applies when fill percent drops (typical for damage feedback); if false, color also smooths when the percent increases.
Parameters:
| Name | Description |
|---|---|
lerp | Smoothing amount in [0,1]; clamped if out of range. |
onDecreaseOnly | true to smooth mainly on falling health; false to smooth on any change. |
Returns: this for chaining.
setText(CharSequence)
Sets an optional label rendered on top of the bar. Text is centered on the bar by default; use FlixelBar.setTextOffset(float, float) to nudge it. Pass null to remove overlay text.
The bar keeps the CharSequence you pass and re-reads it each FlixelBar.update(float), so for live text (a score, a percentage) hand it a FlixelString that you mutate in place: the bar picks up the new characters without you allocating a fresh String every frame, compares them to the last label, and only calls FlixelText.setText(CharSequence) when they actually change. For static text, a plain String works just as well.
Parameters:
| Name | Description |
|---|---|
label | null for no overlay; otherwise the label source (often a reused FlixelString). |
Returns: this for chaining.
setTextOffset(float, float)
Pixel offset added to the centered text position after FlixelBar.setText(CharSequence).
Parameters:
| Name | Description |
|---|---|
dx | Horizontal offset in pixels (positive moves right). |
dy | Vertical offset in pixels (positive moves down in Flixel coordinates). |
Returns: this for chaining.
update(float)
Updates sprite animation state, then applies max supplier, value tracking, value smoothing, and refreshes overlay text from the FlixelBar.setText(CharSequence) source when set.
Parameters:
| Name | Description |
|---|---|
elapsed | Seconds since last frame; passed to FlixelSprite.update(float) and smoothing. |
draw(FlixelBatch)
destroy()
ThresholdStop
record
org.flixelgdx.util.FlixelBar.ThresholdStop
One entry in a piecewise-linear threshold color ramp. At fill percent FlixelBar.percent the bar uses FlixelBar.color, interpolating between stops for values in between.
Constructors
ThresholdStop(float, Color)
Parameters:
| Name | Description |
|---|---|
percent | Fill fraction; clamped to [0,1]. |
color | Stop color; copied internally. |
Methods
toString()
hashCode()
equals(Object)
percent()
color()
BarFillDirection
enum
org.flixelgdx.util.FlixelBar.BarFillDirection
Fill direction for FlixelBar.