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 = 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 Player API
 152 ----------
 153 The player API can register player models and update the player's appearence
 154
 155 default.player_register_model(name, def)
 156 ^ Register a new model to be used by players.
 157  -> name: model filename such as "character.x", "foo.b3d", etc.
 158  -> def: See [#Model definition]
 159
 160 default.registered_player_models[name]
 161 ^ Get a model's definition
 162  -> see [#Model definition]
 163
 164 default.player_set_model(player, model_name)
 165 ^ Change a player's model
 166  -> player: PlayerRef
 167  -> model_name: model registered with player_register_model()
 168
 169 default.player_set_animation(player, anim_name [, speed])
 170 ^ Applies an animation to a player
 171  -> anim_name: name of the animation.
 172  -> speed: frames per second. If nil, default from the model is used
 173
 174 default.player_set_textures(player, textures)
 175 ^ Sets player textures
 176  -> player: PlayerRef
 177  -> textures: array of textures
 178  ^ If <textures> is nil, the default textures from the model def are used
 179
 180 default.player_get_animation(player)
 181 ^ Returns a table containing fields "model", "textures" and "animation".
 182 ^ Any of the fields of the returned table may be nil.
 183  -> player: PlayerRef
 184
 185 Model Definition
 186 ----------------
 187 {
 188         animation_speed = 30, -- Default animation speed, in FPS.
 189         textures = {"character.png", }, -- Default array of textures.
 190         visual_size = {x=1, y=1,}, -- Used to scale the model.
 191         animations = {
 192                 -- <anim_name> = { x=<start_frame>, y=<end_frame>, },
 193                 foo = { x= 0, y=19, },
 194                 bar = { x=20, y=39, },
 195                 -- ...
 196         },
 197 }