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
28 the init.lua scripts in a shared environment.
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 load path for world-specific games
50 --------------------------------------
51 It is possible to include a game in a world; in this case, no mods or
52 games are loaded or checked from anywhere else.
54 This is useful for eg. adventure worlds.
56 This happens if the following directory exists:
59 Mods should be then be placed in:
62 Mod directory structure
63 ------------------------
69 | | |-- modname_stuff.png
70 | | `-- modname_something_else.png
77 The location of this directory can be fetched by using
78 minetest.get_modpath(modname)
81 List of mods that have to be loaded before loading this mod.
82 A single line contains a single modname.
85 The main Lua script. Running this script should register everything it
86 wants to register. Subsequent execution depends on minetest calling the
89 minetest.setting_get(name) and minetest.setting_getbool(name) can be used
90 to read custom or existing settings at load time, if necessary.
92 textures, sounds, media:
93 Media files (textures, sounds, whatever) that will be transferred to the
94 client and will be available for use by the mod.
96 Naming convention for registered textual names
97 ----------------------------------------------
98 Registered names should generally be in this format:
99 "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
101 This is to prevent conflicting names from corrupting maps and is
102 enforced by the mod loader.
104 Example: mod "experimental", ideal item/node/entity name "tnt":
105 -> the name should be "experimental:tnt".
107 Enforcement can be overridden by prefixing the name with ":". This can
108 be used for overriding the registrations of some other mod.
110 Example: Any mod can redefine experimental:tnt by using the name
111 ":experimental:tnt" when registering it.
112 (also that mod is required to have "experimental" as a dependency)
114 The ":" prefix can also be used for maintaining backwards compatibility.
118 Aliases can be added by using minetest.register_alias(name, convert_to)
120 This will make Minetest to convert things called name to things called
123 This can be used for maintaining backwards compatibility.
125 This can be also used for setting quick access names for things, eg. if
126 you have an item called epiclylongmodname:stuff, you could do
127 minetest.register_alias("stuff", "epiclylongmodname:stuff")
128 and be able to use "/giveme stuff".
132 Mods should generally prefix their textures with modname_, eg. given
133 the mod name "foomod", a texture could be called
134 "foomod_foothing.png"
136 Textures are referred to by their complete name, or alternatively by
137 stripping out the file extension:
138 eg. foomod_foothing.png
143 Only OGG files are supported.
145 For positional playing of sounds, only single-channel (mono) files are
146 supported. Otherwise OpenAL will play them non-positionally.
148 Mods should generally prefix their sounds with modname_, eg. given
149 the mod name "foomod", a sound could be called
150 "foomod_foosound.ogg"
152 Sounds are referred to by their name with a dot, a single digit and the
153 file extension stripped out. When a sound is played, the actual sound file
154 is chosen randomly from the matching sounds.
156 When playing the sound "foomod_foosound", the sound is chosen randomly
157 from the available ones of the following files:
159 foomod_foosound.0.ogg
160 foomod_foosound.1.ogg
162 foomod_foosound.9.ogg
164 Examples of sound parameter tables:
165 -- Play locationless on all clients
167 gain = 1.0, -- default
169 -- Play locationless to a player
172 gain = 1.0, -- default
174 -- Play in a location
177 gain = 1.0, -- default
178 max_hear_distance = 32, -- default
180 -- Play connected to an object, looped
182 object = <an ObjectRef>,
183 gain = 1.0, -- default
184 max_hear_distance = 32, -- default
185 loop = true, -- only sounds connected to objects can be looped
190 eg. "default_place_node"
192 eg. {name="default_place_node"}
193 eg. {name="default_place_node", gain=1.0}
197 Nodes are the bulk data of the world: cubes and other things that take the
198 space of a cube. Huge amounts of them are handled efficiently, but they
201 The definition of a node is stored and can be accessed by name in
202 minetest.registered_nodes[node.name]
204 Please note that for unknown nodes (eg. a node of an uninstalled mod) the
205 minetest.registered_nodes field for the node is nil.
207 Nodes are passed by value between Lua and the engine.
208 They are represented by a table:
209 {name="name", param1=num, param2=num}
211 param1 and param2 are 8 bit and 4 bit integers, respectively. The engine
212 uses them for certain automated functions. If you don't use these
213 functions, you can use them to store arbitrary values.
215 The functions of param1 and param2 are determined by certain fields in the
217 param1 is reserved for the engine when paramtype != "none":
219 ^ The value stores light with and without sun in it's
220 upper and lower 4 bits.
221 param2 is reserved for the engine when any of these are used:
222 liquidtype == "flowing"
223 ^ The level and some flags of the liquid is stored in param2
224 drawtype == "flowingliquid"
225 ^ The drawn liquid level is read from param2
226 drawtype == "torchlike"
227 drawtype == "signlike"
228 paramtype2 == "wallmounted"
229 ^ The rotation of the node is stored in param2. You can make this value
230 by using minetest.dir_to_wallmounted().
231 paramtype2 == "facedir"
232 ^ The rotation of the node is stored in param2. Furnaces and chests are
233 rotated this way. Can be made by using minetest.dir_to_facedir().
235 Representations of simple things
236 --------------------------------
238 {x=num, y=num, z=num}
239 Currently the API does not provide any helper functions for addition,
240 subtraction and whatever; you can define those that you need yourself.
244 Node (register_node):
245 A node from the world
246 Tool (register_tool):
247 A tool/weapon that can dig and damage things according to tool_capabilities
248 Craftitem (register_craftitem):
251 Items and item stacks can exist in three formats:
253 Serialized; This is called stackstring or itemstring:
255 eg. 'default:pick_wood 21323'
259 eg. {name="default:dirt", count=5, wear=0, metadata=""}
261 eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
262 ^ a wooden pick about 1/3 weared out
263 eg. {name="default:apple", count=1, wear=0, metadata=""}
267 C++ native format with many helper methods. Useful for converting between
268 formats. See the Class reference section for details.
270 When an item must be passed to a function, it can usually be in any of
275 In a number of places, there is a group table. Groups define the
276 properties of a thing (item, node, armor of entity, capabilities of
277 tool) in such a way that the engine and other mods can can interact with
278 the thing without actually knowing what the thing is.
281 - Groups are stored in a table, having the group names with keys and the
282 group ratings as values. For example:
283 groups = {crumbly=3, soil=1}
284 ^ Default dirt (soil group actually currently not defined; TODO)
285 groups = {crumbly=2, soil=1, level=2, outerspace=1}
286 ^ A more special dirt-kind of thing
287 - Groups always have a rating associated with them. If there is no
288 useful meaning for a rating for an enabled group, it shall be 1.
289 - When not defined, the rating of a group defaults to 0. Thus when you
290 read groups, you must interpret nil and 0 as the same value, 0.
292 You can read the rating of a group for an item or a node by using
293 minetest.get_item_group(itemname, groupname)
297 Groups of items can define what kind of an item it is (eg. wool).
301 In addition to the general item things, groups are used to define whether
302 a node is destroyable and how long it takes to destroy by a tool.
306 For entities, groups are, as of now, used only for calculating damage.
308 object.get_armor_groups() -> a group-rating table (eg. {fleshy=3})
309 object.set_armor_groups({level=2, fleshy=2, cracky=2})
313 Groups in tools define which groups of nodes and entities they are
316 Groups in crafting recipes
317 ---------------------------
318 - Not implemented yet. (TODO)
319 - Will probably look like this:
321 output = 'food:meat_soup_raw',
327 preserve = {'group:bowl'},
332 - immortal: Disables the group damage system for an entity
333 - level: Can be used to give an additional sense of progression in the game.
334 - A larger level will cause eg. a weapon of a lower level make much less
335 damage, and get weared out much faster, or not be able to get drops
336 from destroyed nodes.
337 - 0 is something that is directly accessible at the start of gameplay
338 - There is no upper limit
339 - dig_immediate: (player can always pick up node without tool wear)
340 - 2: node is removed without tool wear after 0.5 seconds or so
342 - 3: node is removed without tool wear immediately (torch)
344 Known damage and digging time defining groups
345 ----------------------------------------------
346 Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.
347 - crumbly: dirt, sand
348 - cracky: tough but crackable stuff like stone.
349 - snappy: something that can be cut using fine tools; eg. leaves, small
350 plants, wire, sheets of metal
351 - choppy: something that can be cut using force; eg. trees, wooden planks
352 - fleshy: Living things like animals and the player. This could imply
353 some blood effects when hitting.
354 - explody: Especially prone to explosions
355 - oddly_breakable_by_hand:
356 Can be added to nodes that shouldn't logically be breakable by the
357 hand but are. Somewhat similar to dig_immediate, but times are more
358 like {[1]=3.50,[2]=2.00,[3]=0.70} and this does not override the
359 speed of a tool if the tool can dig at a faster speed than this
360 suggests for the hand.
362 Examples of custom groups
363 --------------------------
364 Item groups are often used for defining, well, //groups of items//.
365 - meat: any meat-kind of a thing (rating might define the size or healing
366 ability or be irrelevant - it is not defined as of yet)
367 - eatable: anything that can be eaten. Rating might define HP gain in half
369 - flammable: can be set on fire. Rating might define the intensity of the
370 fire, affecting eg. the speed of the spreading of an open fire.
371 - wool: any wool (any origin, any color)
374 - heavy: anything considerably heavy
376 Digging time calculation specifics
377 -----------------------------------
378 Groups such as **crumbly**, **cracky** and **snappy** are used for this
379 purpose. Rating is 1, 2 or 3. A higher rating for such a group implies
382 The **level** group is used to limit the toughness of nodes a tool can dig
383 and to scale the digging times / damage to a greater extent.
385 ^ PLEASE DO UNDERSTAND THIS, otherwise you cannot use the system to it's
388 Tools define their properties by a list of parameters for groups. They
389 cannot dig other groups; thus it is important to use a standard bunch of
390 groups to enable interaction with tools.
393 * Full punch interval
395 * For an arbitrary list of groups:
396 * Uses (until the tool breaks)
397 * Maximum level (usually 0, 1, 2 or 3)
400 **Full punch interval**:
401 When used as a weapon, the tool will do full damage if this time is spent
402 between punches. If eg. half the time is spent, the tool will do half
405 **Maximum drop level**
406 Suggests the maximum level of node, when dug with the tool, that will drop
407 it's useful item. (eg. iron ore to drop a lump of iron).
408 - This is not automated; it is the responsibility of the node definition
412 Determines how many uses the tool has when it is used for digging a node,
413 of this group, of the maximum level. For lower leveled nodes, the use count
414 is multiplied by 3^leveldiff.
415 - uses=10, leveldiff=0 -> actual uses: 10
416 - uses=10, leveldiff=1 -> actual uses: 30
417 - uses=10, leveldiff=2 -> actual uses: 90
420 Tells what is the maximum level of a node of this group that the tool will
424 List of digging times for different ratings of the group, for nodes of the
426 * For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
427 result in the tool to be able to dig nodes that have a rating of 2 or 3
428 for this group, and unable to dig the rating 1, which is the toughest.
429 Unless there is a matching group that enables digging otherwise.
430 * For entities, damage equals the amount of nodes dug in the time spent
431 between hits, with a maximum time of ''full_punch_interval''.
433 Example definition of the capabilities of a tool
434 -------------------------------------------------
435 tool_capabilities = {
436 full_punch_interval=1.5,
439 crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
443 This makes the tool be able to dig nodes that fullfill both of these:
444 - Have the **crumbly** group
445 - Have a **level** group less or equal to 2
447 Table of resulting digging times:
448 crumbly 0 1 2 3 4 <- level
454 level diff: 2 1 0 -1 -2
456 Table of resulting tool uses:
463 - At crumbly=0, the node is not diggable.
464 - At crumbly=3, the level difference digging time divider kicks in and makes
465 easy nodes to be quickly breakable.
466 - At level > 2, the node is not diggable, because it's level > maxlevel
468 Entity damage mechanism
469 ------------------------
471 - Take the time spent after the last hit
472 - Limit time to full_punch_interval
473 - Take the damage groups and imagine a bunch of nodes that have them
474 - Damage in HP is the amount of nodes destroyed in this time.
476 Client predicts damage based on damage groups. Because of this, it is able to
477 give an immediate response when an entity is damaged or dies; the response is
478 pre-defined somehow (eg. by defining a sprite animation) (not implemented;
480 - Currently a smoke puff will appear when an entity dies.
482 The group **immortal** completely disables normal damage.
484 Entities can define a special armor group, which is **punch_operable**. This
485 group disables the regular damage mechanism for players punching it by hand or
486 a non-tool item, so that it can do something else than take damage.
488 On the Lua side, every punch calls ''entity:on_punch(puncher,
489 time_from_last_punch, tool_capabilities, direction)''. This should never be
490 called directly, because damage is usually not handled by the entity itself.
491 * ''puncher'' is the object performing the punch. Can be nil. Should never be
492 accessed unless absolutely required, to encourage interoperability.
493 * ''time_from_last_punch'' is time from last punch (by puncher) or nil.
494 * ''tool_capabilities'' can be nil.
495 * ''direction'' is a unit vector, pointing from the source of the punch to
498 To punch an entity/object in Lua, call ''object:punch(puncher,
499 time_from_last_punch, tool_capabilities, direction)''.
500 * Return value is tool wear.
501 * Parameters are equal to the above callback.
502 * If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
503 automatically filled in based on the location of ''puncher''.
507 dump2(obj, name="_", dumped={})
508 ^ Return object serialized as a string, handles reference loops
510 ^ Return object serialized as a string
511 string:split(separator)
512 ^ eg. string:split("a,b", ",") == {"a","b"}
514 ^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
515 minetest.pos_to_string({x=X,y=Y,z=Z}) -> "(X,Y,Z)"
516 ^ Convert position to a printable string
517 minetest.string_to_pos(string) -> position
519 minetest namespace reference
520 -----------------------------
521 minetest.get_current_modname() -> string
522 minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
523 ^ Useful for loading additional .lua modules or static data from mod
524 minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
525 ^ Useful for storing custom data
526 minetest.is_singleplayer()
529 ^ Always printed to stderr and logfile (print() is redirected here)
531 minetest.log(loglevel, line)
532 ^ loglevel one of "error", "action", "info", "verbose"
534 Registration functions: (Call these only at load time)
535 minetest.register_entity(name, prototype table)
536 minetest.register_abm(abm definition)
537 minetest.register_node(name, node definition)
538 minetest.register_tool(name, item definition)
539 minetest.register_craftitem(name, item definition)
540 minetest.register_alias(name, convert_to)
541 minetest.register_craft(recipe)
543 Global callback registration functions: (Call these only at load time)
544 minetest.register_globalstep(func(dtime))
545 ^ Called every server step, usually interval of 0.05s
546 minetest.register_on_placenode(func(pos, newnode, placer))
547 ^ Called when a node has been placed
548 minetest.register_on_dignode(func(pos, oldnode, digger))
549 ^ Called when a node has been dug. digger can be nil.
550 minetest.register_on_punchnode(func(pos, node, puncher))
551 ^ Called when a node is punched
552 minetest.register_on_generated(func(minp, maxp, blockseed))
553 ^ Called after generating a piece of world. Modifying nodes inside the area
554 is a bit faster than usually.
555 minetest.register_on_newplayer(func(ObjectRef))
556 ^ Called after a new player has been created
557 minetest.register_on_dieplayer(func(ObjectRef))
558 ^ Called when a player dies
559 minetest.register_on_respawnplayer(func(ObjectRef))
560 ^ Called when player is to be respawned
561 ^ Called _before_ repositioning of player occurs
562 ^ return true in func to disable regular player placement
563 minetest.register_on_chat_message(func(name, message))
565 Other registration functions:
566 minetest.register_chatcommand(cmd, chatcommand definition)
567 minetest.register_privilege(name, definition)
568 ^ definition: "description text"
570 description = "description text",
571 give_to_singleplayer = boolean, -- default: true
573 minetest.register_authentication_handler(handler)
574 ^ See minetest.builtin_auth_handler in builtin.lua for reference
577 minetest.setting_set(name, value)
578 minetest.setting_get(name) -> string or nil
579 minetest.setting_getbool(name) -> boolean value or nil
580 minetest.setting_get_pos(name) -> position or nil
581 minetest.add_to_creative_inventory(itemstring)
584 minetest.notify_authentication_modified(name)
585 ^ Should be called by the authentication handler if privileges change.
586 ^ To report everybody, set name=nil.
587 minetest.get_password_hash(name, raw_password)
588 ^ Convert a name-password pair to a password hash that minetest can use
589 minetest.string_to_privs(str) -> {priv1=true,...}
590 minetest.privs_to_string(privs) -> "priv1,priv2,..."
591 ^ Convert between two privilege representations
592 minetest.set_player_password(name, password_hash)
593 minetest.set_player_privs(name, {priv1=true,...})
594 minetest.get_player_privs(name) -> {priv1=true,...}
595 minetest.auth_reload()
596 ^ These call the authentication handler
597 minetest.check_player_privs(name, {priv1=true,...}) -> bool, missing_privs
598 ^ A quickhand for checking privileges
601 minetest.chat_send_all(text)
602 minetest.chat_send_player(name, text)
605 minetest.get_inventory(location) -> InvRef
606 ^ location = eg. {type="player", name="celeron55"}
607 {type="node", pos={x=, y=, z=}}
610 minetest.inventorycube(img1, img2, img3)
611 ^ Returns a string for making an image of a cube (useful as an item image)
612 minetest.get_pointed_thing_position(pointed_thing, above)
613 ^ Get position of a pointed_thing (that you can get from somewhere)
614 minetest.dir_to_facedir(dir)
615 ^ Convert a vector to a facedir value, used in param2 for paramtype2="facedir"
616 minetest.dir_to_wallmounted(dir)
617 ^ Convert a vector to a wallmounted value, used for paramtype2="wallmounted"
618 minetest.get_node_drops(nodename, toolname)
619 ^ Returns list of item names.
620 ^ Note: This will be removed or modified in a future version.
622 Defaults for the on_* item definition functions:
623 (These return the leftover itemstack)
624 minetest.item_place_node(itemstack, placer, pointed_thing)
625 ^ Place item as a node
626 minetest.item_place_object(itemstack, placer, pointed_thing)
628 minetest.item_place(itemstack, placer, pointed_thing)
629 ^ Use one of the above based on what the item is.
630 minetest.item_drop(itemstack, dropper, pos)
632 minetest.item_eat(hp_change, replace_with_item)
633 ^ Eat the item. replace_with_item can be nil.
635 Defaults for the on_punch and on_dig node definition callbacks:
636 minetest.node_punch(pos, node, puncher)
637 ^ Calls functions registered by minetest.register_on_punchnode()
638 minetest.node_dig(pos, node, digger)
639 ^ Checks if node can be dug, puts item into inventory, removes node
640 ^ Calls functions registered by minetest.registered_on_dignodes()
643 minetest.sound_play(spec, parameters) -> handle
644 ^ spec = SimpleSoundSpec
645 ^ parameters = sound parameter table
646 minetest.sound_stop(handle)
649 minetest.after(time, func, param)
650 ^ Call function after time seconds
651 ^ param is optional; to pass multiple parameters, pass a table.
654 minetest.get_connected_players() -> list of ObjectRefs
655 minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
656 ^ Gives a unique hash number for a node position (16+16+16=48bit)
657 minetest.get_item_group(name, group) -> rating
658 ^ Get rating of a group of an item. (0 = not in group)
659 minetest.get_node_group(name, group) -> rating
660 ^ Deprecated: An alias for the former.
663 minetest.env - EnvRef of the server environment and world.
664 ^ Using this you can access nodes and entities
667 minetest.registered_items
668 ^ List of registered items, indexed by name
669 minetest.registered_nodes
670 ^ List of registered node definitions, indexed by name
671 minetest.registered_craftitems
672 ^ List of registered craft item definitions, indexed by name
673 minetest.registered_tools
674 ^ List of registered tool definitions, indexed by name
675 minetest.registered_entities
676 ^ List of registered entity prototypes, indexed by name
678 ^ List of object references, indexed by active object id
680 ^ List of lua entities, indexed by active object id
682 Deprecated but defined for backwards compatibility:
683 minetest.digprop_constanttime(time)
684 minetest.digprop_stonelike(toughness)
685 minetest.digprop_dirtlike(toughness)
686 minetest.digprop_gravellike(toughness)
687 minetest.digprop_woodlike(toughness)
688 minetest.digprop_leaveslike(toughness)
689 minetest.digprop_glasslike(toughness)
693 EnvRef: basically ServerEnvironment and ServerMap combined.
695 - set_node(pos, node)
696 - add_node(pos, node): alias set_node(pos, node)
697 - remove_node(pos): equivalent to set_node(pos, "air")
699 ^ Returns {name="ignore", ...} for unloaded area
700 - get_node_or_nil(pos)
701 ^ Returns nil for unloaded area
702 - get_node_light(pos, timeofday) -> 0...15 or nil
703 ^ timeofday: nil = current time, 0 = night, 0.5 = day
704 - add_entity(pos, name): Spawn Lua-defined entity at position
705 ^ Returns ObjectRef, or nil if failed
706 - add_item(pos, itemstring): Spawn item
707 ^ Returns ObjectRef, or nil if failed
708 - get_meta(pos) -- Get a NodeMetaRef at that position
709 - get_player_by_name(name) -- Get an ObjectRef to a player
710 - get_objects_inside_radius(pos, radius)
711 - set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
713 - find_node_near(pos, radius, nodenames) -> pos or nil
714 ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
715 - find_nodes_in_area(minp, maxp, nodenames) -> list of positions
716 ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
717 - get_perlin(seeddiff, octaves, persistence, scale)
718 ^ Return world-specific perlin noise (int(worldseed)+seeddiff)
720 - add_rat(pos): Add C++ rat object (no-op)
721 - add_firefly(pos): Add C++ firefly object (no-op)
723 NodeMetaRef (this stuff is subject to change in a future version)
726 - allows_text_input()
727 - set_text(text) -- eg. set the text of a sign
731 Generic node metadata specific:
732 - set_infotext(infotext)
733 - get_inventory() -> InvRef
734 - set_inventory_draw_spec(string)
735 - set_allow_text_input(bool)
736 - set_allow_removal(bool)
737 - set_enforce_owner(bool)
738 - is_inventory_modified()
739 - reset_inventory_modified()
741 - reset_text_modified()
742 - set_string(name, value)
745 ObjectRef: Moving things in the game are generally these
746 (basically reference to a C++ ServerActiveObject)
748 - remove(): remove object (after returning from Lua)
749 - getpos() -> {x=num, y=num, z=num}
750 - setpos(pos); pos={x=num, y=num, z=num}
751 - moveto(pos, continuous=false): interpolated move
752 - punch(puncher, time_from_last_punch, tool_capabilities, direction)
753 ^ puncher = an another ObjectRef,
754 ^ time_from_last_punch = time since last punch action of the puncher
755 - right_click(clicker); clicker = an another ObjectRef
756 - get_hp(): returns number of hitpoints (2 * number of hearts)
757 - set_hp(hp): set number of hitpoints (2 * number of hearts)
758 - get_inventory() -> InvRef
759 - get_wield_list(): returns the name of the inventory list the wielded item is in
760 - get_wield_index(): returns the index of the wielded item
761 - get_wielded_item() -> ItemStack
762 - set_wielded_item(item): replaces the wielded item, returns true if successful
763 - set_armor_groups({group1=rating, group2=rating, ...})
764 - set_properties(object property table)
765 LuaEntitySAO-only: (no-op for other objects)
766 - setvelocity({x=num, y=num, z=num})
767 - getvelocity() -> {x=num, y=num, z=num}
768 - setacceleration({x=num, y=num, z=num})
769 - getacceleration() -> {x=num, y=num, z=num}
771 - getyaw() -> radians
773 - setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
774 - select_horiz_by_yawpitch=false)
775 - ^ Select sprite from spritesheet with optional animation and DM-style
776 - texture selection based on yaw relative to camera
777 - get_entity_name() (DEPRECATED: Will be removed in a future version)
779 Player-only: (no-op for other objects)
780 - get_player_name(): will return nil if is not a player
781 - get_look_dir(): get camera direction as a unit vector
782 - get_look_pitch(): pitch in radians
783 - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
785 InvRef: Reference to an inventory
787 - get_size(listname): get size of a list
788 - set_size(listname, size): set size of a list
789 - get_stack(listname, i): get a copy of stack index i in list
790 - set_stack(listname, i, stack): copy stack to index i in list
791 - get_list(listname): return full list
792 - set_list(listname, list): set full list (size will not change)
793 - add_item(listname, stack): add item somewhere in list, returns leftover ItemStack
794 - room_for_item(listname, stack): returns true if the stack of items
795 can be fully added to the list
796 - contains_item(listname, stack): returns true if the stack of items
797 can be fully taken from the list
798 remove_item(listname, stack): take as many items as specified from the list,
799 returns the items that were actually removed (as an ItemStack)
801 ItemStack: A stack of items.
802 - Can be created via ItemStack(itemstack or itemstring or table or nil)
804 - is_empty(): return true if stack is empty
805 - get_name(): returns item name (e.g. "default:stone")
806 - get_count(): returns number of items on the stack
807 - get_wear(): returns tool wear (0-65535), 0 for non-tools
808 - get_metadata(): returns metadata (a string attached to an item stack)
809 - clear(): removes all items from the stack, making it empty
810 - replace(item): replace the contents of this stack (item can also
811 be an itemstring or table)
812 - to_string(): returns the stack in itemstring form
813 - to_table(): returns the stack in Lua table form
814 - get_stack_max(): returns the maximum size of the stack (depends on the item)
815 - get_free_space(): returns get_stack_max() - get_count()
816 - is_known(): returns true if the item name refers to a defined item type
817 - get_definition(): returns the item definition table
818 - get_tool_capabilities(): returns the digging properties of the item,
819 ^ or those of the hand if none are defined for this item type
820 - add_wear(amount): increases wear by amount if the item is a tool
821 - add_item(item): put some item or stack onto this stack,
822 ^ returns leftover ItemStack
823 - item_fits(item): returns true if item or stack can be fully added to this one
824 - take_item(n): take (and remove) up to n items from this stack
825 ^ returns taken ItemStack
826 ^ if n is omitted, n=1 is used
827 - peek_item(n): copy (don't remove) up to n items from this stack
828 ^ returns copied ItemStack
829 ^ if n is omitted, n=1 is used
831 PseudoRandom: A pseudorandom number generator
832 - Can be created via PseudoRandom(seed)
834 - next(): return next integer random number [0...32767]
835 - next(min, max): return next integer random number [min...max]
836 (max - min) must be 32767 or <= 6553 due to the simple
837 implementation making bad distribution otherwise.
839 PerlinNoise: A perlin noise generator
840 - Can be created via PerlinNoise(seed, octaves, persistence, scale)
841 - Also minetest.env:get_perlin(seeddiff, octaves, persistence, scale)
843 - get2d(pos) -> 2d noise value at pos={x=,y=}
844 - get3d(pos) -> 3d noise value at pos={x=,y=,z=}
848 - Functions receive a "luaentity" as self:
849 - It has the member .name, which is the registered name ("mod:thing")
850 - It has the member .object, which is an ObjectRef pointing to the object
851 - The original prototype stuff is visible directly via a metatable
853 - on_activate(self, staticdata)
854 ^ Called when the object is instantiated.
855 - on_step(self, dtime)
856 ^ Called on every server tick (dtime is usually 0.05 seconds)
857 - on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
858 ^ Called when somebody punches the object.
859 ^ Note that you probably want to handle most punches using the
860 automatic armor group system.
861 ^ puncher: ObjectRef (can be nil)
862 ^ time_from_last_punch: Meant for disallowing spamming of clicks (can be nil)
863 ^ tool_capabilities: capability table of used tool (can be nil)
864 ^ dir: unit vector of direction of punch. Always defined. Points from
865 the puncher to the punched.
866 - on_rightclick(self, clicker)
867 - get_staticdata(self)
868 ^ Should return a string that will be passed to on_activate when
869 the object is instantiated the next time.
877 collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
878 visual = "cube"/"sprite"/"upright_sprite",
879 visual_size = {x=1, y=1},
880 textures = {}, -- number of required textures depends on visual
881 spritediv = {x=1, y=1},
882 initial_sprite_basepos = {x=0, y=0},
884 makes_footstep_sound = false,
887 Entity definition (register_entity)
889 (Deprecated: Everything in object properties is read directly from here)
891 initial_properties = <initial object properties>,
893 on_activate = function(self, staticdata),
894 on_step = function(self, dtime),
895 on_punch = function(self, hitter),
896 on_rightclick = function(self, clicker),
897 get_staticdata = function(self),
898 ^ Called sometimes; the string returned is passed to on_activate when
899 the entity is re-activated from static state
901 # Also you can define arbitrary member variables here
902 myvariable = whatever,
905 ABM (ActiveBlockModifier) definition (register_abm)
907 -- In the following two fields, also group:groupname will work.
908 nodenames = {"default:lava_source"},
909 neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
910 ^ If left out or empty, any neighbor will do
911 interval = 1.0, -- (operation interval)
912 chance = 1, -- (chance of trigger is 1.0/this)
913 action = func(pos, node, active_object_count, active_object_count_wider),
916 Item definition (register_node, register_craftitem, register_tool)
918 description = "Steel Axe",
919 groups = {}, -- key=name, value=rating; rating=1..3.
920 if rating not applicable, use 1.
921 eg. {wool=1, fluffy=3}
922 {soil=2, outerspace=1, crumbly=1}
924 {hard=1, metal=1, spikes=1}
925 inventory_image = "default_tool_steelaxe.png",
927 wield_scale = {x=1,y=1,z=1},
929 liquids_pointable = false,
930 tool_capabilities = {
931 full_punch_interval = 1.0,
935 fleshy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
936 snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
937 choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
940 on_drop = func(itemstack, dropper, pos),
941 on_place = func(itemstack, placer, pointed_thing),
942 on_use = func(itemstack, user, pointed_thing),
943 ^ Function must return either nil if no item shall be removed from
944 inventory, or an itemstack to replace the original itemstack.
945 eg. itemstack:take_item(); return itemstack
946 ^ Otherwise, the function is free to do what it wants.
947 ^ The default functions handle regular use cases.
950 Node definition (register_node)
952 <all fields allowed in item definitions>,
956 tile_images = {"default_unknown_block.png"},
957 special_materials = {
958 {image="", backface_culling=true},
959 {image="", backface_culling=true},
962 post_effect_color = {a=0, r=0, g=0, b=0},
965 is_ground_content = false,
966 sunlight_propagates = false,
971 buildable_to = false,
973 -- alternatively drop = { max_items = ..., items = { ... } }
976 liquid_alternative_flowing = "",
977 liquid_alternative_source = "",
978 liquid_viscosity = 0,
980 damage_per_second = 0,
981 selection_box = {type="regular"},
982 legacy_facedir_simple = false, -- Support maps made in and before January 2012
983 legacy_wallmounted = false, -- Support maps made in and before January 2012
985 footstep = <SimpleSoundSpec>,
986 dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
987 dug = <SimpleSoundSpec>,
991 Recipe: (register_craft)
993 output = 'default:pick_stone',
995 {'default:cobble', 'default:cobble', 'default:cobble'},
996 {'', 'default:stick', ''},
997 {'', 'default:stick', ''},
999 replacements = <optional list of item pairs,
1000 replace one input item with another item on crafting>
1006 output = 'mushrooms:mushroom_stew',
1009 "mushrooms:mushroom_brown",
1010 "mushrooms:mushroom_red",
1012 replacements = <optional list of item pairs,
1013 replace one input item with another item on crafting>
1016 Recipe (tool repair):
1018 type = "toolrepair",
1019 additional_wear = -0.02,
1025 output = "default:glass",
1026 recipe = "default:sand",
1030 Recipe (furnace fuel):
1033 recipe = "default:leaves",
1037 Chatcommand definition (register_chatcommand)
1039 params = "<name> <privilege>", -- short parameter description
1040 description = "Remove privilege from player", -- full description
1041 privs = {privs=true}, -- require the "privs" privilege to run
1042 func = function(name, param), -- called when command is run