HUD

Introduction

Heads Up Display (HUD) elements allow you to show text, images, and other graphical elements.

HUD doesn’t accept user input. For that, you should use a Formspec.

• Basic Interface
• Positioning
• Text Elements
• Image Elements
• Other Elements

Basic Interface

HUD elements are created using a player object. You can get the player object from a username like this:

local player = minetest.get_player_by_name("username")

Once you have the player object, you can create an element:

local idx = player:hud_add({
         hud_elem_type = "text",
         position = {x = 1, y = 0},
         offset = {x=-100, y = 20},
         scale = {x = 100, y = 100},
         text = "My Text"
})

This attributes in the above table and what they do vary depending on the hud_elem_type.
A number is returned by the hud_add function which is needed to identify the HUD element at a later time, if you wanted to change or delete it.

You can change an attribute after creating a HUD element, such as what the text says:

player:hud_change(idx, "text", "New Text")

You can also delete the element:

player:hud_remove(idx)

Positioning

Screens come in different sizes, and HUD elements need to work well on all sizes. You locate an element using a combination of a position and an offset.

The position is a co-ordinate between (0, 0) and (1, 1) which determines where, relative to the screen width and height, the element goes. For example, an element with a position of (0.5, 0.5) will be in the center of the screen.

The offset applies a pixel offset to the position.
An element with a position of (0, 0) and an offset of (10, 10) will end up at the screen co-ordinates (0 * width + 10, 0 * height + 10).

Please note that offset scales to DPI and a user defined factor.

Text Elements

A text element is the simplest form of a HUD element.
Here is our earlier example, but with comments to explain each part:

local idx = player:hud_add({
	hud_elem_type = "text",     -- This is a text element
	position = {x = 1, y = 0},
	offset = {x=-100, y = 20},
	scale = {x = 100, y = 100}, -- Maximum size of text, crops off any out of these bounds
	text = "My Text"            -- The actual text shown
})

Colors

You can apply colors to the text, using the number attribute. Colors are in Hexadecimal form.

local idx = player:hud_add({
	hud_elem_type = "text",
	position = {x = 1, y = 0},
	offset = {x=-100, y = 20},
	scale = {x = 100, y = 100},
	text = "My Text",
	number = 0xFF0000 -- Red
})

Image Elements

Displays an image on the HUD.

The X co-ordinate of the scale attribute is the scale of the image, with 1 being the original texture size. Negative values represent that percentage of the screen it should take; e.g. x=-100 means 100% (width).

Use text to specify the name of the texture.

Other Elements

Have a look at lua_api.txt for a complete list of HUD elements.