API.md

   1 API documentation for the HUD bars mod 1.1.0
   2 ============================================
   3
   4 ## Introduction
   5 This API allows you to add, change, hide and unhide custom HUD bars for this mod.
   6
   7 ## Overview
   8 To give you a *very* brief overview over this API, here is the basic workflow on how to add your own custom HUD bar:
   9
  10 * Create images for your HUD bar
  11 * Call `hb.register_hudbar` to make the definition of the HUD bar known to this mod
  12 * Call `hb.init_hudbar` for each player for which you want to use previously defined HUD bar
  13 * Use `hb.change_hudbar` whenever you need to change the values of a HUD bar of a certain player
  14 * If you need it: Use `hb.hide_hudbar` and `hb.unhide_hudbar` to hide or unhide HUD bars of a certain player
  15
  16 ## The basic rules
  17 In order to use this API, you should be aware of a few basic rules in order to understand it:
  18
  19 * A HUD bar is an approximate graphical representation of the ratio of a current value and a maximum value, i.e. current health of 15 and maximum health of 20. A full HUD bar represents 100%, an empty HUD bar represents 0%.
  20 * The current value must always be equal to or smaller then the maximum
  21 * Both current value and maximum must not be smaller than 0
  22 * Both current value and maximum must be real numbers. So no NaN, infinity, etc.
  23 * The HUD bar will be hidden if the maximum equals 0. This is intentional.
  24 * The health and breath HUD bars are hardcoded.
  25
  26 These are soft rules, the HUD bars mod will not enforce all of these.
  27 But this mod has been programmed under the assumption that these rules are followed, for integrity.
  28
  29 ## Adding a HUD bar
  30 To make a new HUD bar known to this mod, you need …
  31
  32 * … an image of size 2×16 for the bar
  33 * … an icon of size 16×16 (optional)
  34 * … to register it with `hb.register_hudbar`
  35
  36 ### Bar image
  37 The image for the bar will be repeated horizontally to denote the “value” of the HUD bar.
  38 It **must** be of size 2×16.
  39 If neccessary, the image will be split vertically in half, and only the left half of the image
  40 is displayed. So the final HUD bar will always be displayed on a per-pixel basis.
  41
  42 The default bar images are single-colored, but you can use other styles as well, for instance,
  43 a vertical gradient.
  44
  45 ### Icon
  46 A 16×16 image shown left of the HUD bar. This is optional.
  47
  48 ### `hb.register_hudbar(identifier, text_color, label, textures, default_start_value, default_start_max, default_start_hidden, format_string)`
  49 This function registers a new custom HUD bar definition to the HUD bars mod, so it can be later used to be displayed, changed, hidden
  50 and unhidden on a per-player basis.
  51 Note this does not yet display the HUD bar.
  52
  53 The HUD bars will be displayed in a “first come, first serve” order. This mod does not allow fow a custom order or a way to set it
  54 manually in a reliable way.
  55
  56
  57 #### Parameters
  58 * `identifier`: A globally unique internal name for the HUD bar, will be used later to refer to it. Please only rely on alphanumeric characters for now. The identifiers “`health`” and “`breath`” are used internally for the built-in health and breath bar, respectively. Please do not use these names.
  59 * `text_color`: A 3-octet number defining the color of the text. The octets denote, in this order red, green and blue and range from `0x00` (complete lack of this component) to `0xFF` (full intensity of this component). Example: `0xFFFFFF` for white.
  60 * `label`: A string which is displayed on the HUD bar itself to describe the HUD bar. Try to keep this string short.
  61 * `textures`: A table with the following fields:
  62  * `bar`: The file name of the bar image (as string).
  63  * `icon`: The file name of the icon, as string. This field can be `nil`, in which case no icon will be used.
  64 * `default_start_value`: If this HUD bar is added to a player, and no initial value is specified, this value will be used as initial current value
  65 * `default_max_value`: If this HUD bar is added to a player, and no initial maximum value is specified, this value will be used as initial maximum value
  66 * `default_start_hidden`: The HUD bar will be initially start hidden by default when added to a player. Use `hb.unhide_hudbar` to unhide it.
  67 * `format_string`: This is optional; You can specify an alternative format string display the final text on the HUD bar. The default format string is “`%s: %d/%d`” (in this order: Label, current value, maximum value). See also the Lua documentation of `string.format`.
  68
  69 #### Return value
  70 Always `nil`.
  71
  72
  73 ## Displaying a HUD bar
  74 After a HUD bar has been registered, they are not yet displayed yet for any player. HUD bars must be
  75 explicitly initialized on a per-player basis.
  76
  77 You probably want to do this in the `minetest.register_on_joinplayer`.
  78
  79 ### `hb.init_hudbar(player, identifier, start_value, start_max, start_hidden)`
  80 This function initialzes and activates a previously registered HUD bar and assigns it to a
  81 certain client/player. This has only to be done once per player and after that, you can change
  82 the values using `hb.change_hudbar`.
  83
  84 However, if `start_hidden` was set to `true` for the HUD bar (in `hb.register_hudbar`), the HUD bar
  85 will initially be hidden, but the HUD elements are still sent to the client. Otherwise,
  86 the HUD bar will be initially be shown to the player.
  87
  88 #### Parameters
  89 * `player`: `ObjectRef` of the player to which the new HUD bar should be displayed to.
  90 * `identifier`: The identifier of the HUD bar type, as specified in `hb.register_hudbar`.
  91 * `start_value`: The initial current value of the HUD bar. This is optional, `default_start_value` of the registration function will be used, if this is `nil`.
  92 * `start_max`: The initial maximum value of the HUD bar. This is optional, `default_start_max` of the registration function will be used, if this is `nil`
  93 * `start_hidden`: Whether the HUD bar is initially hidden. This is optional, `default_start_hidden` of the registration function will be used as default
  94
  95 #### Return value
  96 Always `nil`.
  97
  98
  99
 100 ## Modifying a HUD bar
 101 After a HUD bar has been added, you can change the current and maximum value on a per-player basis.
 102 You use the function `hb.change_hudbar` for this.
 103
 104 ### `hb.change_hudbar(player, identifier, new_value, new_max_value)`
 105 Changes the values of an initialized HUD bar for a certain player. `new_value` and `new_max_value`
 106 can be `nil`; if one of them is `nil`, that means the value is unchanged. If both values
 107 are `nil`, this function is a no-op.
 108 This function also tries minimize the amount of calls to `hud_change` of the Minetest Lua API, and
 109 therefore, network traffic. `hud_change` is only called if it is actually needed, i.e. when the
 110 actual length of the bar or the displayed string changed, so you do not have to worry about it.
 111
 112 #### Parameters
 113 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 114 * `identifier`: The identifier of the HUD bar type to change, as specified in `hb.register_hudbar`.
 115 * `new_value`: The new current value of the HUD bar
 116 * `new_max_value`: The new maximum value of the HUD bar
 117
 118 #### Return value
 119 Always `nil`.
 120
 121
 122 ## Hiding and unhiding a HUD bar
 123 You can also hide custom HUD bars, meaning they will not be displayed for a certain player. You can still
 124 use `hb.change_hudbar` on a hidden HUD bar, the new values will be correctly displayed after the HUD bar
 125 has been unhidden. Both functions will only call `hud_change` if there has been an actual change to avoid
 126 unneccessary traffic.
 127
 128 Note that the hidden state of a HUD bar will *not* be saved by this mod on server shutdown, so you may need
 129 to write your own routines for this or by setting the correct value for `start_hidden` when calling
 130 `hb.init_hudbar`.
 131
 132 ### `hb.hide_hudbar(player, identifier)`
 133 Hides the specified HUD bar from the screen of the specified player.
 134
 135 #### Parameters
 136 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 137 * `identifier`: The identifier of the HUD bar type to hide, as specified in `hb.register_hudbar`.
 138
 139 #### Return value
 140 Always `nil`.
 141
 142
 143 ### `hb.unhide_hudbar(player, identifier)`
 144 Makes a previously hidden HUD bar visible again to a player.
 145
 146 #### Parameters
 147 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 148 * `identifier`: The identifier of the HUD bar type to unhide, as specified in `hb.register_hudbar`.
 149
 150 #### Return value
 151 Always `nil`.
 152
 153
 154 ## Reading HUD bar information
 155 It is also possible to read information about an active HUD bar.
 156
 157 ### `hb.get_hudbar_state(player, identifier)`
 158 Returns the current state of the active player's HUD bar.
 159
 160 #### Parameters
 161 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 162 * `identifier`: The identifier of the HUD bar type to hide, as specified in `hb.register_hudbar`.
 163
 164 #### Return value
 165 A table which holds information on the current state of the HUD bar. Note the table is a deep
 166 copy of the internal HUD bar state, it is *not* a reference; the information hold by the table is
 167 only true for the moment you called this function. The fields of this table are:
 168
 169 * `value`: Current value of HUD bar.
 170 * `max`: Current maximum value of HUD bar.
 171 * `hidden`: Boolean denoting whether the HUD bar is hidden.
 172 * `barlength`: The length of the HUD bar in pixels. This field is meaningless if the HUD bar is currently hidden.
 173 * `text`: The text shown on the HUD bar. This fiels is meaningless if the HUD bar is currently hidden.