A Minetest mod library to make handling formspec-like HUDs easier. Depends on formspec_ast.
API
hud_fs.show_hud(player, formname, formspec)
: Displays or updates a HUD with the specified formname and formspec.formspec
can also be a formspec_ast tree for more advanced usage.
hud_fs.close_hud(player, formname)
: Closesformname
. Equivalent tohud_fs.show_hud(player, formname, "")
.
The player parameter in the above function can either be a player object or a player name.
If you just want to manage HUDs, that's all you need to know! Don't worry
about trying to get incremental updates or tracking HUD IDs, hud_fs
does that
for you behind-the-scenes.
Supported formspec features
All formspecs are assumed to be version 3 and the formspec_version
element
(if any) is ignored.
The following elements are supported:
size
- While there is no background for the HUD, this does change where the co-ordinates start from.
position
,anchor
- You need to use these to set the position of the HUD!
- See the Minetest API documentation for more info.
- You probably want
anchor
to have the same value asposition
.
padding
- When set, hud_fs attempts to calculate the form size in the same way that the client does.
- Use
padding[0.05,0.05]
to make the HUD use roughly the same scaling as formspecs.
container
label
- Because of HUD limitations,
minetest.colorize()
only works at the start of the label.
- Because of HUD limitations,
image
box
textarea
- If the name is non-empty a background is drawn behind the text.
- Text will overflow vertically outside the specified height.
item_image
- Only works with some nodes, should work with all craftitems.
button
,button_exit
,image_button
,image_button_exit
,item_image_button
- Buttons become a grey box with a label in the middle.
- The label has the same limitations as the
label
element. - The
noclip
option is ignored. - Item image buttons have the same limitations as
item_image
.
style
All valid formspec elements not listed above are ignored.
Using normal HUD element definitions
If you want features can't be implemented using formspecs, you can use a list
of HUD elements (the tables sent to hud_add
) instead. Example:
hud_fs.show_hud(player, "waypoints", {
{
type = "waypoint",
world_pos = {x = 0, y = 0, z = 0},
name = "Waypoint 1"
},
{
type = "waypoint",
world_pos = {x = 1, y = 2, z = 3},
name = "Waypoint 2"
}
})
The "type" field shown above is introduced in MT 5.9-dev. hud_fs will automatically convert this to hud_elem_type on older servers.
Advanced API
hud_fs.set_scale(formname, scale)
: Sets the scale of the HUD.- All future HUDs shown with
formname
will use this scale instead of the default (64, subject to change). - The scale is the amount of pixels per co-ordinate. For example, a 1x1 image will have a size of 10x10 pixels if the scale is set to 10.
- This is ignored on MT 5.7.0+ clients if a
padding[]
element exists in the formspec.
- All future HUDs shown with
hud_fs.set_z_index(formname, z_index)
: Sets the base Z-Index of the HUD.- All future HUDs shown with
formname
will use this z-index instead of the default (0). - The HUD will use z-index values from
z_index
toz_index + amount_of_hud_elements
. - This won't work properly with Minetest clients older than 5.2.0.
- All future HUDs shown with
FAQ(?)
Why not implement this mod in the Minetest engine?
This mod (or anything similar) won't be implemented, a proposal to do so was rejected in https://github.com/minetest/minetest/issues/10135.
Why formspecs?
- There isn't a complicated new API to learn, if you write MT mods you probably know how to use formspecs already.
- I have a web-based formspec editor which can now be used to design HUDs for use with this mod.
- You don't need any knowledge of Minetest's HUD API to use this mod.
- As this mod parses formspecs server-side, the lack of differential updates is for the most part a non-issue.
But I hate formspecs and don't want to touch them
The API provided by this mod accepts a list of HUD elements in place of a formspec. Alternatively, there are other HUD library mods around such as hudlib and panel_lib.
Performance
If this mod becomes a performance bottleneck you can try the following things:
- Move any formspec elements that are added or removed frequently to the end
of the formspec. This will allow them to be removed without touching other
elements internally.
- This mod is currently inefficient at updating HUDs when elements are added or removed when they aren't at the end of the formspec.
- Using a formspec_ast tree instead of a formspec in show_hud.
formspec_ast
is relatively slow at parsing formspecs at the time of writing. - Don't call show_hud when you already know that nothing has changed. Doing so will waste time parsing the formspec, converting it to HUD elements, then figuring out what has changed.