game_api.txt

   1 minetest_game API
   2 ======================
   3 GitHub Repo: https://github.com/minetest/minetest_game
   4
   5 Introduction
   6 ------------
   7 The minetest_game gamemode offers multiple new possibilities in addition to Minetest's built-in API, allowing you to
   8 add new plants to farming mod, buckets for new liquids, new stairs and custom panes.
   9 For information on the Minetest API, visit https://github.com/minetest/minetest/blob/master/doc/lua_api.txt
  10 Please note:
  11         [XYZ] refers to a section the Minetest API
  12         [#ABC] refers to a section in this document
  13         ^ Explanation for line above
  14
  15 Bucket API
  16 ----------
  17 The bucket API allows registering new types of buckets for non-default liquids.
  18
  19         bucket.register_liquid(
  20                 "default:lava_source",          -- Source node name
  21                 "default:lava_flowing",         -- Flowing node name
  22                 "bucket:bucket_lava",           -- Name to be used for bucket
  23                 "bucket_lava.png",                      -- Bucket texture (for wielditem and inventory_image)
  24                 "Lava Bucket"                           -- Bucket description
  25         )
  26
  27 Doors API
  28 ---------
  29 The doors mod allows modders to register custom doors and trapdoors.
  30
  31 doors.register_door(name, def)
  32 ^ name: "Door name"
  33 ^ def: See [#Door definition]
  34  -> Registers new door
  35
  36 doors.register_trapdoor(name, def)
  37 ^ name: "Trapdoor name"
  38 ^ def: See [#Trapdoor definition]
  39  -> Registers new trapdoor
  40
  41 #Door definition
  42 ----------------
  43 {
  44         description = "Door description",
  45         inventory_image = "mod_door_inv.png",
  46         groups = {group = 1},
  47         tiles_bottom: [Tile definition],
  48         ^ the tiles of the bottom part of the door {front, side}
  49         tiles_top: [Tile definition],
  50         ^ the tiles of the bottom part of the door {front, side}
  51         node_box_bottom = regular nodebox, see [Node boxes], OPTIONAL,
  52         node_box_top = regular nodebox, see [Node boxes], OPTIONAL,
  53         selection_box_bottom = regular nodebox, see [Node boxes], OPTIONAL,
  54         selection_box_top = regular nodebox, see [Node boxes], OPTIONAL,
  55         sound_open_door = sound play for open door, OPTIONAL,
  56         sound_close_door = sound play for close door, OPTIONAL,
  57         only_placer_can_open = true/false,
  58         ^ If true, only placer can open the door (locked for others)
  59 }
  60
  61 #Trapdoor definition
  62 ----------------
  63 {
  64         tile_front = "doors_trapdoor.png",
  65         ^ the texture for the front and back of the trapdoor
  66         tile_side: "doors_trapdoor_side.png",
  67         ^ the tiles of the four side parts of the trapdoor
  68         sound_open = sound to play when opening the trapdoor, OPTIONAL,
  69         sound_close = sound to play when closing the trapdoor, OPTIONAL,
  70         -> You can add any other node definition properties for minetest.register_node,
  71            such as wield_image, inventory_image, sounds, groups, description, ...
  72            Only node_box, selection_box, tiles, drop, drawtype, paramtype, paramtype2, on_rightclick
  73            will be overwritten by the trapdoor registration function
  74 }
  75
  76 Farming API
  77 -----------
  78 The farming API allows you to easily register plants and hoes.
  79
  80 farming.register_hoe(name, hoe definition)
  81  -> Register a new hoe, see [#hoe definition]
  82
  83 farming.register_plant(name, Plant definition)
  84  -> Register a new growing plant, see [#Plant definition]
  85
  86 #Hoe Definition
  87 ---------------
  88 {
  89         description = "",       -- Description for tooltip
  90         inventory_image = "unknown_item.png",   -- Image to be used as wield- and inventory image
  91         max_uses = 30,  -- Uses until destroyed
  92         recipe = {      -- Craft recipe
  93                 {"air", "air", "air"},
  94                 {"", "group:stick"},
  95                 {"", "group:stick"},
  96         }
  97 }
  98
  99 #Plant definition
 100 -----------------
 101 {
 102         description = "",       -- Description of seed item
 103         inventory_image = "unknown_item.png",   -- Image to be used as seed's wield- and inventory image
 104         steps = 8,      -- How many steps the plant has to grow, until it can be harvested
 105         ^ Always provide a plant texture for ech step, format: modname_plantname_i.png (i = stepnumber)
 106         minlight = 13, -- Minimum light to grow
 107         maxlight = default.LIGHT_MAX -- Maximum light to grow
 108 }
 109
 110 Stairs API
 111 ----------
 112 The stairs API lets you register stairs and slabs and ensures that they are registered the same way as those
 113 delivered with minetest_game, to keep them compatible with other mods.
 114
 115 stairs.register_stair(subname, recipeitem, groups, images, description, sounds)
 116  -> Registers a stair.
 117  -> subname: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
 118  -> recipeitem: Item used in the craft recipe, e.g. "default:cobble"
 119  -> groups: see [Known damage and digging time defining groups]
 120  -> images: see [Tile definition]
 121  -> description: used for the description field in the stair's definition
 122  -> sounds: see [#Default sounds]
 123
 124 stairs.register_slab(subname, recipeitem, groups, images, description, sounds)
 125  -> Registers a slabs
 126  -> subname: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
 127  -> recipeitem: Item used in the craft recipe, e.g. "default:cobble"
 128  -> groups: see [Known damage and digging time defining groups]
 129  -> images: see [Tile definition]
 130  -> description: used for the description field in the stair's definition
 131  -> sounds: see [#Default sounds]
 132
 133 stairs.register_stair_and_slab(subname, recipeitem, groups, images, desc_stair, desc_slab, sounds)
 134  -> A wrapper for stairs.register_stair and stairs.register_slab
 135  -> Uses almost the same arguments as stairs.register_stair
 136  -> desc_stair: Description for stair node
 137  -> desc_slab: Description for slab node
 138
 139 Xpanes API
 140 ----------
 141 Creates panes that automatically connect to each other
 142
 143 xpanes.register_pane(subname, def)
 144  -> subname: used for nodename. Result: "xpanes:subname" and "xpanes:subname_{2..15}"
 145  -> def: See [#Pane definition]
 146
 147 #Pane definition
 148 ----------------
 149 {
 150         textures = {"texture_Bottom_top", "texture_left_right", "texture_front_back"},
 151         ^ More tiles aren't supported
 152         groups = {group = rating},
 153         ^ Uses the known node groups, see [Known damage and digging time defining groups]
 154         sounds = SoundSpec,
 155         ^ See [#Default sounds]
 156         recipe = {{"","","","","","","","",""}},
 157         ^ Recipe field only
 158 }
 159
 160 Default sounds
 161 --------------
 162 Sounds inside the default table can be used within the sounds field of node definitions.
 163
 164 default.node_sound_defaults()
 165 default.node_sound_stone_defaults()
 166 default.node_sound_dirt_defaults()
 167 default.node_sound_sand_defaults()
 168 default.node_sound_wood_defaults()
 169 default.node_sound_leaves_defaults()
 170 default.node_sound_glass_defaults()
 171
 172 Default constants
 173 -----------------
 174 default.LIGHT_MAX
 175 ^ The maximum light level (see [Node definition] light_source)
 176
 177 Player API
 178 ----------
 179 The player API can register player models and update the player's appearence
 180
 181 default.player_register_model(name, def)
 182 ^ Register a new model to be used by players.
 183  -> name: model filename such as "character.x", "foo.b3d", etc.
 184  -> def: See [#Model definition]
 185
 186 default.registered_player_models[name]
 187 ^ Get a model's definition
 188  -> see [#Model definition]
 189
 190 default.player_set_model(player, model_name)
 191 ^ Change a player's model
 192  -> player: PlayerRef
 193  -> model_name: model registered with player_register_model()
 194
 195 default.player_set_animation(player, anim_name [, speed])
 196 ^ Applies an animation to a player
 197  -> anim_name: name of the animation.
 198  -> speed: frames per second. If nil, default from the model is used
 199
 200 default.player_set_textures(player, textures)
 201 ^ Sets player textures
 202  -> player: PlayerRef
 203  -> textures: array of textures
 204  ^ If <textures> is nil, the default textures from the model def are used
 205
 206 default.player_get_animation(player)
 207 ^ Returns a table containing fields "model", "textures" and "animation".
 208 ^ Any of the fields of the returned table may be nil.
 209  -> player: PlayerRef
 210
 211 Model Definition
 212 ----------------
 213 {
 214         animation_speed = 30, -- Default animation speed, in FPS.
 215         textures = {"character.png", }, -- Default array of textures.
 216         visual_size = {x=1, y=1,}, -- Used to scale the model.
 217         animations = {
 218                 -- <anim_name> = { x=<start_frame>, y=<end_frame>, },
 219                 foo = { x= 0, y=19, },
 220                 bar = { x=20, y=39, },
 221                 -- ...
 222         },
 223 }
 224
 225 Leafdecay
 226 ---------
 227 To enable leaf decay for a node, add it to the "leafdecay" group.
 228
 229 The rating of the group determines how far from a node in the group "tree"
 230 the node can be without decaying.
 231
 232 If param2 of the node is ~= 0, the node will always be preserved. Thus, if
 233 the player places a node of that kind, you will want to set param2=1 or so.
 234
 235 The function default.after_place_leaves can be set as after_place_node of a node
 236 to set param2 to 1 if the player places the node (should not be used for nodes
 237 that use param2 otherwise (e.g. facedir)).
 238
 239 If the node is in the leafdecay_drop group then it will always be dropped as an
 240 item.
 241
 242 Dyes
 243 ----
 244 To make recipes that will work with any dye ever made by anybody, define
 245 them based on groups. You can select any group of groups, based on your need for
 246 amount of colors.
 247
 248 #Color groups
 249 -------------
 250 Base color groups:
 251 - basecolor_white
 252 - basecolor_grey
 253 - basecolor_black
 254 - basecolor_red
 255 - basecolor_yellow
 256 - basecolor_green
 257 - basecolor_cyan
 258 - basecolor_blue
 259 - basecolor_magenta
 260
 261 Extended color groups (* = equal to a base color):
 262 * excolor_white
 263 - excolor_lightgrey
 264 * excolor_grey
 265 - excolor_darkgrey
 266 * excolor_black
 267 * excolor_red
 268 - excolor_orange
 269 * excolor_yellow
 270 - excolor_lime
 271 * excolor_green
 272 - excolor_aqua
 273 * excolor_cyan
 274 - excolor_sky_blue
 275 * excolor_blue
 276 - excolor_violet
 277 * excolor_magenta
 278 - excolor_red_violet
 279
 280 The whole unifieddyes palette as groups:
 281 - unicolor_<excolor>
 282 For the following, no white/grey/black is allowed:
 283 - unicolor_medium_<excolor>
 284 - unicolor_dark_<excolor>
 285 - unicolor_light_<excolor>
 286 - unicolor_<excolor>_s50
 287 - unicolor_medium_<excolor>_s50
 288 - unicolor_dark_<excolor>_s50
 289
 290 Example of one shapeless recipe using a color group:
 291 minetest.register_craft({
 292         type = "shapeless",
 293         output = '<mod>:item_yellow',
 294         recipe = {'<mod>:item_no_color', 'group:basecolor_yellow'},
 295 })
 296
 297 #Color lists
 298 ------------
 299 dye.basecolors
 300 ^ Array containing the names of available base colors
 301
 302 dye.excolors
 303 ^ Array containing the names of the available extended colors
 304
 305 Trees
 306 -----
 307 default.grow_tree(pos, is_apple_tree)
 308 ^ Grows a tree or apple tree at pos
 309
 310 default.grow_jungle_tree(pos)
 311 ^ Grows a jungletree at pos
 312
 313 default.grow_pine_tree(pos)
 314 ^ Grows a pinetree at pos