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 Players API
 288 -----------
 289
 290 The player API can register player models and update the player's appearence
 291
 292 * `player_api.register_model(name, def)`
 293         * Register a new model to be used by players
 294         * name: model filename such as "character.x", "foo.b3d", etc.
 295         * def: See [#Model definition]
 296     * saved to player_api.registered_models
 297
 298 * `player_api.registered_player_models[name]`
 299          * Get a model's definition
 300          * see [#Model definition]
 301
 302 * `player_api.set_model(player, model_name)`
 303         * Change a player's model
 304         * `player`: PlayerRef
 305         * `model_name`: model registered with player_api.register_model()
 306
 307 * `player_api.set_animation(player, anim_name [, speed])`
 308         * Applies an animation to a player
 309         * anim_name: name of the animation.
 310         * speed: frames per second. If nil, default from the model is used
 311
 312 * `player_api.set_textures(player, textures)`
 313         * Sets player textures
 314         * `player`: PlayerRef
 315         * `textures`: array of textures, If `textures` is nil the default
 316           textures from the model def are used
 317
 318 * `player_api.get_animation(player)`
 319         * Returns a table containing fields `model`, `textures` and `animation`.
 320         * Any of the fields of the returned table may be nil.
 321         * player: PlayerRef
 322
 323 ### Model Definition
 324
 325         {
 326                 animation_speed = 30,            -- Default animation speed, in FPS.
 327                 textures = {"character.png", },  -- Default array of textures.
 328                 visual_size = {x = 1, y = 1},    -- Used to scale the model.
 329                 animations = {
 330                         -- <anim_name> = {x = <start_frame>, y = <end_frame>},
 331                         foo = {x = 0, y = 19},
 332                         bar = {x = 20, y = 39},
 333                 -- ...
 334                 },
 335                 collisionbox = {-0.3, 0.0, -0.3, 0.3, 1.77, 0.3}, -- In nodes from feet position
 336                 stepheight = 0.6, -- In nodes
 337         }
 338
 339
 340 TNT API
 341 -------
 342
 343 `tnt.register_tnt(definition)`
 344
 345 ^ Register a new type of tnt.
 346
 347  * `name` The name of the node. If no prefix is given `tnt` is used.
 348  * `description` A description for your TNT.
 349  * `radius` The radius within which the TNT can destroy nodes. The default is 3.
 350  * `damage_radius` The radius within which the TNT can damage players and mobs. By default it is twice the `radius`.
 351  * `disable_drops` Disable drops. By default it is set to false.
 352  * `ignore_protection` Don't check `minetest.is_protected` before removing a node.
 353  * `ignore_on_blast` Don't call `on_blast` even if a node has one.
 354  * `tiles` Textures for node
 355   * `side`  Side tiles. By default the name of the tnt with a suffix of `_side.png`.
 356   * `top`  Top tile. By default the name of the tnt with a suffix of `_top.png`.
 357   * `bottom` Bottom tile. By default the name of the tnt with a suffix of `_bottom.png`.
 358   * `burning` Top tile when lit. By default the name of the tnt with a suffix of `_top_burning_animated.png".
 359
 360 `tnt.boom(position, definition)`
 361
 362 ^ Create an explosion.
 363
 364 * `position` The center of explosion.
 365 * `definition` The TNT definion as passed to `tnt.register`
 366
 367 `tnt.burn(position, [nodename])`
 368
 369 ^ Ignite node at position, triggering its `on_ignite` callback (see fire mod).
 370 If no such callback exists, fallback to turn tnt group nodes to their
 371 "_burning" variant.
 372   nodename isn't required unless already known.
 373
 374 To make dropping items from node inventories easier, you can use the
 375 following helper function from 'default':
 376
 377 default.get_inventory_drops(pos, inventory, drops)
 378
 379 ^ Return drops from node inventory "inventory" in drops.
 380
 381 * `pos` - the node position
 382 * `inventory` - the name of the inventory (string)
 383 * `drops` - an initialized list
 384
 385 The function returns no values. The drops are returned in the `drops`
 386 parameter, and drops is not reinitialized so you can call it several
 387 times in a row to add more inventory items to it.
 388
 389
 390 `on_blast` callbacks:
 391
 392 Both nodedefs and entitydefs can provide an `on_blast()` callback
 393
 394 `nodedef.on_blast(pos, intensity)`
 395 ^ Allow drop and node removal overriding
 396 * `pos` - node position
 397 * `intensity` - TNT explosion measure. larger or equal to 1.0
 398 ^ Should return a list of drops (e.g. {"default:stone"})
 399 ^ Should perform node removal itself. If callback exists in the nodedef
 400 ^ then the TNT code will not destroy this node.
 401
 402 `entitydef.on_blast(luaobj, damage)`
 403 ^ Allow TNT effects on entities to be overridden
 404 * `luaobj` - LuaEntityRef of the entity
 405 * `damage` - suggested HP damage value
 406 ^ Should return a list of (bool do_damage, bool do_knockback, table drops)
 407 * `do_damage` - if true then TNT mod wil damage the entity
 408 * `do_knockback` - if true then TNT mod will knock the entity away
 409 * `drops` - a list of drops, e.g. {"wool:red"}
 410
 411
 412 Screwdriver API
 413 ---------------
 414
 415 The screwdriver API allows you to control a node's behaviour when a screwdriver is used on it.
 416 To use it, add the `on_screwdriver` function to the node definition.
 417
 418 `on_rotate(pos, node, user, mode, new_param2)`
 419
 420  * `pos` Position of the node that the screwdriver is being used on
 421  * `node` that node
 422  * `user` The player who used the screwdriver
 423  * `mode` screwdriver.ROTATE_FACE or screwdriver.ROTATE_AXIS
 424  * `new_param2` the new value of param2 that would have been set if on_rotate wasn't there
 425  * return value: false to disallow rotation, nil to keep default behaviour, true to allow
 426         it but to indicate that changed have already been made (so the screwdriver will wear out)
 427  * use `on_rotate = false` to always disallow rotation
 428  * use `on_rotate = screwdriver.rotate_simple` to allow only face rotation
 429
 430
 431 Sethome API
 432 -----------
 433
 434 The sethome API adds three global functions to allow mods to read a players home position,
 435 set a players home position and teleport a player to home position.
 436
 437 `sethome.get(name)`
 438
 439  * `name` Player who's home position you wish to get
 440  * return value: false if no player home coords exist, position table if true
 441
 442 `sethome.set(name, pos)`
 443
 444  * `name` Player who's home position you wish to set
 445  * `pos` Position table containing coords of home position
 446  * return value: false if unable to set and save new home position, otherwise true
 447
 448 `sethome.go(name)`
 449
 450  * `name` Player you wish to teleport to their home position
 451  * return value: false if player cannot be sent home, otherwise true
 452
 453
 454 Sfinv API
 455 ---------
 456
 457 ### sfinv Methods
 458
 459 **Pages**
 460
 461 * sfinv.set_page(player, pagename) - changes the page
 462 * sfinv.get_homepage_name(player) - get the page name of the first page to show to a player
 463 * sfinv.register_page(name, def) - register a page, see section below
 464 * sfinv.override_page(name, def) - overrides fields of an page registered with register_page.
 465     * Note: Page must already be defined, (opt)depend on the mod defining it.
 466 * sfinv.set_player_inventory_formspec(player) - (re)builds page formspec
 467              and calls set_inventory_formspec().
 468 * sfinv.get_formspec(player, context) - builds current page's formspec
 469
 470 **Contexts**
 471
 472 * sfinv.get_or_create_context(player) - gets the player's context
 473 * sfinv.set_context(player, context)
 474
 475 **Theming**
 476
 477 * sfinv.make_formspec(player, context, content, show_inv, size) - adds a theme to a formspec
 478     * show_inv, defaults to false. Whether to show the player's main inventory
 479     * size, defaults to `size[8,8.6]` if not specified
 480 * sfinv.get_nav_fs(player, context, nav, current_idx) - creates tabheader or ""
 481
 482 ### sfinv Members
 483
 484 * pages - table of pages[pagename] = def
 485 * pages_unordered - array table of pages in order of addition (used to build navigation tabs).
 486 * contexts - contexts[playername] = player_context
 487 * enabled - set to false to disable. Good for inventory rehaul mods like unified inventory
 488
 489 ### Context
 490
 491 A table with these keys:
 492
 493 * page - current page name
 494 * nav - a list of page names
 495 * nav_titles - a list of page titles
 496 * nav_idx - current nav index (in nav and nav_titles)
 497 * any thing you want to store
 498     * sfinv will clear the stored data on log out / log in
 499
 500 ### sfinv.register_page
 501
 502 sfinv.register_page(name, def)
 503
 504 def is a table containing:
 505
 506 * `title` - human readable page name (required)
 507 * `get(self, player, context)` - returns a formspec string. See formspec variables. (required)
 508 * `is_in_nav(self, player, context)` - return true to show in the navigation (the tab header, by default)
 509 * `on_player_receive_fields(self, player, context, fields)` - on formspec submit.
 510 * `on_enter(self, player, context)` - called when the player changes pages, usually using the tabs.
 511 * `on_leave(self, player, context)` - when leaving this page to go to another, called before other's on_enter
 512
 513 ### get formspec
 514
 515 Use sfinv.make_formspec to apply a layout:
 516
 517         return sfinv.make_formspec(player, context, [[
 518                 list[current_player;craft;1.75,0.5;3,3;]
 519                 list[current_player;craftpreview;5.75,1.5;1,1;]
 520                 image[4.75,1.5;1,1;gui_furnace_arrow_bg.png^[transformR270]
 521                 listring[current_player;main]
 522                 listring[current_player;craft]
 523                 image[0,4.25;1,1;gui_hb_bg.png]
 524                 image[1,4.25;1,1;gui_hb_bg.png]
 525                 image[2,4.25;1,1;gui_hb_bg.png]
 526                 image[3,4.25;1,1;gui_hb_bg.png]
 527                 image[4,4.25;1,1;gui_hb_bg.png]
 528                 image[5,4.25;1,1;gui_hb_bg.png]
 529                 image[6,4.25;1,1;gui_hb_bg.png]
 530                 image[7,4.25;1,1;gui_hb_bg.png]
 531         ]], true)
 532
 533 See above (methods section) for more options.
 534
 535 ### Customising themes
 536
 537 Simply override this function to change the navigation:
 538
 539         function sfinv.get_nav_fs(player, context, nav, current_idx)
 540                 return "navformspec"
 541         end
 542
 543 And override this function to change the layout:
 544
 545         function sfinv.make_formspec(player, context, content, show_inv, size)
 546                 local tmp = {
 547                         size or "size[8,8.6]",
 548                         theme_main,
 549                         sfinv.get_nav_fs(player, context, context.nav_titles, context.nav_idx),
 550                         content
 551                 }
 552                 if show_inv then
 553                         tmp[4] = theme_inv
 554                 end
 555                 return table.concat(tmp, "")
 556         end
 557
 558 Stairs API
 559 ----------
 560
 561 The stairs API lets you register stairs and slabs and ensures that they are registered the same way as those
 562 delivered with Minetest Game, to keep them compatible with other mods.
 563
 564 `stairs.register_stair(subname, recipeitem, groups, images, description, sounds)`
 565
 566  * Registers a stair.
 567  * `subname`: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
 568  * `recipeitem`: Item used in the craft recipe, e.g. "default:cobble", may be `nil`
 569  * `groups`: see [Known damage and digging time defining groups]
 570  * `images`: see [Tile definition]
 571  * `description`: used for the description field in the stair's definition
 572  * `sounds`: see [#Default sounds]
 573
 574 `stairs.register_slab(subname, recipeitem, groups, images, description, sounds)`
 575
 576  * Registers a slabs
 577  * `subname`: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
 578  * `recipeitem`: Item used in the craft recipe, e.g. "default:cobble"
 579  * `groups`: see [Known damage and digging time defining groups]
 580  * `images`: see [Tile definition]
 581  * `description`: used for the description field in the stair's definition
 582  * `sounds`: see [#Default sounds]
 583
 584 `stairs.register_stair_and_slab(subname, recipeitem, groups, images, desc_stair, desc_slab, sounds)`
 585
 586  * A wrapper for stairs.register_stair and stairs.register_slab
 587  * Uses almost the same arguments as stairs.register_stair
 588  * `desc_stair`: Description for stair node
 589  * `desc_slab`: Description for slab node
 590
 591 Xpanes API
 592 ----------
 593
 594 Creates panes that automatically connect to each other
 595
 596 `xpanes.register_pane(subname, def)`
 597
 598  * `subname`: used for nodename. Result: "xpanes:subname" and "xpanes:subname_{2..15}"
 599  * `def`: See [#Pane definition]
 600
 601 ### Pane definition
 602
 603         {
 604                 textures = {"texture for sides", (unused), "texture for top and bottom"}, -- More tiles aren't supported
 605                 groups = {group = rating}, -- Uses the known node groups, see [Known damage and digging time defining groups]
 606                 sounds = SoundSpec,        -- See [#Default sounds]
 607                 recipe = {{"","","","","","","","",""}}, -- Recipe field only
 608         }
 609
 610 Raillike definitions
 611 --------------------
 612
 613 The following nodes use the group `connect_to_raillike` and will only connect to
 614 raillike nodes within this group and the same group value.
 615 Use `minetest.raillike_group(<Name>)` to get the group value.
 616
 617 | Node type             | Raillike group name
 618 |-----------------------|---------------------
 619 | default:rail          | "rail"
 620 | tnt:gunpowder         | "gunpowder"
 621 | tnt:gunpowder_burning | "gunpowder"
 622
 623 Example:
 624 If you want to add a new rail type and want it to connect with default:rail,
 625 add `connect_to_raillike=minetest.raillike_group("rail")` into the `groups` table
 626 of your node.
 627
 628
 629 Default sounds
 630 --------------
 631
 632 Sounds inside the default table can be used within the sounds field of node definitions.
 633
 634  * `default.node_sound_defaults()`
 635  * `default.node_sound_stone_defaults()`
 636  * `default.node_sound_dirt_defaults()`
 637  * `default.node_sound_sand_defaults()`
 638  * `default.node_sound_wood_defaults()`
 639  * `default.node_sound_leaves_defaults()`
 640  * `default.node_sound_glass_defaults()`
 641  * `default.node_sound_metal_defaults()`
 642
 643 Default constants
 644 -----------------
 645
 646 `default.LIGHT_MAX`  The maximum light level (see [Node definition] light_source)
 647
 648
 649 GUI and formspecs
 650 -----------------
 651
 652 `default.get_hotbar_bg(x, y)`
 653
 654  * Get the hotbar background as string, containing the formspec elements
 655  * x: Horizontal position in the formspec
 656  * y: Vertical position in the formspec
 657
 658 `default.gui_bg`
 659
 660  * Background color formspec element
 661
 662 `default.gui_bg_img`
 663
 664  * Image overlay formspec element for the background to use in formspecs
 665
 666 `default.gui_slots`
 667
 668  * `listcolors` formspec element that is used to format the slots in formspecs
 669
 670 `default.gui_survival_form`
 671
 672  * Entire formspec for the survival inventory
 673
 674 `default.get_chest_formspec(pos)`
 675
 676  * Get the chest formspec using the defined GUI elements
 677  * pos: Location of the node
 678
 679 `default.get_furnace_active_formspec(fuel_percent, item_percent)`
 680
 681  * Get the active furnace formspec using the defined GUI elements
 682  * fuel_percent: Percent of how much the fuel is used
 683  * item_percent: Percent of how much the item is cooked
 684
 685 `default.get_furnace_inactive_formspec()`
 686
 687  * Get the inactive furnace formspec using the defined GUI elements
 688
 689
 690 Leafdecay
 691 ---------
 692
 693 To enable leaf decay for leaves when a tree is cut down by a player,
 694 register the tree with the default.register_leafdecay(leafdecaydef)
 695 function.
 696
 697 If `param2` of any registered node is ~= 0, the node will always be
 698 preserved. Thus, if the player places a node of that kind, you will
 699 want to set `param2 = 1` or so.
 700
 701 The function `default.after_place_leaves` can be set as
 702 `after_place_node of a node` to set param2 to 1 if the player places
 703 the node (should not be used for nodes that use param2 otherwise
 704 (e.g. facedir)).
 705
 706 If the node is in the `leafdecay_drop` group then it will always be
 707 dropped as an item.
 708
 709 `default.register_leafdecay(leafdecaydef)`
 710
 711 `leafdecaydef` is a table, with following members:
 712         {
 713                 trunks = {"default:tree"}, -- nodes considered trunks
 714                 leaves = {"default:leaves", "default:apple"},
 715                         -- nodes considered for removal
 716                 radius = 3, -- radius to consider for searching
 717         }
 718
 719 Note: all the listed nodes in `trunks` have their `on_after_destruct`
 720 callback overridden. All the nodes listed in `leaves` have their
 721 `on_timer` callback overridden.
 722
 723
 724 Dyes
 725 ----
 726
 727 To make recipes that will work with any dye ever made by anybody, define
 728 them based on groups. You can select any group of groups, based on your need for
 729 amount of colors.
 730
 731 ### Color groups
 732
 733 Base color groups:
 734
 735  * `basecolor_white`
 736  * `basecolor_grey`
 737  * `basecolor_black`
 738  * `basecolor_red`
 739  * `basecolor_yellow`
 740  * `basecolor_green`
 741  * `basecolor_cyan`
 742  * `basecolor_blue`
 743  * `basecolor_magenta`
 744
 745 Extended color groups ( * means also base color )
 746
 747  * `excolor_white` *
 748  * `excolor_lightgrey`
 749  * `excolor_grey` *
 750  * `excolor_darkgrey`
 751  * `excolor_black` *
 752  * `excolor_red` *
 753  * `excolor_orange`
 754  * `excolor_yellow` *
 755  * `excolor_lime`
 756  * `excolor_green` *
 757  * `excolor_aqua`
 758  * `excolor_cyan` *
 759  * `excolor_sky_blue`
 760  * `excolor_blue` *
 761  * `excolor_violet`
 762  * `excolor_magenta` *
 763  * `excolor_red_violet`
 764
 765 The whole unifieddyes palette as groups:
 766
 767  * `unicolor_<excolor>`
 768
 769 For the following, no white/grey/black is allowed:
 770
 771  * `unicolor_medium_<excolor>`
 772  * `unicolor_dark_<excolor>`
 773  * `unicolor_light_<excolor>`
 774  * `unicolor_<excolor>_s50`
 775  * `unicolor_medium_<excolor>_s50`
 776  * `unicolor_dark_<excolor>_s50`
 777
 778 Example of one shapeless recipe using a color group:
 779
 780         minetest.register_craft({
 781                 type = "shapeless",
 782                 output = '<mod>:item_yellow',
 783                 recipe = {'<mod>:item_no_color', 'group:basecolor_yellow'},
 784         })
 785
 786 ### Color lists
 787
 788  * `dye.basecolors` are an array containing the names of available base colors
 789
 790  * `dye.excolors` are an array containing the names of the available extended colors
 791
 792 Trees
 793 -----
 794
 795  * `default.grow_tree(pos, is_apple_tree)`
 796   * Grows a mgv6 tree or apple tree at pos
 797
 798  * `default.grow_jungle_tree(pos)`
 799   * Grows a mgv6 jungletree at pos
 800
 801  * `default.grow_pine_tree(pos)`
 802   * Grows a mgv6 pinetree at pos
 803
 804  * `default.grow_new_apple_tree(pos)`
 805   * Grows a new design apple tree at pos
 806
 807  * `default.grow_new_jungle_tree(pos)`
 808   * Grows a new design jungle tree at pos
 809
 810  * `default.grow_new_pine_tree(pos)`
 811   * Grows a new design pine tree at pos
 812
 813  * `default.grow_new_snowy_pine_tree(pos)`
 814   * Grows a new design snowy pine tree at pos
 815
 816  * `default.grow_new_acacia_tree(pos)`
 817   * Grows a new design acacia tree at pos
 818
 819  * `default.grow_new_aspen_tree(pos)`
 820   * Grows a new design aspen tree at pos
 821
 822  * `default.grow_bush(pos)`
 823   * Grows a bush at pos
 824
 825  * `default.grow_acacia_bush(pos)`
 826   * Grows an acaia bush at pos
 827
 828 Carts
 829 -----
 830
 831         carts.register_rail(
 832                 "mycarts:myrail", -- Rail name
 833                 nodedef,          -- standard nodedef
 834                 railparams        -- rail parameter struct (optional)
 835         )
 836
 837         railparams = {
 838                 on_step(obj, dtime), -- Event handler called when
 839                                      -- cart is on rail
 840                 acceleration, -- integer acceleration factor (negative
 841                               -- values to brake)
 842         }
 843
 844         The event handler is called after all default calculations
 845         are made, so the custom on_step handler can override things
 846         like speed, acceleration, player attachment. The handler will
 847         likely be called many times per second, so the function needs
 848         to make sure that the event is handled properly.
 849
 850 Key API
 851 -------
 852
 853 The key API allows mods to add key functionality to nodes that have
 854 ownership or specific permissions. Using the API will make it so
 855 that a node owner can use skeleton keys on their nodes to create keys
 856 for that node in that location, and give that key to other players,
 857 allowing them some sort of access that they otherwise would not have
 858 due to node protection.
 859
 860 To make your new nodes work with the key API, you need to register
 861 two callback functions in each nodedef:
 862
 863
 864 `on_key_use(pos, player)`
 865  * Is called when a player right-clicks (uses) a normal key on your
 866  * node.
 867  * `pos` - position of the node
 868  * `player` - PlayerRef
 869  * return value: none, ignored
 870
 871 The `on_key_use` callback should validate that the player is wielding
 872 a key item with the right key meta secret. If needed the code should
 873 deny access to the node functionality.
 874
 875 If formspecs are used, the formspec callbacks should duplicate these
 876 checks in the metadata callback functions.
 877
 878
 879 `on_skeleton_key_use(pos, player, newsecret)`
 880
 881  * Is called when a player right-clicks (uses) a skeleton key on your
 882  * node.
 883  * `pos` - position of the node
 884  * `player` - PlayerRef
 885  * `newsecret` - a secret value(string)
 886  * return values:
 887  * `secret` - `nil` or the secret value that unlocks the door
 888  * `name` - a string description of the node ("a locked chest")
 889  * `owner` - name of the node owner
 890
 891 The `on_skeleton_key_use` function should validate that the player has
 892 the right permissions to make a new key for the item. The newsecret
 893 value is useful if the node has no secret value. The function should
 894 store this secret value somewhere so that in the future it may compare
 895 key secrets and match them to allow access. If a node already has a
 896 secret value, the function should return that secret value instead
 897 of the newsecret value. The secret value stored for the node should
 898 not be overwritten, as this would invalidate existing keys.
 899
 900 Aside from the secret value, the function should retun a descriptive
 901 name for the node and the owner name. The return values are all
 902 encoded in the key that will be given to the player in replacement
 903 for the wielded skeleton key.
 904
 905 if `nil` is returned, it is assumed that the wielder did not have
 906 permissions to create a key for this node, and no key is created.