-Minetest Lua Modding API Reference 0.4.15
-=========================================
+Minetest Lua Client Modding API Reference 5.1.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
Modpack support
----------------
+**NOTE: Not implemented yet.**
+
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
+ | ├── depends.txt
+ | ├── init.lua
+ └── another
### modname
-The location of this directory can be fetched by using
-`minetest.get_modpath(modname)`.
+The location of this directory.
-### `depends.txt`
+### depends.txt
List of mods that have to be loaded before loading this mod.
A single line contains a single modname.
to a single modname. Their meaning is that if the specified mod
is missing, that does not prevent this mod from being loaded.
-### `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.
-
-### `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.
-
-### `init.lua`
+### 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.
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: max_hear_distance and connecting 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,
}
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", id=ObjectID}`
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
* `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 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_language()`: returns the currently set gettext language.
* `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
### Logging
* `minetest.debug(...)`
### Global callback registration functions
Call these functions only at load time!
-* `minetest.register_globalstep(func(dtime))`
+* `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())`
+* `minetest.unregister_chatcommand(name)`
+ * Unregisters a chatcommands registered with register_chatcommand.
+* `minetest.register_on_death(function())`
* Called when the local player dies
-* `minetest.register_on_hp_modification(func(hp))`
+* `minetest.register_on_hp_modification(function(hp))`
* Called when server modified player's HP
-* `minetest.register_on_damage_taken(func(hp))`
+* `minetest.register_on_damage_taken(function(hp))`
* Called when the local player take damages
-* `minetest.register_on_formspec_input(func(formname, fields))`
+* `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(func(pos, node))`
+* `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(func(pos, node))`
+* `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
### Sounds
* `minetest.sound_play(spec, parameters)`: returns a handle
* `spec` is a `SimpleSoundSpec`
* `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_day_count()`
+ * Returns number days elapsed since world was created, accounting for time changes.
+* `minetest.get_timeofday()`
+ * Returns the time of day: `0` for midnight, `0.5` for midday
### Map
-* `minetest.get_node(pos)`
- * Returns the node at the given position as table in the format
- `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
- for unloaded areas.
* `minetest.get_node_or_nil(pos)`
- * Same as `get_node` but returns `nil` for unloaded areas.
+ * 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.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.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.get_wielded_item()`
- * Returns the itemstack the local player is holding
+ * Returns the itemstack the local player is holding
+* `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.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.get_player_names()`
+ * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)
+* `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.
+
+### 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.parse_json(string[, nullvalue])`: returns something
* 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
* Decodes a string encoded in base64.
-* `core.gettext(string) : returns string
+* `minetest.gettext(string)` : returns string
* look up the translation of a string in the gettext message catalog
* `fgettext_ne(string, ...)`
- * call core.gettext(string), replace "$1"..."$9" with the given
+ * 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 core.formspec_escape before returning result
-* `show_formspec(formname, formspec)` : returns true on success
+ * 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.
+
+### 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.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:
+
+```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.
+
+Methods:
+
+* `get_pos()`
+ * returns current player current position
+* `get_velocity()`
+ * returns player speed vector
+* `get_hp()`
+ * returns player HP
+* `get_name()`
+ * returns player name
+* `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_liquid_viscosity()`
+ * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
+* `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
+ }
+```
+
+* `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_key_pressed()`:
+ * returns last key typed by the player
+* `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`
+
+### 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 = {}, ...}}`
+
+-----------------
+### Definitions
+* `minetest.get_node_def(nodename)`
+ * Returns [node definition](#node-definition) table of `nodename`
+* `minetest.get_item_def(itemstring)`
+ * Returns item definition table of `itemstring`
+
+#### Node Definition
+
+```lua
+ {
+ 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 fast 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
+ }
+```
+
+#### 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
+ }
+```
+
+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.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 `#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.
+
+`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.
+* `number:` An integer containing the RGB value of the color used to draw the text.
+* `world_pos`: World position of the waypoint.
+
+### 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)
}
projects / oweals / minetest.git / blobdiff