diff options
Diffstat (limited to 'doc/client_lua_api.txt')
| -rw-r--r-- | doc/client_lua_api.txt | 403 |
1 files changed, 399 insertions, 4 deletions
diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index d08cd9b5e..75e40945f 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -86,9 +86,16 @@ Mod directory structure clientmods ├── modname │ ├── mod.conf + | ├── settingtypes.txt │ ├── 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. @@ -212,7 +219,7 @@ For helper functions see "Vector helpers". ### pointed_thing * `{type="nothing"}` * `{type="node", under=pos, above=pos}` -* `{type="object", id=ObjectID}` +* `{type="object", ref=ClientObjectRef}` Flag Specifier Format --------------------- @@ -671,6 +678,14 @@ 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 * `minetest.register_globalstep(function(dtime))` * Called every client environment step, usually interval of 0.1s * `minetest.register_on_mods_loaded(function())` @@ -690,6 +705,13 @@ Call these functions only at load time! * Adds definition to minetest.registered_chatcommands * `minetest.unregister_chatcommand(name)` * Unregisters a chatcommands registered with register_chatcommand. +* `minetest.register_list_command(command, desc, setting)` + * 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 + * `del` del removes something from the list + * `list` lists all items on the list * `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. @@ -738,6 +760,32 @@ 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 +* `minetest.register_on_recieve_physics_override(function(override))` + * Called when recieving physics_override from server + * Newest functions are called first + * If any function returns true, the physics override does not change +* `minetest.register_on_play_sound(function(SimpleSoundSpec))` + * Called when recieving a play sound command from server + * Newest functions are called first + * If any function returns true, the sound does not play +* `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 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 + 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` @@ -761,6 +809,20 @@ 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)` + * 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` @@ -777,6 +839,26 @@ 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 +* `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"` + * `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"` @@ -804,7 +886,33 @@ 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`. - +* `minetest.get_pointed_thing()` returns `PointedThing` + * Returns the thing currently pointed by player +* `minetest.get_pointed_thing_position(pointed_thing, above)` + * Returns the position of a `pointed_thing` or `nil` if the `pointed_thing` + does not refer to a node or entity. + * If the optional `above` parameter is true and the `pointed_thing` refers + to a node, then it will return the `above` position of the `pointed_thing`. +* `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}. @@ -816,12 +924,16 @@ Call these functions only at load time! * get max available level for leveled node ### Player +* `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.drop_selected_item()` + * Drops the selected item * `minetest.localplayer` * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods. @@ -833,8 +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`. @@ -843,6 +962,81 @@ Call these functions only at load time! * `minetest.send_respawn()` * Sends a respawn request to the server. +### HTTP Requests + +* `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. + * **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` +* `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` @@ -866,7 +1060,27 @@ Call these functions only at load time! * `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.find_item(item)` + * finds and an item in the inventory + * returns index on success or nil if item is not found +* `minetest.switch_to_item(item)` + * `item` is an Itemstring + * searches to item in inventory, sets the wield index to it if found + * returns true on success, false if item was not found +* `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` @@ -926,6 +1140,16 @@ Call these functions only at load time! * returns the exact position on the surface of a pointed node * `minetest.global_exists(name)` * 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` @@ -935,6 +1159,14 @@ Call these functions only at load time! * Reference to the camera object. See [`Camera`](#camera) class reference for methods. * `minetest.show_formspec(formname, formspec)` : returns true on success * Shows a formspec to the player +* `minetest.close_formspec(formname)` + * `formname`: has to exactly match the one given in `show_formspec`, or the + formspec will not close. + * calling `show_formspec(formname, "")` is equal to this + expression. + * to close a formspec regardless of the formname, call + `minetest.close_formspec("")`. + **USE THIS ONLY WHEN ABSOLUTELY NECESSARY!** * `minetest.display_chat_message(message)` returns true on success * Shows a chat message to the current player. @@ -1013,14 +1245,28 @@ Methods: * `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_pitch()` + * returns the pitch (degrees) +* `set_pitch(pitch)` + * sets the pitch (degrees) * `get_velocity()` * returns player speed vector +* `set_velocity(vel)` + * sets player speed vector * `get_hp()` * returns player HP * `get_name()` * returns player name * `get_wield_index()` - * returns the index of the wielded item + * returns the index of the wielded item (starts at 1) +* `set_wield_index()` + * sets the index (starts at 1) * `get_wielded_item()` * returns the itemstack the player is holding * `is_attached()` @@ -1051,6 +1297,17 @@ Methods: } ``` +* `set_physics_override(override_table)` + * `override_table` is a table with the following fields: + * `speed`: multiplier to default walking speed value (default: `1`) + * `jump`: multiplier to default jump value (default: `1`) + * `gravity`: multiplier to default gravity value (default: `1`) + * `sneak`: whether player can sneak (default: `true`) + * `sneak_glitch`: whether player can use the new move code replications + of the old sneak side-effects: sneak ladders and 2 node sneak jump + (default: `false`) + * `new_move`: use new move/sneak code. When `false` the exact old code + is used for the specific old sneak behaviour (default: `true`) * `get_override_pos()` * returns override position * `get_last_pos()` @@ -1130,6 +1387,8 @@ Methods: * change a value of a previously added HUD element * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir` * Returns `true` on success, otherwise returns `nil` +* `get_object()` + * Returns the ClientObjectRef for the player ### Settings An interface to read config files in the format of `minetest.conf`. @@ -1158,6 +1417,30 @@ Can be obtained via `minetest.get_meta(pos)`. * `fields`: key-value storage * `inventory`: `{list1 = {}, ...}}` +### ClientObjectRef + +Moving things in the game are generally these. +This is basically a reference to a C++ `GenericCAO`. + +#### Methods + +* `get_pos()`: returns `{x=num, y=num, z=num}` +* `get_velocity()`: returns the velocity, a vector +* `get_acceleration()`: returns the acceleration, a vector +* `get_rotation()`: returns the rotation, a vector (radians) +* `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 (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. @@ -1186,15 +1469,80 @@ 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)` * 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 + + +#### 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 @@ -1334,6 +1682,8 @@ The following functions provide escape sequences: `minetest.get_color_escape_sequence(color) .. message .. minetest.get_color_escape_sequence("#ffffff")` +* `minetest.rainbow(message)`: + * Rainbow colorizes the message. * `minetest.get_background_escape_sequence(color)` * `color` is a [ColorString](#colorstring) * The escape sequence sets the background of the whole text element to @@ -1517,3 +1867,48 @@ Same as `image`, but does not accept a `position`; the position is instead deter texture = "image.png", -- ^ Uses texture (string) } + +### InventoryAction +A reference to a C++ InventoryAction. You can move, drop and craft items in all accessible inventories using InventoryActions. + +#### methods + +* `InventoryAction(type)`: + * creates a new InventoryAction + * type is on of "move", "drop", or "craft", else returns nil + * indexing starts at 1 +* `apply()`: + * applies the InventoryAction (InventoryActions can be applied multible times) +* `from(inventorylocation, listname, stack)` + * this is valid for move or drop actions + * when `apply()` is called items are moved / dropped from `listname` `inventorylocation` in` at `stack` +* `to(inventorylocation, listname, stack)` + * this is valid for move actions + * when `apply()` is called items are moved to `listname` in`inventorylocation` at `stack` +* `craft(inventoryaction)` + * this is valid for craft actions + * when `apply()` is called a craft event for this inventory will be triggered +* `set_count(count)` + * this is valid for all actions + * 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) + move_act:to("current_player", "craft", 1) + move_act:set_count(1) + local craft_act = InventoryAction("craft") + craft_act:craft("current_player") + local drop_act = InventoryAction("drop") + drop_act:from("current_player", "craft_result",10) + move_act:apply() + craft_act:apply() + 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 + + + + |