* `disallowed_mapgen_settings= <comma-separated mapgen settings>`
e.g. `disallowed_mapgen_settings = mgv5_spflags`
These mapgen settings are hidden for this game in the world creation
- dialog and game start menu.
+ dialog and game start menu. Add `seed` to hide the seed input field.
* `disabled_settings = <comma-separated settings>`
e.g. `disabled_settings = enable_damage, creative_mode`
These settings are hidden for this game in the "Start game" tab
images named like `$identifier.$n.png`, with an ascending number $n starting
with 1, and a random image will be chosen from the provided ones.
+Menu music
+-----------
+Games can provide custom main menu music. They are put inside a `menu`
+directory inside the game directory.
+The music files are named `theme.ogg`.
+If you want to specify multiple music files for one game, add additional
+images named like `theme.$n.ogg`, with an ascending number $n starting
+with 1 (max 10), and a random music file will be chosen from the provided ones.
Mods
====
color, meaning white surfaces get a lot of your new color while black parts
don't change very much.
+#### `[png:<base64>`
+
+Embed a base64 encoded PNG image in the texture string.
+You can produce a valid string for this by calling
+`minetest.encode_base64(minetest.encode_png(tex))`,
+refer to the documentation of these functions for details.
+You can use this to send disposable images such as captchas
+to individual clients, or render things that would be too
+expensive to compose with `[combine:`.
+
+IMPORTANT: Avoid sending large images this way.
+This is not a replacement for asset files, do not use it to do anything
+that you could instead achieve by just using a file.
+In particular consider `minetest.dynamic_add_media` and test whether
+using other texture modifiers could result in a shorter string than
+embedding a whole image, this may vary by use case.
+
Hardware coloring
-----------------
`param1` is reserved for the engine when `paramtype != "none"`.
* `paramtype = "light"`
- * The value stores light with and without sun in its upper and lower 4 bits
+ * The value stores light with and without sun in its lower and upper 4 bits
respectively.
* Required by a light source node to enable spreading its light.
* Required by the following drawtypes as they determine their visual
Representations of simple things
================================
-Position/vector
----------------
-
- {x=num, y=num, z=num}
+Vector (ie. a position)
+-----------------------
- Note: it is highly recommended to construct a vector using the helper function:
- vector.new(num, num, num)
+ vector.new(x, y, z)
-For helper functions see [Spatial Vectors].
+See [Spatial Vectors] for details.
`pointed_thing`
---------------
from 1).
* `pointed_thing.intersection_normal`: Unit vector, points outwards of the
selected selection box. This specifies which face is pointed at.
- Is a null vector `{x = 0, y = 0, z = 0}` when the pointer is inside the
- selection box.
+ Is a null vector `vector.zero()` when the pointer is inside the selection box.
Examples:
-* `'default:apple'`: 1 apple
-* `'default:dirt 5'`: 5 dirt
-* `'default:pick_stone'`: a new stone pickaxe
-* `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out
+* `"default:apple"`: 1 apple
+* `"default:dirt 5"`: 5 dirt
+* `"default:pick_stone"`: a new stone pickaxe
+* `"default:pick_wood 1 21323"`: a wooden pickaxe, ca. 1/3 worn out
### Table format
An example: Make meat soup from any meat, any water and any bowl:
{
- output = 'food:meat_soup_raw',
+ output = "food:meat_soup_raw",
recipe = {
- {'group:meat'},
- {'group:water'},
- {'group:bowl'},
+ {"group:meat"},
+ {"group:water"},
+ {"group:bowl"},
},
- -- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
+ -- preserve = {"group:bowl"}, -- Not implemented yet (TODO)
}
Another example: Make red wool from white wool and red dye:
{
- type = 'shapeless',
- output = 'wool:red',
- recipe = {'wool:white', 'group:dye,basecolor_red'},
+ type = "shapeless",
+ output = "wool:red",
+ recipe = {"wool:white", "group:dye,basecolor_red"},
}
Special groups
- (14) -- constant tolerance
Negative damage values are discarded as no damage.
* `falling_node`: if there is no walkable block under the node it will fall
-* `float`: the node will not fall through liquids
+* `float`: the node will not fall through liquids (`liquidtype ~= "none"`)
* `level`: Can be used to give an additional sense of progression in the game.
* A larger level will cause e.g. a weapon of a lower level make much less
damage, and get worn out much faster, or not be able to get drops
### Uses (tools only)
Determines how many uses the tool has when it is used for digging a node,
-of this group, of the maximum level. For lower leveled nodes, the use count
-is multiplied by `3^leveldiff`.
+of this group, of the maximum level. The maximum supported number of
+uses is 65535. The special number 0 is used for infinite uses.
+For lower leveled nodes, the use count is multiplied by `3^leveldiff`.
`leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the
node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
* `color`: A `ColorString`, which sets the stack's color.
* `palette_index`: If the item has a palette, this is used to get the
current color from the palette.
+* `count_meta`: Replace the displayed count with any string.
+* `count_alignment`: Set the alignment of the displayed count value. This is an
+ int value. The lowest 2 bits specify the alignment in x-direction, the 3rd and
+ 4th bit specify the alignment in y-direction:
+ 0 = default, 1 = left / up, 2 = middle, 3 = right / down
+ The default currently is the same as right/down.
+ Example: 6 = 2 + 1*4 = middle,up
Example:
meta:set_string("key", "value")
print(dump(meta:to_table()))
+Example manipulations of "description" and expected output behaviors:
+
+ print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe
+ print(ItemStack("foobar"):get_description()) --> Unknown Item
+
+ local stack = ItemStack("default:stone")
+ stack:get_meta():set_string("description", "Custom description\nAnother line")
+ print(stack:get_description()) --> Custom description\nAnother line
+ print(stack:get_short_description()) --> Custom description
+
+ stack:get_meta():set_string("short_description", "Short")
+ print(stack:get_description()) --> Custom description\nAnother line
+ print(stack:get_short_description()) --> Short
+
+ print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc
Version History
---------------
-* FORMSPEC VERSION 1:
+* Formspec version 1 (pre-5.1.0):
* (too much)
-* FORMSPEC VERSION 2:
+* Formspec version 2 (5.1.0):
* Forced real coordinates
* background9[]: 9-slice scaling parameters
-* FORMSPEC VERSION 3:
+* Formspec version 3 (5.2.0):
* Formspec elements are drawn in the order of definition
* bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor)
* box[] and image[] elements enable clipping by default
* new element: scroll_container[]
-* FORMSPEC VERSION 4:
+* Formspec version 4 (5.4.0):
* Allow dropdown indexing events
+* Formspec version 5 (5.5.0):
+ * Added padding[] element
Elements
--------
* `position` and `anchor` elements need suitable values to avoid a formspec
extending off the game window due to particular game window sizes.
-### `no_prepend[]`
+### `padding[<X>,<Y>]`
* Must be used after the `size`, `position`, and `anchor` elements (if present).
+* Defines how much space is padded around the formspec if the formspec tries to
+ increase past the size of the screen and coordinates have to be shrunk.
+* For X and Y, 0.0 represents no padding (the formspec can touch the edge of the
+ screen), and 0.5 represents half the screen (which forces the coordinate size
+ to 0). If negative, the formspec can extend off the edge of the screen.
+* Defaults to [0.05, 0.05].
+
+### `no_prepend[]`
+
+* Must be used after the `size`, `position`, `anchor`, and `padding` elements
+ (if present).
* Disables player:set_formspec_prepend() from applying to this formspec.
### `real_coordinates[<bool>]`
* End of a scroll_container, following elements are no longer bound to this
container.
-### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
+### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
-* Show an inventory list if it has been sent to the client. Nothing will
- be shown if the inventory list is of size 0.
+* Show an inventory list if it has been sent to the client.
+* If the inventory list changes (eg. it didn't exist before, it's resized, or its items
+ are moved) while the formspec is open, the formspec element may (but is not guaranteed
+ to) adapt to the new inventory list.
+* Item slots are drawn in a grid from left to right, then up to down, ordered
+ according to the slot index.
+* `W` and `H` are in inventory slots, not in coordinates.
+* `starting item index` (Optional): The index of the first (upper-left) item to draw.
+ Indices start at `0`. Default is `0`.
+* The number of shown slots is the minimum of `W*H` and the inventory list's size minus
+ `starting item index`.
* **Note**: With the new coordinate system, the spacing between inventory
slots is one-fourth the size of an inventory slot by default. Also see
[Styling Formspecs] for changing the size of slots and spacing.
-### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
-
-* Show an inventory list if it has been sent to the client. Nothing will
- be shown if the inventory list is of size 0.
-* **Note**: With the new coordinate system, the spacing between inventory
- slots is one-fourth the size of an inventory slot.
-
### `listring[<inventory location>;<list name>]`
* Allows to create a ring of inventory lists
`#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).
+[CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-color).
To specify the value of the alpha channel, append `#A` or `#AA` to the end of
the color name (e.g. `colorname#08`).
Spatial Vectors
===============
-A spatial vector is similar to a position, but instead using
-absolute world coordinates, it uses *relative* coordinates, relative to
-no particular point.
-
-Internally, it is implemented as a table with the 3 fields
-`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`.
-However, one should *never* create a vector manually as above, such misbehavior
-is deprecated. The vector helpers set a metatable for the created vectors which
-allows indexing with numbers, calling functions directly on vectors and using
-operators (like `+`). Furthermore, the internal implementation might change in
+
+Minetest stores 3-dimensional spatial vectors in Lua as tables of 3 coordinates,
+and has a class to represent them (`vector.*`), which this chapter is about.
+For details on what a spatial vectors is, please refer to Wikipedia:
+https://en.wikipedia.org/wiki/Euclidean_vector.
+
+Spatial vectors are used for various things, including, but not limited to:
+
+* any 3D spatial vector (x/y/z-directions)
+* Euler angles (pitch/yaw/roll in radians) (Spatial vectors have no real semantic
+ meaning here. Therefore, most vector operations make no sense in this use case.)
+
+Note that they are *not* used for:
+
+* n-dimensional vectors where n is not 3 (ie. n=2)
+* arrays of the form `{num, num, num}`
+
+The API documentation may refer to spatial vectors, as produced by `vector.new`,
+by any of the following notations:
+
+* `(x, y, z)` (Used rarely, and only if it's clear that it's a vector.)
+* `vector.new(x, y, z)`
+* `{x=num, y=num, z=num}` (Even here you are still supposed to use `vector.new`.)
+
+Compatibility notes
+-------------------
+
+Vectors used to be defined as tables of the form `{x = num, y = num, z = num}`.
+Since Minetest 5.5.0, vectors additionally have a metatable to enable easier use.
+Note: Those old-style vectors can still be found in old mod code. Hence, mod and
+engine APIs still need to be able to cope with them in many places.
+
+Manually constructed tables are deprecated and highly discouraged. This interface
+should be used to ensure seamless compatibility between mods and the Minetest API.
+This is especially important to callback function parameters and functions overwritten
+by mods.
+Also, though not likely, the internal implementation of a vector might change in
the future.
-Old code might still use vectors without metatables, be aware of this!
+In your own code, or if you define your own API, you can, of course, still use
+other representations of vectors.
+
+Vectors provided by API functions will provide an instance of this class if not
+stated otherwise. Mods should adapt this for convenience reasons.
+
+Special properties of the class
+-------------------------------
+
+Vectors can be indexed with numbers and allow method and operator syntax.
All these forms of addressing a vector `v` are valid:
`v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13`
+Note: Prefer letter over number indexing for performance and compatibility reasons.
Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does
the same as `vector.foo(v, ...)`, apart from deprecated functionality.
+`tostring` is defined for vectors, see `vector.to_string`.
+
The metatable that is used for vectors can be accessed via `vector.metatable`.
Do not modify it!
All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables.
Returned vectors always have a metatable set.
-For the following functions, `v`, `v1`, `v2` are vectors,
-`p1`, `p2` are positions,
+Common functions and methods
+----------------------------
+
+For the following functions (and subchapters),
+`v`, `v1`, `v2` are vectors,
+`p1`, `p2` are position vectors,
`s` is a scalar (a number),
vectors are written like this: `(x, y, z)`:
* `init`: If given starts looking for the vector at this string index.
* `vector.to_string(v)`:
* Returns a string of the form `"(x, y, z)"`.
+ * `tostring(v)` does the same.
* `vector.direction(p1, p2)`:
* Returns a vector of length 1 with direction `p1` to `p2`.
* If `p1` and `p2` are identical, returns `(0, 0, 0)`.
* `vector.apply(v, func)`:
* Returns a vector where the function `func` has been applied to each
component.
+* `vector.combine(v, w, func)`:
+ * Returns a vector where the function `func` has combined both components of `v` and `w`
+ for each component
* `vector.equals(v1, v2)`:
* Returns a boolean, `true` if the vectors are identical.
* `vector.sort(v1, v2)`:
* Returns the cross product of `v1` and `v2`.
* `vector.offset(v, x, y, z)`:
* Returns the sum of the vectors `v` and `(x, y, z)`.
-* `vector.check()`:
+* `vector.check(v)`:
* Returns a boolean value indicating whether `v` is a real vector, eg. created
by a `vector.*` function.
* Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`.
* Returns a scaled vector.
* Deprecated: If `s` is a vector: Returns the Schur quotient.
+Operators
+---------
+
Operators can be used if all of the involved vectors have metatables:
* `v1 == v2`:
* Returns whether `v1` and `v2` are identical.
* `v / s`:
* Returns `v` scaled by `1 / s`.
+Rotation-related functions
+--------------------------
+
For the following functions `a` is an angle in radians and `r` is a rotation
-vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are
+vector (`{x = <pitch>, y = <yaw>, z = <roll>}`) where pitch, yaw and roll are
angles in radians.
* `vector.rotate(v, r)`:
* If `up` is omitted, the roll of the returned vector defaults to zero.
* Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other.
+Further helpers
+---------------
+
+There are more helper functions involving vectors, but they are listed elsewhere
+because they only work on specific sorts of vectors or involve things that are not
+vectors.
+
+For example:
+
+* `minetest.hash_node_position` (Only works on node positions.)
+* `minetest.dir_to_wallmounted` (Involves wallmounted param2 values.)
+
* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
position.
* returns the exact position on the surface of a pointed node
-* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates an item
- that digs a node.
+* `minetest.get_dig_params(groups, tool_capabilities [, wear])`:
+ Simulates an item that digs a node.
Returns a table with the following fields:
* `diggable`: `true` if node can be dug, `false` otherwise.
* `time`: Time it would take to dig the node.
Parameters:
* `groups`: Table of the node groups of the node that would be dug
* `tool_capabilities`: Tool capabilities table of the item
-* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`:
+ * `wear`: Amount of wear the tool starts with (default: 0)
+* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch [, wear]])`:
Simulates an item that punches an object.
Returns a table with the following fields:
- * `hp`: How much damage the punch would cause.
+ * `hp`: How much damage the punch would cause (between -65535 and 65535).
* `wear`: How much wear would be added to the tool (ignored for non-tools).
Parameters:
* `groups`: Damage groups of the object
* `tool_capabilities`: Tool capabilities table of the item
* `time_from_last_punch`: time in seconds since last punch action
+ * `wear`: Amount of wear the item starts with (default: 0)
### Other API functions operating on a VoxelManip
-If any VoxelManip contents were set to a liquid node,
+If any VoxelManip contents were set to a liquid node (`liquidtype ~= "none"`),
`VoxelManip:update_liquids()` must be called for these liquid nodes to begin
flowing. It is recommended to call this function only after having written all
buffered data back to the VoxelManip object, save for special situations where
abm_min_max_y = true,
-- dynamic_add_media supports passing a table with options (5.5.0)
dynamic_add_media_table = true,
+ -- allows get_sky to return a table instead of separate values (5.6.0)
+ get_sky_as_table = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
* `minetest.mkdir(path)`: returns success.
* Creates a directory specified by `path`, creating parent directories
if they don't exist.
+* `minetest.rmdir(path, recursive)`: returns success.
+ * Removes a directory specified by `path`.
+ * If `recursive` is set to `true`, the directory is recursively removed.
+ Otherwise, the directory will only be removed if it is empty.
+ * Returns true on success, false on failure.
+* `minetest.cpdir(source, destination)`: returns success.
+ * Copies a directory specified by `path` to `destination`
+ * Any files in `destination` will be overwritten if they already exist.
+ * Returns true on success, false on failure.
+* `minetest.mvdir(source, destination)`: returns success.
+ * Moves a directory specified by `path` to `destination`.
+ * If the `destination` is a non-empty directory, then the move will fail.
+ * Returns true on success, false on failure.
* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names
* is_dir is one of:
* nil: return all entries,
* You should have joined some channels to receive events.
* If message comes from a server mod, `sender` field is an empty string.
* `minetest.register_on_liquid_transformed(function(pos_list, node_list))`
- * Called after liquid nodes are modified by the engine's liquid transformation
- process.
+ * Called after liquid nodes (`liquidtype ~= "none"`) are modified by the
+ engine's liquid transformation process.
* `pos_list` is an array of all modified positions.
* `node_list` is an array of the old node that was previously at the position
with the corresponding index in pos_list.
* `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`.
+ * `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be
+ returned. Default is `false`.
* `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
* `minetest.spawn_tree (pos, {treedef})`
* spawns L-system tree at given `pos` with definition in `treedef` table
* `minetest.transforming_liquid_add(pos)`
- * add node to liquid update queue
+ * add node to liquid flow update queue
* `minetest.get_node_max_level(pos)`
* get max available level for leveled node
* `minetest.get_node_level(pos)`
* `minetest.remove_detached_inventory(name)`
* Returns a `boolean` indicating whether the removal succeeded.
* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
- returns left over ItemStack.
+ returns leftover ItemStack or nil to indicate no inventory change
* See `minetest.item_eat` and `minetest.register_on_item_eat`
Formspec
* `job:cancel()`
* Cancels the job function from being called
+Async environment
+-----------------
+
+The engine allows you to submit jobs to be ran in an isolated environment
+concurrently with normal server operation.
+A job consists of a function to be ran in the async environment, any amount of
+arguments (will be serialized) and a callback that will be called with the return
+value of the job function once it is finished.
+
+The async environment does *not* have access to the map, entities, players or any
+globals defined in the 'usual' environment. Consequently, functions like
+`minetest.get_node()` or `minetest.get_player_by_name()` simply do not exist in it.
+
+Arguments and return values passed through this can contain certain userdata
+objects that will be seamlessly copied (not shared) to the async environment.
+This allows you easy interoperability for delegating work to jobs.
+
+* `minetest.handle_async(func, callback, ...)`:
+ * Queue the function `func` to be ran in an async environment.
+ Note that there are multiple persistent workers and any of them may
+ end up running a given job. The engine will scale the amount of
+ worker threads automatically.
+ * When `func` returns the callback is called (in the normal environment)
+ with all of the return values as arguments.
+ * Optional: Variable number of arguments that are passed to `func`
+* `minetest.register_async_dofile(path)`:
+ * Register a path to a Lua file to be imported when an async environment
+ is initialized. You can use this to preload code which you can then call
+ later using `minetest.handle_async()`.
+
+### List of APIs available in an async environment
+
+Classes:
+* `ItemStack`
+* `PerlinNoise`
+* `PerlinNoiseMap`
+* `PseudoRandom`
+* `PcgRandom`
+* `SecureRandom`
+* `VoxelArea`
+* `VoxelManip`
+ * only if transferred into environment; can't read/write to map
+* `Settings`
+
+Class instances that can be transferred between environments:
+* `ItemStack`
+* `PerlinNoise`
+* `PerlinNoiseMap`
+* `VoxelManip`
+
+Functions:
+* Standalone helpers such as logging, filesystem, encoding,
+ hashing or compression APIs
+* `minetest.request_insecure_environment` (same restrictions apply)
+
+Variables:
+* `minetest.settings`
+* `minetest.registered_items`, `registered_nodes`, `registered_tools`,
+ `registered_craftitems` and `registered_aliases`
+ * with all functions and userdata values replaced by `true`, calling any
+ callbacks here is obviously not possible
+
Server
------
a player joined.
* This function may be overwritten by mods to customize the status message.
* `minetest.get_server_uptime()`: returns the server uptime in seconds
+* `minetest.get_server_max_lag()`: returns the current maximum lag
+ of the server in seconds or nil if server is not fully loaded yet
* `minetest.remove_player(name)`: remove player from database (if they are not
connected).
* As auth data is not removed, minetest.player_exists will continue to
* `minetest.kick_player(name, [reason])`: disconnect a player with an optional
reason.
* Returns boolean indicating success (false if player nonexistant)
+* `minetest.disconnect_player(name, [reason])`: disconnect a player with an
+ optional reason, this will not prefix with 'Kicked: ' like kick_player.
+ If no reason is given, it will default to 'Disconnected.'
+ * Returns boolean indicating success (false if player nonexistant)
Particles
---------
This is due to the fact that JSON has two distinct array and object
values.
* Example: `write_json({10, {a = false}})`,
- returns `"[10, {\"a\": false}]"`
+ returns `'[10, {"a": false}]'`
* `minetest.serialize(table)`: returns a string
* Convert a table containing tables, strings, numbers, booleans and `nil`s
into string form readable by `minetest.deserialize`
- * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
+ * Example: `serialize({foo="bar"})`, returns `'return { ["foo"] = "bar" }'`
* `minetest.deserialize(string[, safe])`: returns a table
* Convert a string returned by `minetest.serialize` into a table
* `string` is loaded in an empty sandbox environment.
value of `safe`. It is fine to serialize then deserialize user-provided
data, but directly providing user input to deserialize is always unsafe.
* Example: `deserialize('return { ["foo"] = "bar" }')`,
- returns `{foo='bar'}`
+ returns `{foo="bar"}`
* Example: `deserialize('print("foo")')`, returns `nil`
(function call fails), returns
`error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
`AreaStore`
-----------
-A fast access data structure to store areas, and find areas near a given
-position or area.
-Every area has a `data` string attribute to store additional information.
-You can create an empty `AreaStore` by calling `AreaStore()`, or
-`AreaStore(type_name)`. The mod decides where to save and load AreaStore.
-If you chose the parameter-less constructor, a fast implementation will be
-automatically chosen for you.
+AreaStore is a data structure to calculate intersections of 3D cuboid volumes
+and points. The `data` field (string) may be used to store and retrieve any
+mod-relevant information to the specified area.
+
+Despite its name, mods must take care of persisting AreaStore data. They may
+use the provided load and write functions for this.
+
### Methods
-* `get_area(id, include_borders, include_data)`
+* `AreaStore(type_name)`
+ * Returns a new AreaStore instance
+ * `type_name`: optional, forces the internally used API.
+ * Possible values: `"LibSpatial"` (default).
+ * When other values are specified, or SpatialIndex is not available,
+ the custom Minetest functions are used.
+* `get_area(id, include_corners, include_data)`
* Returns the area information about the specified ID.
* Returned values are either of these:
nil -- Area not found
- true -- Without `include_borders` and `include_data`
+ true -- Without `include_corners` and `include_data`
{
- min = pos, max = pos -- `include_borders == true`
+ min = pos, max = pos -- `include_corners == true`
data = string -- `include_data == true`
}
-* `get_areas_for_pos(pos, include_borders, include_data)`
+* `get_areas_for_pos(pos, include_corners, include_data)`
* Returns all areas as table, indexed by the area ID.
* Table values: see `get_area`.
-* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`
- * Returns all areas that contain all nodes inside the area specified by `edge1`
- and `edge2` (inclusive).
+* `get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data)`
+ * Returns all areas that contain all nodes inside the area specified by`
+ `corner1 and `corner2` (inclusive).
* `accept_overlap`: if `true`, areas are returned that have nodes in
common (intersect) with the specified area.
* Returns the same values as `get_areas_for_pos`.
-* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store.
+* `insert_area(corner1, corner2, data, [id])`: inserts an area into the store.
* Returns the new area's ID, or nil if the insertion failed.
- * The (inclusive) positions `edge1` and `edge2` describe the area.
+ * The (inclusive) positions `corner1` and `corner2` describe the area.
* `data` is a string stored with the area.
* `id` (optional): will be used as the internal area ID if it is an unique
number between 0 and 2^32-2.
-* `reserve(count)`: reserves resources for at most `count` many contained
- areas.
- Only needed for efficiency, and only some implementations profit.
+* `reserve(count)`
+ * Requires SpatialIndex, no-op function otherwise.
+ * Reserves resources for `count` many contained areas to improve
+ efficiency when working with many area entries. Additional areas can still
+ be inserted afterwards at the usual complexity.
* `remove_area(id)`: removes the area with the given id from the store, returns
success.
* `set_cache_params(params)`: sets params for the included prefiltering cache.
* `set_width(listname, width)`: set width of list; currently used for crafting
* `get_stack(listname, i)`: get a copy of stack index `i` in list
* `set_stack(listname, i, stack)`: copy `stack` to index `i` in list
-* `get_list(listname)`: return full list
+* `get_list(listname)`: return full list (list of `ItemStack`s)
* `set_list(listname, list)`: set full list (size will not change)
-* `get_lists()`: returns list of inventory lists
+* `get_lists()`: returns table that maps listnames to inventory lists
* `set_lists(lists)`: sets inventory lists (size will not change)
* `add_item(listname, stack)`: add item somewhere in list, returns leftover
`ItemStack`.
* Fourth column: subject looking to the right
* Fifth column: subject viewed from above
* Sixth column: subject viewed from below
-* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
+* `get_entity_name()` (**Deprecated**: Will be removed in a future version, use the field `self.name` instead)
* `get_luaentity()`
#### Player only (no-op for other objects)
* `set_inventory_formspec(formspec)`
* Redefine player's inventory form
* Should usually be called in `on_joinplayer`
+ * If `formspec` is `""`, the player's inventory is disabled.
* `get_inventory_formspec()`: returns a formspec string
* `set_formspec_prepend(formspec)`:
* the formspec string will be added to every formspec shown to the user,
`aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`.
* The fields `LMB` and `RMB` are equal to `dig` and `place` respectively,
and exist only to preserve backwards compatibility.
+ * Returns an empty table `{}` if the object is not a player.
* `get_player_control_bits()`: returns integer with bit packed player pressed
- keys. Bits:
- * 0 - up
- * 1 - down
- * 2 - left
- * 3 - right
- * 4 - jump
- * 5 - aux1
- * 6 - sneak
- * 7 - dig
- * 8 - place
- * 9 - zoom
+ keys.
+ * Bits:
+ * 0 - up
+ * 1 - down
+ * 2 - left
+ * 3 - right
+ * 4 - jump
+ * 5 - aux1
+ * 6 - sneak
+ * 7 - dig
+ * 8 - place
+ * 9 - zoom
+ * Returns `0` (no bits set) if the object is not a player.
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
* `hud_get(id)`: gets the HUD element definition structure of the specified ID
* `hud_set_flags(flags)`: sets specified HUD flags of player.
* `flags`: A table with the following fields set to boolean values
- * hotbar
- * healthbar
- * crosshair
- * wielditem
- * breathbar
- * minimap
- * minimap_radar
+ * `hotbar`
+ * `healthbar`
+ * `crosshair`
+ * `wielditem`
+ * `breathbar`
+ * `minimap`: Modifies the client's permission to view the minimap.
+ The client may locally elect to not view the minimap.
+ * `minimap_radar`: is only usable when `minimap` is true
+ * `basic_debug`: Allow showing basic debug info that might give a gameplay advantage.
+ This includes map seed, player position, look direction, the pointed node and block bounds.
+ Does not affect players with the `debug` privilege.
* If a flag equals `nil`, the flag is not modified
- * `minimap`: Modifies the client's permission to view the minimap.
- The client may locally elect to not view the minimap.
- * `minimap_radar` is only usable when `minimap` is true
* `hud_get_flags()`: returns a table of player HUD flags with boolean values.
* See `hud_set_flags` for a list of flags that can be toggled.
* `hud_set_hotbar_itemcount(count)`: sets number of items in builtin hotbar
* `set_sky(sky_parameters)`
* The presence of the function `set_sun`, `set_moon` or `set_stars` indicates
whether `set_sky` accepts this format. Check the legacy format otherwise.
+ * Passing no arguments resets the sky to its default values.
* `sky_parameters` is a table with the following optional fields:
* `base_color`: ColorSpec, changes fog in "skybox" and "plain".
+ (default: `#ffffff`)
* `type`: Available types:
* `"regular"`: Uses 0 textures, `base_color` ignored
* `"skybox"`: Uses 6 textures, `base_color` used as fog.
* `"plain"`: Uses 0 textures, `base_color` used as both fog and sky.
+ (default: `"regular"`)
* `textures`: A table containing up to six textures in the following
order: Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south).
* `clouds`: Boolean for whether clouds appear. (default: `true`)
- * `sky_color`: A table containing the following values, alpha is ignored:
- * `day_sky`: ColorSpec, for the top half of the `"regular"`
- sky during the day. (default: `#61b5f5`)
- * `day_horizon`: ColorSpec, for the bottom half of the
- `"regular"` sky during the day. (default: `#90d3f6`)
- * `dawn_sky`: ColorSpec, for the top half of the `"regular"`
- sky during dawn/sunset. (default: `#b4bafa`)
+ * `sky_color`: A table used in `"regular"` type only, containing the
+ following values (alpha is ignored):
+ * `day_sky`: ColorSpec, for the top half of the sky during the day.
+ (default: `#61b5f5`)
+ * `day_horizon`: ColorSpec, for the bottom half of the sky during the day.
+ (default: `#90d3f6`)
+ * `dawn_sky`: ColorSpec, for the top half of the sky during dawn/sunset.
+ (default: `#b4bafa`)
The resulting sky color will be a darkened version of the ColorSpec.
Warning: The darkening of the ColorSpec is subject to change.
- * `dawn_horizon`: ColorSpec, for the bottom half of the `"regular"`
- sky during dawn/sunset. (default: `#bac1f0`)
+ * `dawn_horizon`: ColorSpec, for the bottom half of the sky during dawn/sunset.
+ (default: `#bac1f0`)
The resulting sky color will be a darkened version of the ColorSpec.
Warning: The darkening of the ColorSpec is subject to change.
- * `night_sky`: ColorSpec, for the top half of the `"regular"`
- sky during the night. (default: `#006bff`)
+ * `night_sky`: ColorSpec, for the top half of the sky during the night.
+ (default: `#006bff`)
The resulting sky color will be a dark version of the ColorSpec.
Warning: The darkening of the ColorSpec is subject to change.
- * `night_horizon`: ColorSpec, for the bottom half of the `"regular"`
- sky during the night. (default: `#4090ff`)
+ * `night_horizon`: ColorSpec, for the bottom half of the sky during the night.
+ (default: `#4090ff`)
The resulting sky color will be a dark version of the ColorSpec.
Warning: The darkening of the ColorSpec is subject to change.
- * `indoors`: ColorSpec, for when you're either indoors or
- underground. Only applies to the `"regular"` sky.
+ * `indoors`: ColorSpec, for when you're either indoors or underground.
(default: `#646464`)
* `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun
- at sunrise and sunset.
+ at sunrise and sunset. (default: `#f47d1d`)
* `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon
- at sunrise and sunset.
+ at sunrise and sunset. (default: `#7f99cc`)
* `fog_tint_type`: string, changes which mode the directional fog
abides by, `"custom"` uses `sun_tint` and `moon_tint`, while
`"default"` uses the classic Minetest sun and moon tinting.
* `"plain"`: Uses 0 textures, `bgcolor` used
* `clouds`: Boolean for whether clouds appear in front of `"skybox"` or
`"plain"` custom skyboxes (default: `true`)
-* `get_sky()`: returns base_color, type, table of textures, clouds.
-* `get_sky_color()`: returns a table with the `sky_color` parameters as in
- `set_sky`.
+* `get_sky(as_table)`:
+ * `as_table`: boolean that determines whether the deprecated version of this
+ function is being used.
+ * `true` returns a table containing sky parameters as defined in `set_sky(sky_parameters)`.
+ * Deprecated: `false` or `nil` returns base_color, type, table of textures,
+ clouds.
+* `get_sky_color()`:
+ * Deprecated: Use `get_sky(as_table)` instead.
+ * returns a table with the `sky_color` parameters as in `set_sky`.
* `set_sun(sun_parameters)`:
+ * Passing no arguments resets the sun to its default values.
* `sun_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the sun is visible.
(default: `true`)
* `texture`: A regular texture for the sun. Setting to `""`
- will re-enable the mesh sun. (default: `"sun.png"`)
+ will re-enable the mesh sun. (default: "sun.png", if it exists)
* `tonemap`: A 512x1 texture containing the tonemap for the sun
(default: `"sun_tonemap.png"`)
* `sunrise`: A regular texture for the sunrise texture.
* `get_sun()`: returns a table with the current sun parameters as in
`set_sun`.
* `set_moon(moon_parameters)`:
+ * Passing no arguments resets the moon to its default values.
* `moon_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the moon is visible.
(default: `true`)
* `texture`: A regular texture for the moon. Setting to `""`
- will re-enable the mesh moon. (default: `"moon.png"`)
+ will re-enable the mesh moon. (default: `"moon.png"`, if it exists)
+ Note: Relative to the sun, the moon texture is rotated by 180°.
+ You can use the `^[transformR180` texture modifier to achieve the same orientation.
* `tonemap`: A 512x1 texture containing the tonemap for the moon
(default: `"moon_tonemap.png"`)
* `scale`: Float controlling the overall size of the moon (default: `1`)
* `get_moon()`: returns a table with the current moon parameters as in
`set_moon`.
* `set_stars(star_parameters)`:
+ * Passing no arguments resets stars to their default values.
* `star_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the stars are visible.
(default: `true`)
* `get_stars()`: returns a table with the current stars parameters as in
`set_stars`.
* `set_clouds(cloud_parameters)`: set cloud parameters
+ * Passing no arguments resets clouds to their default values.
* `cloud_parameters` is a table with the following optional fields:
* `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
* `color`: basic cloud color with alpha channel, ColorSpec
* Returns `false` if failed.
* Resource intensive - use sparsely
* To get blockpos, integer divide pos by 16
+* `set_lighting(light_definition)`: sets lighting for the player
+ * `light_definition` is a table with the following optional fields:
+ * `shadows` is a table that controls ambient shadows
+ * `intensity` sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness)
+* `get_lighting()`: returns the current state of lighting for the player.
+ * Result is a table with the same fields as `light_definition` in `set_lighting`.
`PcgRandom`
-----------
* `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.
+* `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be
+ returned. Default is false.
### Methods
-- "sprite" uses 1 texture.
-- "upright_sprite" uses 2 textures: {front, back}.
-- "wielditem" expects 'textures = {itemname}' (see 'visual' above).
+ -- "mesh" requires one texture for each mesh buffer/material (in order)
colors = {},
-- Number of required colors depends on visual
-- for more info) by using a '_' prefix
}
-Collision info passed to `on_step`:
+Collision info passed to `on_step` (`moveresult` argument):
{
touching_ground = boolean,
},
...
}
+ -- `collisions` does not contain data of unloaded mapblock collisions
+ -- or when the velocity changes are negligibly small
}
ABM (ActiveBlockModifier) definition
range = 4.0,
liquids_pointable = false,
+ -- If true, item points to all liquid nodes (`liquidtype ~= "none"`),
+ -- even those for which `pointable = false`
light_source = 0,
-- When used for nodes: Defines amount of light emitted by node.
on_place = function(itemstack, placer, pointed_thing),
-- When the 'place' key was pressed with the item in hand
-- and a node was pointed at.
- -- Shall place item and return the leftover itemstack.
+ -- Shall place item and return the leftover itemstack
+ -- or nil to not modify the inventory.
-- The placer may be any ObjectRef or nil.
-- default: minetest.item_place
on_secondary_use = function(itemstack, user, pointed_thing),
-- Same as on_place but called when not pointing at a node.
+ -- Function must return either nil if inventory shall not be modified,
+ -- or an itemstack to replace the original itemstack.
-- The user may be any ObjectRef or nil.
-- default: nil
on_use = function(itemstack, user, pointed_thing),
-- default: nil
-- When user pressed the 'punch/mine' key with the item in hand.
- -- Function must return either nil if no item shall be removed from
- -- inventory, or an itemstack to replace the original itemstack.
+ -- Function must return either nil if inventory shall not be modified,
+ -- or an itemstack to replace the original itemstack.
-- e.g. itemstack:take_item(); return itemstack
-- Otherwise, the function is free to do what it wants.
-- The user may be any ObjectRef or nil.
climbable = false, -- If true, can be climbed on (ladder)
+ move_resistance = 0,
+ -- Slows down movement of players through this node (max. 7).
+ -- If this is nil, it will be equal to liquid_viscosity.
+ -- Note: If liquid movement physics apply to the node
+ -- (see `liquid_move_physics`), the movement speed will also be
+ -- affected by the `movement_liquid_*` settings.
+
buildable_to = false, -- If true, placed nodes can replace this node
floodable = false,
-- If true, liquids flow into and replace this node.
-- Warning: making a liquid node 'floodable' will cause problems.
- liquidtype = "none", -- specifies liquid physics
- -- * "none": no liquid physics
+ liquidtype = "none", -- specifies liquid flowing physics
+ -- * "none": no liquid flowing physics
-- * "source": spawns flowing liquid nodes at all 4 sides and below;
-- recommended drawtype: "liquid".
-- * "flowing": spawned from source, spawns more flowing liquid nodes
liquid_alternative_source = "", -- Source version of flowing liquid
- liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
+ liquid_viscosity = 0,
+ -- Controls speed at which the liquid spreads/flows (max. 7).
+ -- 0 is fastest, 7 is slowest.
+ -- By default, this also slows down movement of players inside the node
+ -- (can be overridden using `move_resistance`)
liquid_renewable = true,
-- If true, a new liquid source can be created by placing two or more
-- sources nearby
+ liquid_move_physics = nil, -- specifies movement physics if inside node
+ -- * false: No liquid movement physics apply.
+ -- * true: Enables liquid movement physics. Enables things like
+ -- ability to "swim" up/down, sinking slowly if not moving,
+ -- smoother speed change when falling into, etc. The `movement_liquid_*`
+ -- settings apply.
+ -- * nil: Will be treated as true if `liquidype ~= "none"`
+ -- and as false otherwise.
+ -- Default: nil
+
leveled = 0,
-- Only valid for "nodebox" drawtype with 'type = "leveled"'.
-- Allows defining the nodebox height without using param2.
items = {"default:sand", "default:desert_sand"},
},
{
- -- Only drop if using an item in the "magicwand" group, or
+ -- Only drop if using an item in the "magicwand" group, or
-- an item that is in both the "pickaxe" and the "lucky"
-- groups.
tool_groups = {
### Shaped
{
- output = 'default:pick_stone',
+ output = "default:pick_stone",
recipe = {
- {'default:cobble', 'default:cobble', 'default:cobble'},
- {'', 'default:stick', ''},
- {'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly'
+ {"default:cobble", "default:cobble", "default:cobble"},
+ {"", "default:stick", ""},
+ {"", "default:stick", ""}, -- Also groups; e.g. "group:crumbly"
},
replacements = <list of item pairs>,
-- replacements: replace one input item with another item on crafting
{
type = "shapeless",
- output = 'mushrooms:mushroom_stew',
+ output = "mushrooms:mushroom_stew",
recipe = {
"mushrooms:bowl",
"mushrooms:mushroom_brown",
-- Returns an iterator (use with `for` loops) for all player names
-- currently in the auth database
}
+
+Bit Library
+-----------
+
+Functions: bit.tobit, bit.tohex, bit.bnot, bit.band, bit.bor, bit.bxor, bit.lshift, bit.rshift, bit.arshift, bit.rol, bit.ror, bit.bswap
+
+See http://bitop.luajit.org/ for advanced information.
projects / dragonfireclient.git / blobdiff