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