HUD Render (Data Type)

An Object or Array of objects used to define how a resource or cooldown bar should be rendered.

If the specified HUD render is an array of objects, then the HUD render will choose the first object that is allowed to be rendered (its should_render field set to true) and its condition fulfilled (or if its condition field is absent) from top to bottom. The order value of the very first object will also be inherited by the following objects that do not have the order field specified.

Fields#

Field	Type	Default	Description
should_render	Boolean	true	Whether the bar should be visible or not.
sprite_location	Identifier	"origins:textures/gui/resource_bar.png"	The path to the file in the assets which contains what the bar looks like. See the List of sprites for a list of files included by default in the mod.
bar_index	Integer	0	The indexed position of the bar on the sprite to use. Please note that indexes start at 0.
icon_index	Integer	0	The indexed position of the icon on the sprite to use. Please note that indexes start at 0.
condition	Entity Condition Type	optional	If set (and should_render is true), the bar will only display when the entity with the power fulfills this condition.
inverted	Boolean	false	If set to true, inverts the way the hud render process (it’ll look like its value is being decreased).
order	Integer	optional	If specified, this determines the position of the HUD render when being rendered. The higher the order value is, the higher it is on the rendered HUD render stack.
max	Integer OR Expression	optional	The value at which the bar reads full, overriding whatever the power itself would use. Required to draw a bar for a resource that has no max of its own — see below.

Where the bars sit#

Bars stack upward in the right-hand status column, starting on the first free row above whatever the HUD already draws there — the hunger bar, mount health, the air bubbles, and rows other mods add such as a thirst meter. Apoli claims the rows it fills, so a HUD element drawn after it stacks on top rather than through it. Within Apoli’s own bars, a higher order sits higher up.

There is nothing to configure for this in a data pack. It reads the HUD as it is actually drawn, so a mod that hides the hunger bar, keeps the air bubbles up permanently, or adds a row of its own moves the bars without either of you knowing about the other.

On NeoForge every HUD element advances a shared row counter, and Apoli reads and advances the same one. Fabric has no such shared counter, so Apoli measures the column instead: anything drawn on the status-bar row grid inside it counts as a row. An element that draws itself some other way — off the 10-pixel grid, or wider than the column — is not seen, and the offsets below are there for that case.

Client options#

These live in config/apoli-client.json, and on the Apoli Settings screen. They only affect the player who sets them.

Option	Default	What it does
hudAutoStack	true	Position the bars above whatever the HUD already draws. false pins them to the vanilla position — one row above the hunger bar — and leaves the rest to the offsets.
hudOffsetX	0	Moves the bars sideways. Positive is right.
hudOffsetY	0	Moves the bars down. Negative is up.

Examples#

"hud_render": {
    "sprite_location": "apoli:textures/gui/community/spiderkolo/resource_bar_03.png",
    "bar_index": 5
}

This definition shows the resource/cooldown as a white bar with a bone icon.

"hud_render": [
	{
		"sprite_location": "apoli:textures/gui/community/spiderkolo/resource_bar_03.png",
		"bar_index": 3,
		"condition": {
			"type": "apoli:relative_health",
			"comparison": "<=",
			"compare_to": 0.5
		}
	},
	{
		"sprite_location": "apoli:textures/gui/community/spiderkolo/resource_bar_01.png",
		"bar_index": 4
	}
]

This definition will show the resource/cooldown as a white bar with a bone icon if the player has half or less of their max health. Otherwise, the resource/cooldown will be shown as a red bar with a heart icon.

Bars need something to fill up to#

A bar is a fraction: how far the current value has travelled from empty to full. For a apoli:resource that is min to max, and for a cooldown it is the cooldown’s length.

A resource with no max is uncapped, so there is no value that would fill the bar. In that case Apoli does not draw the bar and logs one warning naming the power, rather than showing a bar that is stuck at either end.

Three ways out, depending on what you meant:

• Give the resource a max. The bar then works normally.
• Give the hud_render a max. The resource stays uncapped and the bar fills up to whatever you name, so a score with no ceiling can still show progress toward the next milestone. Because it is an Expression, that milestone can move: "max": "100 * (1 + example:level)".
• Set should_render to false if you did not want a bar at all.

max on the hud_render works for cooldowns too, if you want the bar to fill over something other than the full cooldown.

If min is absent but a maximum is available, the bar treats 0 as empty.

A resource with a size above 1 draws slot 0, the same value everything else reads when no position is given.