HUD

This page contains unofficial Lua API documentation and is likely to be outdated or wrong. For the official and up-to-date documentation, refer to lua_api.txt found in your Minetest installation directory under doc.

The Modding Book chapter provides a good guide: https://rubenwardy.com/minetest_modding_book/en/chapters/hud.html

Methods

• hud_add(hud definition) Shows a HUD element to the Player
• hud_change(id, stat, value) Changes a HUD element shown to the Player
• hud_remove(id) Removes a HUD element shown to the Player
• hud_get(id) Gets a HUD element definition
• hud_set_flags(flags) Sets specified HUD flags to true/false
  • flags: (is visible) hotbar, healthbar, crosshair, wielditem
  • pass a table containing a true/false value of each flag to be set or unset

Note: if a flag is nil, the flag is not modified

• hud_get_flags() Returns a table containing the status of HUD flags
• hud_set_hotbar_itemcount(count) Set number of items in builtin hotbar

Note: Count must be between 1 and 23

• hud_set_hotbar_image(texturename) Sets background image for hotbar
• hud_set_hotbar_selected_image(texturename) Sets image for hotbar selected item
• hud_replace_builtin(name, hud definition) Replace the definition of a builtin HUD element

Element Types

Fields

• position Used for all element types. To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from 0 to 1. 0 means left/top, 1 means right/bottom.
• direction The direction in which something is drawn. 0 is left to right, 1 is right to left, 2 is top to bottom, 3 is bottom to top.
• name UNUSED A description of what the HUD element represents
• alignment Specifies how the item will be aligned. It ranges from -1 to 1, with 0 being the center, -1 is moved to the left/up, and 1 is to the right/down. Fractional values can be used.
• offset Specifies a pixel offset from the position. Not scaled to the screen size.

Note: offset WILL adapt to screen DPI as well as the user defined scaling factor!

Types

• image
  • Displays an image on the HUD.
    • scale The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g x=-100 means 100% (width)
    • text The name of the texture that is displayed
    • alignment The alignment of the image
    • offset Offset in pixels from position

• text
  • Displays text on the HUD.
    • scale Defines the bounding rectangle of the text. A value such as {x=100, y=100} should work.Negative values represent that percentage of the screen it should take; e.g. x=-100 means 100% (width)
    • text The text to be displayed in the HUD element.
    • number An integer containing the RGB color value of the text. Specify 0x00FF00 for green text, 0xFF0000 for red and so on.
    • alignment The alignment of the text
    • offset Offset in pixels from position

• statbar
  • Displays a horizontal bar made up of half-images.
    • text The name of the texture that is used.
    • number The number of half-textures that are displayed. If odd, will end with a vertically center-split texture.
    • direction
    • offset Offset in pixels from position
    • size If used will force full-image size to this value (override texture pack image size)

• inventory
  • • text The name of the inventory list to be displayed.
    • number Number of items in the inventory to be displayed.
    • item Position of item that is selected.
    • direction

• waypoint
  • Displays distance to selected world position.
    • name The name of the waypoint.
    • text Distance suffix. Can be blank.
    • number An integer containing the RGB value of the color used to draw the text.
    • world_pos World position of the waypoint.

Examples

player:hud_add({
    hud_elem_type = "statbar",
    position = {x=0,y=1},
    size = "",
    text = "ui_heart_bg.png",
    number = 20,
    alignment = {x=0,y=1},
    offset = {x=0, y=-32},
})
health_hud[name] = player:hud_add({
    hud_elem_type = "statbar",
    position = {x=0,y=1},
    size = "",
    text = "ui_heart_fg.png",
    number = player:get_hp(),
    alignment = {x=0,y=1},
    offset = {x=0, y=-32},
})

This article is missing examples. Feel free to add them.