-Minetest Lua Client Modding API Reference 5.1.0
+Minetest Lua Client Modding API Reference 5.6.0
================================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
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 in a world, the following conditions need to be satisfied:
+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`
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
----------------
-**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.conf`.
clientmods
├── modname
- | ├── depends.txt
- | ├── init.lua
+ │ ├── mod.conf
+ | ├── settingtypes.txt
+ │ ├── init.lua
└── another
+### `settingtypes.txt`
+
+The format is documented in `builtin/settingtypes.txt`.
+It is parsed by the main menu settings dialogue to list mod-specific
+settings in the "Clientmods" category.
+
### modname
+
The location of this directory.
-### depends.txt
-List of mods that have to be loaded before loading this mod.
+### mod.conf
-A single line contains a single modname.
+An (optional) settings file that provides meta information about the mod.
+
+* `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.
-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.
+### `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.
-`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
----------------------------------------------
Sounds
------
-**NOTE: max_hear_distance and connecting to objects is not implemented.**
+**NOTE: Connecting sounds to objects is not implemented.**
Only Ogg Vorbis files are supported.
{
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,
}
### pointed_thing
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
-* `{type="object", id=ObjectID}`
+* `{type="object", ref=ClientObjectRef}`
Flag Specifier Format
---------------------
* `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:
* `minetest.is_yes(arg)`
* returns whether `arg` can be interpreted as yes
* `minetest.is_nan(arg)`
- * returns true true when the passed number represents NaN.
+ * returns true when the passed number represents NaN.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
### 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_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"
* `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.get_send_speed(speed)`
+ * This function is called every time the player's speed is sent to server
+ * The `speed` argument is the actual speed of the player
+ * If you define it, you can return a modified `speed`. This speed will be
+ sent to server instead.
+* `minetest.open_enderchest()`
+ * This function is called if the client uses the Keybind for it (by default "O")
+ * You can override it
* `minetest.register_globalstep(function(dtime))`
* Called every client environment step, usually interval of 0.1s
* `minetest.register_on_mods_loaded(function())`
* Adds definition to minetest.registered_chatcommands
* `minetest.unregister_chatcommand(name)`
* Unregisters a chatcommands registered with register_chatcommand.
+* `minetest.register_list_command(command, desc, setting)`
+ * Registers a chatcommand `command` to manage a list that takes the args `del | add | list <param>`
+ * The list is stored comma-seperated in `setting`
+ * `desc` is the description
+ * `add` adds something to the list
+ * `del` del removes something from the list
+ * `list` lists all items on the list
+* `minetest.register_on_chatcommand(function(command, params))`
+ * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
+ is checked to see if that the command exists, but after the input is parsed.
+ * 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 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, ...)`
* 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.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 max available level for leveled node
### Player
-* `minetest.get_wielded_item()`
- * Returns the itemstack the local player is holding
+* `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.
* 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.send_respawn()`
* Sends a respawn request to the server.
+### HTTP Requests
+
+* `minetest.request_http_api()`:
+ * returns `HTTPApiTable` containing http functions if the calling mod has
+ been granted access by being listed in the `secure.http_mods` or
+ `secure.trusted_mods` setting, otherwise returns `nil`.
+ * The returned table contains the functions `fetch`, `fetch_async` and
+ `fetch_async_get` described below.
+ * Only works at init time and must be called from the mod's main scope
+ (not from a function).
+ * Function only exists if minetest server was built with cURL support.
+ * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
+ A LOCAL VARIABLE!**
+* `HTTPApiTable.fetch(HTTPRequest req, callback)`
+ * Performs given request asynchronously and calls callback upon completion
+ * callback: `function(HTTPRequestResult res)`
+ * Use this HTTP function if you are unsure, the others are for advanced use
+* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
+ * Performs given request asynchronously and returns handle for
+ `HTTPApiTable.fetch_async_get`
+* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
+ * Return response data for given asynchronous HTTP request
+
+### `HTTPRequest` definition
+
+Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
+
+ {
+ url = "http://example.org",
+
+ timeout = 10,
+ -- Timeout for connection in seconds. Default is 3 seconds.
+
+ post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
+ -- Optional, if specified a POST request with post_data is performed.
+ -- Accepts both a string and a table. If a table is specified, encodes
+ -- table as x-www-form-urlencoded key-value pairs.
+ -- If post_data is not specified, a GET request is performed instead.
+
+ user_agent = "ExampleUserAgent",
+ -- Optional, if specified replaces the default minetest user agent with
+ -- given string
+
+ extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
+ -- Optional, if specified adds additional headers to the HTTP request.
+ -- You must make sure that the header strings follow HTTP specification
+ -- ("Key: Value").
+
+ multipart = boolean
+ -- Optional, if true performs a multipart HTTP request.
+ -- Default is false.
+ }
+
+### `HTTPRequestResult` definition
+
+Passed to `HTTPApiTable.fetch` callback. Returned by
+`HTTPApiTable.fetch_async_get`.
+
+ {
+ completed = true,
+ -- If true, the request has finished (either succeeded, failed or timed
+ -- out)
+
+ succeeded = true,
+ -- If true, the request was successful
+
+ timeout = false,
+ -- If true, the request timed out
+
+ code = 200,
+ -- HTTP status code
+
+ data = "response"
+ }
+
### Storage API
* `minetest.get_mod_storage()`:
* returns reference to mod private `StorageRef`
* `minetest.delete_particlespawner(id)`
* Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
-### Misc.
+### Misc
+* `minetest.set_keypress(key, value)`
+ * Act as if a key was pressed (value = true) / released (value = false)
+ * The key must be an keymap_* setting
+ * e.g. minetest.set_keypress("jump", true) will cause te player to jump until minetest.set_keypress("jump", false) is called or the player presses & releases the space bar himself
+* `minetest.get_inventory(location)`
+ * Returns the inventory at location
+* `minetest.find_item(item)`
+ * finds and an item in the inventory
+ * returns index on success or nil if item is not found
+* `minetest.switch_to_item(item)`
+ * `item` is an Itemstring
+ * searches to item in inventory, sets the wield index to it if found
+ * returns true on success, false if item was not found
+* `minetest.register_cheat(name, category, setting | function)`
+ * Register an entry for the cheat menu
+ * If the Category is nonexistant, it will be created
+ * If the 3rd argument is a string it will be interpreted as a setting and toggled
+ when the player selects the entry in the cheat menu
+ * If the 3rd argument is a function it will be called
+ when the player selects the entry in the cheat menu
* `minetest.parse_json(string[, nullvalue])`: returns something
* Convert a string containing JSON data into the Lua equivalent
* `nullvalue`: returned in place of the JSON null; defaults to `nil`
* 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
* 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 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.
* `get_camera_mode()`
* Returns 0, 1, or 2 as described above
* `get_fov()`
- * Returns:
+ * Returns a table with X, Y, maximum and actual FOV in degrees:
```lua
{
### 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 is in a liquid (This oscillates so that the player jumps a bit above the surface)
* `is_in_liquid_stable()`
* returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
-* `get_liquid_viscosity()`
- * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
+* `get_move_resistance()`
+ * returns move resistance of current node, the higher the slower the player moves
* `is_climbing()`
* returns true if player is climbing
* `swimming_vertical()`
jump = float,
gravity = float,
sneak = boolean,
- sneak_glitch = 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 look horizontal angle
* `get_last_look_vertical()`:
* returns last look vertical angle
-* `get_key_pressed()`:
- * returns last key typed by the player
+* `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)
* 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`.
* `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
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_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
},
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*
}
```
-- ^ 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
}
```
`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
Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
-To specify the value of the alpha channel, append `#AA` to the end of the color name
-(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
-value must (always) be two hexadecimal digits.
+To specify the value of the alpha channel, append `#A` or `#AA` to the end of
+the color name (e.g. `colorname#08`).
`Color`
-------------
* `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.
+* `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`)
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