Add a short_description to be used by mods (#8980)

[minetest.git] / doc / client_lua_api.txt

diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt
index c24de8d8578e5b3ea1b21e877fde2ca230eb0583..32be2fabfd35edaff60335c65fd302d2d37f0f47 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.2.0
+Minetest Lua Client Modding API Reference 5.4.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/>


@@ -112,7 +112,7 @@ The main Lua script. Running this script should register everything it
 wants to register. Subsequent execution depends on minetest calling the
 registered callbacks.
 
 wants to register. Subsequent execution depends on minetest calling the
 registered callbacks.
 

-**NOTE**: Client mods currently can't provide and textures, sounds or models by
+**NOTE**: Client mods currently can't provide textures, sounds, or models by

 themselves. Any media referenced in function calls must already be loaded
 (provided by mods that exist on the server).
 
 themselves. Any media referenced in function calls must already be loaded
 (provided by mods that exist on the server).
 


@@ -686,6 +686,11 @@ Call these functions only at load time!
     * Adds definition to minetest.registered_chatcommands
 * `minetest.unregister_chatcommand(name)`
     * Unregisters a chatcommands registered with register_chatcommand.
     * Adds definition to minetest.registered_chatcommands
 * `minetest.unregister_chatcommand(name)`
     * Unregisters a chatcommands registered with register_chatcommand.

+* `minetest.register_on_chatcommand(function(command, params))`
+    * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
+      is checked to see if that the command exists, but after the input is parsed.
+    * Return `true` to mark the command as handled, which means that the default
+      handlers will be prevented.

 * `minetest.register_on_death(function())`
     * Called when the local player dies
 * `minetest.register_on_hp_modification(function(hp))`
 * `minetest.register_on_death(function())`
     * Called when the local player dies
 * `minetest.register_on_hp_modification(function(hp))`


@@ -734,6 +739,13 @@ Call these functions only at load time!
     * `spec` is a `SimpleSoundSpec`
     * `parameters` is a sound parameter table
 * `minetest.sound_stop(handle)`
     * `spec` is a `SimpleSoundSpec`
     * `parameters` is a sound parameter table
 * `minetest.sound_stop(handle)`

+    * `handle` is a handle returned by `minetest.sound_play`
+* `minetest.sound_fade(handle, step, gain)`
+    * `handle` is a handle returned by `minetest.sound_play`
+    * `step` determines how fast a sound will fade.
+      Negative step will lower the sound volume, positive step will increase
+      the sound volume.
+    * `gain` the target gain for the fade.

 
 ### Timing
 * `minetest.after(time, func, ...)`
 
 ### Timing
 * `minetest.after(time, func, ...)`


@@ -761,12 +773,15 @@ Call these functions only at load time!
     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
     * `search_center` is an optional boolean (default: `false`)
       If true `pos` is also checked for the nodes
     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
     * `search_center` is an optional boolean (default: `false`)
       If true `pos` is also checked for the nodes

-* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of
-  positions.
+* `minetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])`
+    * `pos1` and `pos2` are the min and max positions of the area to search.

     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`

-    * First return value: Table with all node positions
-    * Second return value: Table with the count of each node with the node name
-      as index.
+    * If `grouped` is true the return value is a table indexed by node name
+      which contains lists of positions.
+    * If `grouped` is false or absent the return values are as follows:
+      first value: Table with all node positions
+      second value: Table with the count of each node with the node name
+      as index

     * Area volume is limited to 4,096,000 nodes
 * `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
   list of positions.
     * Area volume is limited to 4,096,000 nodes
 * `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
   list of positions.


@@ -797,8 +812,6 @@ Call these functions only at load time!
     * get max available level for leveled node
 
 ### Player
     * get max available level for leveled node
 
 ### Player

-* `minetest.get_wielded_item()`
-    * Returns the itemstack the local player is holding

 * `minetest.send_chat_message(message)`
     * Act as if `message` was typed by the player into the terminal.
 * `minetest.run_server_chatcommand(cmd, param)`
 * `minetest.send_chat_message(message)`
     * Act as if `message` was typed by the player into the terminal.
 * `minetest.run_server_chatcommand(cmd, param)`


@@ -962,7 +975,7 @@ Please do not try to access the reference until the camera is initialized, other
 * `get_camera_mode()`
     * Returns 0, 1, or 2 as described above
 * `get_fov()`
 * `get_camera_mode()`
     * Returns 0, 1, or 2 as described above
 * `get_fov()`

-    * Returns:
+    * Returns a table with X, Y, maximum and actual FOV in degrees:

 
 ```lua
      {
 
 ```lua
      {


@@ -999,6 +1012,10 @@ Methods:
     * returns player HP
 * `get_name()`
     * returns player name
     * returns player HP
 * `get_name()`
     * returns player name

+* `get_wield_index()`
+    * returns the index of the wielded item
+* `get_wielded_item()`
+    * returns the itemstack the player is holding

 * `is_attached()`
     * returns true if player is attached
 * `is_touching_ground()`
 * `is_attached()`
     * returns true if player is attached
 * `is_touching_ground()`


@@ -1022,7 +1039,8 @@ Methods:
         jump = float,
         gravity = float,
         sneak = boolean,
         jump = float,
         gravity = float,
         sneak = boolean,

-        sneak_glitch = boolean
+        sneak_glitch = boolean,
+        new_move = boolean,

     }
 ```
 
     }
 ```
 


@@ -1074,8 +1092,26 @@ Methods:
     * returns last look horizontal angle
 * `get_last_look_vertical()`:
     * returns last look vertical angle
     * returns last look horizontal angle
 * `get_last_look_vertical()`:
     * returns last look vertical angle

-* `get_key_pressed()`:
-    * returns last key typed by the player
+* `get_control()`:
+    * returns pressed player controls
+
+```lua
+    {
+       up = boolean,
+       down = boolean,
+       left = boolean,
+       right = boolean,
+       jump = boolean,
+       aux1 = boolean,
+       sneak = boolean,
+       zoom = boolean,
+       dig = boolean,
+       place = boolean,
+    }
+```
+
+* `get_armor_groups()`
+    * returns a table with the armor group ratings

 * `hud_add(definition)`
     * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
     * See [`HUD definition`](#hud-definition-hud_add-hud_get)
 * `hud_add(definition)`
     * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
     * See [`HUD definition`](#hud-definition-hud_add-hud_get)


@@ -1388,12 +1424,35 @@ Displays a horizontal bar made up of half-images.
 * `offset`: offset in pixels from position.
 
 ### `waypoint`
 * `offset`: offset in pixels from position.
 
 ### `waypoint`

+

 Displays distance to selected world position.
 
 * `name`: The name of the waypoint.
 * `text`: Distance suffix. Can be blank.
 Displays distance to selected world position.
 
 * `name`: The name of the waypoint.
 * `text`: Distance suffix. Can be blank.

-* `number:` An integer containing the RGB value of the color used to draw the text.
+* `precision`: Waypoint precision, integer >= 0. Defaults to 10.
+  If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`.
+  When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point.
+  `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`).
+  `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on:
+  `precision = n` will show multiples of `1/n`
+* `number:` An integer containing the RGB value of the color used to draw the
+  text.

 * `world_pos`: World position of the waypoint.
 * `world_pos`: World position of the waypoint.

+* `offset`: offset in pixels from position.
+* `alignment`: The alignment of the waypoint.
+
+### `image_waypoint`
+
+Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint.
+
+* `scale`: The scale of the image, with 1 being the original texture size.
+  Only the X coordinate scale is used (positive values).
+  Negative values represent that percentage of the screen it
+  should take; e.g. `x=-100` means 100% (width).
+* `text`: The name of the texture that is displayed.
+* `alignment`: The alignment of the image.
+* `world_pos`: World position of the waypoint.
+* `offset`: offset in pixels from position.

 
 ### Particle definition (`add_particle`)
 
 
 ### Particle definition (`add_particle`)