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