API.md

   1 # Minimal API for `doc_identifier`
   2 ## Introduction
   3 The tool can identify blocks and players natively, and also handles falling
   4 nodes (`__builtin:falling_node`) and dropped items (`__builtin:item`) on its
   5 own.
   6
   7 However, the identifier can't “identify” (=open the appropriate entry) custom
   8 objects because the mod doesn't know which help entry to open (if there is
   9 any). One example would be the boat object (`boats:boat`) from the boats mod
  10 in Minetest Game.
  11 If the player tries to use the tool on an unknown object, an error message is
  12 shown.
  13
  14 Because of this, this mod provides a minimal API for mods to assign a help
  15 entry to an object type: `doc_identifier.register_object`.
  16
  17 ## `doc.sub.identifier.register_object(object_name, category_id, entry_id)`
  18 Registers the object/entity with the internal name `object_name` to the
  19 entry `entry_id` in the category `category_id`.
  20 It is in the modder's responsibility to make sure that both the category and
  21 entry already exist (use `doc.entry_exists` or depend (optionally or not) on
  22 the respective mods) at the time of the function call, otherwise, stability can
  23 not be guaranteed.
  24
  25 Returns `nil`.
  26
  27 ### Example
  28 From `doc_minetest_game`:
  29
  30     if minetest.get_modpath("doc_identifier") ~= nil then
  31         doc.sub.identifier.register_object("boats:boat", "craftitems", "boats:boat")
  32     end
  33
  34 This enables the tool to be used on the boat object itself. The conditional is
  35 an idiom to check for the existence of this mod.
  36
  37 ## Note on dependencies
  38 If you just need `doc.sub.identifier.register_object` using only an **optional**
  39 dependency for your mod is probably enough.
  40