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