runes/api.md

RUNES' API

(as accurate as possible)

1. How it does work

Every rune registered uses the same method to work and access its environment. Runes are first registered using a specific function. Their datas are stored somewhere in a namespace (see below). You can use multiple values to indicate the needed amount of mana, the type of the rune, its texture(s), etc. Then, once a rune is registered (as an item, for minetest), the most important thing is to connect its handler(s). Another specific function is used to this, where you pass as an argument the reference to a function receiving the parameters of the item/node's callback (eg. on_punch, on_dig, on_use, etc). The handler can choose to return "true" in order to manage the use of mana by itself instead of letting the item's code in minetest.registered_items[rune].callback do it.

Functions

runes.register_rune(parameters)

The most important function. This is the function you use to declare your rune and its specifications to minetest itself. It takes one argument, a table. This table can have the following articles : - name is mandatory, it's the rune's name (which will be used to craft its itemstring : runes:rune_name_level)

• desc is the item's description
• img is another table :
  • ["minor"] = texture_file
  • ["medium"] = texture_file
  • ["major"] = texture_file None of these parameters are mandatory. Runes can have 1 or 2 or 3 levels (ok, not implemented yet, but it's coming). You can use a single value like img = texture_file and the texture will be applied for all levels
• type is the type of rune. At the moment, three types are available :
  • "craftitem" will register a craftitem
  • "cube" will register a node
  • "plate" will register a little slab 0.1 node thin
• needed_mana is yet another table with different levels :
  • ["minor"] = value
  • ["medium"] = value
  • ["major"] = value When using this rune at level "major", the ["major"] value of mana will be taken by default if the player has enough mana, or it will be forbidden for him to use the rune if he doesn't have enough mana. You don't have to indicate that parameter and just let the handler manage the mana.

runes.functions.connect(itemname, callback, handler)

This function will connect a registered rune's callback to its handler. It takes three mandatory arguments :

• itemname is the rune's identification name (aka. name for earlier). The same handler is used for every level of a rune, so it has to determine what level he will handle (it's actually passed to it)
• callback is a code identifying the callback. It can be :
  • use for on_use
  • place for after_place_node
  • dig for after_dig_node (actually commented due to bugs in this section)
  • can_dig for can_dig (true logic)
  • punch for on_punch (rather logic too)
• handler is the function handling the callback. See below for details. Do not hesitate to consult lua_api.txt in order to see which callbacks are handled by what type of runes (craftitems, and nodes).

runes.functions.register_amulet(name, desc, maxcount, manadiff)

Amulets are special items able to increase the maximum of mana you can stock. Here are the arguments expected to register an amulet :

• name is its name, used to create its itemstring : 'runes:name_amulet' Don't feel forced to use '_amulet' in an amulet name, it's completly useless.
• desc is the item description.
• maxcount represents the maximum amount of this amulet you can have per stack (aka stack_max, see lua_api.txt for this).
• manadiff is the amount of space you will get to stock more mana in your inventory. A global_step loop is charged with the task of regulary looking into everyone's rune inventory to calculate every player's max_mana. If you loose amulets, your mana_max will dicrease (and mana may be lost with it).

runes.functions.register_detached_inventory(player)

This function is only important for rune's inners. It registers a detached inventory to contain runes. Do not bother using it, there is no actual use of it out of runes' core.

runes.functions.save_detached_inventory(player)

Saves player's rune inventory on hard drive (in minetest.get_worldpath() .. "/runes/" .. player:get_player_name() .. "_rune.inv").

Namespaces

Here are a few namespaces that could be useful :

• runes global namespace, contains everything. Note : When this is merged, do what we have to do.
• runes.datas miscellaneous datas, including tables with parameters transmitted to the registration functions.
• runes.datas.item, the item's datas transmitted to registration
• runes.datas.handlers, handlers of everynodes (the index of this dictionnary is the rune's name)
• runes.datas.amulets, amulet's datas, used for the global_step loop and registration
• runes.functions, multiple useful functions