-Minetest Lua Modding API Reference 0.4.dev
+Minetest Lua Modding API Reference 0.4.0
==========================================
More information at http://c55.me/minetest/
Nodes can also contain extra data. See "Node Metadata".
+Node drawtypes
+---------------
+There are a bunch of different looking node types. These are mostly just
+copied from Minetest 0.3; more may be made in the future.
+
+Look for examples in games/minimal or games/minetest_game.
+
+- normal
+- airlike
+- liquid
+- flowingliquid
+- glasslike
+- allfaces
+- allfaces_optional
+- torchlike
+- signlike
+- plantlike
+- fencelike
+- raillike
+- nodebox -- See below. EXPERIMENTAL
+
+Node boxes
+-----------
+Node selection boxes are defined using "node boxes"
+
+The "nodebox" node drawtype allows defining visual of nodes consisting of
+arbitrary number of boxes. It allows defining stuff like stairs. Only the
+"fixed" box type is supported for these.
+^ Please note that this is still experimental, and may be incompatibly
+ changed in the future.
+
+A nodebox is defined as any of:
+{
+ -- A normal cube; the default in most things
+ type = "regular"
+}
+{
+ -- A fixed box (facedir param2 is used, if applicable)
+ type = "fixed",
+ fixed = box OR {box1, box2, ...}
+}
+{
+ -- A box like the selection box for torches
+ -- (wallmounted param2 is used, if applicable)
+ type = "wallmounted",
+ wall_top = box,
+ wall_bottom = box,
+ wall_side = box
+}
+
+A box is defined as:
+ {x1, y1, z1, x2, y2, z2}
+A box of a regular node would look like:
+ {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
+
Representations of simple things
--------------------------------
Position/vector:
Currently the API does not provide any helper functions for addition,
subtraction and whatever; you can define those that you need yourself.
+pointed_thing:
+ {type="nothing"}
+ {type="node", under=pos, above=pos}
+ {type="object", ref=ObjectRef}
+
Items
------
Node (register_node):
Groups in crafting recipes
---------------------------
-- Not implemented yet. (TODO)
-- Will probably look like this:
+An example:
{
output = 'food:meat_soup_raw',
recipe = {
{'group:water'},
{'group:bowl'},
},
- preserve = {'group:bowl'},
+ preserve = {'group:bowl'}, -- Not implemented yet (TODO)
}
Special groups
local meta = minetest.env:get_meta(pos)
meta:set_string("formspec",
"invsize[8,9;]"..
- "list[current_name;main;0,0;8,4;]"..
+ "list[context;main;0,0;8,4;]"..
"list[current_player;main;0,5;8,4;]")
meta:set_string("infotext", "Chest");
local inv = meta:get_inventory()
main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "", [14] = "default:cobble", [15] = "", [16] = "", [17] = "", [18] = "", [19] = "", [20] = "default:cobble", [21] = "", [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", [32] = ""}
},
fields = {
- formspec = "invsize[8,9;]list[current_name;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
+ formspec = "invsize[8,9;]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
infotext = "Chest"
}
})
Examples:
- Chest:
invsize[8,9;]
- list[current_name;main;0,0;8,4;]
+ list[context;main;0,0;8,4;]
list[current_player;main;0,5;8,4;]
- Furnace:
invsize[8,9;]
- list[current_name;fuel;2,3;1,1;]
- list[current_name;src;2,1;1,1;]
- list[current_name;dst;5,1;2,2;]
+ list[context;fuel;2,3;1,1;]
+ list[context;src;2,1;1,1;]
+ list[context;dst;5,1;2,2;]
list[current_player;main;0,5;8,4;]
+- Minecraft-like player inventory
+ invsize[8,7.5;]
+ image[1,0.6;1,2;player.png]
+ list[current_player;main;0,3.5;8,4;]
+ list[current_player;craft;3,0;3,3;]
+ list[current_player;craftpreview;7,1;1,1;]
Elements:
image[<X>,<Y>;<W>,<H>;<texture name>]
^ Show an image
^ Position and size units are inventory slots
-^ Not implemented
field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
^ Textual field; will be sent to server when a button is clicked
^ Not implemented
Inventory location:
-- "current_name": Selected node metadata
+- "context": Selected node metadata (deprecated: "current_name")
- "current_player": Player to whom the menu is shown
- "player:<name>": Any player
- "nodemeta:<X>,<Y>,<Z>": Any node metadata
minetest.get_current_modname() -> string
minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
^ Useful for loading additional .lua modules or static data from mod
+minetest.get_modnames() -> list of installed mods
+^ Return a list of installed mods, sorted alphabetically
minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
^ Useful for storing custom data
minetest.is_singleplayer()
^ Called every server step, usually interval of 0.05s
minetest.register_on_placenode(func(pos, newnode, placer))
^ Called when a node has been placed
+^ Deprecated: Use on_construct or after_place_node in node definition instead
minetest.register_on_dignode(func(pos, oldnode, digger))
^ Called when a node has been dug. digger can be nil.
+^ Deprecated: Use on_destruct or after_dig_node in node definition instead
minetest.register_on_punchnode(func(pos, node, puncher))
^ Called when a node is punched
minetest.register_on_generated(func(minp, maxp, blockseed))
^ Called when player is to be respawned
^ Called _before_ repositioning of player occurs
^ return true in func to disable regular player placement
+minetest.register_on_joinplayer(func(ObjectRef))
+^ Called when a player joins the game
+minetest.register_on_leaveplayer(func(ObjectRef))
+^ Called when a player leaves the game
minetest.register_on_chat_message(func(name, message))
Other registration functions:
^ output.item = ItemStack, if unsuccessful: empty ItemStack
^ output.time = number, if unsuccessful: 0
^ decremented_input = like input
+minetest.get_craft_recipe(output) -> input
+^ output is a node or item type such as 'default:torch'
+^ input.method = 'normal' or 'cooking' or 'fuel'
+^ input.width = for example 3
+^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
+ stack 5, stack 6, stack 7, stack 8, stack 9 }
+^ input.items = nil if no recipe found
Defaults for the on_* item definition functions:
(These return the leftover itemstack)
^ Get rating of a group of an item. (0 = not in group)
minetest.get_node_group(name, group) -> rating
^ Deprecated: An alias for the former.
+minetest.serialize(table) -> string
+^ Convert a table containing tables, strings, numbers, booleans and nils
+ into string form readable by minetest.deserialize
+^ Example: serialize({foo='bar'}) -> 'return { ["foo"] = "bar" }'
+minetest.deserialize(string) -> table
+^ Convert a string returned by minetest.deserialize into a table
+^ String is loaded in an empty sandbox environment.
+^ Will load functions, but they cannot access the global environment.
+^ Example: deserialize('return { ["foo"] = "bar" }') -> {foo='bar'}
+^ Example: deserialize('print("foo")') -> nil (function call fails)
+ ^ error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)
Global objects:
minetest.env - EnvRef of the server environment and world.
methods:
- set_node(pos, node)
- add_node(pos, node): alias set_node(pos, node)
-- remove_node(pos): equivalent to set_node(pos, "air")
+ ^ Set node at position (node = {name="foo", param1=0, param2=0})
+- remove_node(pos)
+ ^ Equivalent to set_node(pos, "air")
- get_node(pos)
^ Returns {name="ignore", ...} for unloaded area
- get_node_or_nil(pos)
^ Returns nil for unloaded area
- get_node_light(pos, timeofday) -> 0...15 or nil
^ timeofday: nil = current time, 0 = night, 0.5 = day
+
+- place_node(pos, node)
+ ^ Place node with the same effects that a player would cause
+- dig_node(pos)
+ ^ Dig node with the same effects that a player would cause
+- punch_node(pos)
+ ^ Punch node with the same effects that a player would cause
+
- add_entity(pos, name): Spawn Lua-defined entity at position
^ Returns ObjectRef, or nil if failed
-- add_item(pos, itemstring): Spawn item
+- add_item(pos, item): Spawn item
^ Returns ObjectRef, or nil if failed
- get_meta(pos) -- Get a NodeMetaRef at that position
- get_player_by_name(name) -- Get an ObjectRef to a player
- settexturemod(mod)
- setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
- select_horiz_by_yawpitch=false)
-- ^ Select sprite from spritesheet with optional animation and DM-style
-- texture selection based on yaw relative to camera
+ ^ Select sprite from spritesheet with optional animation and DM-style
+ texture selection based on yaw relative to camera
- get_entity_name() (DEPRECATED: Will be removed in a future version)
- get_luaentity()
Player-only: (no-op for other objects)
-- get_player_name(): will return nil if is not a player
+- is_player(): true for players, false for others
+- get_player_name(): returns "" if is not a player
- get_look_dir(): get camera direction as a unit vector
- get_look_pitch(): pitch in radians
- get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
+- set_inventory_formspec(formspec)
+ ^ Redefine player's inventory form
+ ^ Should usually be called in on_joinplayer
+- get_inventory_formspec() -> formspec string
InvRef: Reference to an inventory
methods:
+- is_empty(listname): return true if list is empty
- get_size(listname): get size of a list
- set_size(listname, size): set size of a list
- get_stack(listname, i): get a copy of stack index i in list
Object Properties
{
+ hp_max = 1,
physical = true,
+ weight = 5,
collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
visual = "cube"/"sprite"/"upright_sprite",
visual_size = {x=1, y=1},
initial_sprite_basepos = {x=0, y=0},
is_visible = true,
makes_footstep_sound = false,
+ automatic_rotate = false,
}
Entity definition (register_entity)
choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
}
}
+ node_placement_prediction = nil,
+ ^ If nil and item is node, prediction is made automatically
+ ^ If nil and item is not a node, no prediction is made
+ ^ If "" and item is anything, no prediction is made
+ ^ Otherwise should be name of node which the client immediately places
+ on ground when the player places the item. Server will always update
+ actual result to client in a short moment.
on_place = func(itemstack, placer, pointed_thing),
+ ^ Shall place item and return the leftover itemstack
^ default: minetest.item_place
on_drop = func(itemstack, dropper, pos),
+ ^ Shall drop item and return the leftover itemstack
^ default: minetest.item_drop
on_use = func(itemstack, user, pointed_thing),
^ default: nil
^ The default functions handle regular use cases.
}
+Tile definition:
+- "image.png"
+- {name="image.png", animation={Tile Animation definition}}
+- {name="image.png", backface_culling=bool}
+ ^ backface culling only supported in special tiles
+- deprecated still supported field names:
+ - image -> name
+
+Tile animation definition:
+- {type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}
+
Node definition (register_node)
{
<all fields allowed in item definitions>,
- drawtype = "normal",
+ drawtype = "normal", -- See "Node drawtypes"
visual_scale = 1.0,
- tile_images = {"default_unknown_block.png"},
- special_materials = {
- {image="", backface_culling=true},
- {image="", backface_culling=true},
- },
+ tiles = {tile definition 1, def2, def3, def4, def5, def6},
+ ^ List can be shortened to needed length
+ ^ Old field name: tile_images
+ special_tiles = {tile definition 1, Tile definition 2},
+ ^ List can be shortened to needed length
+ ^ Old field name: special_materials
alpha = 255,
post_effect_color = {a=0, r=0, g=0, b=0},
paramtype = "none",
liquid_viscosity = 0,
light_source = 0,
damage_per_second = 0,
- selection_box = {type="regular"},
+ node_box = {type="regular"}, -- See "Node boxes"
+ selection_box = {type="regular"}, -- See "Node boxes"
legacy_facedir_simple = false, -- Support maps made in and before January 2012
legacy_wallmounted = false, -- Support maps made in and before January 2012
sounds = {
on_construct = func(pos),
^ Node constructor; always called after adding node
^ Can set up metadata and stuff like that
+ ^ default: nil
on_destruct = func(pos),
^ Node destructor; always called before removing node
+ ^ default: nil
+ after_destruct = func(pos, oldnode),
+ ^ Node destructor; always called after removing node
+ ^ default: nil
+
+ after_place_node = func(pos, placer),
+ ^ Called after constructing node when node was placed using
+ minetest.item_place_node / minetest.env:place_node
+ ^ default: nil
+ after_dig_node = func(pos, oldnode, oldmetadata, digger),
+ ^ oldmetadata is in table format
+ ^ Called after destructing node when node was dug using
+ minetest.node_dig / minetest.env:dig_node
+ ^ default: nil
+ can_dig = function(pos,player)
+ ^ returns true if node can be dug, or false if not
+ ^ default: nil
on_punch = func(pos, node, puncher),
^ default: minetest.node_punch
^ default: minetest.node_metadata_inventory_take_allow_all
}
-Recipe: (register_craft)
+Recipe for register_craft: (shaped)
{
output = 'default:pick_stone',
recipe = {
{'default:cobble', 'default:cobble', 'default:cobble'},
{'', 'default:stick', ''},
- {'', 'default:stick', ''},
+ {'', 'default:stick', ''}, -- Also groups; eg. 'group:crumbly'
},
replacements = <optional list of item pairs,
replace one input item with another item on crafting>
}
-Recipe (shapeless):
+Recipe for register_craft (shapeless)
{
type = "shapeless",
output = 'mushrooms:mushroom_stew',
replace one input item with another item on crafting>
}
-Recipe (tool repair):
+Recipe for register_craft (tool repair)
{
type = "toolrepair",
additional_wear = -0.02,
}
-Recipe (cooking):
+Recipe for register_craft (cooking)
{
type = "cooking",
output = "default:glass",
cooktime = 3,
}
-Recipe (furnace fuel):
+Recipe for register_craft (furnace fuel)
{
type = "fuel",
recipe = "default:leaves",