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
175 Representations of simple things
176 --------------------------------
177 MapNode representation:
178 {name="name", param1=num, param2=num}
180 MapNodes do not directly have any other data associated with them.
181 If you want to access the definition of the node, you access
182 minetest.registered_nodes[node.name]
184 param1 and param2 are 8 bit and 4 bit integers, respectively. They
185 are reserved for certain automated functions. If you don't use these
186 functions, you can use them to store arbitrary values.
188 param1 is reserved for the engine when:
190 param2 is reserved for the engine when any of these are used:
191 liquidtype == "flowing"
192 drawtype == "flowingliquid"
193 drawtype == "torchlike"
194 drawtype == "signlike"
197 {x=num, y=num, z=num}
198 Currently the API does not provide any helper functions for addition,
199 subtraction and whatever; you can define those that you need yourself.
201 stackstring/itemstring: A stack of items in serialized format.
203 eg. 'default:pick_wood 21323'
206 item: A stack of items in Lua table format.
207 eg. {name="default:dirt", count=5, wear=0, metadata=""}
209 eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
210 ^ a wooden pick about 1/3 weared out
211 eg. {name="default:apple", count=1, wear=0, metadata=""}
214 Any time an item must be passed to a function, it can be an
215 ItemStack (see below), an itemstring or a table in the above format.
219 eg. "default_place_node"
221 eg. {name="default_place_node"}
222 eg. {name="default_place_node", gain=1.0}
226 Node (register_node):
227 A node from the world
228 Tool (register_tool):
229 A tool/weapon that can dig and damage things according to tool_capabilities
230 Craftitem (register_craftitem):
235 In a number of places, there is a group table. Groups define the
236 properties of a thing (item, node, armor of entity, capabilities of
237 tool) in such a way that the engine and other mods can can interact with
238 the thing without actually knowing what the thing is.
241 - Groups are stored in a table, having the group names with keys and the
242 group ratings as values. For example:
243 groups = {crumbly=3, soil=1}
244 ^ Default dirt (soil group actually currently not defined; TODO)
245 groups = {crumbly=2, soil=1, level=2, outerspace=1}
246 ^ A more special dirt-kind of thing
247 - Groups always have a rating associated with them. If there is no
248 useful meaning for a rating for an enabled group, it shall be 1.
249 - When not defined, the rating of a group defaults to 0. Thus when you
250 read groups, you must interpret nil and 0 as the same value, 0.
254 Groups of items can define what kind of an item it is (eg. wool).
258 In addition to the general item things, groups are used to define whether
259 a node is destroyable and how long it takes to destroy by a tool.
263 For entities, groups are, as of now, used only for calculating damage.
265 object.get_armor_groups() -> a group-rating table (eg. {fleshy=3})
266 object.set_armor_groups({level=2, fleshy=2, cracky=2})
270 Groups in tools define which groups of nodes and entities they are
273 Groups in crafting recipes
274 ---------------------------
275 - Not implemented yet. (TODO)
276 - Will probably look like this:
278 output = 'food:meat_soup_raw',
284 preserve = {'group:bowl'},
289 - immortal: Disables the group damage system for an entity
290 - level: Can be used to give an additional sense of progression in the game.
291 - A larger level will cause eg. a weapon of a lower level make much less
292 damage, and get weared out much faster, or not be able to get drops
293 from destroyed nodes.
294 - 0 is something that is directly accessible at the start of gameplay
295 - There is no upper limit
296 - dig_immediate: (player can always pick up node without tool wear)
297 - 2: node is removed without tool wear after 0.5 seconds or so
299 - 3: node is removed without tool wear immediately (torch)
301 Known damage and digging time defining groups
302 ----------------------------------------------
303 Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.
304 - crumbly: dirt, sand
305 - cracky: tough but crackable stuff like stone.
306 - snappy: something that can be cut using fine tools; eg. leaves, small
307 plants, wire, sheets of metal
308 - choppy: something that can be cut using force; eg. trees, wooden planks
309 - fleshy: Living things like animals and the player. This could imply
310 some blood effects when hitting.
311 - explody: Especially prone to explosions
312 - oddly_breakable_by_hand:
313 Can be added to nodes that shouldn't logically be breakable by the
314 hand but are. Somewhat similar to dig_immediate, but times are more
315 like {[1]=3.50,[2]=2.00,[3]=0.70} and this does not override the
316 speed of a tool if the tool can dig at a larger speed than this
317 suggests for the hand.
319 Examples of custom groups
320 --------------------------
321 Item groups are often used for defining, well, //groups of items//.
322 - meat: any meat-kind of a thing (rating might define the size or healing
323 ability or be irrelevant - it is not defined as of yet)
324 - eatable: anything that can be eaten. Rating might define HP gain in half
326 - flammable: can be set on fire. Rating might define the intensity of the
327 fire, affecting eg. the speed of the spreading of an open fire.
328 - wool: any wool (any origin, any color)
331 - heavy: anything considerably heavy
333 Digging time calculation specifics
334 -----------------------------------
335 Groups such as **crumbly**, **cracky** and **snappy** are used for this
336 purpose. Rating is 1, 2 or 3. A higher rating for such a group implies
339 The **level** group is used to limit the toughness of nodes a tool can dig
340 and to scale the digging times / damage to a greater extent.
342 ^ PLEASE DO UNDERSTAND THIS, otherwise you cannot use the system to it's
345 Tools define their properties by a list of parameters for groups. They
346 cannot dig other groups; thus it is important to use a standard bunch of
347 groups to enable interaction with tools.
350 * Full punch interval
352 * For an arbitrary list of groups:
353 * Uses (until the tool breaks)
354 * Maximum level (usually 0, 1, 2 or 3)
357 **Full punch interval**:
358 When used as a weapon, the tool will do full damage if this time is spent
359 between punches. If eg. half the time is spent, the tool will do half
362 **Maximum drop level**
363 Suggests the maximum level of node, when dug with the tool, that will drop
364 it's useful item. (eg. iron ore to drop a lump of iron).
365 - This is not automated; it is the responsibility of the node definition
369 Determines how many uses the tool has when it is used for digging a node,
370 of this group, of the maximum level. For lower leveled nodes, the use count
371 is multiplied by 3^leveldiff.
372 - uses=10, leveldiff=0 -> actual_uses=10
373 - uses=10, leveldiff=1 -> actual_uses=30
374 - uses=10, leveldiff=2 -> actual_uses=90
377 Tells what is the maximum level of a node of this group that the tool will
381 List of digging times for different ratings of the group, for nodes of the
383 * For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
384 result the tool to be able to dig nodes that have a rating of 2 or 3
385 for this group, and unable to dig the rating 1, which is the toughest.
386 Unless there is a matching group that enables digging otherwise.
387 * For entities, damage equals the amount of nodes dug in the time spent
388 between hits, with a maximum time of ''full_punch_interval''.
390 Example definition of the capabilities of a tool
391 -------------------------------------------------
392 tool_capabilities = {
393 full_punch_interval=1.5,
396 crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
400 This makes the tool be able to dig nodes that fullfill both of these:
401 - Have the **crumbly** group
402 - Have a **level** group less or equal to 2
404 Table of resulting digging times:
405 crumbly 0 1 2 3 4 <- level
411 level diff: 2 1 0 -1 -2
413 Table of resulting tool uses:
420 - At crumbly=0, the node is not diggable.
421 - At crumbly=3, the level difference digging time divider kicks in and makes
422 easy nodes to be quickly breakable.
423 - At level > 2, the node is not diggable, because it's level > maxlevel
425 Entity damage mechanism
426 ------------------------
428 - Take the time spent after the last hit
429 - Limit time to full_punch_interval
430 - Take the damage groups, assume a node has them
431 - Damage in HP is the amount of nodes destroyed in this time.
433 Client predicts damage based on damage groups. Because of this, it is able to
434 give an immediate response when an entity is damaged or dies; the response is
435 pre-defined somehow (eg. by defining a sprite animation) (not implemented;
437 - Currently a smoke puff will appear when an entity dies.
439 The group **immortal** will completely disable normal damage.
441 Entities can define a special armor group, which is **punch_operable**. This
442 group will disable the regular damage mechanism for players punching it by hand
445 On the Lua side, every punch calls ''entity:on_punch(puncher,
446 time_from_last_punch, tool_capabilities, direction)''. This should never be
447 called directly, because damage is usually not handled by the entity itself.
448 * ''puncher'' is the object performing the punch. Can be nil. Should never be
449 accessed unless absolutely required.
450 * ''time_from_last_punch'' is time from last punch (by puncher) or nil.
451 * ''tool_capabilities'' can be nil.
452 * ''direction'' is a unit vector, pointing from the source of the punch to
455 To punch an entity/object in Lua, call ''object:punch(puncher, time_from_last_punch, tool_capabilities, direction)''.
456 * Return value is tool wear.
457 * Parameters are equal to the above callback.
458 * If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
459 automatically filled in based on the location of ''puncher''.
463 dump2(obj, name="_", dumped={})
464 ^ Return object serialized as a string, handles reference loops
466 ^ Return object serialized as a string
467 string:split(separator)
470 minetest namespace reference
471 -----------------------------
472 minetest.get_current_modname() -> string
473 minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
474 ^ Useful for loading additional .lua modules or static data from mod
475 minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
476 ^ Useful for storing custom data
477 minetest.is_singleplayer()
482 minetest.log(loglevel, line)
483 ^ loglevel one of "error", "action", "info", "verbose"
485 Registration functions: (Call these only at load time)
486 minetest.register_entity(name, prototype table)
487 minetest.register_abm(abm definition)
488 minetest.register_node(name, node definition)
489 minetest.register_tool(name, item definition)
490 minetest.register_craftitem(name, item definition)
491 minetest.register_alias(name, convert_to)
492 minetest.register_craft(recipe)
493 minetest.register_globalstep(func(dtime))
494 minetest.register_on_placenode(func(pos, newnode, placer))
495 minetest.register_on_dignode(func(pos, oldnode, digger))
496 minetest.register_on_punchnode(func(pos, node, puncher))
497 minetest.register_on_generated(func(minp, maxp, blockseed))
498 minetest.register_on_newplayer(func(ObjectRef))
499 minetest.register_on_dieplayer(func(ObjectRef))
500 minetest.register_on_respawnplayer(func(ObjectRef))
501 ^ return true in func to disable regular player placement
502 ^ currently called _before_ repositioning of player occurs
503 minetest.register_on_chat_message(func(name, message))
504 minetest.register_chatcommand(cmd, chatcommand definition)
505 minetest.register_privilege(name, description)
506 minetest.register_authentication_handler(handler)
507 ^ See minetest.builtin_auth_handler in builtin.lua for reference
510 minetest.setting_get(name) -> string or nil
511 minetest.setting_getbool(name) -> boolean value or nil
512 minetest.add_to_creative_inventory(itemstring)
515 minetest.get_password_hash(name, raw_password)
516 minetest.set_player_password(name, password_hash)
517 minetest.string_to_privs(str) -> {priv1=true,...}
518 minetest.privs_to_string(privs) -> "priv1,priv2,..."
519 minetest.set_player_privs(name, {priv1=true,...})
520 minetest.get_player_privs(name) -> {priv1=true,...}
521 minetest.check_player_privs(name, {priv1=true,...}) -> bool, missing_privs
524 minetest.chat_send_all(text)
525 minetest.chat_send_player(name, text)
528 minetest.get_inventory(location) -> InvRef
529 ^ location = eg. {type="player", name="celeron55"}
530 {type="node", pos={x=, y=, z=}}
533 minetest.sound_play(spec, parameters) -> handle
534 ^ spec = SimpleSoundSpec
535 ^ parameters = sound parameter table
536 minetest.sound_stop(handle)
539 minetest.after(time, func, param)
540 ^ Call function after time seconds
541 ^ param is optional; to pass multiple parameters, pass a table.
544 minetest.get_connected_players() -> list of ObjectRefs
545 minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
546 ^ Gives a unique hash number for a node position (16+16+16=48bit)
549 minetest.env - environment reference
552 minetest.registered_items
553 ^ List of registered items, indexed by name
554 minetest.registered_nodes
555 ^ List of registered node definitions, indexed by name
556 minetest.registered_craftitems
557 ^ List of registered craft item definitions, indexed by name
558 minetest.registered_tools
559 ^ List of registered tool definitions, indexed by name
560 minetest.registered_entities
561 ^ List of registered entity prototypes, indexed by name
563 ^ List of object references, indexed by active object id
565 ^ List of lua entities, indexed by active object id
567 Deprecated but defined for backwards compatibility:
568 minetest.digprop_constanttime(time)
569 minetest.digprop_stonelike(toughness)
570 minetest.digprop_dirtlike(toughness)
571 minetest.digprop_gravellike(toughness)
572 minetest.digprop_woodlike(toughness)
573 minetest.digprop_leaveslike(toughness)
574 minetest.digprop_glasslike(toughness)
578 EnvRef: basically ServerEnvironment and ServerMap combined.
580 - set_node(pos, node)
581 - add_node(pos, node): alias set_node(pos, node)
582 - remove_node(pos): equivalent to set_node(pos, "air")
584 ^ Returns {name="ignore", ...} for unloaded area
585 - get_node_or_nil(pos)
586 ^ Returns nil for unloaded area
587 - get_node_light(pos, timeofday) -> 0...15 or nil
588 ^ timeofday: nil = current time, 0 = night, 0.5 = day
589 - add_entity(pos, name): Returns ObjectRef or nil if failed
590 - add_item(pos, itemstring)
593 - get_meta(pos) -- Get a NodeMetaRef at that position
594 - get_player_by_name(name) -- Get an ObjectRef to a player
595 - get_objects_inside_radius(pos, radius)
596 - set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
599 NodeMetaRef (this stuff is subject to change in a future version)
602 - allows_text_input()
603 - set_text(text) -- eg. set the text of a sign
607 Generic node metadata specific:
608 - set_infotext(infotext)
609 - get_inventory() -> InvRef
610 - set_inventory_draw_spec(string)
611 - set_allow_text_input(bool)
612 - set_allow_removal(bool)
613 - set_enforce_owner(bool)
614 - is_inventory_modified()
615 - reset_inventory_modified()
617 - reset_text_modified()
618 - set_string(name, value)
621 ObjectRef: Moving things in the game are generally these
622 (basically reference to a C++ ServerActiveObject)
624 - remove(): remove object (after returning from Lua)
625 - getpos() -> {x=num, y=num, z=num}
626 - setpos(pos); pos={x=num, y=num, z=num}
627 - moveto(pos, continuous=false): interpolated move
628 - punch(puncher, time_from_last_punch, tool_capabilities, direction)
629 ^ puncher = an another ObjectRef,
630 ^ time_from_last_punch = time since last punch action of the puncher
631 - right_click(clicker); clicker = an another ObjectRef
632 - get_hp(): returns number of hitpoints (2 * number of hearts)
633 - set_hp(hp): set number of hitpoints (2 * number of hearts)
634 - get_inventory() -> InvRef
635 - get_wield_list(): returns the name of the inventory list the wielded item is in
636 - get_wield_index(): returns the index of the wielded item
637 - get_wielded_item() -> ItemStack
638 - set_wielded_item(item): replaces the wielded item, returns true if successful
639 - set_armor_groups({group1=rating, group2=rating, ...})
640 - set_properties(object property table)
641 LuaEntitySAO-only: (no-op for other objects)
642 - setvelocity({x=num, y=num, z=num})
643 - getvelocity() -> {x=num, y=num, z=num}
644 - setacceleration({x=num, y=num, z=num})
645 - getacceleration() -> {x=num, y=num, z=num}
647 - getyaw() -> radians
649 - setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
650 - select_horiz_by_yawpitch=false)
651 - ^ Select sprite from spritesheet with optional animation and DM-style
652 - texture selection based on yaw relative to camera
653 - get_entity_name() (DEPRECATED: Will be removed in a future version)
655 Player-only: (no-op for other objects)
656 - get_player_name(): will return nil if is not a player
657 - get_look_dir(): get camera direction as a unit vector
658 - get_look_pitch(): pitch in radians
659 - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
661 InvRef: Reference to an inventory
663 - get_size(listname): get size of a list
664 - set_size(listname, size): set size of a list
665 - get_stack(listname, i): get a copy of stack index i in list
666 - set_stack(listname, i, stack): copy stack to index i in list
667 - get_list(listname): return full list
668 - set_list(listname, list): set full list (size will not change)
669 - add_item(listname, stack): add item somewhere in list, returns leftover ItemStack
670 - room_for_item(listname, stack): returns true if the stack of items
671 can be fully added to the list
672 - contains_item(listname, stack): returns true if the stack of items
673 can be fully taken from the list
674 remove_item(listname, stack): take as many items as specified from the list,
675 returns the items that were actually removed (as an ItemStack)
677 ItemStack: A stack of items.
678 - Can be created via ItemStack(itemstack or itemstring or table or nil)
680 - is_empty(): return true if stack is empty
681 - get_name(): returns item name (e.g. "default:stone")
682 - get_count(): returns number of items on the stack
683 - get_wear(): returns tool wear (0-65535), 0 for non-tools
684 - get_metadata(): returns metadata (a string attached to an item stack)
685 - clear(): removes all items from the stack, making it empty
686 - replace(item): replace the contents of this stack (item can also
687 be an itemstring or table)
688 - to_string(): returns the stack in itemstring form
689 - to_table(): returns the stack in Lua table form
690 - get_stack_max(): returns the maximum size of the stack (depends on the item)
691 - get_free_space(): returns get_stack_max() - get_count()
692 - is_known(): returns true if the item name refers to a defined item type
693 - get_definition(): returns the item definition table
694 - get_tool_capabilities(): returns the digging properties of the item,
695 ^ or those of the hand if none are defined for this item type
696 - add_wear(amount): increases wear by amount if the item is a tool
697 - add_item(item): put some item or stack onto this stack,
698 ^ returns leftover ItemStack
699 - item_fits(item): returns true if item or stack can be fully added to this one
700 - take_item(n): take (and remove) up to n items from this stack
701 ^ returns taken ItemStack
702 ^ if n is omitted, n=1 is used
703 - peek_item(n): copy (don't remove) up to n items from this stack
704 ^ returns copied ItemStack
705 ^ if n is omitted, n=1 is used
707 PseudoRandom: A pseudorandom number generator
708 - Can be created via PseudoRandom(seed)
710 - next(): return next integer random number [0...32767]
711 - next(min, max): return next integer random number [min...max]
712 (max - min) must be 32767 or <= 6553 due to the simple
713 implementation making bad distribution otherwise.
717 - Functions receive a "luaentity" as self:
718 - It has the member .name, which is the registered name ("mod:thing")
719 - It has the member .object, which is an ObjectRef pointing to the object
720 - The original prototype stuff is visible directly via a metatable
722 - on_activate(self, staticdata)
723 ^ Called when the object is instantiated.
724 - on_step(self, dtime)
725 ^ Called on every server tick (dtime is usually 0.05 seconds)
726 - on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
727 ^ Called when somebody punches the object.
728 ^ Note that you probably want to handle most punches using the
729 automatic armor group system.
730 ^ puncher: ObjectRef (can be nil)
731 ^ time_from_last_punch: Meant for disallowing spamming of clicks (can be nil)
732 ^ tool_capabilities: capability table of used tool (can be nil)
733 ^ dir: unit vector of direction of punch. Always defined. Points from
734 the puncher to the punched.
735 - on_rightclick(self, clicker)
736 - get_staticdata(self)
737 ^ Should return a string that will be passed to on_activate when
738 the object is instantiated the next time.
746 collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
747 visual = "cube"/"sprite"/"upright_sprite",
748 visual_size = {x=1, y=1},
749 textures = {}, -- number of required textures depends on visual
750 spritediv = {x=1, y=1},
751 initial_sprite_basepos = {x=0, y=0},
753 makes_footstep_sound = false,
756 Entity definition (register_entity)
758 Everything from object properties,
759 -- entity specific --
760 on_activate = function(self, staticdata),
761 on_step = function(self, dtime),
762 on_punch = function(self, hitter),
763 on_rightclick = function(self, clicker),
764 get_staticdata = function(self),
765 ^ Called sometimes; the string returned is passed to on_activate when
766 the entity is re-activated from static state
767 # Also you can define arbitrary member variables here
768 myvariable = whatever,
771 ABM (ActiveBlockModifier) definition (register_abm)
773 -- In the following two fields, also group:groupname will work.
774 nodenames = {"default:lava_source"},
775 neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
776 ^ If left out or empty, any neighbor will do
777 interval = 1.0, -- (operation interval)
778 chance = 1, -- (chance of trigger is 1.0/this)
779 action = func(pos, node, active_object_count, active_object_count_wider),
782 Item definition (register_node, register_craftitem, register_tool)
784 description = "Steel Axe",
785 groups = {}, -- key=name, value=rating; rating=1..3.
786 if rating not applicable, use 1.
787 eg. {wool=1, fluffy=3}
788 {soil=2, outerspace=1, crumbly=1}
790 {hard=1, metal=1, spikes=1}
791 inventory_image = "default_tool_steelaxe.png",
793 wield_scale = {x=1,y=1,z=1},
795 liquids_pointable = false,
796 tool_capabilities = {
797 full_punch_interval = 1.0,
801 fleshy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
802 snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
803 choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
806 on_drop = func(item, dropper, pos),
807 on_place = func(item, placer, pointed_thing),
808 on_use = func(item, user, pointed_thing),
811 Node definition (register_node)
813 <all fields allowed in item definitions>,
817 tile_images = {"default_unknown_block.png"},
818 special_materials = {
819 {image="", backface_culling=true},
820 {image="", backface_culling=true},
823 post_effect_color = {a=0, r=0, g=0, b=0},
826 is_ground_content = false,
827 sunlight_propagates = false,
832 buildable_to = false,
834 -- alternatively drop = { max_items = ..., items = { ... } }
837 liquid_alternative_flowing = "",
838 liquid_alternative_source = "",
839 liquid_viscosity = 0,
841 damage_per_second = 0,
842 selection_box = {type="regular"},
843 legacy_facedir_simple = false, -- Support maps made in and before January 2012
844 legacy_wallmounted = false, -- Support maps made in and before January 2012
846 footstep = <SimpleSoundSpec>,
847 dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
848 dug = <SimpleSoundSpec>,
852 Recipe: (register_craft)
854 output = 'default:pick_stone',
856 {'default:cobble', 'default:cobble', 'default:cobble'},
857 {'', 'default:stick', ''},
858 {'', 'default:stick', ''},
860 replacements = <optional list of item pairs,
861 replace one input item with another item on crafting>
867 output = 'mushrooms:mushroom_stew',
870 "mushrooms:mushroom_brown",
871 "mushrooms:mushroom_red",
873 replacements = <optional list of item pairs,
874 replace one input item with another item on crafting>
877 Recipe (tool repair):
880 additional_wear = -0.02,
886 output = "default:glass",
887 recipe = "default:sand",
891 Recipe (furnace fuel):
894 recipe = "default:leaves",
898 Chatcommand definition (register_chatcommand)
900 params = "<name> <privilege>", -- short parameter description
901 description = "Remove privilege from player", -- full description
902 privs = {privs=true}}, -- require the "privs" privilege to run
903 func = function(name, param), -- called when command is run