X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=3a5927e9cc0525c4b7c7d679de10872f7c5d659c;hb=fa24e6b99581d56fd1a898d9eae7764a1cb48041;hp=1fbf7320db4d3e817515a9d3140fade94f089e13;hpb=fde676a43adfbbfa7e44eacd7d442c2bc26c8d88;p=minetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 1fbf7320d..3a5927e9c 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -55,6 +55,8 @@ mods | |-- textures | | |-- modname_stuff.png | | `-- modname_something_else.png +| |-- sounds +| |-- media | `-- `-- another @@ -74,9 +76,9 @@ init.lua: minetest.setting_get(name) and minetest.setting_getbool(name) can be used to read custom or existing settings at load time, if necessary. -textures: - These textures will be transferred to the client and can be referred to - by the mod. +textures, sounds, media: + Media files (textures, sounds, whatever) that will be transferred to the + client and will be available for use by the mod. Naming convention for registered textual names ---------------------------------------------- @@ -118,6 +120,58 @@ Mods should generally prefix their textures with modname_, eg. given the mod name "foomod", a texture could be called "foomod_foothing.png" +Textures are referred to by their complete name, or alternatively by +stripping out the file extension: + eg. foomod_foothing.png + eg. foomod_foothing + +Sounds +------- +Only OGG files are supported. + +For positional playing of sounds, only single-channel (mono) files are +supported. Otherwise OpenAL will play them non-positionally. + +Mods should generally prefix their sounds with modname_, eg. given +the mod name "foomod", a sound could be called + "foomod_foosound.ogg" + +Sounds are referred to by their name with a dot, a single digit and the +file extension stripped out. When a sound is played, the actual sound file +is chosen randomly from the matching sounds. + +When playing the sound "foomod_foosound", the sound is chosen randomly +from the available ones of the following files: + foomod_foosound.ogg + foomod_foosound.0.ogg + foomod_foosound.1.ogg + ... + foomod_foosound.9.ogg + +Examples of sound parameter tables: +-- Play locationless on all clients +{ + gain = 1.0, -- default +} +-- Play locationless to a player +{ + to_player = name, + gain = 1.0, -- default +} +-- Play in a location +{ + pos = {x=1,y=2,z=3}, + gain = 1.0, -- default + max_hear_distance = 32, -- default +} +-- Play connected to an object, looped +{ + object = , + gain = 1.0, -- default + max_hear_distance = 32, -- default + loop = true, -- only sounds connected to objects can be looped +} + Representations of simple things -------------------------------- MapNode representation: @@ -145,13 +199,13 @@ Currently the API does not provide any helper functions for addition, subtraction and whatever; you can define those that you need yourself. stackstring/itemstring: A stack of items in serialized format. -eg. 'node "default:dirt" 5' -eg. 'tool "default:pick_wood" 21323' -eg. 'craft "default:apple" 2' +eg. 'default:dirt 5' +eg. 'default:pick_wood 21323' +eg. 'default:apple' item: A stack of items in Lua table format. -eg. {name="default:dirt", count=1, wear=0, metadata=""} - ^ a single dirt node +eg. {name="default:dirt", count=5, wear=0, metadata=""} + ^ 5 dirt nodes eg. {name="default:pick_wood", count=1, wear=21323, metadata=""} ^ a wooden pick about 1/3 weared out eg. {name="default:apple", count=1, wear=0, metadata=""} @@ -160,6 +214,13 @@ eg. {name="default:apple", count=1, wear=0, metadata=""} Any time an item must be passed to a function, it can be an ItemStack (see below), an itemstring or a table in the above format. +SimpleSoundSpec: +eg. "" +eg. "default_place_node" +eg. {} +eg. {name="default_place_node"} +eg. {name="default_place_node", gain=1.0} + Items ------ Node (register_node): @@ -358,6 +419,18 @@ dump(obj, dumped={}) minetest namespace reference ----------------------------- +minetest.get_current_modname() -> string +minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname" +^ Useful for loading additional .lua modules or static data from mod +minetest.get_worldpath(modname) -> eg. "/home/user/.minetest/world" +^ Useful for storing custom data + +minetest.debug(line) +^ Goes to dstream +minetest.log(line) +minetest.log(loglevel, line) +^ loglevel one of "error", "action", "info", "verbose" + minetest.register_entity(name, prototype table) minetest.register_abm(abm definition) minetest.register_node(name, node definition) @@ -365,6 +438,7 @@ minetest.register_tool(name, item definition) minetest.register_craftitem(name, item definition) minetest.register_alias(name, convert_to) minetest.register_craft(recipe) + minetest.register_globalstep(func(dtime)) minetest.register_on_placenode(func(pos, newnode, placer)) minetest.register_on_dignode(func(pos, oldnode, digger)) @@ -376,26 +450,26 @@ minetest.register_on_respawnplayer(func(ObjectRef)) ^ return true in func to disable regular player placement ^ currently called _before_ repositioning of player occurs minetest.register_on_chat_message(func(name, message)) + minetest.add_to_creative_inventory(itemstring) minetest.setting_get(name) -> string or nil minetest.setting_getbool(name) -> boolean value or nil + minetest.chat_send_all(text) minetest.chat_send_player(name, text) minetest.get_player_privs(name) -> set of privs minetest.get_inventory(location) -> InvRef ^ location = eg. {type="player", name="celeron55"} {type="node", pos={x=, y=, z=}} -minetest.get_current_modname() -> string -minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname" -^ Useful for loading additional .lua modules or static data from mod -minetest.get_worldpath(modname) -> eg. "/home/user/.minetest/world" -^ Useful for storing custom data -minetest.debug(line) -^ Goes to dstream -minetest.log(line) -minetest.log(loglevel, line) -^ loglevel one of "error", "action", "info", "verbose" +minetest.sound_play(spec, parameters) -> handle +^ spec = SimpleSoundSpec +^ parameters = sound parameter table +minetest.sound_stop(handle) + +minetest.after(time, func, param) +^ Call function after time seconds +^ param is optional; to pass multiple parameters, pass a table. Global objects: minetest.env - environment reference @@ -672,6 +746,11 @@ Node definition (register_node) selection_box = {type="regular"}, legacy_facedir_simple = false, -- Support maps made in and before January 2012 legacy_wallmounted = false, -- Support maps made in and before January 2012 + sounds = { + footstep = , + dig = , -- "__group" = group-based sound (default) + dug = , + }, } Recipe: (register_craft)