diff --git a/doc/lua_api.md b/doc/lua_api.md index 8b6ff856f..12b412dbe 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -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",