API.md

   1 API documentation for the HUD bars mod 0.2.0
   2 ============================================
   3
   4 **Warning**: This API is still experimental, everything may change at any time,
   5 and backwards compability will not be ensured until the 1.0.0 release of the
   6 HUD bars mod.
   7
   8 ## Introduction
   9 This API allows you to add, change, hide and unhide custom HUD bars for this mod.
  10
  11 ## Overview
  12 To give you a *very* brief overview over this API, here is the basic workflow on how to add your own custom HUD bar:
  13
  14 * Create images for your HUD bar
  15 * Call `hud.register_hudbar` to make the definition of the HUD bar known to this mod
  16 * Call `hud.hudbars[identifier].add_all` for each player for which you want to use previously defined HUD bar
  17 * Use `hud.change_hudbar` whenever you need to change the values of a HUD bar of a certain player
  18 * If you need it: Use `hud.hide_hudbar` and `hud.unhide_hudbar` to hide or unhide HUD bars of a certain player
  19
  20 ## The basic rules
  21 In order to use this API, you should be aware of a few basic rules in order to understand it:
  22
  23 * 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%.
  24 * The current value must always be equal to or smaller then the maximum
  25 * Both current value and maximum must not be smaller than 0
  26 * Both current value and maximum must be real numbers. So no NaN, infinity, etc.
  27 * The HUD bar will be hidden if the maximum equals 0. This is intentional.
  28 * The health and breath HUD bars are hardcoded and can not be changed with this API.
  29
  30 These are soft rules, the HUD bars mod will not enforce all of these.
  31 But this mod has been programmed under the assumption that these rules are followed, for integrity.
  32
  33 ## Adding a HUD bar
  34 To add a HUD bar, you need …
  35
  36 * … an image of size 2×16 for the bar
  37 * … an icon of size 16×16 (optional)
  38 * … to register it wiith hud.
  39 * … to activate it for each player for which you want the HUD
  40
  41 ### Bar image
  42 The image for the bar will be repeated horizontally to denote the “value” of the HUD bar.
  43 It **must** be of size 2×16.
  44 If neccessary, the image will be split vertically in half, and only the left half of the image
  45 is displayed. So the final HUD bar will always be displayed on a per-pixel basis.
  46
  47 The default bar images are single-colored, but you can use other styles as well, for instance,
  48 a vertical gradient.
  49
  50 ### Icon
  51 A 16×16 image shown left of the HUD bar. This is optional.
  52
  53 ### `hud.register_hudbar(identifier, text_color, label, textures, default_start_value, default_start_max, start_hide, format_string)`
  54 This function adds a new custom HUD
  55 Note this does not yet display the HUD bar.
  56
  57 There is currently no reliable way to force a certain order at which the custom HUD bars will be placed.
  58
  59 #### Parameters
  60 * `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.
  61 * `text_color`: A 3-byte number defining the color of the text. The bytes 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.
  62 * `label`: A string which is displayed on the HUD bar itself to describe the HUD bar. Try to keep this string short.
  63 * `textures`: A table with the following fields:
  64  * `bar`: The file name of the bar image (as string).
  65  * `icon`: The file name of the icon, as string. This field can be `nil`, in which case no icon will be used.
  66 * `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
  67 * `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
  68 * `start_hide`: The HUD bar will be initially start hidden when added to a player. Use `hud.unhide_hudbar` to unhide it.
  69 * `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`.
  70
  71
  72 #### Return value
  73 Always `nil`.
  74
  75
  76 ## Displaying a HUD bar
  77 After a HUD bar has been registered, they are not yet displayed yet for any player. HUD bars must be
  78 explicitly enabled on a per-player basis.
  79
  80 You probably want to do this in the `minetest.register_on_joinplayer`.
  81
  82 ### `hud.hudtables[identifier].add_all(player, start_value, start_max)`
  83 This function activates and displays
  84
  85 However, if `start_hide` was set to `true` for the HUD bar, the HUD bar will initially be hidden, but
  86 the HUD elements are still sent to the client.
  87
  88 You have to replace `identifier` with the identifier string you have specified previously, i.e. use
  89 `hud.hudtables["example"].add_all` if your identifier string is `"example"`. The identifier
  90 specifies the type of HUD bar you want to display.
  91
  92 This is admittedly a rather odd function call and will likely to be changed.
  93
  94 #### Parameters
  95 * `player`: `ObjectRef` of the player to which the new HUD bar should be displayed to.
  96 * `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`.
  97 * `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`
  98
  99 #### Return value
 100 Always `nil`.
 101
 102
 103
 104 ## Modifying a HUD bar
 105 After a HUD bar has been added, you can change the current and maximum value on a per-player basis.
 106 You use the function `hud.change_hudbar` for this.
 107
 108 ### `hud.change_hudbar(player, hudtable, new_value, new_max_value)`
 109 Changes the values of. If
 110
 111 #### Parameters
 112 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 113 * `hudtable`: The table containing the HUD bar definition. Specify as `hud.hudtables[identifier]`, i.e. if your identifier was `example`, then you use `hud.hudtables["example"]`.
 114 * `new_value`: The new current value of the HUD bar
 115 * `new_max_value`: The new maximum value of the HUD bar
 116
 117 #### Return value
 118 Always `nil`.
 119
 120
 121 ## Hiding and unhiding a HUD bar
 122 You can also hide custom HUD bars, meaning they will not be displayed for a certain player. You can still
 123 use `hud.change_hudbar` on a hidden HUD bar, the new values will be correctly displayed after the HUD bar
 124 has been unhidden.
 125
 126 Note that the hidden state of a HUD bar will *not* be saved by this mod on server shutdown, so you may need
 127 to write your own routines for this.
 128
 129 ### `hud.hide_hudbar(player, hudtable)`
 130 Hides the specified HUD bar from the screen of the specified player.
 131
 132 #### Parameters
 133 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 134 * `hudtable`: The table containing the HUD bar definition, see `hud.change_hudbar`.
 135
 136 #### Return value
 137 Always `nil`.
 138
 139
 140 ### `hud.hide_hudbar(player, hudtable)`
 141 Makes a previously hidden HUD bar visible again to a player
 142
 143 #### Parameters
 144 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 145 * `hudtable`: The table containing the HUD bar definition, see `hud.change_hudbar`.
 146
 147 #### Return value
 148 Always `nil`.
 149