minetest_modding_book/chapters/hud.md

title	layout	root
HUD	default	../

Experimental Feature

The HUD feature will probably be rewritten in an upcoming Minetest release.
Be aware that you may need to update your mods if the API is changed.

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:

{% highlight lua %} local player = minetest.get_player_by_name("username") {% endhighlight %}

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

{% highlight lua %} 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" }) {% endhighlight %}

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:

{% highlight lua %} player:hud_change(idx, "text", "New Text") {% endhighlight %}

You can also delete the element:

{% highlight lua %} player:hud_remove(idx) {% endhighlight %}

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:

{% highlight lua %} 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 }) {% endhighlight %}

Colors

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

{% highlight lua %} 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 }) {% endhighlight %}

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]({{ page.root }}lua_api.html#hud-element-types) for a complete list of HUD elements.