unified_inventory API ===================== This file provides information about the API of unified_inventory and can be viewed in Markdown readers. API revisions within unified_inventory can be checked using: (unified_inventory.version or 1) **Revision history** * Version `1`: Classic formspec layout (no real_coordinates) * Version `2`: Force formspec version 4 (includes real_coordinates) * Version `5` (Y2025): unified_inventory_hide_uncraftable_items * Version `6` (Y2026): Support for multiple craft outputs Misc functions -------------- Grouped by use-case, afterwards sorted alphabetically. * `unified_inventory.is_creative(name)` * Checks whether creative is enabled or the player has `creative` Callbacks --------- Register a callback that will be run whenever a craft is registered via unified_inventory.register_craft. This callback is run before any recipe ingredients checks, hence it is also executed on recipes that are purged after all mods finished loading. unified_inventory.register_on_craft_registered( function (item_name, options) -- item_name (string): name of the output item, equivalent to `ItemStack:get_name()` -- options (table): definition table of crafts registered by `unified_inventory.register_craft` end ) Register a callback that will be run after all mods have loaded and after the unified_inventory mod has initialised all its internal structures: unified_inventory.register_on_initialized(callback) -- The callback is passed no arguments Accessing Data -------------- These methods should be used instead of accessing the unified_inventory data structures directly - this will ensure your code survives any potential restructuring of the mod. * `unified_inventory.get_recipe_list2(output_item)` * Returns a list of registered recipes for the given `output_item` (string, item name). * Output example: --- { { type = "normal", items = { "default:stick", "default:stick", "default:stick", "default:stick" }, output = { ItemStack("default:wood") }, -- ^ Craft outputs. This is always a table of `ItemStack`s. width = 2 }, { type = "shapeless", items = { "default:tree" }, output = { ItemStack("default:wood 4"), ItemStack("mynaturemod:resin 2") }, width = 0 }, ... } --- * `unified_inventory.get_recipe_list(output_item)` * This function is deprecated and will be removed in future releases. * Returns a list of recipes like `unified_inventory.get_recipe_list2` but does not contain recipes with multiple outputs. * The `output` field is of the type `string` (e.g. `default:stick 3`). * `unified_inventory.get_registered_outputs()` * Returns a list of item names that appear in a craft output. * Output example: --- { "default:stone", "default:chest", "default:brick", "doors:door_wood", ... } --- Pages ----- Register a new page: The callback inside this function is called on user input. unified_inventory.register_page("pagename", { get_formspec = function(player) -- ^ `player` is an `ObjectRef` -- Assemble the formspec string here return { formspec = "button[2,2;2,1;mybutton;Press me]", -- ^ Final form of the formspec to display draw_inventory = false, -- default `true` -- ^ Optional. Hides the player's `main` inventory list draw_item_list = false, -- default `true` -- ^ Optional. Hides the item list on the right side formspec_prepend = false, -- default `false` -- ^ Optional. When `false`: Disables the formspec prepend } end, }) Buttons ------- Register a new button for the bottom row: unified_inventory.register_button("skins", { -- ^ Technical name of the button type = "image", -- ^ Supported types: `"image"`. image = "skins_skin_button.png", tooltip = S("Shows some skins"), hide_lite = true -- ^ Button is hidden when following two conditions are met: -- Configuration line `unified_inventory_lite = true` -- Player does not have the privilege `ui_full` condition = function(player) return true end -- ^ Optional callback to check whether the button is enabled for the given -- player (an `ObjectRef`). If used, it must return a boolean. action = function(player) return end -- ^ Optional. Called when the player (an `ObjectRef`) presses the button button. -- By default, the inventory page of the same name will be shown. }) Crafting -------- The code blocks below document each possible parameter using exemplary values. Recipes must be registered before the first server step (`core.register_globalstep`). Provide information to display custom craft types: unified_inventory.register_craft_type("mytype", { -- ^ Unique identifier for `unified_inventory.register_craft` description = S("Sample Craft"), -- ^ Text shown below the crafting arrow icon = "dummy.png", -- ^ Image shown above the crafting arrow width = 3, -- Optional. Default: 3 height = 3, -- Optional. Default: 3 -- ^ Maximal input dimensions of the recipes. dynamic_display_size = function(craft) -- ^ `craft` is the definition from `unified_inventory.register_craft` return { width = 2, height = 3 } end, -- ^ Optional callback to change the displayed recipe size uses_crafting_grid = true, -- Optional. Default: false -- ^ Whether the recipe can be crafted in the player's crafting grid. -- For example, `false` hides the "To craft grid:" buttons. }) Register a non-standard craft recipe: unified_inventory.register_craft({ type = "mytype", -- ^ Craft type. This can be one provided by the engine (e.g. "cooking", "shapeless", ...) -- or custom (see `register_craft_type`). output = "default:foobar", -- == 1 output output = { "default:foobar", "bar:baz 5" }, -- >= 1 output -- ^ Craft outputs. Entries may be an `ItemStack` or an itemstring. items = { "default:foo", "bar:baz", "default:bar", "" }, -- ^ Craft inputs. See also: `core.get_all_craft_recipes` -> `items` width = 2, -- ^ The width of the recipe - in items. Same as `core.register_craft`. }) Categories ---------- * `unified_inventory.register_category(name, def)` * Registers a new category * `name` (string): internal category name * `def` (optional, table): also its fields are optional * Example usage: --- unified_inventory.register_category("category_name", { symbol = source, -- ^ Can be in the format "mod_name:item_name" or "texture.png", label = "Human Readable Label", index = 5, -- ^ Categories are sorted by index. Lower numbers appear before higher ones. -- By default, the name is translated to a number: AA -> 0.0101, ZZ -> 0.2626 --- Predefined category indices: "all" = -2, "uncategorized" = -1 items = { "mod_name:item_name", "another_mod:different_item" } -- ^ List of items within this category }) --- * `unified_inventory.remove_category(name)` * Removes an entire category Modifier functions (to be removed) * `unified_inventory.set_category_symbol(name, source)` * Changes the symbol of the category. The category does not need to exist yet. * `name` (string): internal category name * `source` (string, optional): `"mod_name:item_name"` or `"texture.png"`. Defaults to `"default:stick"` if not specified. * `unified_inventory.set_category_label(name, label)` * Changes the human readable label of the category. * `name` (string): internal category name * `label` (string): human readable label. Defaults to the category name. * `unified_inventory.set_category_index(name, index)` * Changes the sorting index of the category. * `name` (string): internal category name * `index` (numeric): any real number Item management * `unified_inventory.add_category_item(name, itemname)` * Adds a single item to the category * `itemname` (string): self-explanatory * `unified_inventory.add_category_items(name, { itemname1, itemname2, ... }` * Same as above but with multiple items * `unified_inventory.remove_category_item(name, itemname)` * Removes an item from the category * `unified_inventory.find_category(itemname)` * Looks up the first category containing this item * Returns: category name (string) or nil * `unified_inventory.find_categories(itemname)` * Looks up the item name within all registered categories * Returns: array of category names (table)