API.md

   1 # Select Item API
   2 With this API you can open the item selection dialog as well as
   3 catch events when players select an item from this dialog.
   4
   5 You can safely optionally depend on this mod, just make sure
   6 to check for the mod's existence first (`minetest.get_modpath`
   7 returns non-`nil` value).
   8
   9 ## Functions
  10 ### `select_item.show_dialog(playername, dialogname, filter)`
  11 Shows an item selection dialog to a player. The player can choose
  12 one item (which triggers a callback) or abort selection
  13 (in which case nothing happens).
  14
  15 By default, this displays almost all items with the exception of
  16 unknown items and `ignore`. This also includes items which players
  17 may normally not be supposed to see, especially those not
  18 found in Creative Inventory. You should set the `filter` argument
  19 to filter out unwanted items.
  20
  21 #### Parameters
  22 * `playername`: Name of player to show dialog to
  23 * `dialogname`: Identifier of the dialog (must not contain “%%”)
  24 * `filter`: Optional filter function to narrow down the visible
  25    items (see below)
  26
  27 Recommended form of `dialogname` is “`<modname>:<name>`”. Almost all
  28 names are allowed, but they must never contain the substring “%%”.
  29 Example: `example:select_my_item`
  30
  31 #### Filter function
  32 The filter function has the function signature `filter(itemstring)`.
  33 This function will be called for each item with the itemstring
  34 given as argument. The function shall return `true` if the item
  35 in question is allowed in the selection dialog and `false` if
  36 it must not appear.
  37
  38 You can also choose one of the following pre-defined filter functions:
  39
  40 * `select_item.filters.creative`: Removes all items with group
  41   `not_in_creative_inventory=1` and/or empty `description`
  42 * `select_item.filters.all`: Does not filter anything. Same as `nil`.
  43
  44 ### `select_item.register_on_select_item(callback)`
  45 Register a call function `callback` to the `select_item` mod.
  46 Whenever a player selects an item or cancels the selection,
  47 `callback` is called.
  48
  49 #### `callback` function
  50 This has the function signature `callback(playername, dialogname, itemstring)`.
  51
  52 * `playername` is the name of the player who selected the item,
  53 * `dialogname` is the dialog identifier of the used item selection dialog
  54 * `itemstring` is the itemstring of the chosen item or `nil` if aborted
  55
  56 Normally, if the player pushes any button, the formspec is closed.
  57 But if you return `false` in this callback, the formspec is *not*
  58
  59 ## Examples
  60 Display all items from Creative inventory to player 1:
  61 ```
  62 select_item.show_dialog("Player 1", "example:creative", select_item.filters.creative)
  63 ```
  64
  65 Display all flammable to Player 1:
  66 ```
  67 select_item.show_dialog("Player 1", "example:flammable", function(itemstring)
  68         if minetest.get_item_group(itemstring), "flammable") >= 1 then
  69                 return true
  70         else
  71                 return false
  72         end
  73 end
  74 ```
  75
  76 Note the different values for `dialogname`.
  77
  78 Adding a selected to the player's inventory after player selected item in the “Creative” dialog
  79 above:
  80 ```
  81 select_item.register_on_select_item(function(playername, dialogname, itemstring)
  82         -- Check for the dialog type you care about. This check should almost always be done
  83         -- to ensure interopability with other mods.
  84         if dialogname == "example:creative" then
  85                 local inv = minetest.get_inventory({type="player" location=playername})
  86                 inv:add_item("main", ItemStack(itemstring))
  87         end
  88 end)
  89 ```