diff options
Diffstat (limited to 'doc/client_lua_api.txt')
| -rw-r--r-- | doc/client_lua_api.txt | 137 |
1 files changed, 116 insertions, 21 deletions
diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 94d40fe2a..22148ee51 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Client Modding API Reference 5.4.0 +Minetest Lua Client Modding API Reference 5.5.0 ================================================ * More information at <http://www.minetest.net/> * Developer Wiki: <http://dev.minetest.net/> @@ -94,7 +94,7 @@ Mod directory structure 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. +settings in the "Clientmods" category. ### modname @@ -627,7 +627,7 @@ Helper functions * `minetest.is_yes(arg)` * returns whether `arg` can be interpreted as yes * `minetest.is_nan(arg)` - * returns true true when the passed number represents NaN. + * returns true when the passed number represents NaN. * `table.copy(table)`: returns a table * returns a deep copy of `table` @@ -658,6 +658,9 @@ Minetest namespace reference * `minetest.sha1(data, [raw])`: returns the sha1 hash of data * `data`: string of data to hash * `raw`: return raw bytes instead of hex digits, default: false +* `minetest.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a + ColorString. If the ColorSpec is invalid, returns `nil`. + * `colorspec`: The ColorSpec to convert * `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the restrictions applied to the current mod. * If a flag in this table is set to true, the feature is RESTRICTED. @@ -674,6 +677,11 @@ Minetest namespace reference ### Global callback registration functions Call these functions only at load time! +* `minetest.get_send_speed(speed)` + * This function is called every time the player's speed is sent to server + * The `speed` argument is the actual speed of the player + * If you define it, you can return a modified `speed`. This speed will be + sent to server instead. * `minetest.open_enderchest()` * This function is called if the client uses the Keybind for it (by default "O") * You can override it @@ -700,7 +708,7 @@ Call these functions only at load time! * Registers a chatcommand `command` to manage a list that takes the args `del | add | list <param>` * The list is stored comma-seperated in `setting` * `desc` is the description - * `add` adds something to the list + * `add` adds something to the list * `del` del removes something from the list * `list` lists all items on the list * `minetest.register_on_chatcommand(function(command, params))` @@ -762,7 +770,14 @@ Call these functions only at load time! * `minetest.register_on_spawn_partice(function(particle definition))` * Called when recieving a spawn particle command from server * Newest functions are called first - * If any function returns true, the particel does not spawn + * If any function returns true, the particle does not spawn +* `minetest.register_on_object_add(function(obj))` + * Called every time an object is added +* `minetest.register_on_object_properties_change(function(obj))` + * Called every time the properties of an object are changed server-side + * May modify the object's properties without the fear of infinite recursion +* `minetest.register_on_object_hp_change(function(obj))` + * Called every time the hp of an object are changes server-side ### Setting-related * `minetest.settings`: Settings object containing all of the settings from the @@ -929,6 +944,8 @@ Call these functions only at load time! * Convert between two privilege representations ### Client Environment +* `minetest.object_refs` + * Map of object references, indexed by active object id * `minetest.get_player_names()` * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server) * `minetest.get_objects_inside_radius(pos, radius)`: returns a list of @@ -946,13 +963,21 @@ Call these functions only at load time! ### HTTP Requests -* `minetest.get_http_api()` - * returns `HTTPApiTable` containing http functions. - * The returned table contains the functions `fetch_sync`, `fetch_async` and +* `minetest.request_http_api()`: + * returns `HTTPApiTable` containing http functions if the calling mod has + been granted access by being listed in the `secure.http_mods` or + `secure.trusted_mods` setting, otherwise returns `nil`. + * The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get` described below. + * Only works at init time and must be called from the mod's main scope + (not from a function). * Function only exists if minetest server was built with cURL support. -* `HTTPApiTable.fetch_sync(HTTPRequest req)`: returns HTTPRequestResult - * Performs given request synchronously + * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN + A LOCAL VARIABLE!** +* `HTTPApiTable.fetch(HTTPRequest req, callback)` + * Performs given request asynchronously and calls callback upon completion + * callback: `function(HTTPRequestResult res)` + * Use this HTTP function if you are unsure, the others are for advanced use * `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle * Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get` @@ -1051,7 +1076,7 @@ Passed to `HTTPApiTable.fetch` callback. Returned by * `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 + * 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 @@ -1114,6 +1139,14 @@ Passed to `HTTPApiTable.fetch` callback. Returned by * Checks if a global variable has been set, without triggering a warning. * `minetest.make_screenshot()` * Triggers the MT makeScreenshot functionality +* `minetest.request_insecure_environment()`: returns an environment containing + insecure functions if the calling mod has been listed as trusted in the + `secure.trusted_mods` setting or security is disabled, otherwise returns + `nil`. + * Only works at init time and must be called from the mod's main scope + (ie: the init.lua of the mod, not from another Lua file or within a function). + * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE + IT IN A LOCAL VARIABLE!** ### UI * `minetest.ui.minimap` @@ -1395,12 +1428,16 @@ This is basically a reference to a C++ `GenericCAO`. * `is_player()`: returns true if the object is a player * `is_local_player()`: returns true if the object is the local player * `get_attach()`: returns parent or nil if it isn't attached. -* `get_nametag()`: returns the nametag (string) -* `get_item_textures()`: returns the textures -* `get_max_hp()`: returns the maximum heath +* `get_nametag()`: returns the nametag (deprecated, use get_properties().nametag instead) +* `get_item_textures()`: returns the textures (deprecated, use get_properties().textures instead) +* `get_max_hp()`: returns the maximum heath (deprecated, use get_properties().hp_max instead) +* `set_properties(object property table)` +* `get_properties()`: returns object property table * `punch()`: punches the object * `rightclick()`: rightclicks the object - +* `remove()`: removes the object permanently +* `set_nametag_images(images)`: Provides a list of images to be drawn below the nametag + ### `Raycast` A raycast on the map. It works with selection boxes. @@ -1429,6 +1466,8 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or ----------------- ### Definitions +* `minetest.inventorycube(img1, img2, img3)` + * Returns a string for making an image of a cube (useful as an item image) * `minetest.get_node_def(nodename)` * Returns [node definition](#node-definition) table of `nodename` * `minetest.get_item_def(itemstring)` @@ -1440,10 +1479,67 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or {light_source=minetest.LIGHT_MAX})` * Doesnt really work yet an causes strange bugs, I'm working to make is better + +#### Tile definition + +* `"image.png"` +* `{name="image.png", animation={Tile Animation definition}}` +* `{name="image.png", backface_culling=bool, align_style="node"/"world"/"user", scale=int}` + * backface culling enabled by default for most nodes + * align style determines whether the texture will be rotated with the node + or kept aligned with its surroundings. "user" means that client + setting will be used, similar to `glasslike_framed_optional`. + Note: supported by solid nodes and nodeboxes only. + * scale is used to make texture span several (exactly `scale`) nodes, + instead of just one, in each direction. Works for world-aligned + textures only. + Note that as the effect is applied on per-mapblock basis, `16` should + be equally divisible by `scale` or you may get wrong results. +* `{name="image.png", color=ColorSpec}` + * the texture's color will be multiplied with this color. + * the tile's color overrides the owning node's color in all cases. + +##### Tile definition + + { + type = "vertical_frames", + + aspect_w = 16, + -- Width of a frame in pixels + + aspect_h = 16, + -- Height of a frame in pixels + + length = 3.0, + -- Full loop length + } + + { + type = "sheet_2d", + + frames_w = 5, + -- Width in number of frames + + frames_h = 3, + -- Height in number of frames + + frame_length = 0.5, + -- Length of a single frame + } + #### Node Definition ```lua { + tiles = {tile definition 1, def2, def3, def4, def5, def6}, + -- Textures of node; +Y, -Y, +X, -X, +Z, -Z + overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, + -- Same as `tiles`, but these textures are drawn on top of the base + -- tiles. This is used to colorize only specific parts of the + -- texture. If the texture name is an empty string, that overlay is not + -- drawn + special_tiles = {tile definition 1, Tile definition 2}, + -- Special textures of node; used rarely. has_on_construct = bool, -- Whether the node has the on_construct callback defined has_on_destruct = bool, -- Whether the node has the on_destruct callback defined has_after_destruct = bool, -- Whether the node has the after_destruct callback defined @@ -1605,9 +1701,8 @@ The following functions provide escape sequences: Named colors are also supported and are equivalent to [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors). -To specify the value of the alpha channel, append `#AA` to the end of the color name -(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha -value must (always) be two hexadecimal digits. +To specify the value of the alpha channel, append `#A` or `#AA` to the end of +the color name (e.g. `colorname#08`). `Color` ------------- @@ -1792,7 +1887,7 @@ A reference to a C++ InventoryAction. You can move, drop and craft items in all * it specifies how many items to drop / craft / move * `0` means move all items * default count: `0` - + #### example `local move_act = InventoryAction("move") move_act:from("current_player", "main", 1) @@ -1807,7 +1902,7 @@ A reference to a C++ InventoryAction. You can move, drop and craft items in all drop_act:apply() ` * e.g. In first hotbar slot there are tree logs: Move one to craft field, then craft wood out of it and immediately drop it - - + + |