unified_inventory/doc/mod_api.txt

unified_inventory API
=====================

This file provides information about the API of unified_inventory.

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)

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:

	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.

Get a list of recipes for a particular output item:

	unified_inventory.get_recipe_list(output_item)

	Returns a list of tables, each holding a recipe definition, like:
	{
		{
			type = "normal",
			items = { "default:stick", "default:stick", "default:stick", "default:stick" },
			output = "default:wood",
			width = 2
		},
		{
			type = "shapeless",
			items = { "default:tree" },
			output = "default:wood 4",
			width = 0
		},
		...
	}

Get a list of all the output items crafts have been registered for:

	unified_inventory.get_registered_outputs()

	Returns a list of item names, like:
	{
		"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`
			-- Compute 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", {
		type = "image",
		image = "skins_skin_button.png",
		tooltip = "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`
	})



Crafting
--------

The code blocks below document each possible parameter using exemplary values.

Provide information to display custom craft types:

	unified_inventory.register_craft_type("mytype", {
		-- ^ Unique identifier for `register_craft`
		description = "Sample Craft",
		-- ^ Text shown below the crafting arrow
		icon = "dummy.png",
		-- ^ Image shown above the crafting arrow
		width = 3,
		height = 3,
		-- ^ Maximal input dimensions of the recipes
		dynamic_display_size = function(craft)
			-- ^ `craft` is the definition from `register_craft`
			return {
				width = 2,
				height = 3
			}
		end,
		-- ^ Optional callback to change the displayed recipe size
		uses_crafting_grid = true,
	})

Register a non-standard craft recipe:

	unified_inventory.register_craft({
		output = "default:foobar",
		type = "mytype",
		-- ^ Standard craft type or custom (see `register_craft_type`)
		items = {
			{ "default:foo" },
			{ "default:bar" }
		},
		width = 3,
		-- ^ Same as `minetest.register_recipe`
	})


Categories
----------

Register a new category:
	The config table (second argument) is optional, and all its members are optional
	See the unified_inventory.set_category_* functions for more details on the members of the config table

	unified_inventory.register_category("category_name", {
		symbol = "mod_name:item_name" or "texture.png",
		label = "Human Readable Label",
		index = 5,
		items = {
			"mod_name:item_name",
			"another_mod:different_item"
		}
	})

Add / override the symbol for a category:
	The category does not need to exist first
	The symbol can be an item name or a texture image
	If unset this will default to "default:stick"

	unified_inventory.set_category_symbol("category_name", "mod_name:item_name" or "texture.png")

Add / override the human readable label for a category:
	If unset this will default to the category name

	unified_inventory.set_category_label("category_name", "Human Readable Label")

Add / override the sorting index of the category:
	Must be a number, can also be negative (-5) or fractional (2.345)
	This determines the position the category appears in the list of categories
	The "all" meta-category has index -2, the "misc"/"uncategorized" meta-category has index -1, use a negative number smaller than these to make a category appear before these in the list
	By default categories are sorted alphabetically with an index between 0.0101(AA) and 0.2626(ZZ)

	unified_inventory.set_category_index("category_name", 5)

Add a single item to a category:

	unified_inventory.add_category_item("category_name", "mod_name:item_name")

Add multiple items to a category:

	unified_inventory.add_category_items("category_name", {
		"mod_name:item_name",
		"another_mod:different_item"
	})

Remove an item from a category:

	unified_inventory.remove_category_item("category_name", "mod_name:item_name")

Remove a category entirely:

	unified_inventory.remove_category("category_name")

Finding existing items in categories:
	This will find the first category an item exists in
	It should be used for checking if an item is catgorised
	Returns "category_name" or nil

	unified_inventory.find_category("mod_name:item_name")


	This will find all the categories an item exists in
	Returns a number indexed table (list) of category names

	unified_inventory.find_categories("mod_name:item_name")