[CSM] Remove non-functional minetest.get_day_count()

[dragonfireclient.git] / doc / client_lua_api.txt

diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt
index 3b6e1b25b80a3ff540021578d94d52b2ca0aab75..a71421747ff5380482bef2668386fa7beb9f3eae 100644 (file)
--- a/doc/client_lua_api.txt
+++ b/doc/client_lua_api.txt
@@ -1,4 +1,4 @@
-Minetest Lua Client Modding API Reference 5.0.0
+Minetest Lua Client Modding API Reference 5.2.0

 ================================================
 * More information at <http://www.minetest.net/>
 * Developer Wiki: <http://dev.minetest.net/>
 ================================================
 * More information at <http://www.minetest.net/>
 * Developer Wiki: <http://dev.minetest.net/>


@@ -30,17 +30,23 @@ Startup
 Mods are loaded during client startup from the mod load paths by running
 the `init.lua` scripts in a shared environment.
 
 Mods are loaded during client startup from the mod load paths by running
 the `init.lua` scripts in a shared environment.
 

+In order to load client-side mods, the following conditions need to be satisfied:
+
+1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true`
+
+2) The client-side mod located in `$path_user/clientmods/<modname>` is added to
+    `$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
+
+Note: Depending on the remote server's settings, client-side mods might not
+be loaded or have limited functionality. See setting `csm_restriction_flags` for reference.
+

 Paths
 -----
 * `RUN_IN_PLACE=1` (Windows release, local build)
 Paths
 -----
 * `RUN_IN_PLACE=1` (Windows release, local build)

-    *  `$path_user`:
-        * Linux: `<build directory>`
-        * Windows: `<build directory>`
-    * `$path_share`
-        * Linux: `<build directory>`
-        * Windows:  `<build directory>`
+    * `$path_user`: `<build directory>`
+    * `$path_share`: `<build directory>`

 * `RUN_IN_PLACE=0`: (Linux release)
 * `RUN_IN_PLACE=0`: (Linux release)

-    * `$path_share`
+    * `$path_share`:

         * Linux: `/usr/share/minetest`
         * Windows: `<install directory>/minetest-0.4.x`
     * `$path_user`:
         * Linux: `/usr/share/minetest`
         * Windows: `<install directory>/minetest-0.4.x`
     * `$path_user`:


@@ -65,44 +71,50 @@ On an installed version on Linux:
 
 Modpack support
 ----------------
 
 Modpack support
 ----------------

-**NOTE: Not implemented yet.**

 
 Mods can be put in a subdirectory, if the parent directory, which otherwise
 
 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.
+should be a mod, contains a file named `modpack.conf`.
+The file is a key-value store of modpack details.
+
+* `name`: The modpack name.
+* `description`: Description of mod to be shown in the Mods tab of the main
+                 menu.

 
 Mod directory structure
 ------------------------
 
     clientmods
     ├── modname
 
 Mod directory structure
 ------------------------
 
     clientmods
     ├── modname

-    |   ├── depends.txt
-    |   ├── init.lua
+    │   ├── mod.conf
+    │   ├── init.lua

     └── another
 
 ### modname
     └── another
 
 ### modname

+

 The location of this directory.
 
 The location of this directory.
 

-### depends.txt
-List of mods that have to be loaded before loading this mod.
+### mod.conf

 
 

-A single line contains a single modname.
+An (optional) settings file that provides meta information about the mod.

 
 

-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.
+* `name`: The mod name. Allows Minetest to determine the mod name even if the
+          folder is wrongly named.
+* `description`: Description of mod to be shown in the Mods tab of the main
+                 menu.
+* `depends`: A comma separated list of dependencies. These are mods that must be
+             loaded before this mod.
+* `optional_depends`: A comma separated list of optional dependencies.
+                      Like a dependency, but no error if the mod doesn't exist.
+
+### `init.lua`

 
 

-### 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.
 
 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.
+**NOTE**: Client mods currently can't provide and textures, sounds or models by
+themselves. Any media referenced in function calls must already be loaded
+(provided by mods that exist on the server).

 
 Naming convention for registered textual names
 ----------------------------------------------
 
 Naming convention for registered textual names
 ----------------------------------------------


@@ -131,7 +143,7 @@ The `:` prefix can also be used for maintaining backwards compatibility.
 
 Sounds
 ------
 
 Sounds
 ------

-**NOTE: max_hear_distance and connecting to objects is not implemented.**
+**NOTE: Connecting sounds to objects is not implemented.**

 
 Only Ogg Vorbis files are supported.
 
 
 Only Ogg Vorbis files are supported.
 


@@ -171,13 +183,11 @@ Examples of sound parameter tables:
     {
         pos = {x = 1, y = 2, z = 3},
         gain = 1.0, -- default
     {
         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 = <an ObjectRef>,
         gain = 1.0, -- default
     }
     -- Play connected to an object, looped
     {
         object = <an ObjectRef>,
         gain = 1.0, -- default

-        max_hear_distance = 32, -- default, uses an euclidean metric

         loop = true,
     }
 
         loop = true,
     }
 


@@ -620,6 +630,10 @@ Minetest namespace reference
 ### Utilities
 
 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
 ### Utilities
 
 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod

+* `minetest.get_modpath(modname)`: returns virtual path of given mod including
+   the trailing separator. This is useful to load additional Lua files
+   contained in your mod:
+   e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")`

 * `minetest.get_language()`: returns the currently set gettext language.
 * `minetest.get_version()`: returns a table containing components of the
    engine version.  Components:
 * `minetest.get_language()`: returns the currently set gettext language.
 * `minetest.get_version()`: returns a table containing components of the
    engine version.  Components:


@@ -720,8 +734,6 @@ Call these functions only at load time!
     * Optional: Variable number of arguments that are passed to `func`
 * `minetest.get_us_time()`
     * Returns time with microsecond precision. May not return wall time.
     * Optional: Variable number of arguments that are passed to `func`
 * `minetest.get_us_time()`
     * Returns time with microsecond precision. May not return wall time.

-* `minetest.get_day_count()`
-    * Returns number days elapsed since world was created, accounting for time changes.

 * `minetest.get_timeofday()`
     * Returns the time of day: `0` for midnight, `0.5` for midday
 
 * `minetest.get_timeofday()`
     * Returns the time of day: `0` for midnight, `0.5` for midday
 


@@ -763,7 +775,7 @@ Call these functions only at load time!
 
 ### Client Environment
 * `minetest.get_player_names()`
 
 ### Client Environment
 * `minetest.get_player_names()`

-    * Returns list of player names on server
+    * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)

 * `minetest.disconnect()`
     * Disconnect from the server and exit to main menu.
     * Returns `false` if the client is already disconnecting otherwise returns `true`.
 * `minetest.disconnect()`
     * Disconnect from the server and exit to main menu.
     * Returns `false` if the client is already disconnecting otherwise returns `true`.