-Minetest Lua Modding API Reference 0.4.7
+Minetest Lua Modding API Reference 0.4.9
========================================
More information at http://www.minetest.net/
Developer Wiki: http://dev.minetest.net/
mods
|-- modname
| |-- depends.txt
+| |-- screenshot.png
+| |-- description.txt
| |-- init.lua
| |-- textures
| | |-- modname_stuff.png
to a single modname. Their meaning is that if the specified mod
is missing, that does not prevent this mod from being loaded.
-optdepends.txt:
- An alternative way of specifying optional dependencies.
- Like depends.txt, a single line contains a single modname.
+screenshot.png:
+ A screenshot shown in modmanager within mainmenu.
- NOTE: This file exists for compatibility purposes only and
- support for it will be removed from the engine by the end of 2013.
+description.txt:
+ File containing desctiption to be shown within mainmenu.
init.lua:
The main Lua script. Running this script should register everything it
vector.length(v) -> number
vector.normalize(v) -> vector
vector.round(v) -> vector
-vector.equal(v1, v2) -> bool
+vector.equals(v1, v2) -> bool
For the folowing x can be either a vector or a number.
vector.add(v, x) -> vector
vector.subtract(v, x) -> vector
^ Convert position to a printable string
minetest.string_to_pos(string) -> position
^ Same but in reverse
+minetest.formspec_escape(string) -> string
^ escapes characters [ ] \ , ; that can not be used in formspecs
minetest.is_yes(arg)
^ returns whether arg can be interpreted as yes
^ 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_prejoinplayer(func(name, ip))
+^ Called before a player joins the game
+^ If it returns a string, the player is disconnected with that string as reason
minetest.register_on_joinplayer(func(ObjectRef))
^ Called when a player joins the game
minetest.register_on_leaveplayer(func(ObjectRef))
minetest.set_node(pos, node)
minetest.add_node(pos, node): alias set_node(pos, node)
^ Set node at position (node = {name="foo", param1=0, param2=0})
+minetest.swap_node(pos, node)
+^ Set node at position, but don't remove metadata
minetest.remove_node(pos)
^ Equivalent to set_node(pos, "air")
minetest.get_node(pos)
^ Return world-specific perlin noise (int(worldseed)+seeddiff)
minetest.get_voxel_manip()
^ Return voxel manipulator object
+minetest.set_gen_notify(flags)
+^ Set the types of on-generate notifications that should be collected
+^ flags is a comma-delimited combination of:
+^ dungeon, temple, cave_begin, cave_end, large_cave_begin, large_cave_end
minetest.get_mapgen_object(objectname)
^ Return requested mapgen object if available (see Mapgen objects)
minetest.set_mapgen_params(MapgenParams)
^ flags and flagmask are in the same format and have the same options as 'mgflags' in minetest.conf
minetest.clear_objects()
^ clear all objects in the environments
-minetest.line_of_sight(pos1,pos2,stepsize) ->true/false
-^ checkif there is a direct line of sight between pos1 and pos2
+minetest.line_of_sight(pos1, pos2, stepsize) -> true/false, pos
+^ Check if there is a direct line of sight between pos1 and pos2
+^ Returns the position of the blocking node when false
^ pos1 First position
^ pos2 Second position
^ stepsize smaller gives more accurate results but requires more computing
^ 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
+Rollback:
+minetest.rollback_get_node_actions(pos, range, seconds, limit) -> {{actor, pos, time, oldnode, newnode}, ...}
^ 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
^ otherwise on all clients
Schematics:
-minetest.create_schematic(p1, p2, probability_list, filename)
+minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)
^ Create a schematic from the volume of map specified by the box formed by p1 and p2.
^ Apply the specified probability values to the specified nodes in probability_list.
^ probability_list is an array of tables containing two fields, pos and prob.
^ If there are two or more entries with the same pos value, the last occuring in the array is used.
^ If pos is not inside the box formed by p1 and p2, it is ignored.
^ If probability_list is nil, no probabilities are applied.
+ ^ Slice probability works in the same manner, except takes a field called ypos instead which indicates
+ ^ the y position of the slice with a probability applied.
+ ^ If slice probability list is nil, no slice probabilities are applied.
^ Saves schematic in the Minetest Schematic format to filename.
minetest.place_schematic(pos, schematic, rotation, replacements)
^ nullvalue: returned in place of the JSON null; defaults to nil
^ On success returns a table, a string, a number, a boolean or nullvalue
^ On failure outputs an error message and returns nil
-^ Example: parse_json("[10, {\"a\":false}]") -> {[1] = 10, [2] = {a = false}}
+^ Example: parse_json("[10, {\"a\":false}]") -> {10, {a = false}}
+minetest.write_json(data[, styled]) -> string or nil and error message
+^ Convert a Lua table into a JSON string
+^ styled: Outputs in a human-readable format if this is set, defaults to false
+^ Un-serializable things like functions and userdata are saved as null.
+^ Warning: JSON is more strict than the Lua table format.
+ 1. You can only use strings and positive integers of at least one as keys.
+ 2. You can not mix string and integer keys.
+ This is due to the fact that Javascript has two distinct array and object values.
+^ Example: write_json({10, {a = false}}) -> "[10, {\"a\": false}]"
minetest.serialize(table) -> string
^ Convert a table containing tables, strings, numbers, booleans and nils
into string form readable by minetest.deserialize
force_facedir: if true, forcably reset the facedir to north when placing on
the floor or ceiling
+minetest.rotate_node(itemstack, placer, pointed_thing)
+^ calls rotate_and_place() with infinitestacks set according to the state of
+ the creative mode setting, and checks for "sneak" to set the invert_wall
+ parameter.
+
Global objects:
minetest.env - EnvRef of the server environment and world.
^ Any function in the minetest namespace can be called using the syntax
{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
-- set_physics_override(speed, jump, gravity)
- modifies per-player walking speed, jump height, and gravity.
- Values default to 1 and act as offsets to the physics settings
- in minetest.conf. nil will keep the current setting.
+- set_physics_override({
+ speed = 1.0, -- multiplier to default value
+ jump = 1.0, -- multiplier to default value
+ gravity = 1.0, -- multiplier to default value
+ sneak = true, -- whether player can sneak
+ sneak_glitch = true, -- whether player can use the sneak glitch
+ })
- hud_add(hud definition): add a HUD element described by HUD def, returns ID number on success
- hud_remove(id): remove the HUD element of the specified id
- hud_change(id, stat, value): change a value of a previously added HUD element
- 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
+ ^ returns false on error (e.g. invalid listname or listsize)
- 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
- update_map(): Update map after writing chunk back to map.
^ To be used only by VoxelManip objects created by the mod itself; not a VoxelManip that was
^ retrieved from minetest.get_mapgen_object
-- set_lighting(light): Set the lighting within the VoxelManip
+- set_lighting(light, p1, p2): Set the lighting within the VoxelManip to a uniform value
^ light is a table, {day=<0...15>, night=<0...15>}
^ To be used only by a VoxelManip object from minetest.get_mapgen_object
-- calc_lighting(): Calculate lighting within the VoxelManip
+ ^ (p1, p2) is the area in which lighting is set; defaults to the whole area if left out
+- get_light_data(): Gets the light data read into the VoxelManip object
+ ^ Returns an array (indicies 1 to volume) of integers ranging from 0 to 255
+ ^ Each value is the bitwise combination of day and night light values (0..15 each)
+ ^ light = day + (night * 16)
+- set_light_data(light_data): Sets the param1 (light) contents of each node in the VoxelManip
+ ^ expects lighting data in the same format that get_light_data() returns
+- calc_lighting(p1, p2): Calculate lighting within the VoxelManip
^ To be used only by a VoxelManip object from minetest.get_mapgen_object
+ ^ (p1, p2) is the area in which lighting is set; defaults to the whole area if left out
- update_liquids(): Update liquid flow
VoxelArea: A helper class for voxel areas
Returns an array containing the humidity values of nodes in the most recently generated chunk by the
current mapgen.
+- gennotify
+ Returns a table mapping requested generation notification types to arrays of positions at which the
+corresponding generated structures are located at within the current chunk. To set the capture of positions
+of interest to be recorded on generate, use minetest.set_gen_notify().
+Possible fields of the table returned are: dungeon, temple, cave_begin, cave_end, large_cave_begin, large_cave_end
+
Registered entities
--------------------
- Functions receive a "luaentity" as self:
collide_with_objects = true, -- collide with other objects if physical=true
weight = 5,
collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
- visual = "cube"/"sprite"/"upright_sprite"/"mesh",
+ visual = "cube"/"sprite"/"upright_sprite"/"mesh"/"wielditem",
visual_size = {x=1, y=1},
mesh = "model",
textures = {}, -- number of required textures depends on visual
^ Node destructor; always called after removing node
^ default: nil
- after_place_node = func(pos, placer, itemstack),
+ after_place_node = func(pos, placer, itemstack, pointed_thing),
^ Called after constructing node when node was placed using
minetest.item_place_node / minetest.place_node
^ If return true no item is taken from itemstack