3 GitHub Repo: https://github.com/minetest/minetest_game
7 The Minetest Game subgame offers multiple new possibilities in addition to the Minetest engine's built-in API,
8 allowing you to 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
11 [XYZ] refers to a section the Minetest API
12 [#ABC] refers to a section in this document
13 ^ Explanation for line above
17 The bucket API allows registering new types of buckets for non-default liquids.
19 bucket.register_liquid(
20 "default:lava_source", -- name of the source node
21 "default:lava_flowing", -- name of the flowing node
22 "bucket:bucket_lava", -- name of the new bucket item (or nil if liquid is not takeable)
23 "bucket_lava.png", -- texture of the new bucket item (ignored if itemname == nil)
24 "Lava Bucket", -- text description of the bucket item
25 {lava_bucket = 1} -- groups of the bucket item, OPTIONAL
31 "beds:bed", -- Bed name
32 def: See [#Bed definition] -- Bed definition
35 beds.read_spawns() -- returns a table containing players respawn positions
36 beds.kick_players() -- forces all players to leave bed
37 beds.skip_night() -- sets world time to morning and saves respawn position of all players currently sleeping
42 description = "Simple Bed",
43 inventory_image = "beds_bed.png",
44 wield_image = "beds_bed.png",
46 bottom = {[Tile definition],
47 ^ the tiles of the bottom part of the bed
49 top = {[Tile definition],
50 ^ the tiles of the bottom part of the bed
54 bottom = regular nodebox, see [Node boxes], -- bottm part of bed
55 top = regular nodebox, see [Node boxes], -- top part of bed
57 selectionbox = regular nodebox, see [Node boxes], -- for both nodeboxes
58 recipe = { -- Craft recipe
59 {"group:wool", "group:wool", "group:wool"},
60 {"group:wood", "group:wood", "group:wood"}
66 The doors mod allows modders to register custom doors and trapdoors.
68 doors.register_door(name, def)
70 ^ def: See [#Door definition]
73 doors.register_trapdoor(name, def)
74 ^ name: "Trapdoor name"
75 ^ def: See [#Trapdoor definition]
76 -> Registers new trapdoor
81 description = "Door description",
82 inventory_image = "mod_door_inv.png",
84 tiles_bottom: [Tile definition],
85 ^ the tiles of the bottom part of the door {front, side}
86 tiles_top: [Tile definition],
87 ^ the tiles of the bottom part of the door {front, side}
88 node_box_bottom = regular nodebox, see [Node boxes], OPTIONAL,
89 node_box_top = regular nodebox, see [Node boxes], OPTIONAL,
90 selection_box_bottom = regular nodebox, see [Node boxes], OPTIONAL,
91 selection_box_top = regular nodebox, see [Node boxes], OPTIONAL,
92 sound_open_door = sound play for open door, OPTIONAL,
93 sound_close_door = sound play for close door, OPTIONAL,
94 only_placer_can_open = true/false,
95 ^ If true, only placer can open the door (locked for others)
101 tile_front = "doors_trapdoor.png",
102 ^ the texture for the front and back of the trapdoor
103 tile_side: "doors_trapdoor_side.png",
104 ^ the tiles of the four side parts of the trapdoor
105 sound_open = sound to play when opening the trapdoor, OPTIONAL,
106 sound_close = sound to play when closing the trapdoor, OPTIONAL,
107 -> You can add any other node definition properties for minetest.register_node,
108 such as wield_image, inventory_image, sounds, groups, description, ...
109 Only node_box, selection_box, tiles, drop, drawtype, paramtype, paramtype2, on_rightclick
110 will be overwritten by the trapdoor registration function
115 The farming API allows you to easily register plants and hoes.
117 farming.register_hoe(name, hoe definition)
118 -> Register a new hoe, see [#hoe definition]
120 farming.register_plant(name, Plant definition)
121 -> Register a new growing plant, see [#Plant definition]
126 description = "", -- Description for tooltip
127 inventory_image = "unknown_item.png", -- Image to be used as wield- and inventory image
128 max_uses = 30, -- Uses until destroyed
129 material = "", -- Material for recipes
130 recipe = { -- Craft recipe, if material isn't used
131 {"air", "air", "air"},
140 description = "", -- Description of seed item
141 inventory_image = "unknown_item.png", -- Image to be used as seed's wield- and inventory image
142 steps = 8, -- How many steps the plant has to grow, until it can be harvested
143 ^ Always provide a plant texture for each step, format: modname_plantname_i.png (i = stepnumber)
144 minlight = 13, -- Minimum light to grow
145 maxlight = default.LIGHT_MAX -- Maximum light to grow
150 The screwdriver API allows you to control a node's behaviour when a screwdriver is used on it.
151 To use it, add the on_screwdriver function to the node definition.
152 on_rotate(pos, node, user, mode, new_param2)
153 ^ pos: position of the node that the screwdriver is being used on
155 ^ user: the player who used the screwdriver
156 ^ mode: screwdriver.ROTATE_FACE or screwdriver.ROTATE_AXIS
157 ^ new_param2: the new value of param2 that would have been set if on_rotate wasn't there
158 ^ return value: false to disallow rotation, nil to keep default behaviour, true to allow
159 it but to indicate that changed have already been made (so the screwdriver will wear out)
160 ^ use on_rotate = screwdriver.disallow to always disallow rotation
161 ^ use on_rotate = screwdriver.rotate_simple to allow only face rotation
165 The stairs API lets you register stairs and slabs and ensures that they are registered the same way as those
166 delivered with Minetest Game, to keep them compatible with other mods.
168 stairs.register_stair(subname, recipeitem, groups, images, description, sounds)
169 -> Registers a stair.
170 -> subname: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
171 -> recipeitem: Item used in the craft recipe, e.g. "default:cobble"
172 -> groups: see [Known damage and digging time defining groups]
173 -> images: see [Tile definition]
174 -> description: used for the description field in the stair's definition
175 -> sounds: see [#Default sounds]
177 stairs.register_slab(subname, recipeitem, groups, images, description, sounds)
179 -> subname: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname"
180 -> recipeitem: Item used in the craft recipe, e.g. "default:cobble"
181 -> groups: see [Known damage and digging time defining groups]
182 -> images: see [Tile definition]
183 -> description: used for the description field in the stair's definition
184 -> sounds: see [#Default sounds]
186 stairs.register_stair_and_slab(subname, recipeitem, groups, images, desc_stair, desc_slab, sounds)
187 -> A wrapper for stairs.register_stair and stairs.register_slab
188 -> Uses almost the same arguments as stairs.register_stair
189 -> desc_stair: Description for stair node
190 -> desc_slab: Description for slab node
194 Creates panes that automatically connect to each other
196 xpanes.register_pane(subname, def)
197 -> subname: used for nodename. Result: "xpanes:subname" and "xpanes:subname_{2..15}"
198 -> def: See [#Pane definition]
203 textures = {"texture_Bottom_top", "texture_left_right", "texture_front_back"},
204 ^ More tiles aren't supported
205 groups = {group = rating},
206 ^ Uses the known node groups, see [Known damage and digging time defining groups]
208 ^ See [#Default sounds]
209 recipe = {{"","","","","","","","",""}},
215 The following nodes use the group `connect_to_raillike` and will only connect to
216 raillike nodes within this group and the same group value.
217 Use `minetest.raillike_group(<Name>)` to get the group value.
219 | Node type | Raillike group name
220 +-----------------------+--------------------
221 | default:rail | "rail"
222 | tnt:gunpowder | "gunpowder"
223 | tnt:gunpowder_burning | "gunpowder"
226 If you want to add a new rail type and want it to connect with default:rail,
227 add `connect_to_raillike=minetest.raillike_group("rail")` into the `groups` table
233 Sounds inside the default table can be used within the sounds field of node definitions.
235 default.node_sound_defaults()
236 default.node_sound_stone_defaults()
237 default.node_sound_dirt_defaults()
238 default.node_sound_sand_defaults()
239 default.node_sound_wood_defaults()
240 default.node_sound_leaves_defaults()
241 default.node_sound_glass_defaults()
246 ^ The maximum light level (see [Node definition] light_source)
250 The player API can register player models and update the player's appearence
252 default.player_register_model(name, def)
253 ^ Register a new model to be used by players.
254 -> name: model filename such as "character.x", "foo.b3d", etc.
255 -> def: See [#Model definition]
257 default.registered_player_models[name]
258 ^ Get a model's definition
259 -> see [#Model definition]
261 default.player_set_model(player, model_name)
262 ^ Change a player's model
264 -> model_name: model registered with player_register_model()
266 default.player_set_animation(player, anim_name [, speed])
267 ^ Applies an animation to a player
268 -> anim_name: name of the animation.
269 -> speed: frames per second. If nil, default from the model is used
271 default.player_set_textures(player, textures)
272 ^ Sets player textures
274 -> textures: array of textures
275 ^ If <textures> is nil, the default textures from the model def are used
277 default.player_get_animation(player)
278 ^ Returns a table containing fields "model", "textures" and "animation".
279 ^ Any of the fields of the returned table may be nil.
285 animation_speed = 30, -- Default animation speed, in FPS.
286 textures = {"character.png", }, -- Default array of textures.
287 visual_size = {x = 1, y = 1}, -- Used to scale the model.
289 -- <anim_name> = {x = <start_frame>, y = <end_frame>},
290 foo = {x = 0, y = 19},
291 bar = {x = 20, y = 39},
298 To enable leaf decay for a node, add it to the "leafdecay" group.
300 The rating of the group determines how far from a node in the group "tree"
301 the node can be without decaying.
303 If param2 of the node is ~= 0, the node will always be preserved. Thus, if
304 the player places a node of that kind, you will want to set param2=1 or so.
306 The function default.after_place_leaves can be set as after_place_node of a node
307 to set param2 to 1 if the player places the node (should not be used for nodes
308 that use param2 otherwise (e.g. facedir)).
310 If the node is in the leafdecay_drop group then it will always be dropped as an
315 To make recipes that will work with any dye ever made by anybody, define
316 them based on groups. You can select any group of groups, based on your need for
332 Extended color groups (* = equal to a base color):
351 The whole unifieddyes palette as groups:
353 For the following, no white/grey/black is allowed:
354 - unicolor_medium_<excolor>
355 - unicolor_dark_<excolor>
356 - unicolor_light_<excolor>
357 - unicolor_<excolor>_s50
358 - unicolor_medium_<excolor>_s50
359 - unicolor_dark_<excolor>_s50
361 Example of one shapeless recipe using a color group:
362 minetest.register_craft({
364 output = '<mod>:item_yellow',
365 recipe = {'<mod>:item_no_color', 'group:basecolor_yellow'},
371 ^ Array containing the names of available base colors
374 ^ Array containing the names of the available extended colors
378 default.grow_tree(pos, is_apple_tree)
379 ^ Grows a mgv6 tree or apple tree at pos
381 default.grow_jungle_tree(pos)
382 ^ Grows a mgv6 jungletree at pos
384 default.grow_pine_tree(pos)
385 ^ Grows a mgv6 pinetree at pos
387 default.grow_new_apple_tree(pos)
388 ^ Grows a new design apple tree at pos
390 default.grow_new_jungle_tree(pos)
391 ^ Grows a new design jungle tree at pos
393 default.grow_new_pine_tree(pos)
394 ^ Grows a new design pine tree at pos
396 default.grow_new_acacia_tree(pos)
397 ^ Grows a new design acacia tree at pos