X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Fclient_lua_api.txt;h=75e40945ff18517cf0f818e9de69ebb92eea7487;hb=21df26984da91143c15587f5a03c98d68c3adc4e;hp=5618c7a6f62dd501f088c119730a957a392f439b;hpb=8b3eaf5b05379f995bf8d55532c107b190848a69;p=dragonfireclient.git diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 5618c7a6f..75e40945f 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.6.0 ================================================ * More information at * Developer Wiki: @@ -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 @@ -587,6 +587,7 @@ Spatial Vectors * `vector.floor(v)`: returns a vector, each dimension rounded down * `vector.round(v)`: returns a vector, each dimension rounded to nearest int * `vector.apply(v, func)`: returns a vector +* `vector.combine(v, w, func)`: returns a vector * `vector.equals(v1, v2)`: returns a boolean For the following functions `x` can be either a vector or a number: @@ -627,7 +628,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 +659,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 +678,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 +709,7 @@ Call these functions only at load time! * Registers a chatcommand `command` to manage a list that takes the args `del | add | list ` * 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 +771,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 @@ -793,6 +809,16 @@ Call these functions only at load time! * Returns the time of day: `0` for midnight, `0.5` for midday ### Map +* `minetest.interact(action, pointed_thing)` + * Sends an interaction to the server + * `pointed_thing` is a pointed_thing + * `action` is one of + * "start_digging": Use to punch nodes / objects + * "stop_digging": Use to abort digging a "start_digging" command + * "digging_completed": Use to finish a "start_digging" command or dig a node instantly + * "place": Use to rightclick nodes and objects + * "use": Use to leftclick an item in air (pointed_thing.type is usually "nothing") + * "activate": Same as "use", but rightclick * `minetest.place_node(pos)` * Places the wielded node/item of the player at pos. * `minetest.dig_node(pos)` @@ -919,11 +945,15 @@ 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 ClientObjectRefs. * `radius`: using an euclidean metric +* `minetest.get_nearby_objects(radius)` + * alias for minetest.get_objects_inside_radius(minetest.localplayer:get_pos(), radius) * `minetest.disconnect()` * Disconnect from the server and exit to main menu. * Returns `false` if the client is already disconnecting otherwise returns `true`. @@ -934,13 +964,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` @@ -1039,7 +1077,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 @@ -1087,7 +1125,9 @@ Passed to `HTTPApiTable.fetch` callback. Returned by * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"` * `minetest.encode_base64(string)`: returns string encoded in base64 * Encodes a string in base64. -* `minetest.decode_base64(string)`: returns string +* `minetest.decode_base64(string)`: returns string or nil on failure + * Padding characters are only supported starting at version 5.4.0, where + 5.5.0 and newer perform proper checks. * Decodes a string encoded in base64. * `minetest.gettext(string)` : returns string * look up the translation of a string in the gettext message catalog @@ -1102,6 +1142,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` @@ -1191,6 +1239,7 @@ Please do not try to access the reference until the camera is initialized, other ### LocalPlayer An interface to retrieve information about the player. +This object will only be available after the client is initialized. Earlier accesses will yield a `nil` value. Methods: @@ -1228,8 +1277,8 @@ Methods: * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface) * `is_in_liquid_stable()` * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player) -* `get_liquid_viscosity()` - * returns liquid viscosity (Gets the viscosity of liquid to calculate friction) +* `get_move_resistance()` + * returns move resistance of current node, the higher the slower the player moves * `is_climbing()` * returns true if player is climbing * `swimming_vertical()` @@ -1382,12 +1431,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. @@ -1416,6 +1469,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)` @@ -1427,10 +1482,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 @@ -1470,7 +1582,7 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or liquid_type = , -- A string containing "none", "flowing", or "source" *May not exist* liquid_alternative_flowing = , -- Alternative node for liquid *May not exist* liquid_alternative_source = , -- Alternative node for liquid *May not exist* - liquid_viscosity = , -- How fast the liquid flows *May not exist* + liquid_viscosity = , -- How slow the liquid flows *May not exist* liquid_renewable = , -- Whether the liquid makes an infinite source *May not exist* liquid_range = , -- How far the liquid flows *May not exist* drowning = bool, -- Whether the player will drown in the node @@ -1485,6 +1597,7 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or }, legacy_facedir_simple = bool, -- Whether to use old facedir legacy_wallmounted = bool -- Whether to use old wallmounted + move_resistance = , -- How slow players can move through the node *May not exist* } ``` @@ -1551,6 +1664,8 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or -- ^ See "HUD Element Types" size = { x=100, y=100 }, -- default {x=0, y=0} -- ^ Size of element in pixels + style = 0, + -- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace } ``` @@ -1592,9 +1707,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` ------------- @@ -1779,7 +1893,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) @@ -1794,7 +1908,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 - - + +