Add support for statbar “off state” icons (#9462)

This adds support for optional “off state” icons for statbars. “off state icons” can be used to denote the lack of something, like missing hearts or bubbles.

Add "off state" textures to the builtin statbars.

Co-authored-by: SmallJoker <mk939@ymail.com>

2 files changed, 15 insertions, 5 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 961e1ff37..4078e21a1 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1289,9 +1289,9 @@ To account for differing resolutions, the position coordinates are the
 percentage of the screen, ranging in value from `0` to `1`.
 
 The name field is not yet used, but should contain a description of what the
-HUD element represents. The direction field is the direction in which something
-is drawn.
+HUD element represents.
 
+The `direction` field is the direction in which something is drawn.
 `0` draws from left to right, `1` draws from right to left, `2` draws from
 top to bottom, and `3` draws from bottom to top.
 
@@ -1355,12 +1355,16 @@ Displays text on the HUD.
 
 ### `statbar`
 
-Displays a horizontal bar made up of half-images.
+Displays a horizontal bar made up of half-images with an optional background.
 
-* `text`: The name of the texture that is used.
+* `text`: The name of the texture to use.
+* `text2`: Optional texture name to enable a background / "off state"
+  texture (useful to visualize the maximal value). Both textures
+  must have the same size.
 * `number`: The number of half-textures that are displayed.
   If odd, will end with a vertically center-split texture.
-* `direction`
+* `item`: Same as `number` but for the "off state" texture
+* `direction`: To which direction the images will extend to
 * `offset`: offset in pixels from position.
 * `size`: If used, will force full-image size to this value (override texture
   pack image size)
@@ -7772,6 +7776,8 @@ Used by `Player:hud_add`. Returned by `Player:hud_get`.
 
         text = "<text>",
 
+        text2 = "<text>",
+
         number = 2,
 
         item = 3,
diff --git a/doc/texture_packs.txt b/doc/texture_packs.txt
index 4e7bc93c4..94151f1a4 100644
--- a/doc/texture_packs.txt
+++ b/doc/texture_packs.txt
@@ -64,6 +64,8 @@ by texture packs. All existing fallback textures can be found in the directory
 
 * `bubble.png`: the bubble texture when the player is drowning
                 (default size: 12×12)
+* `bubble_gone.png`: like `bubble.png`, but denotes lack of breath
+                     (transparent by default, same size as bubble.png)
 
 * `crack_anylength.png`: node overlay texture when digging
 
@@ -76,6 +78,8 @@ by texture packs. All existing fallback textures can be found in the directory
 
 * `heart.png`: used to display the health points of the player
                (default size: 12×12)
+* `heart_gone.png`: like `heart.png`, but denotes lack of health points
+                    (transparent by default, same size as heart.png)
 
 * `minimap_mask_round.png`: round minimap mask, white gets replaced by the map
 * `minimap_mask_square.png`: mask used for the square minimap