-- 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;
--					};
--				};
--			};
--		};
--	};
