doc/lua_api.txt

   1 -- Quick documentation about the API
   2 -- =================================
   3 --
   4 -- Helper functions defined by builtin.lua:
   5 -- dump2(obj, name="_", dumped={})
   6 -- dump(obj, dumped={})
   7 --
   8 -- Mod load path
   9 -- -------------
  10 -- Generic:
  11 -- $path_data/mods/
  12 -- $path_userdata/usermods/
  13 -- $mapdir/worldmods/
  14 --
  15 -- On a run-in-place version (eg. the distributed windows version):
  16 -- minetest-0.4.x/data/mods/
  17 -- minetest-0.4.x/usermods/
  18 -- minetest-0.4.x/world/worldmods/
  19 --
  20 -- On an installed version on linux:
  21 -- /usr/share/minetest/mods/
  22 -- ~/.minetest/usermods
  23 -- ~/.minetest/world/worldmods
  24 --
  25 -- Naming convention for registered textual names
  26 -- ----------------------------------------------
  27 -- "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
  28 --
  29 -- This is to prevent conflicting names from corrupting maps and is
  30 -- enforced by the mod loader.
  31 --
  32 -- Example: mod "experimental", ideal item/node/entity name "tnt":
  33 --          -> the name should be "experimental:tnt".
  34 --
  35 -- Enforcement can be overridden by prefixing the name with ":". This can
  36 -- be used for overriding the registrations of some other mod.
  37 --
  38 -- Example: Any mod can redefine experimental:tnt by using the name
  39 --          ":experimental:tnt" when registering it.
  40 -- (also that mods is required to have "experimental" as a dependency)
  41 --
  42 -- The legacy mod uses ":" for maintaining backwards compatibility.
  43 --
  44 -- Textures
  45 -- --------
  46 -- Mods should generally prefix their textures with modname_, eg. given
  47 -- the mod name "foomod", a texture could be called "default_foomod_superfurnace.png"
  48 --
  49 -- This is not crucial and a conflicting name will not corrupt maps.
  50 --
  51 -- Representations of simple things
  52 -- --------------------------------
  53 --
  54 -- MapNode representation:
  55 -- {name="name", param1=num, param2=num}
  56 --
  57 -- param1 and param2 are 8 bit and 4 bit integers, respectively. They
  58 -- are reserved for certain automated functions. If you don't use these
  59 -- functions, you can use them to store arbitrary values.
  60 --
  61 -- param1 is reserved for the engine when:
  62 --   paramtype != "none"
  63 -- param2 is reserved for the engine when any of these are used:
  64 --   liquidtype == "flowing"
  65 --   drawtype == "flowingliquid"
  66 --   drawtype == "torchlike"
  67 --   drawtype == "signlike"
  68 --
  69 -- Position representation:
  70 -- {x=num, y=num, z=num}
  71 --
  72 -- stackstring/itemstring: A stack of items in serialized format.
  73 -- eg. 'node "default:dirt" 5'
  74 -- eg. 'tool "default:pick_wood" 21323'
  75 -- eg. 'craft "default:apple" 2'
  76 --
  77 -- item: A stack of items in Lua table format.
  78 -- eg. {name="default:dirt", count=1, wear=0, metadata=""}
  79 --     ^ a single dirt node
  80 -- eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
  81 --     ^ a wooden pick about 1/3 weared out
  82 -- eg. {name="default:apple", count=1, wear=0, metadata=""}
  83 --     ^ an apple.
  84 --
  85 -- Any time an item must be passed to a function, it can be an
  86 -- ItemStack (see below), an itemstring or a table in the above format.
  87 --
  88 -- Global functions:
  89 -- minetest.register_entity(name, prototype table)
  90 -- minetest.register_abm(abm definition)
  91 -- minetest.register_node(name, node definition)
  92 -- minetest.register_tool(name, item definition)
  93 -- minetest.register_craftitem(name, item definition)
  94 -- minetest.register_alias(name, convert_to)
  95 -- minetest.register_craft(recipe)
  96 -- minetest.register_globalstep(func(dtime))
  97 -- minetest.register_on_placenode(func(pos, newnode, placer))
  98 -- minetest.register_on_dignode(func(pos, oldnode, digger))
  99 -- minetest.register_on_punchnode(func(pos, node, puncher))
 100 -- minetest.register_on_generated(func(minp, maxp))
 101 -- minetest.register_on_newplayer(func(ObjectRef))
 102 -- minetest.register_on_dieplayer(func(ObjectRef))
 103 -- minetest.register_on_respawnplayer(func(ObjectRef))
 104 -- ^ return true in func to disable regular player placement
 105 -- ^ currently called _before_ repositioning of player occurs
 106 -- minetest.register_on_chat_message(func(name, message))
 107 -- minetest.add_to_creative_inventory(itemstring)
 108 -- minetest.setting_get(name) -> string or nil
 109 -- minetest.setting_getbool(name) -> boolean value or nil
 110 -- minetest.chat_send_all(text)
 111 -- minetest.chat_send_player(name, text)
 112 -- minetest.get_player_privs(name) -> set of privs
 113 -- minetest.get_inventory(location) -> InvRef
 114 -- minetest.get_current_modname() -> string
 115 -- minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
 116 -- ^ location = eg. {type="player", name="celeron55"}
 117 --                  {type="node", pos={x=, y=, z=}}
 118 --
 119 -- minetest.debug(line)
 120 -- ^ Goes to dstream
 121 -- minetest.log(line)
 122 -- minetest.log(loglevel, line)
 123 -- ^ loglevel one of "error", "action", "info", "verbose"
 124 --
 125 -- minetest.digprop_constanttime(time)
 126 -- minetest.digprop_stonelike(toughness)
 127 -- minetest.digprop_dirtlike(toughness)
 128 -- minetest.digprop_gravellike(toughness)
 129 -- minetest.digprop_woodlike(toughness)
 130 -- minetest.digprop_leaveslike(toughness)
 131 -- minetest.digprop_glasslike(toughness)
 132 --
 133 -- Global objects:
 134 -- minetest.env - environment reference
 135 --
 136 -- Global tables:
 137 -- minetest.registered_items
 138 -- ^ List of registered items, indexed by name
 139 -- minetest.registered_nodes
 140 -- ^ List of registered node definitions, indexed by name
 141 -- minetest.registered_craftitems
 142 -- ^ List of registered craft item definitions, indexed by name
 143 -- minetest.registered_tools
 144 -- ^ List of registered tool definitions, indexed by name
 145 -- minetest.registered_entities
 146 -- ^ List of registered entity prototypes, indexed by name
 147 -- minetest.object_refs
 148 -- ^ List of object references, indexed by active object id
 149 -- minetest.luaentities
 150 -- ^ List of lua entities, indexed by active object id
 151 --
 152 -- EnvRef is basically ServerEnvironment and ServerMap combined.
 153 -- EnvRef methods:
 154 -- - add_node(pos, node)
 155 -- - remove_node(pos)
 156 -- - get_node(pos)
 157 --   ^ Returns {name="ignore", ...} for unloaded area
 158 -- - get_node_or_nil(pos)
 159 --   ^ Returns nil for unloaded area
 160 -- - get_node_light(pos, timeofday) -> 0...15 or nil
 161 --   ^ timeofday: nil = current time, 0 = night, 0.5 = day
 162 -- - add_entity(pos, name): Returns ObjectRef or nil if failed
 163 -- - add_item(pos, itemstring)
 164 -- - add_rat(pos)
 165 -- - add_firefly(pos)
 166 -- - get_meta(pos) -- Get a NodeMetaRef at that position
 167 -- - get_player_by_name(name) -- Get an ObjectRef to a player
 168 -- - get_objects_inside_radius(pos, radius)
 169 --
 170 -- NodeMetaRef (this stuff is subject to change in a future version)
 171 -- - get_type()
 172 -- - allows_text_input()
 173 -- - set_text(text) -- eg. set the text of a sign
 174 -- - get_text()
 175 -- - get_owner()
 176 -- - set_owner(string)
 177 -- Generic node metadata specific:
 178 -- - set_infotext(infotext)
 179 -- - get_inventory() -> InvRef
 180 -- - set_inventory_draw_spec(string)
 181 -- - set_allow_text_input(bool)
 182 -- - set_allow_removal(bool)
 183 -- - set_enforce_owner(bool)
 184 -- - is_inventory_modified()
 185 -- - reset_inventory_modified()
 186 -- - is_text_modified()
 187 -- - reset_text_modified()
 188 -- - set_string(name, value)
 189 -- - get_string(name)
 190 --
 191 -- ObjectRef is basically ServerActiveObject.
 192 -- ObjectRef methods:
 193 -- - remove(): remove object (after returning from Lua)
 194 -- - getpos() -> {x=num, y=num, z=num}
 195 -- - setpos(pos); pos={x=num, y=num, z=num}
 196 -- - moveto(pos, continuous=false): interpolated move
 197 -- - punch(puncher, time_from_last_punch)
 198 --   ^ puncher = an another ObjectRef,
 199 --   ^ time_from_last_punch = time since last punch action of the puncher
 200 -- - right_click(clicker); clicker = an another ObjectRef
 201 -- - get_hp(): returns number of hitpoints (2 * number of hearts)
 202 -- - set_hp(hp): set number of hitpoints (2 * number of hearts)
 203 -- - get_inventory() -> InvRef
 204 -- - get_wield_list(): returns the name of the inventory list the wielded item is in
 205 -- - get_wield_index(): returns the index of the wielded item
 206 -- - get_wielded_item() -> ItemStack
 207 -- - set_wielded_item(item): replaces the wielded item, returns true if successful
 208 -- LuaEntitySAO-only: (no-op for other objects)
 209 -- - setvelocity({x=num, y=num, z=num})
 210 -- - getvelocity() -> {x=num, y=num, z=num}
 211 -- - setacceleration({x=num, y=num, z=num})
 212 -- - getacceleration() -> {x=num, y=num, z=num}
 213 -- - setyaw(radians)
 214 -- - getyaw() -> radians
 215 -- - settexturemod(mod)
 216 -- - setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
 217 -- -           select_horiz_by_yawpitch=false)
 218 -- - ^ Select sprite from spritesheet with optional animation and DM-style
 219 -- -   texture selection based on yaw relative to camera
 220 -- - get_entity_name() (DEPRECATED: Will be removed in a future version)
 221 -- - get_luaentity()
 222 -- Player-only: (no-op for other objects)
 223 -- - get_player_name(): will return nil if is not a player
 224 -- - get_look_dir(): get camera direction as a unit vector
 225 -- - get_look_pitch(): pitch in radians
 226 -- - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
 227 --
 228 -- InvRef methods:
 229 -- - get_size(listname): get size of a list
 230 -- - set_size(listname, size): set size of a list
 231 -- - get_stack(listname, i): get a copy of stack index i in list
 232 -- - set_stack(listname, i, stack): copy stack to index i in list
 233 -- - get_list(listname): return full list
 234 -- - set_list(listname, list): set full list (size will not change)
 235 -- - add_item(listname, stack): add item somewhere in list, returns leftover ItemStack
 236 -- - room_for_item(listname, stack): returns true if the stack of items
 237 --     can be fully added to the list
 238 -- - contains_item(listname, stack): returns true if the stack of items
 239 --     can be fully taken from the list
 240 --   remove_item(listname, stack): take as many items as specified from the list,
 241 --     returns the items that were actually removed (as an ItemStack)
 242 --
 243 -- ItemStack methods:
 244 -- - is_empty(): return true if stack is empty
 245 -- - get_name(): returns item name (e.g. "default:stone")
 246 -- - get_count(): returns number of items on the stack
 247 -- - get_wear(): returns tool wear (0-65535), 0 for non-tools
 248 -- - get_metadata(): returns metadata (a string attached to an item stack)
 249 -- - clear(): removes all items from the stack, making it empty
 250 -- - replace(item): replace the contents of this stack (item can also
 251 --     be an itemstring or table)
 252 -- - to_string(): returns the stack in itemstring form
 253 -- - to_table(): returns the stack in Lua table form
 254 -- - get_stack_max(): returns the maximum size of the stack (depends on the item)
 255 -- - get_free_space(): returns get_stack_max() - get_count()
 256 -- - is_known(): returns true if the item name refers to a defined item type
 257 -- - get_definition(): returns the item definition table
 258 -- - get_tool_digging_properties(): returns the digging properties of the item,
 259 --   ^ or those of the hand if none are defined for this item type
 260 -- - add_wear(amount): increases wear by amount if the item is a tool
 261 -- - add_item(item): put some item or stack onto this stack,
 262 --   ^ returns leftover ItemStack
 263 -- - item_fits(item): returns true if item or stack can be fully added to this one
 264 -- - take_item(n): take (and remove) up to n items from this stack
 265 --   ^ returns taken ItemStack
 266 --   ^ if n is omitted, n=1 is used
 267 -- - peek_item(n): copy (don't remove) up to n items from this stack
 268 --   ^ returns copied ItemStack
 269 --   ^ if n is omitted, n=1 is used
 270 --
 271 -- Registered entities:
 272 -- - Functions receive a "luaentity" as self:
 273 --   - It has the member .name, which is the registered name ("mod:thing")
 274 --   - It has the member .object, which is an ObjectRef pointing to the object
 275 --   - The original prototype stuff is visible directly via a metatable
 276 -- - Callbacks:
 277 --   - on_activate(self, staticdata)
 278 --   - on_step(self, dtime)
 279 --   - on_punch(self, hitter)
 280 --   - on_rightclick(self, clicker)
 281 --   - get_staticdata(self)
 282 --     ^ return string that will be passed to on_activate when the object
 283 --       is created next time
 284 --
 285 -- Entity prototype table:
 286 -- {
 287 --     physical = true,
 288 --     collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
 289 --     visual = "cube"/"sprite",
 290 --     visual_size = {x=1, y=1},
 291 --     textures = {texture,texture,texture,texture,texture,texture},
 292 --     spritediv = {x=1, y=1},
 293 --     initial_sprite_basepos = {x=0, y=0},
 294 --     on_activate = function(self, staticdata),
 295 --     on_step = function(self, dtime),
 296 --     on_punch = function(self, hitter),
 297 --     on_rightclick = function(self, clicker),
 298 --     get_staticdata = function(self),
 299 --     # Also you can define arbitrary member variables here
 300 --     myvariable = whatever,
 301 -- }
 302 --
 303 -- Item definition options (register_node, register_craftitem, register_tool)
 304 -- {
 305 --     description = "Steel Axe",
 306 --     inventory_image = "default_tool_steelaxe.png",
 307 --     wield_image = "",
 308 --     wield_scale = {x=1,y=1,z=1},
 309 --     stack_max = 99,
 310 --     liquids_pointable = false,
 311 --     tool_digging_properties = {
 312 --         full_punch_interval = 1.0,
 313 --         basetime = 1.0,
 314 --         dt_weight = 0.5,
 315 --         dt_crackiness = -0.2,
 316 --         dt_crumbliness = 1,
 317 --         dt_cuttability = -0.5,
 318 --         basedurability = 330,
 319 --         dd_weight = 0,
 320 --         dd_crackiness = 0,
 321 --         dd_crumbliness = 0,
 322 --         dd_cuttability = 0,
 323 --     }
 324 --     on_drop = func(item, dropper, pos),
 325 --     on_place = func(item, placer, pointed_thing),
 326 --     on_use = func(item, user, pointed_thing),
 327 -- }
 328 --
 329 -- Node definition options (register_node):
 330 -- {
 331 --     <all fields allowed in item definitions>,
 332 --     drawtype = "normal",
 333 --     visual_scale = 1.0,
 334 --     tile_images = {"default_unknown_block.png"},
 335 --     special_materials = {
 336 --         {image="", backface_culling=true},
 337 --         {image="", backface_culling=true},
 338 --     },
 339 --     alpha = 255,
 340 --     post_effect_color = {a=0, r=0, g=0, b=0},
 341 --     paramtype = "none",
 342 --     paramtype2 = "none",
 343 --     is_ground_content = false,
 344 --     sunlight_propagates = false,
 345 --     walkable = true,
 346 --     pointable = true,
 347 --     diggable = true,
 348 --     climbable = false,
 349 --     buildable_to = false,
 350 --     drop = "",
 351 --     -- alternatively drop = { max_items = ..., items = { ... } }
 352 --     metadata_name = "",
 353 --     liquidtype = "none",
 354 --     liquid_alternative_flowing = "",
 355 --     liquid_alternative_source = "",
 356 --     liquid_viscosity = 0,
 357 --     light_source = 0,
 358 --     damage_per_second = 0,
 359 --     selection_box = {type="regular"},
 360 --     material = {
 361 --         diggablity = "normal",
 362 --         weight = 0,
 363 --         crackiness = 0,
 364 --         crumbliness = 0,
 365 --         cuttability = 0,
 366 --         flammability = 0,
 367 --     },
 368 --     legacy_facedir_simple = false, -- Support maps made in and before January 2012
 369 --     legacy_wallmounted = false, -- Support maps made in and before January 2012
 370 -- }
 371 --
 372 -- Recipe:
 373 -- {
 374 --     output = 'default:pick_stone',
 375 --     recipe = {
 376 --         {'default:cobble', 'default:cobble', 'default:cobble'},
 377 --         {'', 'default:stick', ''},
 378 --         {'', 'default:stick', ''},
 379 --     },
 380 --     replacements = <optional list of item pairs,
 381 --                     replace one input item with another item on crafting>
 382 -- }
 383 --
 384 -- Recipe (shapeless):
 385 -- {
 386 --     type = "shapeless",
 387 --     output = 'mushrooms:mushroom_stew',
 388 --     recipe = {
 389 --         "mushrooms:bowl",
 390 --         "mushrooms:mushroom_brown",
 391 --         "mushrooms:mushroom_red",
 392 --     },
 393 --     replacements = <optional list of item pairs,
 394 --                     replace one input item with another item on crafting>
 395 -- }
 396 --
 397 -- Recipe (tool repair):
 398 -- {
 399 --     type = "toolrepair",
 400 --     additional_wear = -0.02,
 401 -- }
 402 --
 403 -- Recipe (cooking):
 404 -- {
 405 --     type = "cooking",
 406 --     output = "default:glass",
 407 --     recipe = "default:sand",
 408 --     cooktime = 3,
 409 -- }
 410 --
 411 -- Recipe (furnace fuel):
 412 -- {
 413 --     type = "fuel",
 414 --     recipe = "default:leaves",
 415 --     burntime = 1,
 416 -- }
 417 --
 418 -- ABM (ActiveBlockModifier) definition:
 419 -- {
 420 --     nodenames = {"default:lava_source"},
 421 --     neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
 422 --      ^ If left out or empty, any neighbor will do
 423 --      ^ This might get removed in the future
 424 --     interval = 1.0, -- (operation interval)
 425 --     chance = 1, -- (chance of trigger is 1.0/this)
 426 --     action = func(pos, node, active_object_count, active_object_count_wider),
 427 -- }