1 Minetest Lua Modding API Reference 0.4.dev
2 ==========================================
3 More information at http://c55.me/minetest/
7 Content and functionality can be added to Minetest 0.4 by using Lua
8 scripting in run-time loaded mods.
10 A mod is a self-contained bunch of scripts, textures and other related
11 things that is loaded by and interfaces with Minetest.
13 Mods are contained and ran solely on the server side. Definitions and media
14 files are automatically transferred to the client.
16 If you see a deficiency in the API, feel free to attempt to add the
17 functionality in the engine and API. You can send such improvements as
18 source code patches to <celeron55@gmail.com>.
22 If you have any difficulty in understanding this, please read:
23 http://www.lua.org/pil/
27 Mods are loaded during server startup from the mod load paths by running
33 $path_share/games/gameid/mods/
34 $path_share/mods/gameid/
35 $path_user/games/gameid/mods/
36 $path_user/mods/gameid/ <-- User-installed mods
39 In a run-in-place version (eg. the distributed windows version):
40 minetest-0.4.x/games/gameid/mods/
41 minetest-0.4.x/mods/gameid/ <-- User-installed mods
42 minetest-0.4.x/worlds/worldname/worldmods/
44 On an installed version on linux:
45 /usr/share/minetest/games/gameid/mods/
46 ~/.minetest/mods/gameid/ <-- User-installed mods
47 ~/.minetest/worlds/worldname/worldmods
49 Mod directory structure
50 ------------------------
56 | | |-- modname_stuff.png
57 | | `-- modname_something_else.png
64 The location of this directory can be fetched by using
65 minetest.get_modpath(modname)
68 List of mods that have to be loaded before loading this mod.
69 A single line contains a single modname.
72 The main Lua script. Running this script should register everything it
73 wants to register. Subsequent execution depends on minetest calling the
76 minetest.setting_get(name) and minetest.setting_getbool(name) can be used
77 to read custom or existing settings at load time, if necessary.
79 textures, sounds, media:
80 Media files (textures, sounds, whatever) that will be transferred to the
81 client and will be available for use by the mod.
83 Naming convention for registered textual names
84 ----------------------------------------------
85 Registered names should generally be in this format:
86 "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
88 This is to prevent conflicting names from corrupting maps and is
89 enforced by the mod loader.
91 Example: mod "experimental", ideal item/node/entity name "tnt":
92 -> the name should be "experimental:tnt".
94 Enforcement can be overridden by prefixing the name with ":". This can
95 be used for overriding the registrations of some other mod.
97 Example: Any mod can redefine experimental:tnt by using the name
98 ":experimental:tnt" when registering it.
99 (also that mod is required to have "experimental" as a dependency)
101 The ":" prefix can also be used for maintaining backwards compatibility.
105 Aliases can be added by using minetest.register_alias(name, convert_to)
107 This will make Minetest to convert things called name to things called
110 This can be used for maintaining backwards compatibility.
112 This can be also used for setting quick access names for things, eg. if
113 you have an item called epiclylongmodname:stuff, you could do
114 minetest.register_alias("stuff", "epiclylongmodname:stuff")
115 and be able to use "/giveme stuff".
119 Mods should generally prefix their textures with modname_, eg. given
120 the mod name "foomod", a texture could be called
121 "foomod_foothing.png"
123 Textures are referred to by their complete name, or alternatively by
124 stripping out the file extension:
125 eg. foomod_foothing.png
130 Only OGG files are supported.
132 For positional playing of sounds, only single-channel (mono) files are
133 supported. Otherwise OpenAL will play them non-positionally.
135 Mods should generally prefix their sounds with modname_, eg. given
136 the mod name "foomod", a sound could be called
137 "foomod_foosound.ogg"
139 Sounds are referred to by their name with a dot, a single digit and the
140 file extension stripped out. When a sound is played, the actual sound file
141 is chosen randomly from the matching sounds.
143 When playing the sound "foomod_foosound", the sound is chosen randomly
144 from the available ones of the following files:
146 foomod_foosound.0.ogg
147 foomod_foosound.1.ogg
149 foomod_foosound.9.ogg
151 Examples of sound parameter tables:
152 -- Play locationless on all clients
154 gain = 1.0, -- default
156 -- Play locationless to a player
159 gain = 1.0, -- default
161 -- Play in a location
164 gain = 1.0, -- default
165 max_hear_distance = 32, -- default
167 -- Play connected to an object, looped
169 object = <an ObjectRef>,
170 gain = 1.0, -- default
171 max_hear_distance = 32, -- default
172 loop = true, -- only sounds connected to objects can be looped
177 Nodes are the bulk data of the world: cubes and other things that take the
178 space of a cube. Huge amounts of them are handled efficiently, but they
181 The definition of a node is stored and can be accessed by name in
182 minetest.registered_nodes[node.name]
184 Please note that for unknown nodes (eg. a node of an uninstalled mod) the
185 minetest.registered_nodes field for the node is nil.
187 Nodes are passed by value in Lua. They are represented by a table:
188 {name="name", param1=num, param2=num}
190 param1 and param2 are 8 bit and 4 bit integers, respectively. The engine
191 uses them for certain automated functions. If you don't use these
192 functions, you can use them to store arbitrary values.
194 The functions of param1 and param2 are determined by certain fields in the
196 param1 is reserved for the engine when paramtype != "none":
198 ^ The value stores light with and without sun in it's
199 upper and lower 4 bits.
200 param2 is reserved for the engine when any of these are used:
201 liquidtype == "flowing"
202 ^ The level and some flags of the liquid is stored in param2
203 drawtype == "flowingliquid"
204 ^ The drawn liquid level is read from param2
205 drawtype == "torchlike"
206 drawtype == "signlike"
207 paramtype2 == "wallmounted"
208 ^ The rotation of the node is stored in param2. You can make this value
209 by using minetest.dir_to_wallmounted().
210 paramtype2 == "facedir"
211 ^ The rotation of the node is stored in param2. Furnaces and chests are
212 rotated this way. Can be made by using minetest.dir_to_facedir().
214 Representations of simple things
215 --------------------------------
217 {x=num, y=num, z=num}
218 Currently the API does not provide any helper functions for addition,
219 subtraction and whatever; you can define those that you need yourself.
221 stackstring/itemstring: A stack of items in serialized format.
223 eg. 'default:pick_wood 21323'
226 item: A stack of items in Lua table format.
227 eg. {name="default:dirt", count=5, wear=0, metadata=""}
229 eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
230 ^ a wooden pick about 1/3 weared out
231 eg. {name="default:apple", count=1, wear=0, metadata=""}
234 Any time an item must be passed to a function, it can be an
235 ItemStack (see below), an itemstring or a table in the above format.
239 eg. "default_place_node"
241 eg. {name="default_place_node"}
242 eg. {name="default_place_node", gain=1.0}
246 Node (register_node):
247 A node from the world
248 Tool (register_tool):
249 A tool/weapon that can dig and damage things according to tool_capabilities
250 Craftitem (register_craftitem):
255 In a number of places, there is a group table. Groups define the
256 properties of a thing (item, node, armor of entity, capabilities of
257 tool) in such a way that the engine and other mods can can interact with
258 the thing without actually knowing what the thing is.
261 - Groups are stored in a table, having the group names with keys and the
262 group ratings as values. For example:
263 groups = {crumbly=3, soil=1}
264 ^ Default dirt (soil group actually currently not defined; TODO)
265 groups = {crumbly=2, soil=1, level=2, outerspace=1}
266 ^ A more special dirt-kind of thing
267 - Groups always have a rating associated with them. If there is no
268 useful meaning for a rating for an enabled group, it shall be 1.
269 - When not defined, the rating of a group defaults to 0. Thus when you
270 read groups, you must interpret nil and 0 as the same value, 0.
274 Groups of items can define what kind of an item it is (eg. wool).
278 In addition to the general item things, groups are used to define whether
279 a node is destroyable and how long it takes to destroy by a tool.
283 For entities, groups are, as of now, used only for calculating damage.
285 object.get_armor_groups() -> a group-rating table (eg. {fleshy=3})
286 object.set_armor_groups({level=2, fleshy=2, cracky=2})
290 Groups in tools define which groups of nodes and entities they are
293 Groups in crafting recipes
294 ---------------------------
295 - Not implemented yet. (TODO)
296 - Will probably look like this:
298 output = 'food:meat_soup_raw',
304 preserve = {'group:bowl'},
309 - immortal: Disables the group damage system for an entity
310 - level: Can be used to give an additional sense of progression in the game.
311 - A larger level will cause eg. a weapon of a lower level make much less
312 damage, and get weared out much faster, or not be able to get drops
313 from destroyed nodes.
314 - 0 is something that is directly accessible at the start of gameplay
315 - There is no upper limit
316 - dig_immediate: (player can always pick up node without tool wear)
317 - 2: node is removed without tool wear after 0.5 seconds or so
319 - 3: node is removed without tool wear immediately (torch)
321 Known damage and digging time defining groups
322 ----------------------------------------------
323 Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.
324 - crumbly: dirt, sand
325 - cracky: tough but crackable stuff like stone.
326 - snappy: something that can be cut using fine tools; eg. leaves, small
327 plants, wire, sheets of metal
328 - choppy: something that can be cut using force; eg. trees, wooden planks
329 - fleshy: Living things like animals and the player. This could imply
330 some blood effects when hitting.
331 - explody: Especially prone to explosions
332 - oddly_breakable_by_hand:
333 Can be added to nodes that shouldn't logically be breakable by the
334 hand but are. Somewhat similar to dig_immediate, but times are more
335 like {[1]=3.50,[2]=2.00,[3]=0.70} and this does not override the
336 speed of a tool if the tool can dig at a larger speed than this
337 suggests for the hand.
339 Examples of custom groups
340 --------------------------
341 Item groups are often used for defining, well, //groups of items//.
342 - meat: any meat-kind of a thing (rating might define the size or healing
343 ability or be irrelevant - it is not defined as of yet)
344 - eatable: anything that can be eaten. Rating might define HP gain in half
346 - flammable: can be set on fire. Rating might define the intensity of the
347 fire, affecting eg. the speed of the spreading of an open fire.
348 - wool: any wool (any origin, any color)
351 - heavy: anything considerably heavy
353 Digging time calculation specifics
354 -----------------------------------
355 Groups such as **crumbly**, **cracky** and **snappy** are used for this
356 purpose. Rating is 1, 2 or 3. A higher rating for such a group implies
359 The **level** group is used to limit the toughness of nodes a tool can dig
360 and to scale the digging times / damage to a greater extent.
362 ^ PLEASE DO UNDERSTAND THIS, otherwise you cannot use the system to it's
365 Tools define their properties by a list of parameters for groups. They
366 cannot dig other groups; thus it is important to use a standard bunch of
367 groups to enable interaction with tools.
370 * Full punch interval
372 * For an arbitrary list of groups:
373 * Uses (until the tool breaks)
374 * Maximum level (usually 0, 1, 2 or 3)
377 **Full punch interval**:
378 When used as a weapon, the tool will do full damage if this time is spent
379 between punches. If eg. half the time is spent, the tool will do half
382 **Maximum drop level**
383 Suggests the maximum level of node, when dug with the tool, that will drop
384 it's useful item. (eg. iron ore to drop a lump of iron).
385 - This is not automated; it is the responsibility of the node definition
389 Determines how many uses the tool has when it is used for digging a node,
390 of this group, of the maximum level. For lower leveled nodes, the use count
391 is multiplied by 3^leveldiff.
392 - uses=10, leveldiff=0 -> actual_uses=10
393 - uses=10, leveldiff=1 -> actual_uses=30
394 - uses=10, leveldiff=2 -> actual_uses=90
397 Tells what is the maximum level of a node of this group that the tool will
401 List of digging times for different ratings of the group, for nodes of the
403 * For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
404 result the tool to be able to dig nodes that have a rating of 2 or 3
405 for this group, and unable to dig the rating 1, which is the toughest.
406 Unless there is a matching group that enables digging otherwise.
407 * For entities, damage equals the amount of nodes dug in the time spent
408 between hits, with a maximum time of ''full_punch_interval''.
410 Example definition of the capabilities of a tool
411 -------------------------------------------------
412 tool_capabilities = {
413 full_punch_interval=1.5,
416 crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
420 This makes the tool be able to dig nodes that fullfill both of these:
421 - Have the **crumbly** group
422 - Have a **level** group less or equal to 2
424 Table of resulting digging times:
425 crumbly 0 1 2 3 4 <- level
431 level diff: 2 1 0 -1 -2
433 Table of resulting tool uses:
440 - At crumbly=0, the node is not diggable.
441 - At crumbly=3, the level difference digging time divider kicks in and makes
442 easy nodes to be quickly breakable.
443 - At level > 2, the node is not diggable, because it's level > maxlevel
445 Entity damage mechanism
446 ------------------------
448 - Take the time spent after the last hit
449 - Limit time to full_punch_interval
450 - Take the damage groups, assume a node has them
451 - Damage in HP is the amount of nodes destroyed in this time.
453 Client predicts damage based on damage groups. Because of this, it is able to
454 give an immediate response when an entity is damaged or dies; the response is
455 pre-defined somehow (eg. by defining a sprite animation) (not implemented;
457 - Currently a smoke puff will appear when an entity dies.
459 The group **immortal** will completely disable normal damage.
461 Entities can define a special armor group, which is **punch_operable**. This
462 group will disable the regular damage mechanism for players punching it by hand
465 On the Lua side, every punch calls ''entity:on_punch(puncher,
466 time_from_last_punch, tool_capabilities, direction)''. This should never be
467 called directly, because damage is usually not handled by the entity itself.
468 * ''puncher'' is the object performing the punch. Can be nil. Should never be
469 accessed unless absolutely required.
470 * ''time_from_last_punch'' is time from last punch (by puncher) or nil.
471 * ''tool_capabilities'' can be nil.
472 * ''direction'' is a unit vector, pointing from the source of the punch to
475 To punch an entity/object in Lua, call ''object:punch(puncher, time_from_last_punch, tool_capabilities, direction)''.
476 * Return value is tool wear.
477 * Parameters are equal to the above callback.
478 * If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
479 automatically filled in based on the location of ''puncher''.
483 dump2(obj, name="_", dumped={})
484 ^ Return object serialized as a string, handles reference loops
486 ^ Return object serialized as a string
487 string:split(separator)
488 ^ eg. string:split("a,b", ",") == {"a","b"}
490 ^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
491 minetest.pos_to_string({x=X,y=Y,z=Z}) -> "(X,Y,Z)"
492 ^ Convert position to a printable string
494 minetest namespace reference
495 -----------------------------
496 minetest.get_current_modname() -> string
497 minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
498 ^ Useful for loading additional .lua modules or static data from mod
499 minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
500 ^ Useful for storing custom data
501 minetest.is_singleplayer()
506 minetest.log(loglevel, line)
507 ^ loglevel one of "error", "action", "info", "verbose"
509 Registration functions: (Call these only at load time)
510 minetest.register_entity(name, prototype table)
511 minetest.register_abm(abm definition)
512 minetest.register_node(name, node definition)
513 minetest.register_tool(name, item definition)
514 minetest.register_craftitem(name, item definition)
515 minetest.register_alias(name, convert_to)
516 minetest.register_craft(recipe)
517 minetest.register_globalstep(func(dtime))
518 minetest.register_on_placenode(func(pos, newnode, placer))
519 minetest.register_on_dignode(func(pos, oldnode, digger))
520 minetest.register_on_punchnode(func(pos, node, puncher))
521 minetest.register_on_generated(func(minp, maxp, blockseed))
522 minetest.register_on_newplayer(func(ObjectRef))
523 minetest.register_on_dieplayer(func(ObjectRef))
524 minetest.register_on_respawnplayer(func(ObjectRef))
525 ^ return true in func to disable regular player placement
526 ^ currently called _before_ repositioning of player occurs
527 minetest.register_on_chat_message(func(name, message))
528 minetest.register_chatcommand(cmd, chatcommand definition)
529 minetest.register_privilege(name, definition)
530 ^ definition: "description text"
532 description = "description text",
533 give_to_singleplayer = boolean, -- default: true
535 minetest.register_authentication_handler(handler)
536 ^ See minetest.builtin_auth_handler in builtin.lua for reference
539 minetest.setting_set(name, value)
540 minetest.setting_get(name) -> string or nil
541 minetest.setting_getbool(name) -> boolean value or nil
542 minetest.add_to_creative_inventory(itemstring)
545 minetest.notify_authentication_modified(name)
546 ^ Should be called by the authentication handler if privileges change.
547 ^ To report everybody, set name=nil.
548 minetest.get_password_hash(name, raw_password)
549 ^ Convert a name-password pair to a password hash that minetest can use
550 minetest.string_to_privs(str) -> {priv1=true,...}
551 minetest.privs_to_string(privs) -> "priv1,priv2,..."
552 ^ Convert between two privilege representations
553 minetest.set_player_password(name, password_hash)
554 minetest.set_player_privs(name, {priv1=true,...})
555 minetest.get_player_privs(name) -> {priv1=true,...}
556 minetest.auth_reload()
557 ^ These call the authentication handler
558 minetest.check_player_privs(name, {priv1=true,...}) -> bool, missing_privs
559 ^ A quickhand for checking privileges
562 minetest.chat_send_all(text)
563 minetest.chat_send_player(name, text)
566 minetest.get_inventory(location) -> InvRef
567 ^ location = eg. {type="player", name="celeron55"}
568 {type="node", pos={x=, y=, z=}}
571 minetest.inventorycube(img1, img2, img3)
572 ^ Returns a string for making an image of a cube (useful as an item image)
573 minetest.get_pointed_thing_position(pointed_thing, above)
574 ^ Get position of a pointed_thing (that you can get from somewhere)
575 minetest.dir_to_facedir(dir)
576 ^ Convert a vector to a facedir value, used in param2 for paramtype2="facedir"
577 minetest.dir_to_wallmounted(dir)
578 ^ Convert a vector to a wallmounted value, used for paramtype2="wallmounted"
579 minetest.get_node_drops(nodename, toolname)
580 ^ Returns list of item names.
581 ^ Note: This will be removed or modified in a future version.
583 Defaults for the on_* item definition functions:
584 (These return the leftover itemstack)
585 minetest.item_place_node(itemstack, placer, pointed_thing)
586 ^ Place item as a node
587 minetest.item_place_object(itemstack, placer, pointed_thing)
589 minetest.item_place(itemstack, placer, pointed_thing)
590 ^ Use one of the above based on what the item is.
591 minetest.item_drop(itemstack, dropper, pos)
593 minetest.item_eat(hp_change, replace_with_item)
594 ^ Eat the item. replace_with_item can be nil.
596 Defaults for the on_punch and on_dig node definition callbacks:
597 minetest.node_punch(pos, node, puncher)
598 ^ Calls functions registered by minetest.register_on_punchnode()
599 minetest.node_dig(pos, node, digger)
600 ^ Checks if node can be dug, puts item into inventory, removes node
601 ^ Calls functions registered by minetest.registered_on_dignodes()
604 minetest.sound_play(spec, parameters) -> handle
605 ^ spec = SimpleSoundSpec
606 ^ parameters = sound parameter table
607 minetest.sound_stop(handle)
610 minetest.after(time, func, param)
611 ^ Call function after time seconds
612 ^ param is optional; to pass multiple parameters, pass a table.
615 minetest.get_connected_players() -> list of ObjectRefs
616 minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
617 ^ Gives a unique hash number for a node position (16+16+16=48bit)
620 minetest.env - environment reference
623 minetest.registered_items
624 ^ List of registered items, indexed by name
625 minetest.registered_nodes
626 ^ List of registered node definitions, indexed by name
627 minetest.registered_craftitems
628 ^ List of registered craft item definitions, indexed by name
629 minetest.registered_tools
630 ^ List of registered tool definitions, indexed by name
631 minetest.registered_entities
632 ^ List of registered entity prototypes, indexed by name
634 ^ List of object references, indexed by active object id
636 ^ List of lua entities, indexed by active object id
638 Deprecated but defined for backwards compatibility:
639 minetest.digprop_constanttime(time)
640 minetest.digprop_stonelike(toughness)
641 minetest.digprop_dirtlike(toughness)
642 minetest.digprop_gravellike(toughness)
643 minetest.digprop_woodlike(toughness)
644 minetest.digprop_leaveslike(toughness)
645 minetest.digprop_glasslike(toughness)
649 EnvRef: basically ServerEnvironment and ServerMap combined.
651 - set_node(pos, node)
652 - add_node(pos, node): alias set_node(pos, node)
653 - remove_node(pos): equivalent to set_node(pos, "air")
655 ^ Returns {name="ignore", ...} for unloaded area
656 - get_node_or_nil(pos)
657 ^ Returns nil for unloaded area
658 - get_node_light(pos, timeofday) -> 0...15 or nil
659 ^ timeofday: nil = current time, 0 = night, 0.5 = day
660 - add_entity(pos, name): Spawn Lua-defined entity at position
661 ^ Returns ObjectRef, or nil if failed
662 - add_item(pos, itemstring): Spawn item
663 ^ Returns ObjectRef, or nil if failed
664 - get_meta(pos) -- Get a NodeMetaRef at that position
665 - get_player_by_name(name) -- Get an ObjectRef to a player
666 - get_objects_inside_radius(pos, radius)
667 - set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
669 - find_node_near(pos, radius, nodenames) -> pos or nil
670 ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
671 - find_nodes_in_area(minp, maxp, nodenames) -> list of positions
672 ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
673 - get_perlin(seeddiff, octaves, persistence, scale)
674 ^ Return world-specific perlin noise (int(worldseed)+seeddiff)
676 - add_rat(pos): Add C++ rat object (no-op)
677 - add_firefly(pos): Add C++ firefly object (no-op)
679 NodeMetaRef (this stuff is subject to change in a future version)
682 - allows_text_input()
683 - set_text(text) -- eg. set the text of a sign
687 Generic node metadata specific:
688 - set_infotext(infotext)
689 - get_inventory() -> InvRef
690 - set_inventory_draw_spec(string)
691 - set_allow_text_input(bool)
692 - set_allow_removal(bool)
693 - set_enforce_owner(bool)
694 - is_inventory_modified()
695 - reset_inventory_modified()
697 - reset_text_modified()
698 - set_string(name, value)
701 ObjectRef: Moving things in the game are generally these
702 (basically reference to a C++ ServerActiveObject)
704 - remove(): remove object (after returning from Lua)
705 - getpos() -> {x=num, y=num, z=num}
706 - setpos(pos); pos={x=num, y=num, z=num}
707 - moveto(pos, continuous=false): interpolated move
708 - punch(puncher, time_from_last_punch, tool_capabilities, direction)
709 ^ puncher = an another ObjectRef,
710 ^ time_from_last_punch = time since last punch action of the puncher
711 - right_click(clicker); clicker = an another ObjectRef
712 - get_hp(): returns number of hitpoints (2 * number of hearts)
713 - set_hp(hp): set number of hitpoints (2 * number of hearts)
714 - get_inventory() -> InvRef
715 - get_wield_list(): returns the name of the inventory list the wielded item is in
716 - get_wield_index(): returns the index of the wielded item
717 - get_wielded_item() -> ItemStack
718 - set_wielded_item(item): replaces the wielded item, returns true if successful
719 - set_armor_groups({group1=rating, group2=rating, ...})
720 - set_properties(object property table)
721 LuaEntitySAO-only: (no-op for other objects)
722 - setvelocity({x=num, y=num, z=num})
723 - getvelocity() -> {x=num, y=num, z=num}
724 - setacceleration({x=num, y=num, z=num})
725 - getacceleration() -> {x=num, y=num, z=num}
727 - getyaw() -> radians
729 - setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
730 - select_horiz_by_yawpitch=false)
731 - ^ Select sprite from spritesheet with optional animation and DM-style
732 - texture selection based on yaw relative to camera
733 - get_entity_name() (DEPRECATED: Will be removed in a future version)
735 Player-only: (no-op for other objects)
736 - get_player_name(): will return nil if is not a player
737 - get_look_dir(): get camera direction as a unit vector
738 - get_look_pitch(): pitch in radians
739 - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
741 InvRef: Reference to an inventory
743 - get_size(listname): get size of a list
744 - set_size(listname, size): set size of a list
745 - get_stack(listname, i): get a copy of stack index i in list
746 - set_stack(listname, i, stack): copy stack to index i in list
747 - get_list(listname): return full list
748 - set_list(listname, list): set full list (size will not change)
749 - add_item(listname, stack): add item somewhere in list, returns leftover ItemStack
750 - room_for_item(listname, stack): returns true if the stack of items
751 can be fully added to the list
752 - contains_item(listname, stack): returns true if the stack of items
753 can be fully taken from the list
754 remove_item(listname, stack): take as many items as specified from the list,
755 returns the items that were actually removed (as an ItemStack)
757 ItemStack: A stack of items.
758 - Can be created via ItemStack(itemstack or itemstring or table or nil)
760 - is_empty(): return true if stack is empty
761 - get_name(): returns item name (e.g. "default:stone")
762 - get_count(): returns number of items on the stack
763 - get_wear(): returns tool wear (0-65535), 0 for non-tools
764 - get_metadata(): returns metadata (a string attached to an item stack)
765 - clear(): removes all items from the stack, making it empty
766 - replace(item): replace the contents of this stack (item can also
767 be an itemstring or table)
768 - to_string(): returns the stack in itemstring form
769 - to_table(): returns the stack in Lua table form
770 - get_stack_max(): returns the maximum size of the stack (depends on the item)
771 - get_free_space(): returns get_stack_max() - get_count()
772 - is_known(): returns true if the item name refers to a defined item type
773 - get_definition(): returns the item definition table
774 - get_tool_capabilities(): returns the digging properties of the item,
775 ^ or those of the hand if none are defined for this item type
776 - add_wear(amount): increases wear by amount if the item is a tool
777 - add_item(item): put some item or stack onto this stack,
778 ^ returns leftover ItemStack
779 - item_fits(item): returns true if item or stack can be fully added to this one
780 - take_item(n): take (and remove) up to n items from this stack
781 ^ returns taken ItemStack
782 ^ if n is omitted, n=1 is used
783 - peek_item(n): copy (don't remove) up to n items from this stack
784 ^ returns copied ItemStack
785 ^ if n is omitted, n=1 is used
787 PseudoRandom: A pseudorandom number generator
788 - Can be created via PseudoRandom(seed)
790 - next(): return next integer random number [0...32767]
791 - next(min, max): return next integer random number [min...max]
792 (max - min) must be 32767 or <= 6553 due to the simple
793 implementation making bad distribution otherwise.
795 PerlinNoise: A perlin noise generator
796 - Can be created via PerlinNoise(seed, octaves, persistence, scale)
797 - Also minetest.env:get_perlin(seeddiff, octaves, persistence, scale)
799 - get2d(pos) -> 2d noise value at pos={x=,y=}
800 - get3d(pos) -> 3d noise value at pos={x=,y=,z=}
804 - Functions receive a "luaentity" as self:
805 - It has the member .name, which is the registered name ("mod:thing")
806 - It has the member .object, which is an ObjectRef pointing to the object
807 - The original prototype stuff is visible directly via a metatable
809 - on_activate(self, staticdata)
810 ^ Called when the object is instantiated.
811 - on_step(self, dtime)
812 ^ Called on every server tick (dtime is usually 0.05 seconds)
813 - on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
814 ^ Called when somebody punches the object.
815 ^ Note that you probably want to handle most punches using the
816 automatic armor group system.
817 ^ puncher: ObjectRef (can be nil)
818 ^ time_from_last_punch: Meant for disallowing spamming of clicks (can be nil)
819 ^ tool_capabilities: capability table of used tool (can be nil)
820 ^ dir: unit vector of direction of punch. Always defined. Points from
821 the puncher to the punched.
822 - on_rightclick(self, clicker)
823 - get_staticdata(self)
824 ^ Should return a string that will be passed to on_activate when
825 the object is instantiated the next time.
833 collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
834 visual = "cube"/"sprite"/"upright_sprite",
835 visual_size = {x=1, y=1},
836 textures = {}, -- number of required textures depends on visual
837 spritediv = {x=1, y=1},
838 initial_sprite_basepos = {x=0, y=0},
840 makes_footstep_sound = false,
843 Entity definition (register_entity)
845 (Deprecated: Everything in object properties is read directly from here)
847 initial_properties = <initial object properties>,
849 on_activate = function(self, staticdata),
850 on_step = function(self, dtime),
851 on_punch = function(self, hitter),
852 on_rightclick = function(self, clicker),
853 get_staticdata = function(self),
854 ^ Called sometimes; the string returned is passed to on_activate when
855 the entity is re-activated from static state
857 # Also you can define arbitrary member variables here
858 myvariable = whatever,
861 ABM (ActiveBlockModifier) definition (register_abm)
863 -- In the following two fields, also group:groupname will work.
864 nodenames = {"default:lava_source"},
865 neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
866 ^ If left out or empty, any neighbor will do
867 interval = 1.0, -- (operation interval)
868 chance = 1, -- (chance of trigger is 1.0/this)
869 action = func(pos, node, active_object_count, active_object_count_wider),
872 Item definition (register_node, register_craftitem, register_tool)
874 description = "Steel Axe",
875 groups = {}, -- key=name, value=rating; rating=1..3.
876 if rating not applicable, use 1.
877 eg. {wool=1, fluffy=3}
878 {soil=2, outerspace=1, crumbly=1}
880 {hard=1, metal=1, spikes=1}
881 inventory_image = "default_tool_steelaxe.png",
883 wield_scale = {x=1,y=1,z=1},
885 liquids_pointable = false,
886 tool_capabilities = {
887 full_punch_interval = 1.0,
891 fleshy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
892 snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
893 choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
896 on_drop = func(itemstack, dropper, pos),
897 on_place = func(itemstack, placer, pointed_thing),
898 on_use = func(itemstack, user, pointed_thing),
899 ^ Function must return either nil if no item shall be removed from
900 inventory, or an itemstack to replace the original itemstack.
901 eg. itemstack:take_item(); return itemstack
902 ^ Otherwise, the function is free to do what it wants.
903 ^ The default functions handle regular use cases.
906 Node definition (register_node)
908 <all fields allowed in item definitions>,
912 tile_images = {"default_unknown_block.png"},
913 special_materials = {
914 {image="", backface_culling=true},
915 {image="", backface_culling=true},
918 post_effect_color = {a=0, r=0, g=0, b=0},
921 is_ground_content = false,
922 sunlight_propagates = false,
927 buildable_to = false,
929 -- alternatively drop = { max_items = ..., items = { ... } }
932 liquid_alternative_flowing = "",
933 liquid_alternative_source = "",
934 liquid_viscosity = 0,
936 damage_per_second = 0,
937 selection_box = {type="regular"},
938 legacy_facedir_simple = false, -- Support maps made in and before January 2012
939 legacy_wallmounted = false, -- Support maps made in and before January 2012
941 footstep = <SimpleSoundSpec>,
942 dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
943 dug = <SimpleSoundSpec>,
947 Recipe: (register_craft)
949 output = 'default:pick_stone',
951 {'default:cobble', 'default:cobble', 'default:cobble'},
952 {'', 'default:stick', ''},
953 {'', 'default:stick', ''},
955 replacements = <optional list of item pairs,
956 replace one input item with another item on crafting>
962 output = 'mushrooms:mushroom_stew',
965 "mushrooms:mushroom_brown",
966 "mushrooms:mushroom_red",
968 replacements = <optional list of item pairs,
969 replace one input item with another item on crafting>
972 Recipe (tool repair):
975 additional_wear = -0.02,
981 output = "default:glass",
982 recipe = "default:sand",
986 Recipe (furnace fuel):
989 recipe = "default:leaves",
993 Chatcommand definition (register_chatcommand)
995 params = "<name> <privilege>", -- short parameter description
996 description = "Remove privilege from player", -- full description
997 privs = {privs=true}, -- require the "privs" privilege to run
998 func = function(name, param), -- called when command is run