-Minetest Lua Modding API Reference 0.4.15
-=========================================
+Minetest Lua Client Modding API Reference 5.6.0
+================================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
Introduction
------------
-Content and functionality can be added to Minetest 0.4 by using Lua
+
+** WARNING: The client API is currently unstable, and may break/change without warning. **
+
+Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
scripting in run-time loaded mods.
A mod is a self-contained bunch of scripts, textures and other related
things that is loaded by and interfaces with Minetest.
-Mods are contained and ran solely on the server side. Definitions and media
-files are automatically transferred to the client.
+Transferring client-sided mods from the server to the client is planned, but not implemented yet.
If you see a deficiency in the API, feel free to attempt to add the
functionality in the engine and API. You can send such improvements as
Mods are loaded during client startup from the mod load paths by running
the `init.lua` scripts in a shared environment.
+In order to load client-side mods, the following conditions need to be satisfied:
+
+1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true`
+
+2) The client-side mod located in `$path_user/clientmods/<modname>` is added to
+ `$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
+
+Note: Depending on the remote server's settings, client-side mods might not
+be loaded or have limited functionality. See setting `csm_restriction_flags` for reference.
+
Paths
-----
* `RUN_IN_PLACE=1` (Windows release, local build)
- * `$path_user`:
- * Linux: `<build directory>`
- * Windows: `<build directory>`
- * `$path_share`
- * Linux: `<build directory>`
- * Windows: `<build directory>`
+ * `$path_user`: `<build directory>`
+ * `$path_share`: `<build directory>`
* `RUN_IN_PLACE=0`: (Linux release)
- * `$path_share`
+ * `$path_share`:
* Linux: `/usr/share/minetest`
* Windows: `<install directory>/minetest-0.4.x`
* `$path_user`:
Modpack support
----------------
+
Mods can be put in a subdirectory, if the parent directory, which otherwise
-should be a mod, contains a file named `modpack.txt`. This file shall be
-empty, except for lines starting with `#`, which are comments.
+should be a mod, contains a file named `modpack.conf`.
+The file is a key-value store of modpack details.
+
+* `name`: The modpack name.
+* `description`: Description of mod to be shown in the Mods tab of the main
+ menu.
Mod directory structure
------------------------
- mods
- |-- modname
- | |-- depends.txt
- | |-- screenshot.png
- | |-- description.txt
- | |-- settingtypes.txt
- | |-- init.lua
- | |-- models
- | |-- textures
- | | |-- modname_stuff.png
- | | `-- modname_something_else.png
- | |-- sounds
- | |-- media
- | `-- <custom data>
- `-- another
+ clientmods
+ ├── modname
+ │ ├── mod.conf
+ | ├── settingtypes.txt
+ │ ├── init.lua
+ └── another
+### `settingtypes.txt`
-### modname
-The location of this directory can be fetched by using
-`minetest.get_modpath(modname)`.
+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.
-### `depends.txt`
-List of mods that have to be loaded before loading this mod.
+### modname
-A single line contains a single modname.
+The location of this directory.
-Optional dependencies can be defined by appending a question mark
-to a single modname. Their meaning is that if the specified mod
-is missing, that does not prevent this mod from being loaded.
+### mod.conf
-### `screenshot.png`
-A screenshot shown in the mod manager within the main menu. It should
-have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
+An (optional) settings file that provides meta information about the mod.
-### `description.txt`
-A File containing description to be shown within mainmenu.
-
-### `settingtypes.txt`
-A file in the same format as the one in builtin. It will be parsed by the
-settings menu and the settings will be displayed in the "Mods" category.
+* `name`: The mod name. Allows Minetest to determine the mod name even if the
+ folder is wrongly named.
+* `description`: Description of mod to be shown in the Mods tab of the main
+ menu.
+* `depends`: A comma separated list of dependencies. These are mods that must be
+ loaded before this mod.
+* `optional_depends`: A comma separated list of optional dependencies.
+ Like a dependency, but no error if the mod doesn't exist.
### `init.lua`
+
The main Lua script. Running this script should register everything it
wants to register. Subsequent execution depends on minetest calling the
registered callbacks.
-`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
-to read custom or existing settings at load time, if necessary.
-
-### `sounds`
-Media files (sounds) that will be transferred to the
-client and will be available for use by the mod.
+**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).
Naming convention for registered textual names
----------------------------------------------
The `:` prefix can also be used for maintaining backwards compatibility.
-### Aliases
-Aliases can be added by using `minetest.register_alias(name, convert_to)` or
-`minetest.register_alias_force(name, convert_to).
-
-This will make Minetest to convert things called name to things called
-`convert_to`.
-
-The only difference between `minetest.register_alias` and
-`minetest.register_alias_force` is that if an item called `name` exists,
-`minetest.register_alias` will do nothing while
-`minetest.register_alias_force` will unregister it.
-
-This can be used for maintaining backwards compatibility.
-
-This can be also used for setting quick access names for things, e.g. if
-you have an item called `epiclylongmodname:stuff`, you could do
-
- minetest.register_alias("stuff", "epiclylongmodname:stuff")
-
-and be able to use `/giveme stuff`.
-
Sounds
------
+**NOTE: Connecting sounds to objects is not implemented.**
+
Only Ogg Vorbis files are supported.
For positional playing of sounds, only single-channel (mono) files are
Examples of sound parameter tables:
- -- Play locationless on all clients
+ -- Play locationless
{
gain = 1.0, -- default
}
- -- Play locationless to one player
+ -- Play locationless, looped
{
- to_player = name,
- gain = 1.0, -- default
- }
- -- Play locationless to one player, looped
- {
- to_player = name,
gain = 1.0, -- default
loop = true,
}
{
pos = {x = 1, y = 2, z = 3},
gain = 1.0, -- default
- max_hear_distance = 32, -- default, uses an euclidean metric
}
-- Play connected to an object, looped
{
object = <an ObjectRef>,
gain = 1.0, -- default
- max_hear_distance = 32, -- default, uses an euclidean metric
loop = true,
}
-Looped sounds must either be connected to an object or played locationless to
-one player using `to_player = name,`
+Looped sounds must either be connected to an object or played locationless.
-### `SimpleSoundSpec`
+### SimpleSoundSpec
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
For helper functions see "Vector helpers".
-### `pointed_thing`
+### pointed_thing
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
-* `{type="object", ref=ObjectRef}`
+* `{type="object", ref=ClientObjectRef}`
Flag Specifier Format
---------------------
Formspec
--------
-Formspec defines a menu. Currently not much else than inventories are
-supported. It is a string, with a somewhat strange format.
+Formspec defines a menu. It is a string, with a somewhat strange format.
Spaces and newlines can be inserted between the blocks, as is used in the
examples.
* Clickable button. When clicked, fields will be sent.
* `x`, `y` and `name` work as per field
* `w` and `h` are the size of the button
+* Fixed button height. It will be vertically centred on `h`
* `label` is the text on the button
* Position and size units are inventory slots
* `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:
* `math.sign(x, tolerance)`
* Get the sign of a number.
Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
-* `string.split(str, separator=",", include_empty=false, max_splits=-1,
-* sep_is_pattern=false)`
+* `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
* If `max_splits` is negative, do not limit splits.
* `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
* e.g. `string:split("a,b", ",") == {"a","b"}`
* `string:trim()`
* e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
+* `minetest.wrap_text(str, limit)`: returns a string
+ * Adds new lines to the string to keep it within the specified character limit
+ * limit: Maximal amount of characters in one line
+* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
+ * Convert position to a printable string
+ Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
+* `minetest.string_to_pos(string)`: returns a position
+ * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
+* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
+ * Converts a string representing an area box into two positions
* `minetest.is_yes(arg)`
* returns whether `arg` can be interpreted as yes
-* `minetest.get_us_time()`
- * returns time with microsecond precision. May not return wall time.
+* `minetest.is_nan(arg)`
+ * returns true when the passed number represents NaN.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
-`minetest` namespace reference
+Minetest namespace reference
------------------------------
### Utilities
* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
+* `minetest.get_modpath(modname)`: returns virtual path of given mod including
+ 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 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"
* `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
Use this for informational purposes only. The information in the returned
table does not represent the capabilities of the engine, nor is it
- reliable or verifyable. Compatible forks will have a different name and
+ reliable or verifiable. Compatible forks will have a different name and
version entirely. To check for the presence of engine features, test
whether the functions exported by the wanted features exist. For example:
- `if core.nodeupdate then ... end`.
+ `if minetest.check_for_falling then ... end`.
+* `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.
+ * Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`,
+ `read_nodedefs`, `lookup_nodes`, `read_playerinfo`
### Logging
* `minetest.debug(...)`
### Global callback registration functions
Call these functions only at load time!
-* `minetest.register_globalstep(func(dtime))`
+* `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_shutdown(func())`
+* `minetest.register_on_mods_loaded(function())`
+ * Called just after mods have finished loading.
+* `minetest.register_on_shutdown(function())`
* Called before client shutdown
* **Warning**: If the client terminates abnormally (i.e. crashes), the registered
callbacks **will likely not be run**. Data should be saved at
semi-frequent intervals as well as on server shutdown.
-* `minetest.register_on_receiving_chat_message(func(name, message))`
+* `minetest.register_on_receiving_chat_message(function(message))`
* Called always when a client receive a message
* Return `true` to mark the message as handled, which means that it will not be shown to chat
-* `minetest.register_on_sending_chat_message(func(name, message))`
+* `minetest.register_on_sending_chat_message(function(message))`
* Called always when a client send a message from chat
* Return `true` to mark the message as handled, which means that it will not be sent to server
* `minetest.register_chatcommand(cmd, chatcommand definition)`
* Adds definition to minetest.registered_chatcommands
-* `minetest.register_on_death(func())`
- * Called when player die
-* `minetest.register_on_hp_modification(func(hp))`
+* `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.
+ * 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))`
* Called when server modified player's HP
-* `minetest.register_on_damage_taken(func(hp))`
- * Called when player take damages
+* `minetest.register_on_damage_taken(function(hp))`
+ * Called when the local player take damages
+* `minetest.register_on_formspec_input(function(formname, fields))`
+ * Called when a button is pressed in the local player's inventory form
+ * Newest functions are called first
+ * If function returns `true`, remaining functions are not called
+* `minetest.register_on_dignode(function(pos, node))`
+ * Called when the local player digs a node
+ * Newest functions are called first
+ * If any function returns true, the node isn't dug
+* `minetest.register_on_punchnode(function(pos, node))`
+ * Called when the local player punches a node
+ * Newest functions are called first
+ * If any function returns true, the punch is ignored
+* `minetest.register_on_placenode(function(pointed_thing, node))`
+ * Called when a node has been placed
+* `minetest.register_on_item_use(function(item, pointed_thing))`
+ * Called when the local player uses an item.
+ * Newest functions are called first.
+ * If any function returns true, the item use is not sent to server.
+* `minetest.register_on_modchannel_message(function(channel_name, sender, message))`
+ * Called when an incoming mod channel message is received
+ * You must have joined some channels before, and server must acknowledge the
+ join request.
+ * If message comes from a server mod, `sender` field is an empty string.
+* `minetest.register_on_modchannel_signal(function(channel_name, signal))`
+ * Called when a valid incoming mod channel signal is received
+ * Signal id permit to react to server mod channel events
+ * Possible values are:
+ 0: join_ok
+ 1: join_failed
+ 2: leave_ok
+ 3: leave_failed
+ 4: event_on_not_joined_channel
+ 5: state_changed
+* `minetest.register_on_inventory_open(function(inventory))`
+ * 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`
* `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, ...)`
* Call the function `func` after `time` seconds, may be fractional
* Optional: Variable number of arguments that are passed to `func`
+* `minetest.get_us_time()`
+ * Returns time with microsecond precision. May not return wall time.
+* `minetest.get_timeofday()`
+ * 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`
+ for unloaded areas or flavor limited areas.
+* `minetest.get_node_light(pos, timeofday)`
+ * Gets the light value at the given position. Note that the light value
+ "inside" the node at the given position is returned, so you usually want
+ to get the light value of a neighbor.
+ * `pos`: The position where to measure the light.
+ * `timeofday`: `nil` for current time, `0` for night, `0.5` for day
+ * Returns a number between `0` and `15` or `nil`
+* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
+ * `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(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"`
+ * 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.
+ * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
+ * Return value: Table with all node positions with a node air above
+ * Area volume is limited to 4,096,000 nodes
+* `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos`
+ * Checks if there is anything other than air between pos1 and pos2.
+ * Returns false if something is blocking the sight.
+ * Returns the position of the blocking node when `false`
+ * `pos1`: First position
+ * `pos2`: Second position
+* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
+ * Creates a `Raycast` object.
+ * `pos1`: start of the ray
+ * `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}.
+* `minetest.get_meta(pos)`
+ * Get a `NodeMetaRef` at that position
+* `minetest.get_node_level(pos)`
+ * get level of leveled node (water, snow)
+* `minetest.get_node_max_level(pos)`
+ * 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.
+
+### Privileges
+* `minetest.get_privilege_list()`
+ * Returns a list of privileges the current player has in the format `{priv1=true,...}`
+* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
+* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
+ * 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`.
+* `minetest.get_server_info()`
+ * Returns [server info](#server-info).
+* `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",
-### Misc.
+ 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`
+ * must be called during mod load time
+
+### Mod channels
+
+
+* `minetest.mod_channel_join(channel_name)`
+ * Client joins channel `channel_name`, and creates it, if necessary. You
+ should listen from incoming messages with `minetest.register_on_modchannel_message`
+ call to receive incoming messages. Warning, this function is asynchronous.
+
+### Particles
+* `minetest.add_particle(particle definition)`
+
+* `minetest.add_particlespawner(particlespawner definition)`
+ * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
+ * Returns an `id`, and -1 if adding didn't succeed
+
+* `minetest.delete_particlespawner(id)`
+ * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
+
+### 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`
* See documentation on `minetest.compress()` for supported compression methods.
* currently supported.
* `...` indicates method-specific arguments. Currently, no methods use this.
+* `minetest.rgba(red, green, blue[, alpha])`: returns a string
+ * Each argument is a 8 Bit unsigned integer
+ * Returns the ColorString from rgb or rgba values
+ * 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
+* `fgettext_ne(string, ...)`
+ * call minetest.gettext(string), replace "$1"..."$9" with the given
+ extra arguments and return the result
+* `fgettext(string, ...)` : returns string
+ * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
+* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
+ * 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`
+ * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
+ * If client disabled minimap (using enable_minimap setting) this reference will be nil.
+* `minetest.camera`
+ * 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.
Class reference
---------------
-### `Settings`
+### ModChannel
+
+An interface to use mod channels on client and server
+
+#### Methods
+* `leave()`: leave the mod channel.
+ * Client leaves channel `channel_name`.
+ * No more incoming or outgoing messages can be sent to this channel from client mods.
+ * This invalidate all future object usage
+ * Ensure your set mod_channel to nil after that to free Lua resources
+* `is_writeable()`: returns true if channel is writable and mod can send over it.
+* `send_all(message)`: Send `message` though the mod channel.
+ * If mod channel is not writable or invalid, message will be dropped.
+ * Message size is limited to 65535 characters by protocol.
+
+### Minimap
+An interface to manipulate minimap on client UI
+
+#### Methods
+* `show()`: shows the minimap (if not disabled by server)
+* `hide()`: hides the minimap
+* `set_pos(pos)`: sets the minimap position on screen
+* `get_pos()`: returns the minimap current position
+* `set_angle(deg)`: sets the minimap angle in degrees
+* `get_angle()`: returns the current minimap angle in degrees
+* `set_mode(mode)`: sets the minimap mode (0 to 6)
+* `get_mode()`: returns the current minimap mode
+* `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
+* `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
+
+### Camera
+An interface to get or set information about the camera and camera-node.
+Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
+
+#### Methods
+* `set_camera_mode(mode)`
+ * Pass `0` for first-person, `1` for third person, and `2` for third person front
+* `get_camera_mode()`
+ * Returns 0, 1, or 2 as described above
+* `get_fov()`
+ * Returns a table with X, Y, maximum and actual FOV in degrees:
+
+```lua
+ {
+ x = number,
+ y = number,
+ max = number,
+ actual = number
+ }
+```
+
+* `get_pos()`
+ * Returns position of camera with view bobbing
+* `get_offset()`
+ * Returns eye offset vector
+* `get_look_dir()`
+ * Returns eye direction unit vector
+* `get_look_vertical()`
+ * Returns pitch in radians
+* `get_look_horizontal()`
+ * Returns yaw in radians
+* `get_aspect_ratio()`
+ * Returns aspect ratio of screen
+
+### 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:
+
+* `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 (starts at 1)
+* `set_wield_index()`
+ * sets the index (starts at 1)
+* `get_wielded_item()`
+ * returns the itemstack the player is holding
+* `is_attached()`
+ * returns true if player is attached
+* `is_touching_ground()`
+ * returns true if player touching ground
+* `is_in_liquid()`
+ * 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_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()`
+ * returns true if player is swimming in vertical
+* `get_physics_override()`
+ * returns:
+
+```lua
+ {
+ speed = float,
+ jump = float,
+ gravity = float,
+ sneak = boolean,
+ sneak_glitch = boolean,
+ new_move = boolean,
+ }
+```
+
+* `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()`
+ * returns last player position before the current client step
+* `get_last_velocity()`
+ * returns last player speed
+* `get_breath()`
+ * returns the player's breath
+* `get_movement_acceleration()`
+ * returns acceleration of the player in different environments:
+
+```lua
+ {
+ fast = float,
+ air = float,
+ default = float,
+ }
+```
+
+* `get_movement_speed()`
+ * returns player's speed in different environments:
+
+```lua
+ {
+ walk = float,
+ jump = float,
+ crouch = float,
+ fast = float,
+ climb = float,
+ }
+```
+
+* `get_movement()`
+ * returns player's movement in different environments:
+
+```lua
+ {
+ liquid_fluidity = float,
+ liquid_sink = float,
+ liquid_fluidity_smooth = float,
+ gravity = float,
+ }
+```
+
+* `get_last_look_horizontal()`:
+ * returns last look horizontal angle
+* `get_last_look_vertical()`:
+ * returns last look vertical angle
+* `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_get(id)`
+ * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.
+* `hud_remove(id)`
+ * remove the HUD element of the specified id, returns `true` on success
+* `hud_change(id, stat, value)`
+ * 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`.
It can be created via `Settings(filename)`.
* write changes to file
* `to_table()`: returns `{[key1]=value1,...}`
-Definition tables
+### NodeMetaRef
+Node metadata: reference extra data and functionality stored in a node.
+Can be obtained via `minetest.get_meta(pos)`.
+
+#### Methods
+* `get_string(name)`
+* `get_int(name)`
+* `get_float(name)`
+* `to_table()`: returns `nil` or a table with keys:
+ * `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.
+Can be used as an iterator in a for loop as:
+
+ local ray = Raycast(...)
+ for pointed_thing in ray do
+ ...
+ end
+
+The map is loaded as the ray advances. If the map is modified after the
+`Raycast` is created, the changes may or may not have an effect on the object.
+
+It can be created via `Raycast(pos1, pos2, objects, liquids)` or
+`minetest.raycast(pos1, pos2, objects, liquids)` where:
+
+* `pos1`: start of the ray
+* `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.
+
+#### Methods
+
+* `next()`: returns a `pointed_thing` with exact pointing location
+ * Returns the next thing pointed by the ray or nil.
+
+-----------------
+### 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
+ name = string, -- The name of the node e.g. "air", "default:dirt"
+ groups = table, -- The groups of the node
+ paramtype = string, -- Paramtype of the node
+ paramtype2 = string, -- ParamType2 of the node
+ drawtype = string, -- Drawtype of the node
+ mesh = <string>, -- Mesh name if existant
+ minimap_color = <Color>, -- Color of node on minimap *May not exist*
+ visual_scale = number, -- Visual scale of node
+ alpha = number, -- Alpha of the node. Only used for liquids
+ color = <Color>, -- Color of node *May not exist*
+ palette_name = <string>, -- Filename of palette *May not exist*
+ palette = <{ -- List of colors
+ Color,
+ Color
+ }>,
+ waving = number, -- 0 of not waving, 1 if waving
+ connect_sides = number, -- Used for connected nodes
+ connects_to = { -- List of nodes to connect to
+ "node1",
+ "node2"
+ },
+ post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
+ leveled = number, -- Max level for node
+ sunlight_propogates = bool, -- Whether light passes through the block
+ light_source = number, -- Light emitted by the block
+ is_ground_content = bool, -- Whether caves should cut through the node
+ walkable = bool, -- Whether the player collides with the node
+ pointable = bool, -- Whether the player can select the node
+ diggable = bool, -- Whether the player can dig the node
+ climbable = bool, -- Whether the player can climb up the node
+ buildable_to = bool, -- Whether the player can replace the node by placing a node on it
+ rightclickable = bool, -- Whether the player can place nodes pointing at this node
+ damage_per_second = number, -- HP of damage per second when the player is in the node
+ liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
+ liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
+ liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
+ liquid_viscosity = <number>, -- How slow the liquid flows *May not exist*
+ liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
+ liquid_range = <number>, -- How far the liquid flows *May not exist*
+ drowning = bool, -- Whether the player will drown in the node
+ floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
+ node_box = table, -- Nodebox to draw the node with
+ collision_box = table, -- Nodebox to set the collision area
+ selection_box = table, -- Nodebox to set the area selected by the player
+ sounds = { -- Table of sounds that the block makes
+ sound_footstep = SimpleSoundSpec,
+ sound_dig = SimpleSoundSpec,
+ sound_dug = SimpleSoundSpec
+ },
+ legacy_facedir_simple = bool, -- Whether to use old facedir
+ legacy_wallmounted = bool -- Whether to use old wallmounted
+ move_resistance = <number>, -- How slow players can move through the node *May not exist*
+ }
+```
+
+#### Item Definition
+
+```lua
+ {
+ name = string, -- Name of the item e.g. "default:stone"
+ description = string, -- Description of the item e.g. "Stone"
+ type = string, -- Item type: "none", "node", "craftitem", "tool"
+ inventory_image = string, -- Image in the inventory
+ wield_image = string, -- Image in wieldmesh
+ palette_image = string, -- Image for palette
+ color = Color, -- Color for item
+ wield_scale = Vector, -- Wieldmesh scale
+ stack_max = number, -- Number of items stackable together
+ usable = bool, -- Has on_use callback defined
+ liquids_pointable = bool, -- Whether you can point at liquids with the item
+ tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item
+ groups = table, -- Groups of the item
+ sound_place = SimpleSoundSpec, -- Sound played when placed
+ sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
+ node_placement_prediction = string -- Node placed in client until server catches up
+ }
+```
-----------------
### Chat command definition (`register_chatcommand`)
{
params = "<name> <privilege>", -- Short parameter description
description = "Remove privilege from player", -- Full description
- privs = {privs=true}, -- Require the "privs" privilege to run
- func = function(name, param), -- Called when command is run.
- -- Returns boolean success and text output.
+ func = function(param), -- Called when command is run.
+ -- Returns boolean success and text output.
}
+### Server info
+```lua
+{
+ address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
+ ip = "203.0.113.156", -- The IP address of the server.
+ port = 30000, -- The port the client is connected to.
+ protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
+}
+```
+
+### HUD Definition (`hud_add`, `hud_get`)
+```lua
+ {
+ hud_elem_type = "image", -- see HUD element types, default "text"
+ -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
+ position = {x=0.5, y=0.5},
+ -- ^ Left corner position of element, default `{x=0,y=0}`.
+ name = "<name>", -- default ""
+ scale = {x=2, y=2}, -- default {x=0,y=0}
+ text = "<text>", -- default ""
+ number = 2, -- default 0
+ item = 3, -- default 0
+ -- ^ Selected item in inventory. 0 for no item selected.
+ direction = 0, -- default 0
+ -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
+ alignment = {x=0, y=0}, -- default {x=0, y=0}
+ -- ^ See "HUD Element Types"
+ offset = {x=0, y=0}, -- default {x=0, y=0}
+ -- ^ 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
+ }
+```
+
+Escape sequences
+----------------
+Most text can contain escape sequences, that can for example color the text.
+There are a few exceptions: tab headers, dropdowns and vertical labels can't.
+The following functions provide escape sequences:
+* `minetest.get_color_escape_sequence(color)`:
+ * `color` is a [ColorString](#colorstring)
+ * The escape sequence sets the text color to `color`
+* `minetest.colorize(color, message)`:
+ * Equivalent to:
+ `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
+ `color`. Only defined for item descriptions and tooltips.
+* `minetest.strip_foreground_colors(str)`
+ * Removes foreground colors added by `get_color_escape_sequence`.
+* `minetest.strip_background_colors(str)`
+ * Removes background colors added by `get_background_escape_sequence`.
+* `minetest.strip_colors(str)`
+ * Removes all color escape sequences.
+
+`ColorString`
+-------------
+`#RGB` defines a color in hexadecimal format.
+
+`#RGBA` defines a color in hexadecimal format and alpha channel.
+
+`#RRGGBB` defines a color in hexadecimal format.
+
+`#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
+
+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 `#A` or `#AA` to the end of
+the color name (e.g. `colorname#08`).
+
+`Color`
+-------------
+`{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.
+
+HUD element types
+-----------------
+The position field is used for all element types.
+
+To account for differing resolutions, the position coordinates are the percentage
+of the screen, ranging in value from `0` to `1`.
+
+The name field is not yet used, but should contain a description of what the
+HUD element represents. The direction field is the direction in which something
+is drawn.
+
+`0` draws from left to right, `1` draws from right to left, `2` draws from
+top to bottom, and `3` draws from bottom to top.
+
+The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
+with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
+Fractional values can be used.
+
+The `offset` field specifies a pixel offset from the position. Contrary to position,
+the offset is not scaled to screen size. This allows for some precisely-positioned
+items in the HUD.
+
+**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
+
+Below are the specific uses for fields in each type; fields not listed for that type are ignored.
+
+**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
+in the experimental stages.
+
+### `image`
+Displays an image on the HUD.
+
+* `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.
+* `offset`: offset in pixels from position.
+
+### `text`
+Displays text on the HUD.
+
+* `scale`: Defines the bounding rectangle of the text.
+ A value such as `{x=100, y=100}` should work.
+* `text`: The text to be displayed in the HUD element.
+* `number`: An integer containing the RGB value of the color used to draw the text.
+ Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
+* `alignment`: The alignment of the text.
+* `offset`: offset in pixels from position.
+
+### `statbar`
+Displays a horizontal bar made up of half-images.
+
+* `text`: The name of the texture that is used.
+* `number`: The number of half-textures that are displayed.
+ If odd, will end with a vertically center-split texture.
+* `direction`
+* `offset`: offset in pixels from position.
+* `size`: If used, will force full-image size to this value (override texture pack image size)
+
+### `inventory`
+* `text`: The name of the inventory list to be displayed.
+* `number`: Number of items in the inventory to be displayed.
+* `item`: Position of item that is selected.
+* `direction`
+* `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.
+* `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.
+* `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`)
+
+ {
+ pos = {x=0, y=0, z=0},
+ velocity = {x=0, y=0, z=0},
+ acceleration = {x=0, y=0, z=0},
+ -- ^ Spawn particle at pos with velocity and acceleration
+ expirationtime = 1,
+ -- ^ Disappears after expirationtime seconds
+ size = 1,
+ collisiondetection = false,
+ -- ^ collisiondetection: if true collides with physical objects
+ collision_removal = false,
+ -- ^ collision_removal: if true then particle is removed when it collides,
+ -- ^ requires collisiondetection = true to have any effect
+ vertical = false,
+ -- ^ vertical: if true faces player using y axis only
+ texture = "image.png",
+ -- ^ Uses texture (string)
+ animation = {Tile Animation definition},
+ -- ^ optional, specifies how to animate the particle texture
+ glow = 0
+ -- ^ optional, specify particle self-luminescence in darkness
+ }
+
+### `ParticleSpawner` definition (`add_particlespawner`)
+
+ {
+ amount = 1,
+ time = 1,
+ -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
+ minpos = {x=0, y=0, z=0},
+ maxpos = {x=0, y=0, z=0},
+ minvel = {x=0, y=0, z=0},
+ maxvel = {x=0, y=0, z=0},
+ minacc = {x=0, y=0, z=0},
+ maxacc = {x=0, y=0, z=0},
+ minexptime = 1,
+ maxexptime = 1,
+ minsize = 1,
+ maxsize = 1,
+ -- ^ The particle's properties are random values in between the bounds:
+ -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
+ -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
+ collisiondetection = false,
+ -- ^ collisiondetection: if true uses collision detection
+ collision_removal = false,
+ -- ^ collision_removal: if true then particle is removed when it collides,
+ -- ^ requires collisiondetection = true to have any effect
+ vertical = false,
+ -- ^ vertical: if true faces player using y axis only
+ 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
+
+
+
+
projects / dragonfireclient.git / blobdiff