-Minetest Lua Modding API Reference 0.4.0
+Minetest Lua Modding API Reference 0.4.4
==========================================
More information at http://c55.me/minetest/
Groups in crafting recipes
---------------------------
-An example:
+An example: Make meat soup from any meat, any water and any bowl
{
output = 'food:meat_soup_raw',
recipe = {
{'group:water'},
{'group:bowl'},
},
- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
+ -- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
+}
+An another example: Make red wool from white wool and red dye
+{
+ type = 'shapeless',
+ output = 'wool:red',
+ recipe = {'wool:white', 'group:dye,basecolor_red'},
}
Special groups
- 2: node is removed without tool wear after 0.5 seconds or so
(rail, sign)
- 3: node is removed without tool wear immediately (torch)
+- disable_jump: Player (and possibly other things) cannot jump from node
+- fall_damage_add_percent: damage speed = speed * (1 + value/100)
+- bouncy: value is bounce speed in percent
+- falling_node: if there is no walkable block under the node it will fall
+- attached_node: if the node under it is not a walkable block the node will be
+ dropped as an item. If the node is wallmounted the
+ wallmounted direction is checked.
Known damage and digging time defining groups
----------------------------------------------
^ Show an image
^ Position and size units are inventory slots
+item_image[<X>,<Y>;<W>,<H>;<item name>]
+^ Show an inventory image of registered item/node
+^ Position and size units are inventory slots
+
+background[<X>,<Y>;<W>,<H>;<texture name>]
+^ Use a background. Inventory rectangles are not drawn then.
+^ Position and size units are inventory slots
+^ Example for formspec 8x4 in 16x resolution: image shall be sized 8*16px x 4*16px
+
field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
^ Textual field; will be sent to server when a button is clicked
^ x and y position the field relative to the top left of the menu
^ image is the filename of an image
^ Position and size units are inventory slots
+item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
+^ x, y, w, h, name and label work as per button
+^ item name is the registered name of an item/node,
+ tooltip will be made out of its descritption
+^ Position and size units are inventory slots
+
button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]
^ When clicked, fields will be sent and the form will quit.
Global callback registration functions: (Call these only at load time)
minetest.register_globalstep(func(dtime))
^ Called every server step, usually interval of 0.05s
-minetest.register_on_placenode(func(pos, newnode, placer, oldnode))
+minetest.register_on_shutdown(func())
+^ Called before server shutdown
+^ WARNING: If the server terminates abnormally (i.e. crashes), the registered
+ callbacks WILL LIKELY NOT BE RUN. Data should be saved at
+ semi-frequent intervals as well as on server shutdown.
+minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack))
^ Called when a node has been placed
+^ If return true no item is taken from itemstack
^ 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.
minetest.create_detached_inventory(name, callbacks) -> InvRef
^ callbacks: See "Detached inventory callbacks"
^ Creates a detached inventory. If it already exists, it is cleared.
+minetest.show_formspec(playername, formspec)
+^ playername: name of player to show formspec
+^ formspec: formspec to display
Item handling:
minetest.inventorycube(img1, img2, img3)
^ 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
+minetest.handle_node_drops(pos, drops, digger)
+^ drops: list of itemstrings
+^ Handles drops from nodes after digging: Default action is to put them into
+ digger's inventory
+^ Can be overridden to get different functionality (eg. dropping items on
+ ground)
+
+Rollbacks:
+minetest.rollback_get_last_node_actor(p, range, seconds) -> actor, p, seconds
+^ Find who has done something to a node, or near a node
+^ actor: "player:<name>", also "liquid".
+minetest.rollback_revert_actions_by(actor, seconds) -> bool, log messages
+^ Revert latest actions of someone
+^ actor: "player:<name>", also "liquid".
Defaults for the on_* item definition functions:
(These return the leftover itemstack)
^ Call function after time seconds
^ param is optional; to pass multiple parameters, pass a table.
+Server:
+minetest.request_shutdown() -> request for server shutdown
+minetest.get_server_status() -> server status string
+
+Bans:
+minetest.get_ban_list() -> ban list (same as minetest.get_ban_description(""))
+minetest.get_ban_description(ip_or_name) -> ban description (string)
+minetest.ban_player(name) -> ban a player
+minetest.unban_player_or_ip(name) -> unban player or IP address
+
Random:
minetest.get_connected_players() -> list of ObjectRefs
minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
- get_perlin(seeddiff, octaves, persistence, scale)
^ Return world-specific perlin noise (int(worldseed)+seeddiff)
+- clear_objects()
+ ^ clear all objects in the environments
+- spawn_tree (pos, {treedef})
+ ^ spawns L-System tree at given pos with definition in treedef table
+ treedef={
+ axiom, - string initial tree axiom
+ rules_a, - string rules set A
+ rules_b, - string rules set B
+ rules_c, - string rules set C
+ rules_d, - string rules set D
+ trunk, - string trunk node name
+ leaves, - string leaves node name
+ angle, - num angle in deg
+ iterations, - num max # of iterations, usually 2 -5
+ random_level, - num factor to lower nr of iterations, usually 0 - 3
+ thin_trunks, - boolean true -> use thin trunks
+ fruit_tree, - boolean true -> is a fruit tree
+ fruit - string fruit node name
+ }
+
+ Key for Special L-System Symbols used in Axioms
+ G - move forward one unit with the pin down
+ F - move forward one unit with the pin up
+ A - replace with rules set A
+ B - replace with rules set B
+ C - replace with rules set C
+ D - replace with rules set D
+ a - replace with rules set A, chance 90%
+ b - replace with rules set B, chance 80%
+ c - replace with rules set C, chance 70%
+ d - replace with rules set D, chance 60%
+ + - yaw the turtle right by angle parameter
+ - - yaw the turtle left by angle parameter
+ & - pitch the turtle down by angle parameter
+ ^ - pitch the turtle up by angle parameter
+ / - roll the turtle to the right by angle parameter
+ * - roll the turtle to the left by angle parameter
+ [ - save in stack current state info
+ ] - recover from stack state info
+
+ Example usage: spawn small apple tree
+ apple_tree={
+ axiom="FFFFFAFFBF",
+ rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
+ rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
+ trunk="default:tree",
+ leaves="default:leaves",
+ angle=30,
+ iterations=2,
+ random_level=0,
+ thin_trunks=true,
+ fruit_tree=true,
+ fruit="default:apple"
+ }
+ minetest.env:spawn_tree(pos,apple_tree)
+
Deprecated:
- add_rat(pos): Add C++ rat object (no-op)
- add_firefly(pos): Add C++ firefly object (no-op)
- punch(puncher, time_from_last_punch, tool_capabilities, direction)
^ puncher = an another ObjectRef,
^ time_from_last_punch = time since last punch action of the puncher
+ ^ direction: can be nil
- right_click(clicker); clicker = an another ObjectRef
- get_hp(): returns number of hitpoints (2 * number of hearts)
- set_hp(hp): set number of hitpoints (2 * number of hearts)
- get_wielded_item() -> ItemStack
- set_wielded_item(item): replaces the wielded item, returns true if successful
- set_armor_groups({group1=rating, group2=rating, ...})
+- set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)
+- set_attach(parent, "", {x=0,y=0,z=0}, {x=0,y=0,z=0})
+- set_detach()
+- set_bone_position("", {x=0,y=0,z=0}, {x=0,y=0,z=0})
- set_properties(object property table)
LuaEntitySAO-only: (no-op for other objects)
- setvelocity({x=num, y=num, z=num})
^ Redefine player's inventory form
^ Should usually be called in on_joinplayer
- get_inventory_formspec() -> formspec string
-
+- get_player_control(): returns table with player pressed keys
+ {jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}
+- get_player_control_bits(): returns integer with bit packed player pressed keys
+ bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
+
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_width(listname): get width of a list
+- set_width(listname, width): set width of list; currently used for crafting
- get_stack(listname, i): get a copy of stack index i in list
- set_stack(listname, i, stack): copy stack to index i in list
- get_list(listname): return full list
physical = true,
weight = 5,
collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
- visual = "cube"/"sprite"/"upright_sprite",
+ visual = "cube"/"sprite"/"upright_sprite"/"mesh",
visual_size = {x=1, y=1},
+ mesh = "model",
textures = {}, -- number of required textures depends on visual
+ colors = {}, -- number of required colors depends on visual
spritediv = {x=1, y=1},
initial_sprite_basepos = {x=0, y=0},
is_visible = true,
initial_properties = <initial object properties>,
- on_activate = function(self, staticdata),
+ on_activate = function(self, staticdata, dtime_s),
on_step = function(self, dtime),
on_punch = function(self, hitter),
on_rightclick = function(self, clicker),
liquid_alternative_flowing = "", -- Flowing version of source liquid
liquid_alternative_source = "", -- Source version of flowing liquid
liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
+ liquid_renewable = true, -- Can new liquid source be created by placing
+ two or more sources nearly?
light_source = 0, -- Amount of light emitted by node
damage_per_second = 0, -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes"
^ Node destructor; always called after removing node
^ default: nil
- after_place_node = func(pos, placer),
+ after_place_node = func(pos, placer, itemstack),
^ Called after constructing node when node was placed using
minetest.item_place_node / minetest.env:place_node
+ ^ If return true no item is taken from itemstack
^ default: nil
after_dig_node = func(pos, oldnode, oldmetadata, digger),
^ oldmetadata is in table format
allow_metadata_inventory_put = func(pos, listname, index, stack, player),
^ Called when a player wants to put something into the inventory
^ Return value: number of items allowed to put
+ ^ Return value: -1: Allow and don't modify item count in inventory
- allow_metadata_inventory_take = func(pos, listname, index, count, player),
+ allow_metadata_inventory_take = func(pos, listname, index, stack, player),
^ Called when a player wants to take something out of the inventory
^ Return value: number of items allowed to take
+ ^ Return value: -1: Allow and don't modify item count in inventory
on_metadata_inventory_move = func(pos, from_list, from_index,
to_list, to_index, count, player),
on_metadata_inventory_put = func(pos, listname, index, stack, player),
- on_metadata_inventory_take = func(pos, listname, index, count, player),
+ on_metadata_inventory_take = func(pos, listname, index, stack, player),
^ Called after the actual action has happened, according to what was allowed.
^ No return value
+
+ on_blast = func(pos, intensity),
+ ^ intensity: 1.0 = mid range of regular TNT
+ ^ If defined, called when an explosion touches the node, instead of
+ removing the node
}
Recipe for register_craft: (shaped)
allow_put = func(inv, listname, index, stack, player),
^ Called when a player wants to put something into the inventory
^ Return value: number of items allowed to put
+ ^ Return value: -1: Allow and don't modify item count in inventory
- allow_take = func(inv, listname, index, count, player),
+ allow_take = func(inv, listname, index, stack, player),
^ Called when a player wants to take something out of the inventory
^ Return value: number of items allowed to take
+ ^ Return value: -1: Allow and don't modify item count in inventory
on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
on_put = func(inv, listname, index, stack, player),
- on_take = func(inv, listname, index, count, player),
+ on_take = func(inv, listname, index, stack, player),
^ Called after the actual action has happened, according to what was allowed.
^ No return value
}