game_api.txt

   1 Minetest Game API
   2 =================
   3 GitHub Repo: https://github.com/minetest/minetest_game
   4
   5 Introduction
   6 ------------
   7
   8 The Minetest Game subgame offers multiple new possibilities in addition to the Minetest engine's built-in API,
   9 allowing you to add new plants to farming mod, buckets for new liquids, new stairs and custom panes.
  10 For information on the Minetest API, visit https://github.com/minetest/minetest/blob/master/doc/lua_api.txt
  11 Please note:
  12
  13  * [XYZ] refers to a section the Minetest API
  14  * [#ABC] refers to a section in this document
  15  * [pos] refers to a position table `{x = -5, y = 0, z = 200}`
  16
  17 Bucket API
  18 ----------
  19
  20 The bucket API allows registering new types of buckets for non-default liquids.
  21
  22         bucket.register_liquid(
  23                 "default:lava_source",   -- name of the source node
  24                 "default:lava_flowing",  -- name of the flowing node
  25                 "bucket:bucket_lava",    -- name of the new bucket item (or nil if liquid is not takeable)
  26                 "bucket_lava.png",       -- texture of the new bucket item (ignored if itemname == nil)
  27                 "Lava Bucket",           -- text description of the bucket item
  28                 {lava_bucket = 1},       -- groups of the bucket item, OPTIONAL
  29                 false                    -- force-renew, OPTIONAL. Force the liquid source to renew if it has
  30                                          -- a source neighbour, even if defined as 'liquid_renewable = false'.
  31                                          -- Needed to avoid creating holes in sloping rivers.
  32         )
  33
  34 The filled bucket item is returned to the player that uses an empty bucket pointing to the given liquid source.
  35 When punching with an empty bucket pointing to an entity or a non-liquid node, the on_punch of the entity or node will be triggered.
  36
  37 Beds API
  38 --------
  39
  40         beds.register_bed(
  41                 "beds:bed",    -- Bed name
  42                 def            -- See [#Bed definition]
  43         )
  44
  45  * `beds.read_spawns() `   Returns a table containing players respawn positions
  46  * `beds.kick_players()`  Forces all players to leave bed
  47  * `beds.skip_night()`   Sets world time to morning and saves respawn position of all players currently sleeping
  48
  49 ### Bed definition
  50
  51         {
  52                 description = "Simple Bed",
  53                 inventory_image = "beds_bed.png",
  54                 wield_image = "beds_bed.png",
  55                 tiles = {
  56                         bottom = {'Tile definition'}, -- the tiles of the bottom part of the bed.
  57                         top = {Tile definition} -- the tiles of the bottom part of the bed.
  58                 },
  59                 nodebox = {
  60                         bottom = 'regular nodebox',     -- bottom part of bed (see [Node boxes])
  61                         top = 'regular nodebox',        -- top part of bed (see [Node boxes])
  62                 },
  63                 selectionbox = 'regular nodebox',  -- for both nodeboxes (see [Node boxes])
  64                 recipe = {                                         -- Craft recipe
  65                         {"group:wool", "group:wool", "group:wool"},
  66                         {"group:wood", "group:wood", "group:wood"}
  67                 }
  68         }
  69
  70 Creative API
  71 ------------
  72
  73 Use `creative.register_tab(name, title, items)` to add a tab with filtered items.
  74 For example,
  75
  76         creative.register_tab("tools", "Tools", minetest.registered_tools)
  77
  78 is used to show all tools. Name is used in the sfinv page name, title is the
  79 human readable title.
  80
  81 `is_enabled_for` is used to check whether a player is in creative mode:
  82
  83     creative.is_enabled_for(name)
  84
  85 Override this to allow per-player game modes.
  86
  87 The contents of `creative.formspec_add` is appended to every creative inventory
  88 page. Mods can use it to add additional formspec elements onto the default
  89 creative inventory formspec to be drawn after each update.
  90
  91 Doors API
  92 ---------
  93
  94 The doors mod allows modders to register custom doors and trapdoors.
  95
  96 `doors.register_door(name, def)`
  97
  98  * Registers new door
  99  * `name` Name for door
 100  * `def`  See [#Door definition]
 101
 102 `doors.register_trapdoor(name, def)`
 103
 104  * Registers new trapdoor
 105  * `name` Name for trapdoor
 106  * `def`  See [#Trapdoor definition]
 107
 108 `doors.register_fencegate(name, def)`
 109
 110  * Registers new fence gate
 111  * `name` Name for fence gate
 112  * `def`  See [#Fence gate definition]
 113
 114 `doors.get(pos)`
 115
 116  * `pos` A position as a table, e.g `{x = 1, y = 1, z = 1}`
 117  * Returns an ObjectRef to a door, or nil if the position does not contain a door
 118
 119     ### Methods
 120
 121         :open(player)   -- Open the door object, returns if door was opened
 122         :close(player)  -- Close the door object, returns if door was closed
 123         :toggle(player) -- Toggle the door state, returns if state was toggled
 124         :state()        -- returns the door state, true = open, false = closed
 125
 126     the "player" parameter can be omitted in all methods. If passed then
 127     the usual permission checks will be performed to make sure the player
 128     has the permissions needed to open this door. If omitted then no
 129     permission checks are performed.
 130
 131 ### Door definition
 132
 133         description = "Door description",
 134         inventory_image = "mod_door_inv.png",
 135         groups = {choppy = 2},
 136         tiles = {"mod_door.png"}, -- UV map.
 137         recipe = craftrecipe,
 138         sounds = default.node_sound_wood_defaults(), -- optional
 139         sound_open = sound play for open door, -- optional
 140         sound_close = sound play for close door, -- optional
 141         protected = false, -- If true, only placer can open the door (locked for others)
 142
 143 ### Trapdoor definition
 144
 145         description = "Trapdoor description",
 146         inventory_image = "mod_trapdoor_inv.png",
 147         groups = {choppy = 2},
 148         tile_front = "doors_trapdoor.png", -- the texture for the front and back of the trapdoor
 149         tile_side = "doors_trapdoor_side.png", -- the tiles of the four side parts of the trapdoor
 150         sounds = default.node_sound_wood_defaults(), -- optional
 151         sound_open = sound play for open door, -- optional
 152         sound_close = sound play for close door, -- optional
 153         protected = false, -- If true, only placer can open the door (locked for others)
 154
 155 ### Fence gate definition
 156
 157         description = "Wooden Fence Gate",
 158         texture = "default_wood.png", -- `backface_culling` will automatically be
 159                                       -- set to `true` if not specified.
 160         material = "default:wood",
 161         groups = {choppy = 2, oddly_breakable_by_hand = 2, flammable = 2},
 162         sounds = default.node_sound_wood_defaults(), -- optional
 163
 164 Fence API
 165 ---------
 166
 167 Allows creation of new fences with "fencelike" drawtype.
 168
 169 `default.register_fence(name, item definition)`
 170
 171  Registers a new fence. Custom fields texture and material are required, as
 172  are name and description. The rest is optional. You can pass most normal
 173  nodedef fields here except drawtype. The fence group will always be added
 174  for this node.
 175
 176 ### fence definition
 177
 178         name = "default:fence_wood",
 179         description = "Wooden Fence",
 180         texture = "default_wood.png",
 181         material = "default:wood",
 182         groups = {choppy = 2, oddly_breakable_by_hand = 2, flammable = 2},
 183         sounds = default.node_sound_wood_defaults(),
 184
 185 Walls API
 186 ---------
 187
 188 The walls API allows easy addition of stone auto-connecting wall nodes.
 189
 190 walls.register(name, desc, texture, mat, sounds)
 191 ^ name = "walls:stone_wall". Node name.
 192 ^ desc = "A Stone wall"
 193 ^ texture = "default_stone.png"
 194 ^ mat = "default:stone". Used to auto-generate crafting recipe.
 195 ^ sounds = sounds: see [#Default sounds]
 196
 197 Farming API
 198 -----------
 199
 200 The farming API allows you to easily register plants and hoes.
 201
 202 `farming.register_hoe(name, hoe definition)`
 203  * Register a new hoe, see [#hoe definition]
 204
 205 `farming.register_plant(name, Plant definition)`
 206  * Register a new growing plant, see [#Plant definition]
 207
 208 `farming.registered_plants[name] = definition`
 209  * Table of registered plants, indexed by plant name
 210
 211 ### Hoe Definition
 212
 213
 214         {
 215                 description = "",                      -- Description for tooltip
 216                 inventory_image = "unknown_item.png",  -- Image to be used as wield- and inventory image
 217                 max_uses = 30,                         -- Uses until destroyed
 218                 material = "",                         -- Material for recipes
 219                 recipe = {                             -- Craft recipe, if material isn't used
 220                         {"air", "air", "air"},
 221                         {"", "group:stick"},
 222                         {"", "group:stick"},
 223                 }
 224         }
 225
 226 ### Plant definition
 227
 228         {
 229                 description = "",                      -- Description of seed item
 230                 inventory_image = "unknown_item.png",  -- Image to be used as seed's wield- and inventory image
 231                 steps = 8,                             -- How many steps the plant has to grow, until it can be harvested
 232                 -- ^ Always provide a plant texture for each step, format: modname_plantname_i.png (i = stepnumber)
 233                 minlight = 13,                         -- Minimum light to grow
 234                 maxlight = default.LIGHT_MAX           -- Maximum light to grow
 235         }
 236
 237 Fire API
 238 --------
 239
 240 New node def property:
 241
 242 `on_burn(pos)`
 243
 244  * Called when fire attempts to remove a burning node.
 245  * `pos` Position of the burning node.
 246
 247  `on_ignite(pos, igniter)`
 248
 249   * Called when Flint and steel (or a mod defined ignitor) is used on a node.
 250     Defining it may prevent the default action (spawning flames) from triggering.
 251   * `pos` Position of the ignited node.
 252   * `igniter` Player that used the tool, when available.
 253
 254
 255 Give Initial Stuff API
 256 ----------------------
 257
 258 `give_initial_stuff.give(player)`
 259
 260 ^ Give initial stuff to "player"
 261
 262 `give_initial_stuff.add(stack)`
 263
 264 ^ Add item to the initial stuff
 265 ^ Stack can be an ItemStack or a item name eg: "default:dirt 99"
 266 ^ Can be called after the game has loaded
 267
 268 `give_initial_stuff.clear()`
 269
 270 ^ Removes all items from the initial stuff
 271 ^ Can be called after the game has loaded
 272
 273 `give_initial_stuff.get_list()`
 274
 275 ^ returns list of item stacks
 276
 277 `give_initial_stuff.set_list(list)`
 278
 279 ^ List of initial items with numeric indices.
 280
 281 `give_initial_stuff.add_from_csv(str)`
 282
 283 ^ str is a comma separated list of initial stuff
 284 ^ Adds items to the list of items to be given
 285
 286
 287 TNT API
 288 ----------
 289
 290 `tnt.register_tnt(definition)`
 291
 292 ^ Register a new type of tnt.
 293
 294  * `name` The name of the node. If no prefix is given `tnt` is used.
 295  * `description` A description for your TNT.
 296  * `radius` The radius within which the TNT can destroy nodes. The default is 3.
 297  * `damage_radius` The radius within which the TNT can damage players and mobs. By default it is twice the `radius`.
 298  * `disable_drops` Disable drops. By default it is set to false.
 299  * `ignore_protection` Don't check `minetest.is_protected` before removing a node.
 300  * `ignore_on_blast` Don't call `on_blast` even if a node has one.
 301  * `tiles` Textures for node
 302   * `side`  Side tiles. By default the name of the tnt with a suffix of `_side.png`.
 303   * `top`  Top tile. By default the name of the tnt with a suffix of `_top.png`.
 304   * `bottom` Bottom tile. By default the name of the tnt with a suffix of `_bottom.png`.
 305   * `burning` Top tile when lit. By default the name of the tnt with a suffix of `_top_burning_animated.png".
 306
 307 `tnt.boom(position, definition)`
 308
 309 ^ Create an explosion.
 310
 311 * `position` The center of explosion.
 312 * `definition` The TNT definion as passed to `tnt.register`
 313
 314 `tnt.burn(position, [nodename])`
 315
 316 ^ Ignite node at position, triggering its `on_ignite` callback (see fire mod).
 317 If no such callback exists, fallback to turn tnt group nodes to their
 318 "_burning" variant.
 319   nodename isn't required unless already known.
 320
 321 To make dropping items from node inventories easier, you can use the
 322 following helper function from 'default':
 323
 324 default.get_inventory_drops(pos, inventory, drops)
 325
 326 ^ Return drops from node inventory "inventory" in drops.
 327
 328 * `pos` - the node position
 329 * `inventory` - the name of the inventory (string)
 330 * `drops` - an initialized list
 331
 332 The function returns no values. The drops are returned in the `drops`
 333 parameter, and drops is not reinitialized so you can call it several
 334 times in a row to add more inventory items to it.
 335
 336
 337 `on_blast` callbacks:
 338
 339 Both nodedefs and entitydefs can provide an `on_blast()` callback
 340
 341 `nodedef.on_blast(pos, intensity)`
 342 ^ Allow drop and node removal overriding
 343 * `pos` - node position
 344 * `intensity` - TNT explosion measure. larger or equal to 1.0
 345 ^ Should return a list of drops (e.g. {"default:stone"})
 346 ^ Should perform node removal itself. If callback exists in the nodedef
 347 ^ then the TNT code will not destroy this node.
 348
 349 `entitydef.on_blast(luaobj, damage)`
 350 ^ Allow TNT effects on entities to be overridden
 351 * `luaobj` - LuaEntityRef of the entity
 352 * `damage` - suggested HP damage value
 353 ^ Should return a list of (bool do_damage, bool do_knockback, table drops)
 354 * `do_damage` - if true then TNT mod wil damage the entity
 355 * `do_knockback` - if true then TNT mod will knock the entity away
 356 * `drops` - a list of drops, e.g. {"wool:red"}
 357
 358
 359 Screwdriver API
 360 ---------------
 361
 362 The screwdriver API allows you to control a node's behaviour when a screwdriver is used on it.
 363 To use it, add the `on_screwdriver` function to the node definition.
 364
 365 `on_rotate(pos, node, user, mode, new_param2)`
 366
 367  * `pos` Position of the node that the screwdriver is being used on
 368  * `node` that node
 369  * `user` The player who used the screwdriver
 370  * `mode` screwdriver.ROTATE_FACE or screwdriver.ROTATE_AXIS
 371  * `new_param2` the new value of param2 that would have been set if on_rotate wasn't there
 372  * return value: false to disallow rotation, nil to keep default behaviour, true to allow
 373         it but to indicate that changed have already been made (so the screwdriver will wear out)
 374  * use `on_rotate = false` to always disallow rotation
 375  * use `on_rotate = screwdriver.rotate_simple` to allow only face rotation
 376
 377
 378 Sethome API
 379 -----------
 380
 381 The sethome API adds three global functions to allow mods to read a players home position,
 382 set a players home position and teleport a player to home position.
 383
 384 `sethome.get(name)`
 385
 386  * `name` Player who's home position you wish to get
 387  * return value: false if no player home coords exist, position table if true
 388
 389 `sethome.set(name, pos)`
 390
 391  * `name` Player who's home position you wish to set
 392  * `pos` Position table containing coords of home position
 393  * return value: false if unable to set and save new home position, otherwise true
 394
 395 `sethome.go(name)`
 396
 397  * `name` Player you wish to teleport to their home position
 398  * return value: false if player cannot be sent home, otherwise true
 399
 400
 401 Sfinv API
 402 ---------
 403
 404 ### sfinv Methods
 405
 406 **Pages**
 407
 408 * sfinv.set_page(player, pagename) - changes the page
 409 * sfinv.get_homepage_name(player) - get the page name of the first page to show to a player
 410 * sfinv.register_page(name, def) - register a page, see section below
 411 * sfinv.override_page(name, def) - overrides fields of an page registered with register_page.
 412     * Note: Page must already be defined, (opt)depend on the mod defining it.
 413 * sfinv.set_player_inventory_formspec(player) - (re)builds page formspec
 414              and calls set_inventory_formspec().
 415 * sfinv.get_formspec(player, context) - builds current page's formspec
 416
 417 **Contexts**
 418
 419 * sfinv.get_or_create_context(player) - gets the player's context
 420 * sfinv.set_context(player, context)
 421
 422 **Theming**
 423
 424 * sfinv.make_formspec(player, context, content, show_inv, size) - adds a theme to a formspec
 425     * show_inv, defaults to false. Whether to show the player's main inventory
 426     * size, defaults to `size[8,8.6]` if not specified
 427 * sfinv.get_nav_fs(player, context, nav, current_idx) - creates tabheader or ""
 428
 429 ### sfinv Members
 430
 431 * pages - table of pages[pagename] = def
 432 * pages_unordered - array table of pages in order of addition (used to build navigation tabs).
 433 * contexts - contexts[playername] = player_context
 434 * enabled - set to false to disable. Good for inventory rehaul mods like unified inventory
 435
 436 ### Context
 437
 438 A table with these keys:
 439
 440 * page - current page name
 441 * nav - a list of page names
 442 * nav_titles - a list of page titles
 443 * nav_idx - current nav index (in nav and nav_titles)
 444 * any thing you want to store
 445     * sfinv will clear the stored data on log out / log in
 446
 447 ### sfinv.register_page
 448
 449 sfinv.register_page(name, def)
 450
 451 def is a table containing:
 452
 453 * `title` - human readable page name (required)
 454 * `get(self, player, context)` - returns a formspec string. See formspec variables. (required)
 455 * `is_in_nav(self, player, context)` - return true to show in the navigation (the tab header, by default)
 456 * `on_player_receive_fields(self, player, context, fields)` - on formspec submit.
 457 * `on_enter(self, player, context)` - called when the player changes pages, usually using the tabs.
 458 * `on_leave(self, player, context)` - when leaving this page to go to another, called before other's on_enter
 459
 460 ### get formspec
 461
 462 Use sfinv.make_formspec to apply a layout:
 463
 464         return sfinv.make_formspec(player, context, [[
 465                 list[current_player;craft;1.75,0.5;3,3;]
 466                 list[current_player;craftpreview;5.75,1.5;1,1;]
 467                 image[4.75,1.5;1,1;gui_furnace_arrow_bg.png^[transformR270]
 468                 listring[current_player;main]
 469                 listring[current_player;craft]
 470                 image[0,4.25;1,1;gui_hb_bg.png]
 471                 image[1,4.25;1,1;gui_hb_bg.png]
 472                 image[2,4.25;1,1;gui_hb_bg.png]
 473                 image[3,4.25;1,1;gui_hb_bg.png]
 474                 image[4,4.25;1,1;gui_hb_bg.png]
 475                 image[5,4.25;1,1;gui_hb_bg.png]
 476                 image[6,4.25;1,1;gui_hb_bg.png]
 477                 image[7,4.25;1,1;gui_hb_bg.png]
 478         ]], true)
 479
 480 See above (methods section) for more options.
 481
 482 ### Customising themes
 483
 484 Simply override this function to change the navigation:
 485
 486         function sfinv.get_nav_fs(player, context, nav, current_idx)
 487                 return "navformspec"
 488         end
 489
 490 And override this function to change the layout:
 491
 492         function sfinv.make_formspec(player, context, content, show_inv, size)
 493                 local tmp = {
 494                         size or "size[8,8.6]",
 495                         theme_main,
 496                         sfinv.get_nav_fs(player, context, context.nav_titles, context.nav_idx),
 497                         content
 498                 }
 499                 if show_inv then
 500                         tmp[4] = theme_inv
 501                 end
 502                 return table.concat(tmp, "")
 503         end
 504
 505 Stairs API
 506 ----------
 507
 508 The stairs API lets you register stairs and slabs and ensures that they are registered the same way as those
 509 delivered with Minetest Game, to keep them compatible with other mods.
 510
 511 `stairs.register_stair(subname, recipeitem, groups, images, description, sounds)`
 512
 513  * Registers a stair.
 514  * `subname`: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
 515  * `recipeitem`: Item used in the craft recipe, e.g. "default:cobble", may be `nil`
 516  * `groups`: see [Known damage and digging time defining groups]
 517  * `images`: see [Tile definition]
 518  * `description`: used for the description field in the stair's definition
 519  * `sounds`: see [#Default sounds]
 520
 521 `stairs.register_slab(subname, recipeitem, groups, images, description, sounds)`
 522
 523  * Registers a slabs
 524  * `subname`: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
 525  * `recipeitem`: Item used in the craft recipe, e.g. "default:cobble"
 526  * `groups`: see [Known damage and digging time defining groups]
 527  * `images`: see [Tile definition]
 528  * `description`: used for the description field in the stair's definition
 529  * `sounds`: see [#Default sounds]
 530
 531 `stairs.register_stair_and_slab(subname, recipeitem, groups, images, desc_stair, desc_slab, sounds)`
 532
 533  * A wrapper for stairs.register_stair and stairs.register_slab
 534  * Uses almost the same arguments as stairs.register_stair
 535  * `desc_stair`: Description for stair node
 536  * `desc_slab`: Description for slab node
 537
 538 Xpanes API
 539 ----------
 540
 541 Creates panes that automatically connect to each other
 542
 543 `xpanes.register_pane(subname, def)`
 544
 545  * `subname`: used for nodename. Result: "xpanes:subname" and "xpanes:subname_{2..15}"
 546  * `def`: See [#Pane definition]
 547
 548 ### Pane definition
 549
 550         {
 551                 textures = {"texture for sides", (unused), "texture for top and bottom"}, -- More tiles aren't supported
 552                 groups = {group = rating}, -- Uses the known node groups, see [Known damage and digging time defining groups]
 553                 sounds = SoundSpec,        -- See [#Default sounds]
 554                 recipe = {{"","","","","","","","",""}}, -- Recipe field only
 555         }
 556
 557 Raillike definitions
 558 --------------------
 559
 560 The following nodes use the group `connect_to_raillike` and will only connect to
 561 raillike nodes within this group and the same group value.
 562 Use `minetest.raillike_group(<Name>)` to get the group value.
 563
 564 | Node type             | Raillike group name
 565 |-----------------------|---------------------
 566 | default:rail          | "rail"
 567 | tnt:gunpowder         | "gunpowder"
 568 | tnt:gunpowder_burning | "gunpowder"
 569
 570 Example:
 571 If you want to add a new rail type and want it to connect with default:rail,
 572 add `connect_to_raillike=minetest.raillike_group("rail")` into the `groups` table
 573 of your node.
 574
 575
 576 Default sounds
 577 --------------
 578
 579 Sounds inside the default table can be used within the sounds field of node definitions.
 580
 581  * `default.node_sound_defaults()`
 582  * `default.node_sound_stone_defaults()`
 583  * `default.node_sound_dirt_defaults()`
 584  * `default.node_sound_sand_defaults()`
 585  * `default.node_sound_wood_defaults()`
 586  * `default.node_sound_leaves_defaults()`
 587  * `default.node_sound_glass_defaults()`
 588  * `default.node_sound_metal_defaults()`
 589
 590 Default constants
 591 -----------------
 592
 593 `default.LIGHT_MAX`  The maximum light level (see [Node definition] light_source)
 594
 595 Player API
 596 ----------
 597
 598 The player API can register player models and update the player's appearence
 599
 600 `default.player_register_model(name, def)`
 601
 602  * Register a new model to be used by players.
 603  * name: model filename such as "character.x", "foo.b3d", etc.
 604  * def: See [#Model definition]
 605
 606 `default.registered_player_models[name]`
 607
 608  * Get a model's definition
 609  * see [#Model definition]
 610
 611 `default.player_set_model(player, model_name)`
 612
 613  * Change a player's model
 614  * `player`: PlayerRef
 615  * `model_name`: model registered with player_register_model()
 616
 617 `default.player_set_animation(player, anim_name [, speed])`
 618
 619  * Applies an animation to a player
 620  * anim_name: name of the animation.
 621  * speed: frames per second. If nil, default from the model is used
 622
 623 `default.player_set_textures(player, textures)`
 624
 625  * Sets player textures
 626  * `player`: PlayerRef
 627  * `textures`: array of textures, If `textures` is nil, the default textures from the model def are used
 628
 629 default.player_get_animation(player)
 630
 631  * Returns a table containing fields `model`, `textures` and `animation`.
 632  * Any of the fields of the returned table may be nil.
 633  * player: PlayerRef
 634
 635 ### Model Definition
 636
 637         {
 638                 animation_speed = 30,            -- Default animation speed, in FPS.
 639                 textures = {"character.png", },  -- Default array of textures.
 640                 visual_size = {x = 1, y = 1},    -- Used to scale the model.
 641                 animations = {
 642                         -- <anim_name> = {x = <start_frame>, y = <end_frame>},
 643                         foo = {x = 0, y = 19},
 644                         bar = {x = 20, y = 39},
 645                 -- ...
 646                 },
 647         }
 648
 649 Leafdecay
 650 ---------
 651
 652 To enable leaf decay for leaves when a tree is cut down by a player,
 653 register the tree with the default.register_leafdecay(leafdecaydef)
 654 function.
 655
 656 If `param2` of any registered node is ~= 0, the node will always be
 657 preserved. Thus, if the player places a node of that kind, you will
 658 want to set `param2 = 1` or so.
 659
 660 The function `default.after_place_leaves` can be set as
 661 `after_place_node of a node` to set param2 to 1 if the player places
 662 the node (should not be used for nodes that use param2 otherwise
 663 (e.g. facedir)).
 664
 665 If the node is in the `leafdecay_drop` group then it will always be
 666 dropped as an item.
 667
 668 `default.register_leafdecay(leafdecaydef)`
 669
 670 `leafdecaydef` is a table, with following members:
 671         {
 672                 trunks = {"default:tree"}, -- nodes considered trunks
 673                 leaves = {"default:leaves", "default:apple"},
 674                         -- nodes considered for removal
 675                 radius = 3, -- radius to consider for searching
 676         }
 677
 678 Note: all the listed nodes in `trunks` have their `on_after_destruct`
 679 callback overridden. All the nodes listed in `leaves` have their
 680 `on_timer` callback overridden.
 681
 682
 683 Dyes
 684 ----
 685
 686 To make recipes that will work with any dye ever made by anybody, define
 687 them based on groups. You can select any group of groups, based on your need for
 688 amount of colors.
 689
 690 ### Color groups
 691
 692 Base color groups:
 693
 694  * `basecolor_white`
 695  * `basecolor_grey`
 696  * `basecolor_black`
 697  * `basecolor_red`
 698  * `basecolor_yellow`
 699  * `basecolor_green`
 700  * `basecolor_cyan`
 701  * `basecolor_blue`
 702  * `basecolor_magenta`
 703
 704 Extended color groups ( * means also base color )
 705
 706  * `excolor_white` *
 707  * `excolor_lightgrey`
 708  * `excolor_grey` *
 709  * `excolor_darkgrey`
 710  * `excolor_black` *
 711  * `excolor_red` *
 712  * `excolor_orange`
 713  * `excolor_yellow` *
 714  * `excolor_lime`
 715  * `excolor_green` *
 716  * `excolor_aqua`
 717  * `excolor_cyan` *
 718  * `excolor_sky_blue`
 719  * `excolor_blue` *
 720  * `excolor_violet`
 721  * `excolor_magenta` *
 722  * `excolor_red_violet`
 723
 724 The whole unifieddyes palette as groups:
 725
 726  * `unicolor_<excolor>`
 727
 728 For the following, no white/grey/black is allowed:
 729
 730  * `unicolor_medium_<excolor>`
 731  * `unicolor_dark_<excolor>`
 732  * `unicolor_light_<excolor>`
 733  * `unicolor_<excolor>_s50`
 734  * `unicolor_medium_<excolor>_s50`
 735  * `unicolor_dark_<excolor>_s50`
 736
 737 Example of one shapeless recipe using a color group:
 738
 739         minetest.register_craft({
 740                 type = "shapeless",
 741                 output = '<mod>:item_yellow',
 742                 recipe = {'<mod>:item_no_color', 'group:basecolor_yellow'},
 743         })
 744
 745 ### Color lists
 746
 747  * `dye.basecolors` are an array containing the names of available base colors
 748
 749  * `dye.excolors` are an array containing the names of the available extended colors
 750
 751 Trees
 752 -----
 753
 754  * `default.grow_tree(pos, is_apple_tree)`
 755   * Grows a mgv6 tree or apple tree at pos
 756
 757  * `default.grow_jungle_tree(pos)`
 758   * Grows a mgv6 jungletree at pos
 759
 760  * `default.grow_pine_tree(pos)`
 761   * Grows a mgv6 pinetree at pos
 762
 763  * `default.grow_new_apple_tree(pos)`
 764   * Grows a new design apple tree at pos
 765
 766  * `default.grow_new_jungle_tree(pos)`
 767   * Grows a new design jungle tree at pos
 768
 769  * `default.grow_new_pine_tree(pos)`
 770   * Grows a new design pine tree at pos
 771
 772  * `default.grow_new_snowy_pine_tree(pos)`
 773   * Grows a new design snowy pine tree at pos
 774
 775  * `default.grow_new_acacia_tree(pos)`
 776   * Grows a new design acacia tree at pos
 777
 778  * `default.grow_new_aspen_tree(pos)`
 779   * Grows a new design aspen tree at pos
 780
 781  * `default.grow_bush(pos)`
 782   * Grows a bush at pos
 783
 784  * `default.grow_acacia_bush(pos)`
 785   * Grows an acaia bush at pos
 786
 787 Carts
 788 -----
 789
 790         carts.register_rail(
 791                 "mycarts:myrail", -- Rail name
 792                 nodedef,          -- standard nodedef
 793                 railparams        -- rail parameter struct (optional)
 794         )
 795
 796         railparams = {
 797                 on_step(obj, dtime), -- Event handler called when
 798                                      -- cart is on rail
 799                 acceleration, -- integer acceleration factor (negative
 800                               -- values to brake)
 801         }
 802
 803         The event handler is called after all default calculations
 804         are made, so the custom on_step handler can override things
 805         like speed, acceleration, player attachment. The handler will
 806         likely be called many times per second, so the function needs
 807         to make sure that the event is handled properly.
 808
 809 Key API
 810 -------
 811
 812 The key API allows mods to add key functionality to nodes that have
 813 ownership or specific permissions. Using the API will make it so
 814 that a node owner can use skeleton keys on their nodes to create keys
 815 for that node in that location, and give that key to other players,
 816 allowing them some sort of access that they otherwise would not have
 817 due to node protection.
 818
 819 To make your new nodes work with the key API, you need to register
 820 two callback functions in each nodedef:
 821
 822
 823 `on_key_use(pos, player)`
 824  * Is called when a player right-clicks (uses) a normal key on your
 825  * node.
 826  * `pos` - position of the node
 827  * `player` - PlayerRef
 828  * return value: none, ignored
 829
 830 The `on_key_use` callback should validate that the player is wielding
 831 a key item with the right key meta secret. If needed the code should
 832 deny access to the node functionality.
 833
 834 If formspecs are used, the formspec callbacks should duplicate these
 835 checks in the metadata callback functions.
 836
 837
 838 `on_skeleton_key_use(pos, player, newsecret)`
 839
 840  * Is called when a player right-clicks (uses) a skeleton key on your
 841  * node.
 842  * `pos` - position of the node
 843  * `player` - PlayerRef
 844  * `newsecret` - a secret value(string)
 845  * return values:
 846  * `secret` - `nil` or the secret value that unlocks the door
 847  * `name` - a string description of the node ("a locked chest")
 848  * `owner` - name of the node owner
 849
 850 The `on_skeleton_key_use` function should validate that the player has
 851 the right permissions to make a new key for the item. The newsecret
 852 value is useful if the node has no secret value. The function should
 853 store this secret value somewhere so that in the future it may compare
 854 key secrets and match them to allow access. If a node already has a
 855 secret value, the function should return that secret value instead
 856 of the newsecret value. The secret value stored for the node should
 857 not be overwritten, as this would invalidate existing keys.
 858
 859 Aside from the secret value, the function should retun a descriptive
 860 name for the node and the owner name. The return values are all
 861 encoded in the key that will be given to the player in replacement
 862 for the wielded skeleton key.
 863
 864 if `nil` is returned, it is assumed that the wielder did not have
 865 permissions to create a key for this node, and no key is created.