diff --git a/builtin/client/init.lua b/builtin/client/init.lua
index 4797ac4b6..dd218aab6 100644
--- a/builtin/client/init.lua
+++ b/builtin/client/init.lua
@@ -4,9 +4,10 @@ local clientpath = scriptpath.."client"..DIR_DELIM
local commonpath = scriptpath.."common"..DIR_DELIM
dofile(clientpath .. "register.lua")
+dofile(commonpath .. "after.lua")
+dofile(commonpath .. "chatcommands.lua")
dofile(clientpath .. "preview.lua")
core.register_on_death(function()
core.display_chat_message("You died.")
end)
-
diff --git a/builtin/client/preview.lua b/builtin/client/preview.lua
index c421791f5..22e8bb97f 100644
--- a/builtin/client/preview.lua
+++ b/builtin/client/preview.lua
@@ -1,6 +1,6 @@
-- This is an example function to ensure it's working properly, should be removed before merge
core.register_on_shutdown(function()
- print("shutdown client")
+ print("[PREVIEW] shutdown client")
end)
-- This is an example function to ensure it's working properly, should be removed before merge
@@ -15,17 +15,28 @@ core.register_on_sending_chat_messages(function(message)
return false
end)
+-- This is an example function to ensure it's working properly, should be removed before merge
core.register_on_hp_modification(function(hp)
print("[PREVIEW] HP modified " .. hp)
end)
+-- This is an example function to ensure it's working properly, should be removed before merge
core.register_on_damage_taken(function(hp)
print("[PREVIEW] Damage taken " .. hp)
end)
+-- This is an example function to ensure it's working properly, should be removed before merge
+core.register_globalstep(function(dtime)
+ -- print("[PREVIEW] globalstep " .. dtime)
+end)
+
-- This is an example function to ensure it's working properly, should be removed before merge
core.register_chatcommand("dump", {
func = function(name, param)
return true, dump(_G)
end,
-})
\ No newline at end of file
+})
+
+core.after(2, function()
+ print("After 2")
+end)
diff --git a/builtin/client/register.lua b/builtin/client/register.lua
index ddaf4f424..8b60c1222 100644
--- a/builtin/client/register.lua
+++ b/builtin/client/register.lua
@@ -55,6 +55,7 @@ local function make_registration()
return t, registerfunc
end
+core.registered_globalsteps, core.register_globalstep = make_registration()
core.registered_on_shutdown, core.register_on_shutdown = make_registration()
core.registered_on_receiving_chat_messages, core.register_on_receiving_chat_messages = make_registration()
core.registered_on_sending_chat_messages, core.register_on_sending_chat_messages = make_registration()
diff --git a/builtin/common/after.lua b/builtin/common/after.lua
new file mode 100644
index 000000000..30a9c7bad
--- /dev/null
+++ b/builtin/common/after.lua
@@ -0,0 +1,43 @@
+local jobs = {}
+local time = 0.0
+local last = core.get_us_time() / 1000000
+
+core.register_globalstep(function(dtime)
+ local new = core.get_us_time() / 1000000
+ if new > last then
+ time = time + (new - last)
+ else
+ -- Overflow, we may lose a little bit of time here but
+ -- only 1 tick max, potentially running timers slightly
+ -- too early.
+ time = time + new
+ end
+ last = new
+
+ if #jobs < 1 then
+ return
+ end
+
+ -- Iterate backwards so that we miss any new timers added by
+ -- a timer callback, and so that we don't skip the next timer
+ -- in the list if we remove one.
+ for i = #jobs, 1, -1 do
+ local job = jobs[i]
+ if time >= job.expire then
+ core.set_last_run_mod(job.mod_origin)
+ job.func(unpack(job.arg))
+ table.remove(jobs, i)
+ end
+ end
+end)
+
+function core.after(after, func, ...)
+ assert(tonumber(after) and type(func) == "function",
+ "Invalid core.after invocation")
+ jobs[#jobs + 1] = {
+ func = func,
+ expire = time + after,
+ arg = {...},
+ mod_origin = core.get_last_run_mod()
+ }
+end
diff --git a/builtin/game/init.lua b/builtin/game/init.lua
index 793d9fe2b..3e192a30a 100644
--- a/builtin/game/init.lua
+++ b/builtin/game/init.lua
@@ -17,6 +17,7 @@ if core.setting_getbool("profiler.load") then
profiler = dofile(scriptpath.."profiler"..DIR_DELIM.."init.lua")
end
+dofile(commonpath .. "after.lua")
dofile(gamepath.."item_entity.lua")
dofile(gamepath.."deprecated.lua")
dofile(gamepath.."misc.lua")
diff --git a/builtin/game/misc.lua b/builtin/game/misc.lua
index 3419c1980..25376c180 100644
--- a/builtin/game/misc.lua
+++ b/builtin/game/misc.lua
@@ -4,50 +4,6 @@
-- Misc. API functions
--
-local jobs = {}
-local time = 0.0
-local last = core.get_us_time() / 1000000
-
-core.register_globalstep(function(dtime)
- local new = core.get_us_time() / 1000000
- if new > last then
- time = time + (new - last)
- else
- -- Overflow, we may lose a little bit of time here but
- -- only 1 tick max, potentially running timers slightly
- -- too early.
- time = time + new
- end
- last = new
-
- if #jobs < 1 then
- return
- end
-
- -- Iterate backwards so that we miss any new timers added by
- -- a timer callback, and so that we don't skip the next timer
- -- in the list if we remove one.
- for i = #jobs, 1, -1 do
- local job = jobs[i]
- if time >= job.expire then
- core.set_last_run_mod(job.mod_origin)
- job.func(unpack(job.arg))
- table.remove(jobs, i)
- end
- end
-end)
-
-function core.after(after, func, ...)
- assert(tonumber(after) and type(func) == "function",
- "Invalid core.after invocation")
- jobs[#jobs + 1] = {
- func = func,
- expire = time + after,
- arg = {...},
- mod_origin = core.get_last_run_mod()
- }
-end
-
function core.check_player_privs(name, ...)
local arg_type = type(name)
if (arg_type == "userdata" or arg_type == "table") and
diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt
new file mode 100644
index 000000000..8ce487bf8
--- /dev/null
+++ b/doc/client_lua_api.txt
@@ -0,0 +1,787 @@
+Minetest Lua Modding API Reference 0.4.15
+=========================================
+* More information at
+* Developer Wiki:
+
+Introduction
+------------
+Content and functionality can be added to Minetest 0.4 by using Lua
+scripting in run-time loaded mods.
+
+A mod is a self-contained bunch of scripts, textures and other related
+things that is loaded by and interfaces with Minetest.
+
+Mods are contained and ran solely on the server side. Definitions and media
+files are automatically transferred to the client.
+
+If you see a deficiency in the API, feel free to attempt to add the
+functionality in the engine and API. You can send such improvements as
+source code patches on GitHub (https://github.com/minetest/minetest).
+
+Programming in Lua
+------------------
+If you have any difficulty in understanding this, please read
+[Programming in Lua](http://www.lua.org/pil/).
+
+Startup
+-------
+Mods are loaded during client startup from the mod load paths by running
+the `init.lua` scripts in a shared environment.
+
+Paths
+-----
+* `RUN_IN_PLACE=1` (Windows release, local build)
+ * `$path_user`:
+ * Linux: ``
+ * Windows: ``
+ * `$path_share`
+ * Linux: ``
+ * Windows: ``
+* `RUN_IN_PLACE=0`: (Linux release)
+ * `$path_share`
+ * Linux: `/usr/share/minetest`
+ * Windows: `/minetest-0.4.x`
+ * `$path_user`:
+ * Linux: `$HOME/.minetest`
+ * Windows: `C:/users//AppData/minetest` (maybe)
+
+Mod load path
+-------------
+Generic:
+
+* `$path_share/clientmods/`
+* `$path_user/clientmods/` (User-installed mods)
+
+In a run-in-place version (e.g. the distributed windows version):
+
+* `minetest-0.4.x/clientmods/` (User-installed mods)
+
+On an installed version on Linux:
+
+* `/usr/share/minetest/clientmods/`
+* `$HOME/.minetest/clientmods/` (User-installed mods)
+
+Modpack support
+----------------
+Mods can be put in a subdirectory, if the parent directory, which otherwise
+should be a mod, contains a file named `modpack.txt`. This file shall be
+empty, except for lines starting with `#`, which are comments.
+
+Mod directory structure
+------------------------
+
+ mods
+ |-- modname
+ | |-- depends.txt
+ | |-- screenshot.png
+ | |-- description.txt
+ | |-- settingtypes.txt
+ | |-- init.lua
+ | |-- models
+ | |-- textures
+ | | |-- modname_stuff.png
+ | | `-- modname_something_else.png
+ | |-- sounds
+ | |-- media
+ | `--
+ `-- another
+
+
+### modname
+The location of this directory can be fetched by using
+`minetest.get_modpath(modname)`.
+
+### `depends.txt`
+List of mods that have to be loaded before loading this mod.
+
+A single line contains a single modname.
+
+Optional dependencies can be defined by appending a question mark
+to a single modname. Their meaning is that if the specified mod
+is missing, that does not prevent this mod from being loaded.
+
+### `screenshot.png`
+A screenshot shown in the mod manager within the main menu. It should
+have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
+
+### `description.txt`
+A File containing description to be shown within mainmenu.
+
+### `settingtypes.txt`
+A file in the same format as the one in builtin. It will be parsed by the
+settings menu and the settings will be displayed in the "Mods" category.
+
+### `init.lua`
+The main Lua script. Running this script should register everything it
+wants to register. Subsequent execution depends on minetest calling the
+registered callbacks.
+
+`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
+to read custom or existing settings at load time, if necessary.
+
+### `sounds`
+Media files (sounds) that will be transferred to the
+client and will be available for use by the mod.
+
+Naming convention for registered textual names
+----------------------------------------------
+Registered names should generally be in this format:
+
+ "modname:" ( can have characters a-zA-Z0-9_)
+
+This is to prevent conflicting names from corrupting maps and is
+enforced by the mod loader.
+
+### Example
+In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
+So the name should be `experimental:tnt`.
+
+Enforcement can be overridden by prefixing the name with `:`. This can
+be used for overriding the registrations of some other mod.
+
+Example: Any mod can redefine `experimental:tnt` by using the name
+
+ :experimental:tnt
+
+when registering it.
+(also that mod is required to have `experimental` as a dependency)
+
+The `:` prefix can also be used for maintaining backwards compatibility.
+
+### Aliases
+Aliases can be added by using `minetest.register_alias(name, convert_to)` or
+`minetest.register_alias_force(name, convert_to).
+
+This will make Minetest to convert things called name to things called
+`convert_to`.
+
+The only difference between `minetest.register_alias` and
+`minetest.register_alias_force` is that if an item called `name` exists,
+`minetest.register_alias` will do nothing while
+`minetest.register_alias_force` will unregister it.
+
+This can be used for maintaining backwards compatibility.
+
+This can be also used for setting quick access names for things, e.g. if
+you have an item called `epiclylongmodname:stuff`, you could do
+
+ minetest.register_alias("stuff", "epiclylongmodname:stuff")
+
+and be able to use `/giveme stuff`.
+
+Sounds
+------
+Only Ogg Vorbis 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_`, e.g. 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 one player
+ {
+ to_player = name,
+ gain = 1.0, -- default
+ }
+ -- Play locationless to one player, looped
+ {
+ to_player = name,
+ gain = 1.0, -- default
+ loop = true,
+ }
+ -- Play in a location
+ {
+ pos = {x = 1, y = 2, z = 3},
+ gain = 1.0, -- default
+ max_hear_distance = 32, -- default, uses an euclidean metric
+ }
+ -- Play connected to an object, looped
+ {
+ object = ,
+ gain = 1.0, -- default
+ max_hear_distance = 32, -- default, uses an euclidean metric
+ loop = true,
+ }
+
+Looped sounds must either be connected to an object or played locationless to
+one player using `to_player = name,`
+
+### `SimpleSoundSpec`
+* e.g. `""`
+* e.g. `"default_place_node"`
+* e.g. `{}`
+* e.g. `{name = "default_place_node"}`
+* e.g. `{name = "default_place_node", gain = 1.0}`
+
+Representations of simple things
+--------------------------------
+
+### Position/vector
+
+ {x=num, y=num, z=num}
+
+For helper functions see "Vector helpers".
+
+### `pointed_thing`
+* `{type="nothing"}`
+* `{type="node", under=pos, above=pos}`
+* `{type="object", ref=ObjectRef}`
+
+Flag Specifier Format
+---------------------
+Flags using the standardized flag specifier format can be specified in either of
+two ways, by string or table.
+
+The string format is a comma-delimited set of flag names; whitespace and
+unrecognized flag fields are ignored. Specifying a flag in the string sets the
+flag, and specifying a flag prefixed by the string `"no"` explicitly
+clears the flag from whatever the default may be.
+
+In addition to the standard string flag format, the schematic flags field can
+also be a table of flag names to boolean values representing whether or not the
+flag is set. Additionally, if a field with the flag name prefixed with `"no"`
+is present, mapped to a boolean of any value, the specified flag is unset.
+
+E.g. A flag field of value
+
+ {place_center_x = true, place_center_y=false, place_center_z=true}
+
+is equivalent to
+
+ {place_center_x = true, noplace_center_y=true, place_center_z=true}
+
+which is equivalent to
+
+ "place_center_x, noplace_center_y, place_center_z"
+
+or even
+
+ "place_center_x, place_center_z"
+
+since, by default, no schematic attributes are set.
+
+Formspec
+--------
+Formspec defines a menu. Currently not much else than inventories are
+supported. It is a string, with a somewhat strange format.
+
+Spaces and newlines can be inserted between the blocks, as is used in the
+examples.
+
+### Examples
+
+#### Chest
+
+ size[8,9]
+ list[context;main;0,0;8,4;]
+ list[current_player;main;0,5;8,4;]
+
+#### Furnace
+
+ size[8,9]
+ list[context;fuel;2,3;1,1;]
+ list[context;src;2,1;1,1;]
+ list[context;dst;5,1;2,2;]
+ list[current_player;main;0,5;8,4;]
+
+#### Minecraft-like player inventory
+
+ size[8,7.5]
+ image[1,0.6;1,2;player.png]
+ list[current_player;main;0,3.5;8,4;]
+ list[current_player;craft;3,0;3,3;]
+ list[current_player;craftpreview;7,1;1,1;]
+
+### Elements
+
+#### `size[,,]`
+* Define the size of the menu in inventory slots
+* `fixed_size`: `true`/`false` (optional)
+* deprecated: `invsize[,;]`
+
+#### `container[,]`
+* Start of a container block, moves all physical elements in the container by (X, Y)
+* Must have matching container_end
+* Containers can be nested, in which case the offsets are added
+ (child containers are relative to parent containers)
+
+#### `container_end[]`
+* End of a container, following elements are no longer relative to this container
+
+#### `list[;;,;,;]`
+* Show an inventory list
+
+#### `list[;;,;,;]`
+* Show an inventory list
+
+#### `listring[;]`
+* Allows to create a ring of inventory lists
+* Shift-clicking on items in one element of the ring
+ will send them to the next inventory list inside the ring
+* The first occurrence of an element inside the ring will
+ determine the inventory where items will be sent to
+
+#### `listring[]`
+* Shorthand for doing `listring[;]`
+ for the last two inventory lists added by list[...]
+
+#### `listcolors[;]`
+* Sets background color of slots as `ColorString`
+* Sets background color of slots on mouse hovering
+
+#### `listcolors[;;]`
+* Sets background color of slots as `ColorString`
+* Sets background color of slots on mouse hovering
+* Sets color of slots border
+
+#### `listcolors[;;;;]`
+* Sets background color of slots as `ColorString`
+* Sets background color of slots on mouse hovering
+* Sets color of slots border
+* Sets default background color of tooltips
+* Sets default font color of tooltips
+
+#### `tooltip[;;,]`
+* Adds tooltip for an element
+* `` tooltip background color as `ColorString` (optional)
+* `` tooltip font color as `ColorString` (optional)
+
+#### `image[,;,;]`
+* Show an image
+* Position and size units are inventory slots
+
+#### `item_image[,;,;]`
+* Show an inventory image of registered item/node
+* Position and size units are inventory slots
+
+#### `bgcolor[;]`
+* Sets background color of formspec as `ColorString`
+* If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
+
+#### `background[,;,;]`
+* Use a background. Inventory rectangles are not drawn then.
+* Position and size units are inventory slots
+* Example for formspec 8x4 in 16x resolution: image shall be sized
+ 8 times 16px times 4 times 16px.
+
+#### `background[,;,;;]`
+* Use a background. Inventory rectangles are not drawn then.
+* Position and size units are inventory slots
+* Example for formspec 8x4 in 16x resolution:
+ image shall be sized 8 times 16px times 4 times 16px
+* If `true` the background is clipped to formspec size
+ (`x` and `y` are used as offset values, `w` and `h` are ignored)
+
+#### `pwdfield[,;,;;