Added minetest.drop_selected_item(), Improved AutoEject

[dragonfireclient.git] / doc / client_lua_api.txt

diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt
index a7e928f566eb6765bbf061688adfe675e77352b1..85fe1005df2d56769d9ff5c921b1702faa1d1636 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/>


@@ -86,9 +86,16 @@ Mod directory structure
     clientmods
     ├── modname
     │   ├── mod.conf
     clientmods
     ├── modname
     │   ├── mod.conf

+    |   ├── settingtypes.txt

     │   ├── init.lua
     └── another
 
     │   ├── init.lua
     └── another
 

+### `settingtypes.txt`
+
+The format is documented in `builtin/settingtypes.txt`.
+It is parsed by the main menu settings dialogue to list mod-specific
+settings in the "Clientmods" category.    
+

 ### modname
 
 The location of this directory.
 ### modname
 
 The location of this directory.


@@ -112,7 +119,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).
 


@@ -634,7 +641,9 @@ Minetest namespace reference
    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")`
    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_language()`: returns two strings
+   * the current gettext locale
+   * the current language code (the same as used for client-side translations)

 * `minetest.get_version()`: returns a table containing components of the
    engine version.  Components:
     * `project`: Name of the project, eg, "Minetest"
 * `minetest.get_version()`: returns a table containing components of the
    engine version.  Components:
     * `project`: Name of the project, eg, "Minetest"


@@ -665,6 +674,10 @@ Minetest namespace reference
 ### Global callback registration functions
 Call these functions only at load time!
 
 ### Global callback registration functions
 Call these functions only at load time!
 

+* `minetest.open_special_inventory()`
+    * This function is called if the client uses the Keybind for it (by default "O")
+    * It is used for a client provided inventory
+    * You can override it

 * `minetest.register_globalstep(function(dtime))`
     * Called every client environment step, usually interval of 0.1s
 * `minetest.register_on_mods_loaded(function())`
 * `minetest.register_globalstep(function(dtime))`
     * Called every client environment step, usually interval of 0.1s
 * `minetest.register_on_mods_loaded(function())`


@@ -727,11 +740,25 @@ Call these functions only at load time!
     * Called when the local player open inventory
     * Newest functions are called first
     * If any function returns true, inventory doesn't open
     * Called when the local player open inventory
     * Newest functions are called first
     * If any function returns true, inventory doesn't open

+
+### Setting-related
+* `minetest.settings`: Settings object containing all of the settings from the
+  main config file (`minetest.conf`).
+* `minetest.setting_get_pos(name)`: Loads a setting from the main settings and
+  parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
+

 ### Sounds
 * `minetest.sound_play(spec, parameters)`: returns a handle
     * `spec` is a `SimpleSoundSpec`
     * `parameters` is a sound parameter table
 * `minetest.sound_stop(handle)`
 ### Sounds
 * `minetest.sound_play(spec, parameters)`: returns a 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, ...)`


@@ -743,6 +770,10 @@ Call these functions only at load time!
     * Returns the time of day: `0` for midnight, `0.5` for midday
 
 ### Map
     * Returns the time of day: `0` for midnight, `0.5` for midday
 
 ### Map

+* `minetest.place_node(pos)`
+    * Places the wielded node/item of the player at pos.
+* `minetest.dig_node(pos)`
+    * Instantly digs the node at pos. This may fuck up with anticheat.

 * `minetest.get_node_or_nil(pos)`
     * Returns the node at the given position as table in the format
       `{name="node_name", param1=0, param2=0}`, returns `nil`
 * `minetest.get_node_or_nil(pos)`
     * Returns the node at the given position as table in the format
       `{name="node_name", param1=0, param2=0}`, returns `nil`


@@ -759,12 +790,35 @@ 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_near(pos, radius, nodenames, [search_center])`: returns a
+  list of positions.
+    * `radius`: using a maximum metric
+    * `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_near_under_air(pos, radius, nodenames, [search_center])`: returns a
+  list of positions.
+    * `radius`: using a maximum metric

     * `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.
+    * `search_center` is an optional boolean (default: `false`)
+      If true `pos` is also checked for the nodes
+    * Return value: Table with all node positions with a node air above
+* `minetest.find_nodes_near_under_air_except(pos, radius, nodenames, [search_center])`: returns a
+  list of positions.
+    * `radius`: using a maximum metric
+    * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`, specifies the nodes to be ignored
+    * `search_center` is an optional boolean (default: `false`)
+      If true `pos` is also checked for the nodes
+    * Return value: Table with all node positions with a node air above
+* `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"`
+    * 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.


@@ -783,7 +837,26 @@ Call these functions only at load time!
     * `pos2`: end of the ray
     * `objects`: if false, only nodes will be returned. Default is `true`.
     * `liquids`: if false, liquid nodes won't be returned. Default is `false`.
     * `pos2`: end of the ray
     * `objects`: if false, only nodes will be returned. Default is `true`.
     * `liquids`: if false, liquid nodes won't be returned. Default is `false`.

-
+* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
+    * returns table containing path that can be walked on
+    * returns a table of 3D points representing a path from `pos1` to `pos2` or
+      `nil` on failure.
+    * Reasons for failure:
+        * No path exists at all
+        * No path exists within `searchdistance` (see below)
+        * Start or end pos is buried in land
+    * `pos1`: start position
+    * `pos2`: end position
+    * `searchdistance`: maximum distance from the search positions to search in.
+      In detail: Path must be completely inside a cuboid. The minimum
+      `searchdistance` of 1 will confine search between `pos1` and `pos2`.
+      Larger values will increase the size of this cuboid in all directions
+    * `max_jump`: maximum height difference to consider walkable
+    * `max_drop`: maximum height difference to consider droppable
+    * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`.
+      Difference between `"A*"` and `"A*_noprefetch"` is that
+      `"A*"` will pre-calculate the cost-data, the other will calculate it
+      on-the-fly

 * `minetest.find_nodes_with_meta(pos1, pos2)`
     * Get a table of positions of nodes that have metadata within a region
       {pos1, pos2}.
 * `minetest.find_nodes_with_meta(pos1, pos2)`
     * Get a table of positions of nodes that have metadata within a region
       {pos1, pos2}.


@@ -795,14 +868,16 @@ 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_damage(hp)`
+    * Sends fall damage to server

 * `minetest.send_chat_message(message)`
     * Act as if `message` was typed by the player into the terminal.
 * `minetest.run_server_chatcommand(cmd, param)`
     * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
 * `minetest.clear_out_chat_queue()`
     * Clears the out chat queue
 * `minetest.send_chat_message(message)`
     * Act as if `message` was typed by the player into the terminal.
 * `minetest.run_server_chatcommand(cmd, param)`
     * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
 * `minetest.clear_out_chat_queue()`
     * Clears the out chat queue

+* `minetest.drop_selected_item()`
+    * Drops the selected item

 * `minetest.localplayer`
     * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
 
 * `minetest.localplayer`
     * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
 


@@ -824,6 +899,73 @@ Call these functions only at load time!
 * `minetest.send_respawn()`
     * Sends a respawn request to the server.
 
 * `minetest.send_respawn()`
     * Sends a respawn request to the server.
 

+### HTTP Requests
+
+* `minetest.get_http_api()`
+    * returns `HTTPApiTable` containing http functions.
+    * The returned table contains the functions `fetch_sync`, `fetch_async` and
+      `fetch_async_get` described below.
+    * Function only exists if minetest server was built with cURL support.
+* `HTTPApiTable.fetch_sync(HTTPRequest req)`: returns HTTPRequestResult
+    * Performs given request synchronously
+* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
+    * Performs given request asynchronously and returns handle for
+      `HTTPApiTable.fetch_async_get`
+* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
+    * Return response data for given asynchronous HTTP request
+
+### `HTTPRequest` definition
+
+Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
+
+    {
+        url = "http://example.org",
+
+        timeout = 10,
+        -- Timeout for connection in seconds. Default is 3 seconds.
+
+        post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
+        -- Optional, if specified a POST request with post_data is performed.
+        -- Accepts both a string and a table. If a table is specified, encodes
+        -- table as x-www-form-urlencoded key-value pairs.
+        -- If post_data is not specified, a GET request is performed instead.
+
+        user_agent = "ExampleUserAgent",
+        -- Optional, if specified replaces the default minetest user agent with
+        -- given string
+
+        extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
+        -- Optional, if specified adds additional headers to the HTTP request.
+        -- You must make sure that the header strings follow HTTP specification
+        -- ("Key: Value").
+
+        multipart = boolean
+        -- Optional, if true performs a multipart HTTP request.
+        -- Default is false.
+    }
+
+### `HTTPRequestResult` definition
+
+Passed to `HTTPApiTable.fetch` callback. Returned by
+`HTTPApiTable.fetch_async_get`.
+
+    {
+        completed = true,
+        -- If true, the request has finished (either succeeded, failed or timed
+        -- out)
+
+        succeeded = true,
+        -- If true, the request was successful
+
+        timeout = false,
+        -- If true, the request timed out
+
+        code = 200,
+        -- HTTP status code
+
+        data = "response"
+    }
+

 ### Storage API
 * `minetest.get_mod_storage()`:
     * returns reference to mod private `StorageRef`
 ### Storage API
 * `minetest.get_mod_storage()`:
     * returns reference to mod private `StorageRef`


@@ -847,7 +989,20 @@ Call these functions only at load time!
 * `minetest.delete_particlespawner(id)`
     * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
 
 * `minetest.delete_particlespawner(id)`
     * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
 

-### Misc.
+### Misc
+* `minetest.set_keypress(key, value)`
+    * Act as if a key was pressed (value = true) / released (value = false)
+    * The key must be an keymap_* setting
+    * e.g. minetest.set_keypress("jump", true) will cause te player to jump until minetest.set_keypress("jump", false) is called or the player presses & releases the space bar himself
+* `minetest.get_inventory(location)`
+    * Returns the inventory at location
+* `minetest.register_cheat(name, category, setting | function)`
+    * Register an entry for the cheat menu
+    * If the Category is nonexistant, it will be created
+    * If the 3rd argument is a string it will be interpreted as a setting and toggled 
+        when the player selects the entry in the cheat menu
+    * If the 3rd argument is a function it will be called
+        when the player selects the entry in the cheat menu

 * `minetest.parse_json(string[, nullvalue])`: returns something
     * Convert a string containing JSON data into the Lua equivalent
     * `nullvalue`: returned in place of the JSON null; defaults to `nil`
 * `minetest.parse_json(string[, nullvalue])`: returns something
     * Convert a string containing JSON data into the Lua equivalent
     * `nullvalue`: returned in place of the JSON null; defaults to `nil`


@@ -960,7 +1115,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
      {


@@ -991,12 +1146,26 @@ Methods:
 
 * `get_pos()`
     * returns current player current position
 
 * `get_pos()`
     * returns current player current position

+* `set_pos(pos)`
+    * sets the position (anticheat may not like this)
+* `get_yaw()`
+    * returns the yaw (degrees)
+* `set_yaw(yaw)`
+    * sets the yaw (degrees)

 * `get_velocity()`
     * returns player speed vector
 * `get_velocity()`
     * returns player speed vector

+* `set_velocity(vel)`
+    * sets player speed vector

 * `get_hp()`
     * returns player HP
 * `get_name()`
     * returns player name
 * `get_hp()`
     * returns player HP
 * `get_name()`
     * returns player name

+* `get_wield_index()`
+    * returns the index of the wielded item
+* `set_wield_index()`
+    * sets the index
+* `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()`


@@ -1020,7 +1189,8 @@ Methods:
         jump = float,
         gravity = float,
         sneak = boolean,
         jump = float,
         gravity = float,
         sneak = boolean,

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

     }
 ```
 
     }
 ```
 


@@ -1072,8 +1242,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,
+       LMB = boolean,
+       RMB = 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)


@@ -1145,6 +1333,12 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or
        * Returns [node definition](#node-definition) table of `nodename`
 * `minetest.get_item_def(itemstring)`
        * Returns item definition table of `itemstring`
        * Returns [node definition](#node-definition) table of `nodename`
 * `minetest.get_item_def(itemstring)`
        * Returns item definition table of `itemstring`

+* `minetest.override_item(itemstring, redefinition)`
+    * Overrides fields of an item registered with register_node/tool/craftitem.
+    * Note: Item must already be defined by the server
+    * Example: `minetest.override_item("default:mese",
+      {light_source=minetest.LIGHT_MAX})`
+    * Doesnt really work yet an causes strange bugs, I'm working to make is better

 
 #### Node Definition
 
 
 #### Node Definition
 


@@ -1386,12 +1580,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`)
 


@@ -1447,3 +1664,4 @@ Displays distance to selected world position.
         texture = "image.png",
     --  ^ Uses texture (string)
     }
         texture = "image.png",
     --  ^ Uses texture (string)
     }

+