oss/luanti
oss/luanti
1
0
Fork 0
mirror of https://github.com/luanti-org/luanti.git synced 2025-06-27 16:36:03 +00:00
Code Wiki Activity

lua_api.md: Mapblock-related and misc improvements (#15972)

Browse source 
Co-authored-by: sfan5 <sfan5@live.de>
Co-authored-by: DS <ds.desour@proton.me>
This commit is contained in:
grorp 2025-04-03 13:46:06 -04:00 • committed by GitHub
parent 7dbd3a0744
commit 66dedf1e21
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 50 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

57
doc/lua_api.md
View file

@ -1596,7 +1596,8 @@ There are a bunch of different looking node types.
Node boxes
----------
Node selection boxes are defined using "node boxes".
Node selection boxes and collision boxes, and the appearance of the `nodebox`
drawtype, are defined using "node boxes".
A nodebox is defined as any of:
@ -1681,8 +1682,8 @@ roughly 1x1x1 meters in size.
A 'mapblock' (often abbreviated to 'block') is 16x16x16 nodes and is the
fundamental region of a world that is stored in the world database, sent to
clients and handled by many parts of the engine. This size is defined by the constant
`core.MAP_BLOCKSIZE` (=16).
clients and handled by many parts of the engine. This size is available as the
constant `core.MAP_BLOCKSIZE` (=16).
'mapblock' is preferred terminology to 'block' to help avoid confusion with
'node', however 'block' often appears in the API.
@ -1692,6 +1693,38 @@ A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks
the map generator.
The size in mapblocks has been chosen to optimize map generation.
### Mapblock status
A mapblock being "loaded" means that is in memory. These are the mapblocks that
API functions like `core.get_node` or `core.set_node` can operate on. To reach
this state, the mapblock must first go through the process of being "emerged".
This means that it is loaded from disk, and/or, if it isn't yet generated,
generated by the map generator.
Mapblocks are loaded in a broad area around each player. They become "unloaded"
again if no player is close enough. The engine commonly represents the contents
of unloaded mapblocks as `"ignore"` nodes.
A mapblock being "active" means that it is not only in memory, but also affected
by world simulation:
* Entities are active
* They are in memory as `ServerActiveObject`, exposed to Lua as `ObjectRef`
* They exist in Lua as luaentity tables
* ABMs are executed
* Node timers are executed
Also, when a mapblock is "activated", LBMs are executed. Mapblocks are active
in a smaller area around each player, and are "deactivated" again if no player
is close enough.
Related API functions:
* `core.compare_block_status`
* `core.forceload_block`
* `core.load_area`
* `core.emerge_area`
Coordinates
-----------
@ -2032,10 +2065,14 @@ The following items are predefined and have special properties.
* `"unknown"`: An item that represents every item which has not been registered
* `"air"`: The node which appears everywhere where no other node is
* `"ignore"`: Mapblocks which have not been yet generated consist of this node
* `""`: The player's hand, which is in use whenever the player wields no item
* Its rage and tool capabilities are also used as an fallback for the wield item
* It can be overridden to change those properties
* `"ignore"`: Mapblocks that are not loaded are represented using this node.
* Also used for nodes that have not yet been set by the map generator.
* This is also what appears outside of the map boundary.
* `""`: The player's hand, which is in use whenever the player wields no item.
* Its range and tool capabilities are also used as a fallback for the wielded item.
* It can be overridden to change those properties:
* globally using `core.override_item`
* per-player using the special `"hand"` inventory list
Amount and wear
---------------
@ -7648,6 +7685,8 @@ Misc.
* `core.forceload_block(pos[, transient[, limit]])`
* forceloads the position `pos`.
* this means that the mapblock containing `pos` will always be kept in the
`"active"` state, regardless of nearby players or server settings.
* returns `true` if area could be forceloaded
* If `transient` is `false` or absent, the forceload will be persistent
(saved between server runs). If `true`, the forceload will be transient
@ -9442,6 +9481,10 @@ ABM (ActiveBlockModifier) definition
Used by `core.register_abm`.
An active block modifier (ABM) is used to define a function that is continously
and randomly called for specific nodes (defined by `nodenames` and other conditions)
in active mapblocks.
```lua
{
label = "Lava cooling",