Go to file
luk3yx 577b318fa0 Document handling of type field 2023-12-30 11:29:15 +13:00
.github/workflows Fix luacheck 2021-03-28 10:16:28 +13:00
textures Initial commit 2021-03-24 08:30:33 +13:00
.luacheckrc Update .luacheckrc 2023-08-27 08:57:22 +12:00
LICENSE.md Initial commit 2021-03-24 08:30:33 +13:00
README.md Document handling of type field 2023-12-30 11:29:15 +13:00
colorstring_to_number.lua Use modlib's colorspec helpers if installed 2021-03-28 08:27:06 +13:00
init.lua Support new "type" field in HUD definitions 2023-12-30 11:21:05 +13:00
mod.conf Add supported_games to mod.conf 2023-06-20 13:07:19 +12:00

README.md

hud_fs

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): Closes formname. Equivalent to hud_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 as position.
  • 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.
  • 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.
  • 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 to z_index + amount_of_hud_elements.
    • This won't work properly with Minetest clients older than 5.2.0.

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.