diff --git a/content/Filesystem.md b/content/Filesystem.md index 0c63c70..d367d4d 100644 --- a/content/Filesystem.md +++ b/content/Filesystem.md @@ -1,7 +1,9 @@ # Filesystem Luanti provides various utility functions to help with managing paths, files & directories. -IMPORTANT: Mod security restricts file system access to the mod path (at load time) and the world path later on in secure environments, see [Lua Environment](/Lua_Environment/). +{{< notice info >}} +Mod security restricts file system access to the mod path (at load time) and the world path later on in secure environments, see [Lua Environment](/Lua_Environment/). +{{< /notice >}} ## Paths diff --git a/content/ItemStackMetaData.md b/content/ItemStackMetaData.md index 338a892..4f5fc38 100644 --- a/content/ItemStackMetaData.md +++ b/content/ItemStackMetaData.md @@ -1,7 +1,9 @@ # ItemStackMetaData ItemStackMetaData is a subclass of [[MetaData]] obtained via `stack:get_meta()` allowing for persistent storage of key-value pairs tied to ItemStacks. -WARNING: ItemStack metadata is serialized with ItemStacks, increasing the ItemString length. Inventories have to store multiple ItemStrings, all of which an attacker will try to get to maximum length. Always limit the size of your ItemStackMetaData to keep inventories sendable. +{{< notice warning >}} +ItemStack metadata is serialized with ItemStacks, increasing the ItemString length. Inventories have to store multiple ItemStrings, all of which an attacker will try to get to maximum length. Always limit the size of your ItemStackMetaData to keep inventories sendable. +{{< /notice >}} ## Special Fields @@ -31,7 +33,9 @@ Alignment of the displayed item count value is encoded as `x_align + 4 * y_align | `2` | Centered/Middle | Centered/Middle | | `3` | Right | Bottom/Down | -TIP: Magic numbers make code unreadable. Add an explanatory comment when setting alignment: +{{< notice tip >}} +Magic numbers make code unreadable. Add an explanatory comment when setting alignment: +{{< /notice >}} ```lua local meta = stack:get_meta() @@ -80,4 +84,6 @@ Allows overriding the tool capabilities specified in the item definition. - `nil`: Clears the tool capability override, or - Tool capabilities table: Overrides the defined tool capabilities (see ItemDefinition for the table format) -NOTE: The corresponding `:get_tool_capabilities` is not a method of ItemStackMetaData but rather of the "parent" ItemStack. +{{< notice note >}} +The corresponding `:get_tool_capabilities` is not a method of ItemStackMetaData but rather of the "parent" ItemStack. +{{< /notice >}} diff --git a/content/Lua_Environment.md b/content/Lua_Environment.md index 181c189..9103d8e 100644 --- a/content/Lua_Environment.md +++ b/content/Lua_Environment.md @@ -38,9 +38,13 @@ set_global() Warnings are identified by their location as returned by `debug.getinfo` (`short_src` and `currentline`) and won't be logged twice. -WARNING: Accessing undeclared global variables will be an order of magnitude slower than accessing declared globals due to the executed strictness checking code. +{{< notice warning >}} +Accessing undeclared global variables will be an order of magnitude slower than accessing declared globals due to the executed strictness checking code. +{{< /notice >}} -TIP: These warnings are only triggered at run time as the global variable access or assignment occurs. It is recommended to use a linter like [`luacheck`](https://github.com/mpeterv/luacheck) to detect mistaken global variable usage statically at the time of development. +{{< notice tip >}} +These warnings are only triggered at run time as the global variable access or assignment occurs. It is recommended to use a linter like [`luacheck`](https://github.com/mpeterv/luacheck) to detect mistaken global variable usage statically at the time of development. +{{< /notice >}} ### Checking for global existence @@ -51,10 +55,14 @@ As Luanti implements global strictness over a metatable, `rawget(_G, name)` can #### `core.global_exists(name)` Returns `true` if a global variable with the given `name` exists (is not `nil`), `false` otherwise. An error is thrown if `name` is not a string. -NOTE: This wraps `rawget(_G, name)` in the end but might be considered more readable as it makes the intention clear. +{{< notice note >}} +This wraps `rawget(_G, name)` in the end but might be considered more readable as it makes the intention clear. +{{< /notice >}} ## Standard Library Extensions -NOTE: It is considered bad practice to extend the standard library yourself, as this may collide with other mods doing the same as well as future engine changes including Lua version upgrades. Put your extensions into distinct API tables instead of modifying Lua's builtin libraries. +{{< notice note >}} +It is considered bad practice to extend the standard library yourself, as this may collide with other mods doing the same as well as future engine changes including Lua version upgrades. Put your extensions into distinct API tables instead of modifying Lua's builtin libraries. +{{< /notice >}} ### `math` @@ -114,7 +122,9 @@ for i = 0, 255 do end ``` -WARNING: Platform-independence is not guaranteed: "The definitions of letter, space, and other character groups depend on the current locale." - [Lua 5.1 Reference Manual, section 5.4.1](https://www.lua.org/manual/5.1/manual.html#5.4.1) +{{< notice warning >}} +Platform-independence is not guaranteed: "The definitions of letter, space, and other character groups depend on the current locale." - [Lua 5.1 Reference Manual, section 5.4.1](https://www.lua.org/manual/5.1/manual.html#5.4.1) +{{< /notice >}} #### `string.split(str, [delim], [include_empty], [max_splits], [sep_is_pattern])` * `str`: The string to split. diff --git a/content/MetaData.md b/content/MetaData.md index 02b57a2..258df8c 100644 --- a/content/MetaData.md +++ b/content/MetaData.md @@ -12,11 +12,17 @@ Subclasses tie the key-value store to various objects recognized by Luanti: ## Methods ### Getters -NOTE: No type information is stored for values; values will be coerced to and from string as needed. Mods need to know which type they expect in order to call the appropriate getters & setters. Do not rely on coercion to work one way or another; never mix different types. +{{< notice note >}} +No type information is stored for values; values will be coerced to and from string as needed. Mods need to know which type they expect in order to call the appropriate getters & setters. Do not rely on coercion to work one way or another; never mix different types. +{{< /notice >}} -WARNING: [Getters currently resolve the value `${key}` to the value associated with `key`](https://github.com/minetest/minetest/issues/12577). +{{< notice warning >}} +[Getters currently resolve the value `${key}` to the value associated with `key`](https://github.com/minetest/minetest/issues/12577). +{{< /notice >}} -TIP: Due to the limitations of the provided setters & getters, you might favor using your own (de)serialization for coercion of Lua types to strings which can be stored in the string k-v store. +{{< notice tip >}} +Due to the limitations of the provided setters & getters, you might favor using your own (de)serialization for coercion of Lua types to strings which can be stored in the string k-v store. +{{< /notice >}} * `core.write_json` & `core.parse_json` for Lua tables which are representable as JSON; * `core.serialize` & `core.deserialize` for arbitrary Lua tables (consisting of tables & primitive types); @@ -101,13 +107,17 @@ Setters have no return values; they all take exactly two arguments: Key & value. **Arguments:** - `value` - `{type-number}`: The integer value to coerce to a string & associate with `key` -WARNING: Integer refers to a C(++) `int` as internally used by the implementation - usually 32 bits wide - meaning it is unable to represent as large integer numbers as the Lua number type. Be careful when storing integers with large absolute values; they may overflow. Keep `value` between `-2^31` and `2^31 - 1`, both inclusive. +{{< notice warning >}} +Integer refers to a C(++) `int` as internally used by the implementation - usually 32 bits wide - meaning it is unable to represent as large integer numbers as the Lua number type. Be careful when storing integers with large absolute values; they may overflow. Keep `value` between `-2^31` and `2^31 - 1`, both inclusive. +{{< /notice >}} #### `:set_float(key, value)` **Arguments:** - `value` - `{type-number}`: The floating-point value to coerce to a string & associate with `key` -WARNING: The implementation internally uses the C(++) `float` type - usually 32 bits wide - whereas Lua guarantees 64-bit "double-precision" floating point numbers. This may lead to a precision loss. Large numbers in particular may be hardly representable. +{{< notice warning >}} +The implementation internally uses the C(++) `float` type - usually 32 bits wide - whereas Lua guarantees 64-bit "double-precision" floating point numbers. This may lead to a precision loss. Large numbers in particular may be hardly representable. +{{< /notice >}} #### `:equals(other)` **Arguments:** @@ -126,7 +136,9 @@ Converts the metadata to a Lua table representation. - `fields`: Table `{[key] = value, ...}` - Additional fields depending on the subclass -TIP: Use `table = assert(meta:to_table())` to error if the operation failed. +{{< notice tip >}} +Use `table = assert(meta:to_table())` to error if the operation failed. +{{< /notice >}} #### `:from_table(table)` Sets the key-value pairs to match those of a given table representation or clears the metadata. @@ -139,4 +151,6 @@ Sets the key-value pairs to match those of a given table representation or clear **Returns:** - `value` - `{type-bool}`: whether loading the table representation succeeded -TIP: Use `assert(meta:from_table(table))` to error if the operation failed. +{{< notice tip >}} +Use `assert(meta:from_table(table))` to error if the operation failed. +{{< /notice >}} diff --git a/content/ModStorage.md b/content/ModStorage.md index f4fab7d..41857d0 100644 --- a/content/ModStorage.md +++ b/content/ModStorage.md @@ -6,7 +6,9 @@ The granularity of the persisted snapshots is determined by the `map_save_interv ## Backends Two backends are available for ModStorage: JSON and SQLite3. -WARNING: The JSON backend is incapable of saving raw binary data due to JSON restrictions. Even though the SQLite3 backend supports arbitrary bytestrings, you may not rely on saving arbitrary bytestrings to work, since you can't ensure that the SQLite3 backend is being used. +{{< notice warning >}} +The JSON backend is incapable of saving raw binary data due to JSON restrictions. Even though the SQLite3 backend supports arbitrary bytestrings, you may not rely on saving arbitrary bytestrings to work, since you can't ensure that the SQLite3 backend is being used. +{{< /notice >}} If the SQLite3 backend is used, it is usually more efficient to leverage the key-value store than to store fully serialized data structures; fully serializing the data takes linear time in the size of the data whereas updating the key-value store only takes linear time in the size of the changes with the SQLite3 backend; for the JSON backend it is irrelevant - it has to fully serialize the data every map save interval anyways, increasing the risk of data loss if writing the file fails due to a hard crash (or freeze) of the Luanti server process. diff --git a/content/Modchannels.md b/content/Modchannels.md index ecf8b47..53bb2b8 100644 --- a/content/Modchannels.md +++ b/content/Modchannels.md @@ -18,12 +18,16 @@ Returns an object for use with [Methods](#methods). Creates the channel if it do Used for handling messages received from the client. ### Methods -NOTE: `channel` here means the object returned by `core.mod_channel_join`. +{{< notice note >}} +`channel` here means the object returned by `core.mod_channel_join`. +{{< /notice >}} #### `channel:leave()` The server will leave the channel, meaning no more messages from this channel on `core.register_on_modchannel_message` -TIP: Set the channel to `nil` afterwards to free resources +{{< notice tip >}} +Set the channel to `nil` afterwards to free resources +{{< /notice >}} #### `channel:is_writeable()` * Returns `bool`: `true` true if the channel is writeable, `false` if it's not. @@ -33,7 +37,9 @@ TIP: Set the channel to `nil` afterwards to free resources Sends to all SSMs and CSMs on the channel. -CAUTION: The message will not if channel is not writable or invalid. +{{< notice info >}} +The message will not if channel is not writable or invalid. +{{< /notice >}} ## Client Side API @@ -65,12 +71,16 @@ Used for handling messages received from the client. Is equivalent to the the se Used to handle signals generated by the mod channel system. ### Methods -NOTE: `channel` here means the object returned by `core.mod_channel_join`. +{{< notice note >}} +`channel` here means the object returned by `core.mod_channel_join`. +{{< /notice >}} #### `channel:leave()` The client will leave the channel, meaning no more messages from this channel on `core.register_on_modchannel_message` -TIP: Set the channel to `nil` afterwards to free resources +{{< notice tip >}} +Set the channel to `nil` afterwards to free resources +{{< /notice >}} #### `channel:is_writeable()` * Returns `bool`: `true` true if the channel is writeable, `false` if it's not. @@ -80,4 +90,6 @@ TIP: Set the channel to `nil` afterwards to free resources Sends to all SSMs and CSMs on the channel. -CAUTION: The message will not if channel is not writable or invalid. +{{< notice info >}} +The message will not if channel is not writable or invalid. +{{< /notice >}} diff --git a/content/NodeMetaData.md b/content/NodeMetaData.md index 3877812..72d9fef 100644 --- a/content/NodeMetaData.md +++ b/content/NodeMetaData.md @@ -41,7 +41,9 @@ The client can immediately show the FormSpec; the second approach requires the c The obvious disadvantage is that FormSpecs can't be dynamically generated in response to user interaction; formspecs must be mostly static. To alleviate this, formspecs provide context-dependant placeholders like the `context` or `current_player` inventory locations (see FormSpec). -IMPORTANT: The `context` inventory location can only be used in FormSpecs using the special `formspec` NodeMetaData field. FormSpecs shown using `core.show_formspec` must use `nodemeta:,,` to reference inventories instead. +{{< notice info >}} +The `context` inventory location can only be used in FormSpecs using the special `formspec` NodeMetaData field. FormSpecs shown using `core.show_formspec` must use `nodemeta:,,` to reference inventories instead. +{{< /notice >}} Another disadvantage is that plenty of redundant metadata - often a constant FormSpec - has to be stored with every node. This metadata also has to be sent to clients. Luanti's mapblock compression should be able to compress duplicate substrings - FormSpecs in this case - reasonably well though. @@ -58,15 +60,21 @@ NodeMetaData is by default fully sent to clients; the special `formspec` and `in All other fields do not need to be sent to clients unless you want to explicitly support local mapsaving. -TIP: Mark all other fields as private to reduce traffic. +{{< notice tip >}} +Mark all other fields as private to reduce traffic. +{{< /notice >}} If you don't want clients to be able to see private NodeMetaData fields - usually to prevent cheating - you must mark them as private. -NOTE: The private marking is tied to a key-value pair. +{{< notice note >}} +The private marking is tied to a key-value pair. - If the key-value pair is deleted, the private marking is deleted as well. - If the key-value pair is recreated, the private marking must be recreated as well. +{{< /notice >}} -NOTE: `to_table` and `from_table` do not keep track of which fields were marked as private. +{{< notice note >}} +`to_table` and `from_table` do not keep track of which fields were marked as private. +{{< /notice >}} **Arguments:** - `keys` - `{type-string}` or list of `{type-string}`: Either: @@ -84,7 +92,9 @@ Extends MetaData `:to_table()` by additionally adding an `inventory` field for a table `{[listname] = list}` where `list` is a list of ItemStrings (`""` for empty) with the same length as the size of the inventory list. -TIP: Use `table = assert(meta:to_table())` to error if the operation failed. +{{< notice tip >}} +Use `table = assert(meta:to_table())` to error if the operation failed. +{{< /notice >}} ### `:from_table(table)` Extends MetaData `:from_table(table)` to add support for the `inventory` field. diff --git a/content/Object_Properties.md b/content/Object_Properties.md index 55064bf..8716688 100644 --- a/content/Object_Properties.md +++ b/content/Object_Properties.md @@ -9,7 +9,9 @@ This page lists the properties an object may have. Sets the max HP of a player. -NOTE: Decreasing the `hp_max` value to below the current hp will trigger a damage flash. +{{< notice note >}} +Decreasing the `hp_max` value to below the current hp will trigger a damage flash. +{{< /notice >}} ### `breath_max` * internal type: `u16` @@ -44,9 +46,13 @@ Controls whether the object collides with nodes that are `walkable`. Controls whether the object collides with other objects. -CAUTION: `physical` must be set to `true` for this to take effect! +{{< notice info >}} +`physical` must be set to `true` for this to take effect! +{{< /notice >}} -NOTE: This works with players as well but you may experience [strange bugs](https://github.com/minetest/minetest/issues/11783). +{{< notice note >}} +This works with players as well but you may experience [strange bugs](https://github.com/minetest/minetest/issues/11783). +{{< /notice >}} ### `collisionbox` //This could maybe be linked somewhere else. @@ -61,7 +67,9 @@ The collision box of an object. Wanted value is `{xmin, ymin, zmin, xmax, ymax, The selection box of an object, if not set, uses `collisionbox`. Wanted value is `{xmin, ymin, zmin, xmax, ymax, zmax}` (in nodes from the center of the object/ object position). -NOTE: This uses the same format as a nodebox cuboid. +{{< notice note >}} +This uses the same format as a nodebox cuboid. +{{< /notice >}} ### `pointable` * field type: `bool` @@ -84,7 +92,9 @@ Possible values: Sets what the object will look like. -TIP: The `"wielditem"` value supports item hardware colorization +{{< notice tip >}} +The `"wielditem"` value supports item hardware colorization +{{< /notice >}} ### `mesh` * field type: `string` @@ -115,7 +125,9 @@ Wanted value is `{"texture.png", "texture.png", ...}`. The number of textures de * internal type: `ColorSpec list` * default value: `{{r = 255, g = 255, b = 255, a = 255}}` -CAUTION: This feature is not functional. +{{< notice info >}} +This feature is not functional. +{{< /notice >}} ### `spritediv` * field type: `2d_vector` @@ -153,14 +165,18 @@ This sets the maximum height (in nodes) that an object can travel up if it colli How fast the object automatically rotates along the `y` axis in radians/second. -NOTE: Does not (yet) work for attached entities +{{< notice note >}} +Does not (yet) work for attached entities +{{< /notice >}} ### `automatic_face_movement_dir` * field type: `int` or `false` * unit: `degrees` * default value: `0` -TIP: This property can be set to `false` to disable it. +{{< notice tip >}} +This property can be set to `false` to disable it. +{{< /notice >}} Make the object automatically face the direction it is moving in, the value is the offset in degrees. @@ -188,14 +204,18 @@ Text displayed above an object, typically used for names. If the object is a pla The color that the nametag text will be. -TIP: This property can be set to `false` to disable it. +{{< notice tip >}} +This property can be set to `false` to disable it. +{{< /notice >}} ### `nametag_bgcolor` * field type: `ColorSpec` or `false` The color that the nametag's background will be. -TIP: This property can be set to `false` to not show a background. +{{< notice tip >}} +This property can be set to `false` to not show a background. +{{< /notice >}} ### `automatic_face_movement_max_rotation_per_sec` * field type: `f32` @@ -225,7 +245,9 @@ Only when using "wielditem" visual. Whether buggy semitransparency is enabled for the texture. -WARNING: Faces, entities and other semitransparent world elements might not be rendered in the right order for semitransparency to work. +{{< notice warning >}} +Faces, entities and other semitransparent world elements might not be rendered in the right order for semitransparency to work. +{{< /notice >}} ### `shaded` * field type: `bool` @@ -249,13 +271,21 @@ A texture modifier that will be appended to the object's current textures for th The way these properties are laid out is in a table. -NOTE: Extraneous properties will be ignored, but might be interpreted incorrectly by future versions of the engine, which is why it is recommended to prefix them with an underscore. +{{< notice note >}} +Extraneous properties will be ignored, but might be interpreted incorrectly by future versions of the engine, which is why it is recommended to prefix them with an underscore. +{{< /notice >}} -NOTE: This uses regular indexing so metatables work as expected. +{{< notice note >}} +This uses regular indexing so metatables work as expected. +{{< /notice >}} -WARNING: For all string properties, the maximum number of characters is the `u16` max value. +{{< notice warning >}} +For all string properties, the maximum number of characters is the `u16` max value. +{{< /notice >}} -NOTE: Number properties will be clamped to their value ranges. +{{< notice note >}} +Number properties will be clamped to their value ranges. +{{< /notice >}} ## Example diff --git a/content/Persistence.md b/content/Persistence.md index ec8be4b..74300df 100644 --- a/content/Persistence.md +++ b/content/Persistence.md @@ -22,9 +22,13 @@ The following types are supported by JSON: * strings * tables (objects/arrays) -NOTE: Negative and positive infinity are represented by numbers which exceed the double number range by a lot (plus/minus `1e9999`). +{{< notice note >}} +Negative and positive infinity are represented by numbers which exceed the double number range by a lot (plus/minus `1e9999`). +{{< /notice >}} -WARNING: The empty table `{}` (ambiguous: might be either `{}` or `[]`) and `nan` aren't supported by JSON and will be turned into `null`. +{{< notice warning >}} +The empty table `{}` (ambiguous: might be either `{}` or `[]`) and `nan` aren't supported by JSON and will be turned into `null`. +{{< /notice >}} Tables may either: 1. Contain only positive integer keys (represented as array) or @@ -39,24 +43,33 @@ Else:: Returns `nil` and one of the following errors if it fails: * `Lua key to convert to JSON is not a string or number` * `Can't mix array and object values in JSON` -WARNING: Hash tables containing only positive integer keys - a table of `core.hash_node_position` hashes for instance - +{{< notice warning >}} +Hash tables containing only positive integer keys - a table of `core.hash_node_position` hashes for instance - will be turned into *an array with holes*, that is, all `nil` values from `1` to the maximum index will be filled with `null`, which means terrible performance and possibly very large output generated from very small input. *Do not allow direct access to `core.write_json`* as it can be trivially used to DoS your server. +{{< /notice >}} -TIP: Sparse hash maps, should always be converted to objects, using only string keys, for JSON. You might do this just for serialization. +{{< notice tip >}} +Sparse hash maps, should always be converted to objects, using only string keys, for JSON. You might do this just for serialization. +{{< /notice >}} -WARNING: The JSON serializer is furthermore limited by its recursion depth: Only a recursion depth up to *16* is allowed. Very nested data structures can't be (de)serialized. Circular references will cause the JSON serializer to recurse until the maximum recursion depth is exceeded. +{{< notice warning >}} +The JSON serializer is furthermore limited by its recursion depth: Only a recursion depth up to *16* is allowed. Very nested data structures can't be (de)serialized. Circular references will cause the JSON serializer to recurse until the maximum recursion depth is exceeded. +{{< /notice >}} -TIP: Use the `json = assert(core.write_json(data))` idiom to not silently ignore errors when serializing. +{{< notice tip >}} +Use the `json = assert(core.write_json(data))` idiom to not silently ignore errors when serializing. +{{< /notice >}} #### `core.parse_json(json, [nullvalue])` If `json` is valid JSON:: Returns the Lua value represented by the JSON string `json`, with `null` values deserialized to `nullvalue` (which defaults to `nil`). Else:: Returns `nil` and logs an error. -TIP: If you must use JSON (to interact with a web interface, for instance), consider using your JSON library of choice; -Lua-only implementations such as [`lunajson`](https://github.com/grafi-tt/lunajson/) are available. +{{< notice tip >}} +If you must use JSON (to interact with a web interface, for instance), consider using your JSON library of choice; Lua-only implementations such as [`lunajson`](https://github.com/grafi-tt/lunajson/) are available. +{{< /notice >}} ### Lua @@ -96,9 +109,13 @@ If `safe` is truthy, serialized functions will be deserialized to `nil`. This will trigger an error if functions are used as table keys (`{[function()end] = true}`). Otherwise, serialized functions will get an empty function environment set - only being able to operate on literals and arguments. -TIP: Use of the `data = assert(core.deserialize(lua, safe))` idiom is recommended. +{{< notice tip >}} +Use of the `data = assert(core.deserialize(lua, safe))` idiom is recommended. +{{< /notice >}} -WARNING: [`core.deserialize` errors on large objects on LuaJIT](https://github.com/minetest/minetest/issues/7574) +{{< notice warning >}} +[`core.deserialize` errors on large objects on LuaJIT](https://github.com/minetest/minetest/issues/7574) +{{< /notice >}} ## Engine-provided default persistence @@ -140,7 +157,9 @@ If your data is rather larger or gets updated frequently, a full serialization m Performance can be improved at the expense of granularity by saving periodically and choosing "long" periods. A transaction log improves performance by only storing changes, at the expense of disk space. -TIP: A mix of both approaches can provide satisfying results, logging only changes and rewriting the logfile periodically to keep disk space waste acceptable. +{{< notice tip >}} +A mix of both approaches can provide satisfying results, logging only changes and rewriting the logfile periodically to keep disk space waste acceptable. +{{< /notice >}} For special cases like logging, an append-only file may be the ideal solution if using the global `core.log` is not desirable. diff --git a/content/PlayerMetaData.md b/content/PlayerMetaData.md index d53be29..665ca68 100644 --- a/content/PlayerMetaData.md +++ b/content/PlayerMetaData.md @@ -3,7 +3,9 @@ PlayerMetaData is a per-world, per-player persistent string key-value store impl The granularity of the persisted snapshots is determined by the `map_save_interval` setting. -NOTE: Since PlayerMetaData is shared across all mods, it is considered good practice to prefix the keys set by your mod with your mod name plus a delimiter such as `:` to avoid collisions: The `score` field of a quest mod and a mobs mod f.E. might be called `fancy_quests:score` and `fancy_mobs:score` respectively. +{{< notice note >}} +Since PlayerMetaData is shared across all mods, it is considered good practice to prefix the keys set by your mod with your mod name plus a delimiter such as `:` to avoid collisions: The `score` field of a quest mod and a mobs mod f.E. might be called `fancy_quests:score` and `fancy_mobs:score` respectively. +{{< /notice >}} ## `player:get_meta()` Used to obtain a mutable PlayerMetaData reference. @@ -11,7 +13,9 @@ Used to obtain a mutable PlayerMetaData reference. **Arguments:** - `player`: A valid Player object -NOTE: Luanti requiring a valid `player` object means PlayerMetaData is only accessible while players are online; if you need per-player storage while players are offline, you can use ModStorage and save either a serialized table per-player or concatenate the keys of the per-player entries with the playername using a delimiter. Reusing the above example, `fancy_quests:score` might be stored as `:score` or as key-value pair with key `` and value `core.write_json{score = ...}` (or `core.serialize`) in ModStorage. +{{< notice note >}} +Luanti requiring a valid `player` object means PlayerMetaData is only accessible while players are online; if you need per-player storage while players are offline, you can use ModStorage and save either a serialized table per-player or concatenate the keys of the per-player entries with the playername using a delimiter. Reusing the above example, `fancy_quests:score` might be stored as `:score` or as key-value pair with key `` and value `core.write_json{score = ...}` (or `core.serialize`) in ModStorage. +{{< /notice >}} A [feature request](https://github.com/minetest/minetest/issues/6193) to make PlayerMetaData available for offline players exists; diff --git a/content/Random.md b/content/Random.md index e4eb968..2b598dd 100644 --- a/content/Random.md +++ b/content/Random.md @@ -8,7 +8,9 @@ Not restricted by mod security, these functions are available to both SSMs and C ### [`math.randomseed`](https://www.lua.org/manual/5.1/manual.html#pdf-math.randomseed) Seed the random. Luanti already does this for you using the system time. -IMPORTANT: Do not seed the random to turn it into a deterministic random source as other mods may expect it to be "non-deterministic". +{{< notice info >}} +Do not seed the random to turn it into a deterministic random source as other mods may expect it to be "non-deterministic". +{{< /notice >}} Conversely, do not rely on the random to have any particular seed either; other mods & the engine may have seeded it (using the system time) to be "non-deterministic". @@ -29,13 +31,21 @@ math.randomseed(reseed) ### [`math.random`](https://www.lua.org/manual/5.1/manual.html#pdf-math.random) Get a random number. Very versatile; allows getting floats between `0` and `1` or integers in a range. -NOTE: The random numbers between `0` and `1` do not provide a full 52-bit mantissa full of entropy; they usually have around 32 bits of entropy. +{{< notice note >}} +The random numbers between `0` and `1` do not provide a full 52-bit mantissa full of entropy; they usually have around 32 bits of entropy. +{{< /notice >}} -WARNING: When using this to obtain integers, make sure that both the upper & lower bound as well as their difference are within the C `int` range - otherwise you may get overflows & errors. +{{< notice warning >}} +When using this to obtain integers, make sure that both the upper & lower bound as well as their difference are within the C `int` range - otherwise you may get overflows & errors. +{{< /notice >}} -WARNING: This is not portable; different builds on different platforms will produce different random numbers. PUC Lua 5.1 builds use a system-provided random generator. LuaJIT builds use LuaJIT's PRNG implementation. Do not use `math.random` in mapgen, for example. +{{< notice warning >}} +This is not portable; different builds on different platforms will produce different random numbers. PUC Lua 5.1 builds use a system-provided random generator. LuaJIT builds use LuaJIT's PRNG implementation. Do not use `math.random` in mapgen, for example. +{{< /notice >}} -TIP: Use `math.random` as your go-to versatile "non-deterministic" random source. +{{< notice tip >}} +Use `math.random` as your go-to versatile "non-deterministic" random source. +{{< /notice >}} ## Random Number Generators @@ -49,7 +59,9 @@ Constructs a `PcgRandom` instance with the given seed, which should be an intege If `min` and `max` are both omitted, they default to `-2^31` (`-2147483648`) and `2^31 - 1` (`2147483647`) respectively. #### `:rand_normal_dist(min, max, [num_trials])` -WARNING: No successful use of this function is documented. Consider implementing your own normal distribution instead. +{{< notice warning >}} +No successful use of this function is documented. Consider implementing your own normal distribution instead. +{{< /notice >}} `min` and `max` are required; they need to be integers. @@ -72,7 +84,9 @@ Constructor: Takes a `seed` and returns a `PseudoRandom` object. #### `:next([min, max])` If `min` and `max` are both omitted, they default to `0` and `2^16-1` (`32767`) respectively. -WARNING: Requires `((max - min) == 32767) or ((max-min) <= 6553))` for a proper distribution. +{{< notice warning >}} +Requires `((max - min) == 32767) or ((max-min) <= 6553))` for a proper distribution. +{{< /notice >}} ### `SecureRandom` System-provided cryptographically secure random: An attacker should not be able to predict the generated sequence of random numbers. Use this when generating cryptographic keys or tokens. @@ -82,7 +96,9 @@ On Windows, the Win32 Crypto API is used to retrieve cryptographically secure ra #### `SecureRandom()` Constructor: Returns a SecureRandom object or `nil` if no secure random source is available. -TIP: Use `assert(SecureRandom(), "no secure random available")` to error if no secure random source is available. +{{< notice tip >}} +Use `assert(SecureRandom(), "no secure random available")` to error if no secure random source is available. +{{< /notice >}} #### `:next_bytes([count])` Only argument is `count`, an optional integer defaulting to `1` and limited to `2048` specifying how many bytes are to be returned. Returned as a Lua bytestring of length `count` diff --git a/content/Raycast.md b/content/Raycast.md index 33b5d9c..948f777 100644 --- a/content/Raycast.md +++ b/content/Raycast.md @@ -46,11 +46,17 @@ You may use this to determine e.g. whether a target would be visible to a mob. R ## `Raycast(from_pos, to_pos, include_objects, include_liquid_nodes)` Creates a raycast object; OOP-constructor-style alias for `core.raycast`. -IMPORTANT: [Raycasts work on selection-, not collision boxes, making them coherent with player pointing but not physics (collisions) unless selection- and collision boxes are identical.](https://github.com/minetest/minetest/issues/12673) +{{< notice info >}} +[Raycasts work on selection-, not collision boxes, making them coherent with player pointing but not physics (collisions) unless selection- and collision boxes are identical.](https://github.com/minetest/minetest/issues/12673) +{{< /notice >}} -TIP: Have selection boxes, collision boxes (and ideally even visuals) match for all nodes & entities if possible. +{{< notice tip >}} +Have selection boxes, collision boxes (and ideally even visuals) match for all nodes & entities if possible. +{{< /notice >}} -IMPORTANT: [Serverside raycasts do not support attachments properly; the server is unaware of model specificities, doesn't keep track of automatic rotation etc.](https://github.com/minetest/minetest/issues/10304) +{{< notice info >}} +[Serverside raycasts do not support attachments properly; the server is unaware of model specificities, doesn't keep track of automatic rotation etc.](https://github.com/minetest/minetest/issues/10304) +{{< /notice >}} **Arguments:** - `from_pos` - `{type-vector}`: Starting position of the raycast (usually eye position) @@ -100,7 +106,8 @@ end There is absolutely no need to manually step through raycasts using the latter two more verbose loops. -IMPORTANT: Restartability is the ability of an iterator to start again. For example, `ipairs` is resumable: +{{< notice info >}} +Restartability is the ability of an iterator to start again. For example, `ipairs` is resumable: ```lua local t = {1, 2, 3} @@ -137,6 +144,7 @@ for pt in ray do -- will resume looping with the next pointed thing end ``` +{{< /notice >}} ## Examples diff --git a/content/Setting_up_a_server.md b/content/Setting_up_a_server.md index 467ea26..7d51b20 100644 --- a/content/Setting_up_a_server.md +++ b/content/Setting_up_a_server.md @@ -188,7 +188,11 @@ Many of these problems can be removed or minimised by advanced planning and awar - Install a protection mod, such as [areas](https://content.luanti.org/packages/ShadowNinja/areas/) or [protectors](https://content.luanti.org/packages/TenPlus1/protector/). These allow players to protect areas, which cannot be changed by other players. - Enable rollback by adding `enable_rollback_recording = true` to minetest.conf. Rollback can tell you which player placed a node, and allows a player's actions to be reverted. - - **NOTE:** The engine rollback functionality is very limited and can't roll back griefing caused by mod-made node changes (e.g. spawning a bunch of trees or covering things in water). In addition to rollback, you should also always make regular backups of the map database. + +{{< notice warning >}} +The engine rollback functionality is very limited and can't roll back griefing caused by mod-made node changes (e.g. spawning a bunch of trees or covering things in water). In addition to rollback, you should also always make regular backups of the map database. +{{< /notice >}} + - Install a mod to help you manage bans, such as [xban2](https://content.luanti.org/packages/kaeza/xban2/). - On the other hand, if you are setting up a private server, install a whitelist mod such as [whitelist](https://content.luanti.org/packages/Zughy/whitelist/). - Create rules for your server and make sure you have enough time (or a team of moderators) to supervise your server and watch for players who breaks your rules. diff --git a/content/Texture_Modifiers.md b/content/Texture_Modifiers.md index 5987519..3d90416 100644 --- a/content/Texture_Modifiers.md +++ b/content/Texture_Modifiers.md @@ -3,7 +3,9 @@ Texture modifiers - strings instructing Luanti to manipulate images - are, besid They can also be used to simplify mods by generating repetitive textures such as differently colored tool textures. -IMPORTANT: Texture modifiers are partially redundant with hardware colorization. Hardware colorization should be preferred as it is more flexible and presumably generates fewer garbage textures. +{{< notice info >}} +Texture modifiers are partially redundant with hardware colorization. Hardware colorization should be preferred as it is more flexible and presumably generates fewer garbage textures. +{{< /notice >}} ## Performance Issues * All textures are generated on the CPU, not the GPU. Generation is therefore slow and may temporarily block the client thread. @@ -23,11 +25,15 @@ Use texture modifiers mostly statically. Keep dynamically generated textures to ## Texture Packs Texture modifiers can be used in node & item texture overrides. -IMPORTANT: Texture-modifier-generated textures can not be replaced by a texture pack (except through texture overrides); only base textures can be properly replaced. +{{< notice info >}} +Texture-modifier-generated textures can not be replaced by a texture pack (except through texture overrides); only base textures can be properly replaced. +{{< /notice >}} Usage of certain texture modifiers might require certain texture resolutions to be used by texture packs, as texture modifiers operate on pixels instead of relative units. Lower-res TPs can usually scale up but higher-res TPs will have to scale down. -TIP: Use `[resize` to forcibly resize textures to your required resolution (e.g. for `[combine`) in order to be as TP-agnostic as possible. +{{< notice tip >}} +Use `[resize` to forcibly resize textures to your required resolution (e.g. for `[combine`) in order to be as TP-agnostic as possible. +{{< /notice >}} ## In Lua @@ -55,12 +61,18 @@ Example: +\[\[\[`combine:1x1:0,0=a.png`\]\]+. Using equals signs is never necessary since texture modifiers won't contain \[\[ or \]\]. -TIP: You can use metamethods in order to implement a neat, possibly OOP-ish Lua DSL that does the escaping and formatting for you. +{{< notice tip >}} +You can use metamethods in order to implement a neat, possibly OOP-ish Lua DSL that does the escaping and formatting for you. +{{< /notice >}} ## Syntax -WARNING: Texture modifiers are only parsed clientside, where errors lead to poor behavior (error messages in the best case, sometimes the wrong texture, crashes in the worst case). They are not validated serverside. Take additional care to ensure no syntax errors or values which cause undefined behavior. +{{< notice warning >}} +Texture modifiers are only parsed clientside, where errors lead to poor behavior (error messages in the best case, sometimes the wrong texture, crashes in the worst case). They are not validated serverside. Take additional care to ensure no syntax errors or values which cause undefined behavior. +{{< /notice >}} -TIP: Use a string builder which guarantees valid texture modifiers. +{{< notice tip >}} +Use a string builder which guarantees valid texture modifiers. +{{< /notice >}} ### Base textures Texture modifiers work on _base textures_ which are specified in a string form as media file names. See the supported file formats. @@ -112,12 +124,16 @@ Also wrong: `+[combine:1x2:0,0=(a^b):0,1=(c^[multiply:red)+` - the combine parsi Grouping can however be used to enclose combining texture modifiers, separating them from the containing texture modifier. -TIP: Use grouping for evaluating parts of the right-hand side first, like this: `+a^[multiply:green^(b^[multiply:red)+` +{{< notice tip >}} +Use grouping for evaluating parts of the right-hand side first, like this: `+a^[multiply:green^(b^[multiply:red)+` +{{< /notice >}} ### Modifiers All texture modifiers create new textures which can be modified further and do not modify the textures they operate on. -TIP: Use `string.format("%d", number)` - `("%d"):format(number)` in shorthand - to guarantee that integers are parsable. In practice, `tostring(number)` or implicit conversion to string when concatenating will work as expected. +{{< notice tip >}} +Use `string.format("%d", number)` - `("%d"):format(number)` in shorthand - to guarantee that integers are parsable. In practice, `tostring(number)` or implicit conversion to string when concatenating will work as expected. +{{< /notice >}} #### Combining Texture Modifiers The following texture modifiers are considered "combining", as they operate by combining multiple textures into one, taking textures other than the "base texture" as arguments: @@ -176,7 +192,9 @@ Transformation names are case insensitive. Result: Vertically crops the texture by dividing the base texture height through the frame count to determine the frame height. As the division is an integer division, a remaining fractional frame will be discarded. -WARNING: Specifying a `framecount` of `0` will trigger a floating point exception, crashing the client. +{{< notice warning >}} +Specifying a `framecount` of `0` will trigger a floating point exception, crashing the client. +{{< /notice >}} ##### `+^[crack[]:[:]:+` Shorthand for overlaying a scaled frame of the crack texture, `crack_anylength.png`, @@ -187,7 +205,9 @@ over a texture, with options for alpha and blitting on all frames. * `tilecount`: Vertical & horizontal tile count of the base texture. The crack will be blit on each tile of the base texture. Usually `1`. * `frame`: Current animation frame ("crack progression"). -NOTE: This always scales the crack to the size of the base texture (or the tiles of the base texture, if `tilesize` is provided). +{{< notice note >}} +This always scales the crack to the size of the base texture (or the tiles of the base texture, if `tilesize` is provided). +{{< /notice >}} ##### `+^[sheet:x:,+` * `w`, `h`: Tilesheet dimensions (positive integers, in tiles) @@ -228,7 +248,9 @@ Masking is associative and commutative if all involved textures have the same di Overlays the lower `percent` part of `texture` on the base texture. -TIP: Use `blank.png` as base texture if you do not want a background. +{{< notice tip >}} +Use `blank.png` as base texture if you do not want a background. +{{< /notice >}} #### Base Texture Generators These modifiers do not accept a base texture as they generate one from their arguments. @@ -246,11 +268,17 @@ local function embedded_png(width, height, data) end ``` -IMPORTANT: Not supported by Luanti 5.4 and older clients. May lead to client crashes if used in node tiles. Luanti 5.5 and newer servers will automatically prepend `+blank.png^+` to `[png` tiles to mitigate this. +{{< notice warning >}} +Not supported by Luanti 5.4 and older clients. May lead to client crashes if used in node tiles. Luanti 5.5 and newer servers will automatically prepend `+blank.png^+` to `[png` tiles to mitigate this. +{{< /notice >}} -WARNING: Do not use this for large textures. If used as an object texture, the texture modifier will get sent arbitrarily often, putting a strain on the network. +{{< notice warning >}} +Do not use this for large textures. If used as an object texture, the texture modifier will get sent arbitrarily often, putting a strain on the network. +{{< /notice >}} -TIP: Consider using other texture modifiers cleverly or using dynamic media instead. +{{< notice tip >}} +Consider using other texture modifiers cleverly or using dynamic media instead. +{{< /notice >}} ##### `[combine:x:` * `w`: Width of the resulting texture @@ -263,9 +291,13 @@ Nesting `combine` is possible through escaping. Generates a texture of dimensions `w`, `h` on which all `textures` have been blit at the specified locations. The background is black and transparent (`#00000000`). -IMPORTANT: Node tiles starting with `[combine` are broken on Luanti 5.4 and older clients connecting to 5.5 servers due to the aforementioned `[png` workaround accidentally being applied to `[combine` as well. +{{< notice info >}} +Node tiles starting with `[combine` are broken on Luanti 5.4 and older clients connecting to 5.5 servers due to the aforementioned `[png` workaround accidentally being applied to `[combine` as well. +{{< /notice >}} -TIP: To work around this, you can enclose your node tile texture modifiers using `[combine` in parentheses: `([combine:...)`. A generic patch which loops over node definitions and wraps matching texture modifiers [is available as well](https://gist.github.com/appgurueu/dea1d1d9d8494e9c00114d36d58c5932). +{{< notice tip >}} +To work around this, you can enclose your node tile texture modifiers using `[combine` in parentheses: `([combine:...)`. A generic patch which loops over node definitions and wraps matching texture modifiers [is available as well](https://gist.github.com/appgurueu/dea1d1d9d8494e9c00114d36d58c5932). +{{< /notice >}} ##### `[inventorycube{{{` Renders a cube with the three given textures using simple software rendering. @@ -309,4 +341,6 @@ The below examples use `progress_bar.png` & `progress_bar_bg.png` from Luanti's * Rotate everything by 270° to undo the vertical orientation * *Advantage over using `combine`*: Due to the usage of `lowpart`, this is resolution-agnostic (will work with texture packs of different resolutions) -NOTE: For HUDs, `statbar`s should be preferred over `image`s using texture modifiers. +{{< notice note >}} +For HUDs, `statbar`s should be preferred over `image`s using texture modifiers. +{{< /notice >}} diff --git a/content/Timing_and_Event_loop.md b/content/Timing_and_Event_loop.md index c660b1a..26a2473 100644 --- a/content/Timing_and_Event_loop.md +++ b/content/Timing_and_Event_loop.md @@ -54,11 +54,17 @@ time = core.get_us_time() #### Returns - `time` - `{type-number}`: System-dependent timestamp in microseconds since an arbitrary starting point (µs) -TIP: Divide by `1e6` to convert `time` into seconds. +{{< notice tip >}} +Divide by `1e6` to convert `time` into seconds. +{{< /notice >}} -CAUTION: The returned `time` is not portable and not relative to any specific point in time across restarts - keep it only in memory for use while the game is running. +{{< notice info >}} +The returned `time` is not portable and not relative to any specific point in time across restarts - keep it only in memory for use while the game is running. +{{< notice info >}} -TIP: You can use the difference between ``core.get_us_time`` and the returned times to check whether a real-world timespan has passed, which is useful for rate limiting. For in-game timers, you might prefer adding up `dtime` or (if second precision is enough) using gametime. +{{< notice tip >}} +You can use the difference between ``core.get_us_time`` and the returned times to check whether a real-world timespan has passed, which is useful for rate limiting. For in-game timers, you might prefer adding up `dtime` or (if second precision is enough) using gametime. +{{< /notice >}} #### Example @@ -69,7 +75,9 @@ local start = core.get_us_time() repeat until core.get_us_time() - start > 1e3 -- Wait for 1000 µs to pass ``` -WARNING: This blocks the server thread, possibly delaying the sending of packets that are sent each step and creating "lag". Use this only if absolutely necessary and only for very small timespans. +{{< notice warning >}} +This blocks the server thread, possibly delaying the sending of packets that are sent each step and creating "lag". Use this only if absolutely necessary and only for very small timespans. +{{< /notice >}} ### `core.get_gametime` @@ -98,10 +106,13 @@ core.after(0, function() end end) ``` +{{< notice info >}} +This naive implementation might be one server step ahead or behind `core.get_gametime`. Note that the initial gametime is rounded. Do not persist the values for this reason. +{{< /notice >}} -IMPORTANT: This naive implementation might be one server step ahead or behind `core.get_gametime`. Note that the initial gametime is rounded. Do not persist the values for this reason. - -TIP: Use this implementation only for measuring in-game timespans. +{{< notice tip >}} +Use this implementation only for measuring in-game timespans. +{{< /notice >}} ### `core.register_globalstep` @@ -118,9 +129,13 @@ end) #### Params - `dtime` - `{type-number}`: Delta (elapsed) time since last step in seconds -TIP: Use globalsteps to poll for an event for which there are no callbacks, such as player controls (`player:get_player_control()`). +{{< notice tip >}} +Use globalsteps to poll for an event for which there are no callbacks, such as player controls (`player:get_player_control()`). +{{< /notice >}} -CAUTION: As globalsteps run every server step, they are highly performance-critical and must be well optimized. If globalsteps take longer than the server step to complete, the server thread is blocked and the server becomes "laggy". +{{< notice info >}} +As globalsteps run every server step, they are highly performance-critical and must be well optimized. If globalsteps take longer than the server step to complete, the server thread is blocked and the server becomes "laggy". +{{< /notice >}} #### Examples @@ -149,9 +164,13 @@ This will call `func` after at least `timer` seconds have passed. Note that ther Will call `func(...)` after at least `time` seconds have passed. -TIP: Use `core.after(0, func)` to immediately do load-time stuff that is only possible at run-time, or to schedule something for the next server step. +{{< notice tip >}} +Use `core.after(0, func)` to immediately do load-time stuff that is only possible at run-time, or to schedule something for the next server step. +{{< /notice >}} -CAUTION: Scheduled calls that run in the same server step are executed in no particular order. +{{< notice info >}} +Scheduled calls that run in the same server step are executed in no particular order. +{{< /notice >}} The following snippet emulates a globalstep, sending `Hello World!` to chat every server step: @@ -179,17 +198,23 @@ end #### Returns - `job` - job object: Simple object providing a `job:cancel()` method to cancel a scheduled "job". -CAUTION: `...` may be arbitrarily cut off at `nil` values, as Luanti uses a simple list to store the arguments. Don't include `nil`s in the arguments if possible or you may lose arguments. +{{< notice info >}} +`...` may be arbitrarily cut off at `nil` values, as Luanti uses a simple list to store the arguments. Don't include `nil`s in the arguments if possible or you may lose arguments. +{{< /notice >}} -TIP: If you have to call a function with ``nil``s in it's argument list, use a closure for reliable behavior: +{{< notice tip >}} +If you have to call a function with ``nil``s in it's argument list, use a closure for reliable behavior: ```lua core.after(time, function() func(nil, arg, arg2, nil, nil) end) ``` +{{< /notice >}} -NOTE: All scheduled callbacks are stored in a list until they are called. This list is traversed in linear time if *any* of the callbacks are executed. Excessive use of `core.after` may result in slow execution time. +{{< notice note >}} +All scheduled callbacks are stored in a list until they are called. This list is traversed in linear time if *any* of the callbacks are executed. Excessive use of `core.after` may result in slow execution time. +{{< /notice >}} ## Entities diff --git a/content/Vector_API.md b/content/Vector_API.md index f4987fe..bd5ff16 100644 --- a/content/Vector_API.md +++ b/content/Vector_API.md @@ -4,7 +4,9 @@ However it has more recently been given metatable methods for convenience. Unless otherwise noted, the `vector` type always refers to the metatable-enhanced variety. Do note that functions here will accept an old-style (non-metatable) `vector`, but you cannot perform metatable operations with said `vector`. -TIP: The respective source code is located [here](https://github.com/minetest/minetest/blob/master/builtin/common/vector.lua). +{{< notice tip >}} +The respective source code is located [here](https://github.com/minetest/minetest/blob/master/builtin/common/vector.lua). +{{< /notice >}} ## `vector` Namespace @@ -244,14 +246,18 @@ Returns a new `vector` which is the inverse of `v`. Returns a new `vector` where each component of `a` is added to each respective component of `b`. -NOTE: Unlike `vector.add()` this does not support adding `number` values. +{{< notice note >}} +Unlike `vector.add()` this does not support adding `number` values. +{{< /notice >}} ### `metatable.__sub(a, b)` * `a`, `b`: `vector` Returns a new `vector` where each component of `a` is subtracted from each respective component of `b`. -NOTE: Unlike `vector.subtract()` this does not support subtracting `number` values. +{{< notice note >}} +Unlike `vector.subtract()` this does not support subtracting `number` values. +{{< /notice >}} ### `metatable.__mul(a, b)` * `a`: `vector` or `number` @@ -259,7 +265,9 @@ NOTE: Unlike `vector.subtract()` this does not support subtracting `number` valu Returns a new `vector` where each component of `a` is multiplied by each respective component of `b`. Because of the way metatables work, either argument can be a `number` or a `vector` without any practical difference. -CAUTION: This function assumes that one just one argument is a number, and will probably return confusing errors about "accessing a `nil` value" if two `vector` arguments are passed to it. +{{< notice info >}} +This function assumes that one just one argument is a number, and will probably return confusing errors about "accessing a `nil` value" if two `vector` arguments are passed to it. +{{< /notice >}} ### `metatable.__div(a, b)` * `a`: `vector` @@ -267,4 +275,6 @@ CAUTION: This function assumes that one just one argument is a number, and will Returns a new `vector` where each component of `a` is divided by `b`. -CAUTION: This function assumes `b` is a number, and will probably return confusing errors about "accessing a `nil` value" if it is not. +{{< notice info >}} +This function assumes `b` is a number, and will probably return confusing errors about "accessing a `nil` value" if it is not. +{{< /notice >}} diff --git a/content/VoxelArea.md b/content/VoxelArea.md index 0161a32..f33a996 100644 --- a/content/VoxelArea.md +++ b/content/VoxelArea.md @@ -19,11 +19,17 @@ local emin, emax = voxelmanip:read_from_map(pos_min, pos_max) local voxelarea = VoxelArea:new{ MinEdge = emin, MaxEdge = emax } ``` -WARNING: Always pass the actual emerged min & max positions. Do not pass the desired min & max positions. +{{< notice warning >}} +Always pass the actual emerged min & max positions. Do not pass the desired min & max positions. +{{< /notice >}} -WARNING: Never pass fractional values as min- or max edge. +{{< notice warning >}} +Never pass fractional values as min- or max edge. +{{< /notice >}} -TIP: You can use `vector.floor`, `vector.round` or `vector.apply(vec, math.ceil)` to guarantee integer values. +{{< notice tip >}} +You can use `vector.floor`, `vector.round` or `vector.apply(vec, math.ceil)` to guarantee integer values. +{{< /notice >}} The following methods can both be called in an imperative manner (`VoxelArea.(self, ...)`) or an OOP manner (recommended): `self:(...)`. The below examples are documented using the latter style, where `area` is a valid table with `VoxelArea` as the metatable. @@ -39,7 +45,9 @@ Returns the volume of `area` as integer. `x`, `y`, `z` are absolute coordinates of a node within the area. Returns an integer index to be used for data tables returned by VoxelManip objects. -WARNING: This will silently `floor` the returned index instead of throwing an error. Make sure that the coordinates you pass are (1) not fractional and (2) within the area. +{{< notice warning >}} +This will silently `floor` the returned index instead of throwing an error. Make sure that the coordinates you pass are (1) not fractional and (2) within the area. +{{< /notice >}} ## `area:indexp(p)` @@ -49,7 +57,9 @@ Shorthand for `area:index(p.x, p.y, p.z)`. Inverse to `area:indexp`. Returns the absolute node position corresponding to the `index` as a table with `x`, `y` and `z` fields. -TIP: The returned table is missing the `vector` metatable. If it is not performance-critical, use `p = vector.new(area:position(index))` to create a copied vector with metatable. +{{< notice tip >}} +The returned table is missing the `vector` metatable. If it is not performance-critical, use `p = vector.new(area:position(index))` to create a copied vector with metatable. +{{< /notice >}} ## `area:contains(x, y, z)` @@ -63,7 +73,9 @@ Shorthand for `area:contains(p.x, p.y, p.z)` Returns `true` if `i` is between `1` and the `area` volume, both inclusive. -WARNING: `area:containsi(area:indexp(p))` *is not equivalent to* `area:containsp(p)`, as `area:indexp` will happily produce valid indices for some out-of-area positions. +{{< notice warning >}} +`area:containsi(area:indexp(p))` *is not equivalent to* `area:containsp(p)`, as `area:indexp` will happily produce valid indices for some out-of-area positions. +{{< /notice >}} ## `area:iter(minx, miny, minz, maxx, maxy, maxz)`