]> git.lizzy.rs Git - minetest.git/blob - doc/lua_api.txt
Add minetest.is_singleplayer()
[minetest.git] / doc / lua_api.txt
1 Minetest Lua Modding API Reference 0.4.dev
2 ==========================================
3 More information at http://c55.me/minetest/
4
5 Introduction
6 -------------
7 Content and functionality can be added to Minetest 0.4 by using Lua
8 scripting in run-time loaded mods.
9
10 A mod is a self-contained bunch of scripts, textures and other related
11 things that is loaded by and interfaces with Minetest.
12
13 Mods are contained and ran solely on the server side. Definitions and media
14 files are automatically transferred to the client.
15
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>.
19
20 Programming in Lua
21 -------------------
22 If you have any difficulty in understanding this, please read:
23   http://www.lua.org/pil/
24
25 Startup
26 --------
27 Mods are loaded during server startup from the mod load paths by running
28 the init.lua scripts.
29
30 Mod load path
31 -------------
32 Generic:
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
37   $worldpath/worldmods/
38
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/
43
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
48
49 Mod directory structure
50 ------------------------
51 mods
52 |-- modname
53 |   |-- depends.txt
54 |   |-- init.lua
55 |   |-- textures
56 |   |   |-- modname_stuff.png
57 |   |   `-- modname_something_else.png
58 |   |-- sounds
59 |   |-- media
60 |   `-- <custom data>
61 `-- another
62
63 modname:
64   The location of this directory can be fetched by using
65   minetest.get_modpath(modname)
66
67 depends.txt:
68   List of mods that have to be loaded before loading this mod.
69   A single line contains a single modname.
70
71 init.lua:
72   The main Lua script. Running this script should register everything it
73   wants to register. Subsequent execution depends on minetest calling the
74   registered callbacks.
75
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.
78
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.
82
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_)
87
88 This is to prevent conflicting names from corrupting maps and is
89 enforced by the mod loader.
90
91 Example: mod "experimental", ideal item/node/entity name "tnt":
92          -> the name should be "experimental:tnt".
93
94 Enforcement can be overridden by prefixing the name with ":". This can
95 be used for overriding the registrations of some other mod.
96
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)
100
101 The ":" prefix can also be used for maintaining backwards compatibility.
102
103 Aliases
104 -------
105 Aliases can be added by using minetest.register_alias(name, convert_to)
106
107 This will make Minetest to convert things called name to things called
108 convert_to.
109
110 This can be used for maintaining backwards compatibility.
111
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".
116
117 Textures
118 --------
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"
122
123 Textures are referred to by their complete name, or alternatively by
124 stripping out the file extension:
125   eg. foomod_foothing.png
126   eg. foomod_foothing
127
128 Sounds
129 -------
130 Only OGG files are supported.
131
132 For positional playing of sounds, only single-channel (mono) files are
133 supported. Otherwise OpenAL will play them non-positionally.
134
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"
138
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.
142
143 When playing the sound "foomod_foosound", the sound is chosen randomly
144 from the available ones of the following files:
145   foomod_foosound.ogg
146   foomod_foosound.0.ogg
147   foomod_foosound.1.ogg
148   ...
149   foomod_foosound.9.ogg
150
151 Examples of sound parameter tables:
152 -- Play locationless on all clients
153 {
154         gain = 1.0, -- default
155 }
156 -- Play locationless to a player
157 {
158         to_player = name,
159         gain = 1.0, -- default
160 }
161 -- Play in a location
162 {
163         pos = {x=1,y=2,z=3},
164         gain = 1.0, -- default
165         max_hear_distance = 32, -- default
166 }
167 -- Play connected to an object, looped
168 {
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
173 }
174
175 Representations of simple things
176 --------------------------------
177 MapNode representation:
178   {name="name", param1=num, param2=num}
179
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]
183
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.
187
188 param1 is reserved for the engine when:
189   paramtype != "none"
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"
195
196 Position/vector:
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.
200
201 stackstring/itemstring: A stack of items in serialized format.
202 eg. 'default:dirt 5'
203 eg. 'default:pick_wood 21323'
204 eg. 'default:apple'
205
206 item: A stack of items in Lua table format.
207 eg. {name="default:dirt", count=5, wear=0, metadata=""} 
208     ^ 5 dirt nodes
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=""}
212     ^ an apple.
213
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.
216
217 SimpleSoundSpec:
218 eg. ""
219 eg. "default_place_node"
220 eg. {}
221 eg. {name="default_place_node"}
222 eg. {name="default_place_node", gain=1.0}
223
224 Items
225 ------
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):
231   A miscellaneous item
232
233 Groups
234 -------
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.
239
240 Usage:
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.
251
252 Groups of items
253 ----------------
254 Groups of items can define what kind of an item it is (eg. wool).
255
256 Groups of nodes
257 ----------------
258 In addition to the general item things, whether a node is diggable and how
259 long it takes is defined by using groups.
260
261 Groups of entities
262 -------------------
263 For entities, groups are, as of now, used only for calculating damage.
264
265 object.get_armor_groups() -> a group-rating table (eg. {fleshy=3})
266 object.set_armor_groups({level=2, fleshy=2, cracky=2})
267
268 Groups of tools
269 ----------------
270 Groups in tools define which groups of nodes and entities they are
271 effective towards.
272
273 Groups in crafting recipes
274 ---------------------------
275 - Not implemented yet. (TODO)
276 - Will probably look like this:
277 {
278     output = 'food:meat_soup_raw',
279     recipe = {
280         {'group:meat'},
281         {'group:water'},
282         {'group:bowl'},
283     },
284         preserve = {'group:bowl'},
285 }
286
287 Special groups
288 ---------------
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 - dig_immediate: (player can always pick up node without tool wear)
296   - 2: node is removed without tool wear after 0.5 seconds or so
297        (rail, sign)
298   - 3: node is removed without tool wear immediately (torch)
299
300 Known damage and digging time defining groups
301 ----------------------------------------------
302 - crumbly: dirt, sand
303 - cracky: tough but crackable stuff like stone.
304 - snappy: something that can be cut using fine tools; eg. leaves, small
305           plants, wire, sheets of metal
306 - choppy: something that can be cut using force; eg. trees, wooden planks
307 - fleshy: Living things like animals and the player. This could imply
308           some blood effects when hitting.
309 - explody: Especially prone to explosions
310 - oddly_breakable_by_hand:
311    Can be added to nodes that shouldn't logically be breakable by the
312    hand but are. Somewhat similar to dig_immediate, but times are more
313    like {[1]=3.50,[2]=2.00,[3]=0.70} and this does not override the
314    speed of a tool if the tool can dig at a larger speed than this
315    suggests for the hand.
316
317 Examples of custom groups
318 --------------------------
319 Item groups are often used for defining, well, //groups of items//.
320 - meat: any meat-kind of a thing (rating might define the size or healing
321   ability or be irrelevant - it is not defined as of yet)
322 - eatable: anything that can be eaten. Rating might define HP gain in half
323   hearts.
324 - flammable: can be set on fire. Rating might define the intensity of the
325   fire, affecting eg. the speed of the spreading of an open fire.
326 - wool: any wool (any origin, any color)
327 - metal: any metal
328 - weapon: any weapon
329 - heavy: anything considerably heavy
330
331 Digging time calculation specifics
332 -----------------------------------
333 Groups such as **crumbly**, **cracky** and **snappy** are used for this
334 purpose. Rating is 1, 2 or 3. A higher rating for such a group implies
335 faster digging time.
336
337 Also, the **level** group is used.
338
339 Tools define their properties by a list of parameters for groups. They
340 cannot dig other groups; thus it is important to use a standard bunch of
341 groups to enable interaction with tools.
342
343 **Example definition of the digging capabilities of a tool:**
344 tool_capabilities = {
345         full_punch_interval=1.5,
346         max_drop_level=1,
347         groupcaps={
348                 crumbly={maxwear=0.01, maxlevel=2, times={[1]=0.80, [2]=0.60, [3]=0.40}}
349         }
350 }
351
352 **Tools define:**
353   * Full punch interval Maximum drop level For an arbitrary list of groups:
354   * Maximum level (usually 0, 1, 2 or 3) Maximum wear (0...1) Digging times
355
356 **Full punch interval**: When used as a weapon, the tool will do full
357 damage if this time is spent between punches. If eg. half the time is
358 spent, the tool will do half damage.
359
360 **Maximum drop level** suggests the maximum level of node, when dug with
361 the tool, that will drop it's useful item. (eg. iron ore to drop a lump of
362 iron).
363
364 **Maximum level** tells what is the maximum level of a node of this group
365 that the tool will be able to dig.
366
367 **Maximum wear** determines how much the tool wears out when it is used for
368 digging a node, of this group, of the maximum level. For lower leveled
369 tools, the wear is divided by //4// to the exponent //level difference//.
370 This means for a maximum wear of 0.1, a level difference 1 will result in
371 wear=0.1/4=0.025, and a level difference of 2 will result in
372 wear=0.1/(4*4)=0.00625.
373
374 **Digging times** is basically a list of digging times for different
375 ratings of the group. It also determines the damage done to entities, based
376 on their "armor groups".
377   * For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
378   * result the tool to be able to dig nodes that have a rating of 2 or 3
379   * for this group, and unable to dig the rating 1, which is the toughest.
380   * Unless there is a matching group that enables digging otherwise.  For
381   * entities, damage equals the amount of nodes dug in the time spent
382   * between hits, with a maximum of ''full_punch_interval''.
383
384 Entity damage mechanism
385 ------------------------
386 Client predicts damage based on damage groups. Because of this, it is able to
387 give an immediate response when an entity is damaged or dies; the response is
388 pre-defined somehow (eg. by defining a sprite animation) (not implemented;
389 TODO).
390
391 The group **immortal** will completely disable normal damage.
392
393 Entities can define a special armor group, which is **punch_operable**. This
394 group will disable the regular damage mechanism for players punching it by hand
395 or a non-tool item.
396
397 On the Lua side, every punch calls ''entity:on_punch(puncher,
398 time_from_last_punch, tool_capabilities, direction)''. This should never be
399 called directly, because damage is usually not handled by the entity itself.
400   * ''puncher'' is the object performing the punch. Can be nil. Should never be
401     accessed unless absolutely required.
402   * ''time_from_last_punch'' is time from last punch (by puncher) or nil.
403   * ''tool_capabilities'' can be nil.
404   * ''direction'' is a unit vector, pointing from the source of the punch to
405     the punched object.
406
407 To punch an entity/object in Lua, call ''object:punch(puncher, time_from_last_punch, tool_capabilities, direction)''.
408   * Return value is tool wear.
409   * Parameters are equal to the above callback.
410   * If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
411     automatically filled in based on the location of ''puncher''.
412
413 Helper functions
414 -----------------
415 dump2(obj, name="_", dumped={})
416 ^ Return object serialized as a string, handles reference loops
417 dump(obj, dumped={})
418 ^ Return object serialized as a string
419
420 minetest namespace reference
421 -----------------------------
422 minetest.get_current_modname() -> string
423 minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
424 ^ Useful for loading additional .lua modules or static data from mod
425 minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
426 ^ Useful for storing custom data
427 minetest.is_singleplayer()
428
429 minetest.debug(line)
430 ^ Goes to dstream
431 minetest.log(line)
432 minetest.log(loglevel, line)
433 ^ loglevel one of "error", "action", "info", "verbose"
434
435 minetest.register_entity(name, prototype table)
436 minetest.register_abm(abm definition)
437 minetest.register_node(name, node definition)
438 minetest.register_tool(name, item definition)
439 minetest.register_craftitem(name, item definition)
440 minetest.register_alias(name, convert_to)
441 minetest.register_craft(recipe)
442
443 minetest.register_globalstep(func(dtime))
444 minetest.register_on_placenode(func(pos, newnode, placer))
445 minetest.register_on_dignode(func(pos, oldnode, digger))
446 minetest.register_on_punchnode(func(pos, node, puncher))
447 minetest.register_on_generated(func(minp, maxp))
448 minetest.register_on_newplayer(func(ObjectRef))
449 minetest.register_on_dieplayer(func(ObjectRef))
450 minetest.register_on_respawnplayer(func(ObjectRef))
451 ^ return true in func to disable regular player placement
452 ^ currently called _before_ repositioning of player occurs
453 minetest.register_on_chat_message(func(name, message))
454
455 minetest.add_to_creative_inventory(itemstring)
456 minetest.setting_get(name) -> string or nil
457 minetest.setting_getbool(name) -> boolean value or nil
458
459 minetest.chat_send_all(text)
460 minetest.chat_send_player(name, text)
461 minetest.get_player_privs(name) -> set of privs
462 minetest.get_inventory(location) -> InvRef
463 ^ location = eg. {type="player", name="celeron55"}
464                  {type="node", pos={x=, y=, z=}}
465
466 minetest.sound_play(spec, parameters) -> handle
467 ^ spec = SimpleSoundSpec
468 ^ parameters = sound parameter table
469 minetest.sound_stop(handle)
470
471 minetest.after(time, func, param)
472 ^ Call function after time seconds
473 ^ param is optional; to pass multiple parameters, pass a table.
474
475 Global objects:
476 minetest.env - environment reference
477
478 Global tables:
479 minetest.registered_items
480 ^ List of registered items, indexed by name
481 minetest.registered_nodes
482 ^ List of registered node definitions, indexed by name
483 minetest.registered_craftitems
484 ^ List of registered craft item definitions, indexed by name
485 minetest.registered_tools
486 ^ List of registered tool definitions, indexed by name
487 minetest.registered_entities
488 ^ List of registered entity prototypes, indexed by name
489 minetest.object_refs
490 ^ List of object references, indexed by active object id
491 minetest.luaentities
492 ^ List of lua entities, indexed by active object id
493
494 Deprecated but defined for backwards compatibility:
495 minetest.digprop_constanttime(time)
496 minetest.digprop_stonelike(toughness)
497 minetest.digprop_dirtlike(toughness)
498 minetest.digprop_gravellike(toughness)
499 minetest.digprop_woodlike(toughness)
500 minetest.digprop_leaveslike(toughness)
501 minetest.digprop_glasslike(toughness)
502
503 Class reference
504 ----------------
505 EnvRef: basically ServerEnvironment and ServerMap combined.
506 methods:
507 - add_node(pos, node)
508 - remove_node(pos)
509 - get_node(pos)
510   ^ Returns {name="ignore", ...} for unloaded area
511 - get_node_or_nil(pos)
512   ^ Returns nil for unloaded area
513 - get_node_light(pos, timeofday) -> 0...15 or nil
514   ^ timeofday: nil = current time, 0 = night, 0.5 = day
515 - add_entity(pos, name): Returns ObjectRef or nil if failed
516 - add_item(pos, itemstring)
517 - add_rat(pos)
518 - add_firefly(pos)
519 - get_meta(pos) -- Get a NodeMetaRef at that position
520 - get_player_by_name(name) -- Get an ObjectRef to a player
521 - get_objects_inside_radius(pos, radius)
522 - set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
523 - get_timeofday()
524
525 NodeMetaRef (this stuff is subject to change in a future version)
526 methods:
527 - get_type()
528 - allows_text_input()
529 - set_text(text) -- eg. set the text of a sign
530 - get_text()
531 - get_owner()
532 - set_owner(string)
533 Generic node metadata specific:
534 - set_infotext(infotext)
535 - get_inventory() -> InvRef
536 - set_inventory_draw_spec(string)
537 - set_allow_text_input(bool)
538 - set_allow_removal(bool)
539 - set_enforce_owner(bool)
540 - is_inventory_modified()
541 - reset_inventory_modified()
542 - is_text_modified()
543 - reset_text_modified()
544 - set_string(name, value)
545 - get_string(name)
546
547 ObjectRef: Moving things in the game are generally these
548 (basically reference to a C++ ServerActiveObject)
549 methods:
550 - remove(): remove object (after returning from Lua)
551 - getpos() -> {x=num, y=num, z=num}
552 - setpos(pos); pos={x=num, y=num, z=num}
553 - moveto(pos, continuous=false): interpolated move
554 - punch(puncher, time_from_last_punch, tool_capabilities, direction)
555   ^ puncher = an another ObjectRef,
556   ^ time_from_last_punch = time since last punch action of the puncher
557 - right_click(clicker); clicker = an another ObjectRef
558 - get_hp(): returns number of hitpoints (2 * number of hearts)
559 - set_hp(hp): set number of hitpoints (2 * number of hearts)
560 - get_inventory() -> InvRef
561 - get_wield_list(): returns the name of the inventory list the wielded item is in
562 - get_wield_index(): returns the index of the wielded item
563 - get_wielded_item() -> ItemStack
564 - set_wielded_item(item): replaces the wielded item, returns true if successful
565 LuaEntitySAO-only: (no-op for other objects)
566 - setvelocity({x=num, y=num, z=num})
567 - getvelocity() -> {x=num, y=num, z=num}
568 - setacceleration({x=num, y=num, z=num})
569 - getacceleration() -> {x=num, y=num, z=num}
570 - setyaw(radians)
571 - getyaw() -> radians
572 - settexturemod(mod)
573 - setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
574 -           select_horiz_by_yawpitch=false)
575 - ^ Select sprite from spritesheet with optional animation and DM-style
576 -   texture selection based on yaw relative to camera
577 - set_armor_groups({group1=rating, group2=rating, ...})
578 - get_entity_name() (DEPRECATED: Will be removed in a future version)
579 - get_luaentity()
580 Player-only: (no-op for other objects)
581 - get_player_name(): will return nil if is not a player
582 - get_look_dir(): get camera direction as a unit vector
583 - get_look_pitch(): pitch in radians
584 - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
585
586 InvRef: Reference to an inventory
587 methods:
588 - get_size(listname): get size of a list
589 - set_size(listname, size): set size of a list
590 - get_stack(listname, i): get a copy of stack index i in list
591 - set_stack(listname, i, stack): copy stack to index i in list
592 - get_list(listname): return full list
593 - set_list(listname, list): set full list (size will not change)
594 - add_item(listname, stack): add item somewhere in list, returns leftover ItemStack
595 - room_for_item(listname, stack): returns true if the stack of items
596     can be fully added to the list
597 - contains_item(listname, stack): returns true if the stack of items
598     can be fully taken from the list
599   remove_item(listname, stack): take as many items as specified from the list,
600     returns the items that were actually removed (as an ItemStack)
601
602 ItemStack: A stack of items.
603 - Can be created via ItemStack(itemstack or itemstring or table or nil)
604 methods:
605 - is_empty(): return true if stack is empty
606 - get_name(): returns item name (e.g. "default:stone")
607 - get_count(): returns number of items on the stack
608 - get_wear(): returns tool wear (0-65535), 0 for non-tools
609 - get_metadata(): returns metadata (a string attached to an item stack)
610 - clear(): removes all items from the stack, making it empty
611 - replace(item): replace the contents of this stack (item can also
612     be an itemstring or table)
613 - to_string(): returns the stack in itemstring form
614 - to_table(): returns the stack in Lua table form
615 - get_stack_max(): returns the maximum size of the stack (depends on the item)
616 - get_free_space(): returns get_stack_max() - get_count()
617 - is_known(): returns true if the item name refers to a defined item type
618 - get_definition(): returns the item definition table
619 - get_tool_capabilities(): returns the digging properties of the item,
620   ^ or those of the hand if none are defined for this item type
621 - add_wear(amount): increases wear by amount if the item is a tool
622 - add_item(item): put some item or stack onto this stack,
623   ^ returns leftover ItemStack
624 - item_fits(item): returns true if item or stack can be fully added to this one
625 - take_item(n): take (and remove) up to n items from this stack
626   ^ returns taken ItemStack
627   ^ if n is omitted, n=1 is used
628 - peek_item(n): copy (don't remove) up to n items from this stack
629   ^ returns copied ItemStack
630   ^ if n is omitted, n=1 is used
631
632 PseudoRandom: A pseudorandom number generator
633 - Can be created via PseudoRandom(seed)
634 methods:
635 - next(): return next random number [0...32767]
636
637 Registered entities
638 --------------------
639 - Functions receive a "luaentity" as self:
640   - It has the member .name, which is the registered name ("mod:thing")
641   - It has the member .object, which is an ObjectRef pointing to the object
642   - The original prototype stuff is visible directly via a metatable
643 - Callbacks:
644   - on_activate(self, staticdata)
645     ^ Called when the object is instantiated.
646   - on_step(self, dtime)
647     ^ Called on every server tick (dtime is usually 0.05 seconds)
648   - on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
649     ^ Called when somebody punches the object.
650     ^ Note that you probably want to handle most punches using the
651       automatic armor group system.
652     ^ puncher: ObjectRef (can be nil)
653     ^ time_from_last_punch: Meant for disallowing spamming of clicks (can be nil)
654     ^ tool_capabilities: capability table of used tool (can be nil)
655         ^ dir: unit vector of direction of punch. Always defined. Points from
656                the puncher to the punched.
657   - on_rightclick(self, clicker)
658   - get_staticdata(self)
659     ^ Should return a string that will be passed to on_activate when
660       the object is instantiated the next time.
661
662 Definition tables
663 ------------------
664
665 Entity definition (register_entity)
666 {
667     physical = true,
668     collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
669     visual = "cube"/"sprite",
670     visual_size = {x=1, y=1},
671     textures = {texture,texture,texture,texture,texture,texture},
672     spritediv = {x=1, y=1},
673     initial_sprite_basepos = {x=0, y=0},
674     on_activate = function(self, staticdata),
675     on_step = function(self, dtime),
676     on_punch = function(self, hitter),
677     on_rightclick = function(self, clicker),
678     get_staticdata = function(self),
679     # Also you can define arbitrary member variables here
680     myvariable = whatever,
681 }
682
683 ABM (ActiveBlockModifier) definition (register_abm)
684 {
685     nodenames = {"default:lava_source"},
686     neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
687      ^ If left out or empty, any neighbor will do
688     interval = 1.0, -- (operation interval)
689     chance = 1, -- (chance of trigger is 1.0/this)
690     action = func(pos, node, active_object_count, active_object_count_wider),
691 }
692
693 Item definition (register_node, register_craftitem, register_tool)
694 {
695     description = "Steel Axe",
696     groups = {}, -- key=name, value=rating; rating=1..3.
697                     if rating not applicable, use 1.
698                     eg. {wool=1, fluffy=3}
699                         {soil=2, outerspace=1, crumbly=1}
700                         {bendy=2, snappy=1},
701                         {hard=1, metal=1, spikes=1}
702     inventory_image = "default_tool_steelaxe.png",
703     wield_image = "",
704     wield_scale = {x=1,y=1,z=1},
705     stack_max = 99,
706     liquids_pointable = false,
707     tool_capabilities = {
708         full_punch_interval = 1.0,
709         max_drop_level=0,
710         groupcaps={
711             -- For example:
712             fleshy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
713             snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
714             choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
715         }
716     }
717     on_drop = func(item, dropper, pos),
718     on_place = func(item, placer, pointed_thing),
719     on_use = func(item, user, pointed_thing),
720 }
721
722 Node definition (register_node)
723 {
724     <all fields allowed in item definitions>,
725
726     drawtype = "normal",
727     visual_scale = 1.0,
728     tile_images = {"default_unknown_block.png"},
729     special_materials = {
730         {image="", backface_culling=true},
731         {image="", backface_culling=true},
732     },
733     alpha = 255,
734     post_effect_color = {a=0, r=0, g=0, b=0},
735     paramtype = "none",
736     paramtype2 = "none",
737     is_ground_content = false,
738     sunlight_propagates = false,
739     walkable = true,
740     pointable = true,
741     diggable = true,
742     climbable = false,
743     buildable_to = false,
744     drop = "",
745     -- alternatively drop = { max_items = ..., items = { ... } }
746     metadata_name = "",
747     liquidtype = "none",
748     liquid_alternative_flowing = "",
749     liquid_alternative_source = "",
750     liquid_viscosity = 0,
751     light_source = 0,
752     damage_per_second = 0,
753     selection_box = {type="regular"},
754     legacy_facedir_simple = false, -- Support maps made in and before January 2012
755     legacy_wallmounted = false, -- Support maps made in and before January 2012
756     sounds = {
757         footstep = <SimpleSoundSpec>,
758         dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
759         dug = <SimpleSoundSpec>,
760     },
761 }
762
763 Recipe: (register_craft)
764 {
765     output = 'default:pick_stone',
766     recipe = {
767         {'default:cobble', 'default:cobble', 'default:cobble'},
768         {'', 'default:stick', ''},
769         {'', 'default:stick', ''},
770     },
771     replacements = <optional list of item pairs,
772                     replace one input item with another item on crafting>
773 }
774
775 Recipe (shapeless):
776 {
777     type = "shapeless",
778     output = 'mushrooms:mushroom_stew',
779     recipe = {
780         "mushrooms:bowl",
781         "mushrooms:mushroom_brown",
782         "mushrooms:mushroom_red",
783     },
784     replacements = <optional list of item pairs,
785                     replace one input item with another item on crafting>
786 }
787
788 Recipe (tool repair):
789 {
790     type = "toolrepair",
791     additional_wear = -0.02,
792 }
793
794 Recipe (cooking):
795 {
796     type = "cooking",
797     output = "default:glass",
798     recipe = "default:sand",
799     cooktime = 3,
800 }
801
802 Recipe (furnace fuel):
803 {
804     type = "fuel",
805     recipe = "default:leaves",
806     burntime = 1,
807 }
808
809