-- the HUD library provides an easy-to-use interface for create custom
-- item UIs. the idea is that an item <id> will define one or more UI layouts
-- in its _sorcery.hud property, then call lib.hud.open(id, layout, player, ...)
-- when it wishes to open <layout>, usually from its on_use handler. the library
-- will then iterate through the elements in its definition, transmit them to
-- the user, and store the resulting handles in a user context. it will also
-- register any timer callbacks needed to ensure a timely update of the item.
-- if the item is removed from the hotbar, any UI associated with it will be
-- closed.
--
-- each UI element can have a function that is called to set its value. if
-- this is present, it will be called at initialization and at update.
--
-- example:
-- _sorcery = {
-- hud = {
-- powerlevel = {
-- period = 0.1;
-- elements = {
-- {kind = 'text',
-- text = function(ctx)
-- return ctx.stack:get_meta():get_int("power")
-- end;
-- };
-- };
-- };
-- };
-- };