minetest_select_item/API.md

Select Item API

With this API you can open the item selection dialog as well as catch events when players select an item from this dialog.

You can safely optionally depend on this mod, just make sure to check for the mod's existence first (minetest.get_modpath returns non-nil value).

Functions

select_item.show_dialog(playername, filter)

Shows an item selection dialog to a player. The player can choose one item (which triggers a callback) or abort selection (in which case nothing happens).

By default, this displays almost all items with the exception of unknown items and ignore. This also includes items which players may normally not be supposed to see, especially those not found in Creative Inventory. You should set the filter argument to filter out unwanted items.

Parameters

• playername: Name of player to show dialog to
• filter: Optional filter function to narrow down the visible items (see below)

Filter function

The filter function has the function signature filter(itemstring). This function will be called for each item with the itemstring given as argument. The function shall return true if the item in question is allowed in the selection dialog and false if it must not appear.

You can also choose one of the following pre-defined filter functions:

• select_item.filters.creative: Removes all items with group not_in_creative_inventory=1 and/or empty description
• select_item.filters.all: Does not filter anything. Same as nil.

select_item.register_on_select_item(callback)

Register a call function callback to the select_item mod. Whenever a player selects an item, callback is called.

callback function

This has the function signature callback(playername, itemstring).

• playername is the name of the player who selected the item,
• itemstring is the itemstring of the chosen item.

Normally, if the player pushes a button, the formspec is closed. But if you return false in this callback, the formspec is not Use this when you run into problems.

Examples

Display all items from Creative inventory to player 1:

select_item.show_dialog("Player 1", select_item.filters.creative)

Display all flammable to Player 1:

select_item.show_dialog("Player 1", function(itemstring)
	if minetest.get_item_group(itemstring), "flammable") >= 1 then
		return true
	else
		return false
	end
end

Adding a selected to the player's inventory:

select_item.register_on_select_item(function(playername, itemstring)
	local inv = minetest.get_inventory({type="player" location=playername})
	inv:add_item("main", ItemStack(itemstring))
end)