Difference between revisions of "minetest.register lbm"

From Minetest Developer Wiki
Jump to navigation Jump to search
(Created the page)
 
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{UnofficialLua}}
 
{{DISPLAYTITLE:minetest.register_lbm}}
 
{{DISPLAYTITLE:minetest.register_lbm}}
== Syntax ==
 
<source>
 
minetest.register_lbm(lbm_defintion_table)
 
</source>
 
  
== Description ==
+
Registers a LBM. See [https://minetest.gitlab.io/minetest/definition-tables/#lbm-loadingblockmodifier-definition the Lua API documentation] for information about the LBM definition.
The Loading Block Modifier consists of a function that is executed when the server loads nodes that match a passed filter.
+
 
 +
== Introducement time ==
 +
Originally, LBMs were written for legacy replacement jobs like when a mod defines a newer node to replace an older one, or to remove nodes from a removed mod from the world. Such replacement jobs usually only need to be carried out on mapblocks that were stored before the node was removed or replaced, as the changes that remove the node usually make it impossible to place such nodes into the world.
  
The LBM registered with the callback will only take effect if register_lbm gets called while the mod is loading.
+
LBMs use this property, for optimisation: The time you first load a world with a certain LBM gets stored by the engine as "introducement time" for the LBM to that world. As all mapblocks get stored with a timestamp, its easy to check whether the mapblock was stored before the introcuement time or after. In the default configuration, LBMs only get executed in mapblocks that were stored before the introducement.
  
<source enclose="none">lbm_defintion_table</source> is a table which can contain following fields:
+
This spares checking each node in the mapblock whether it matches one of the node and group names.
  
{| class="wikitable collapsible sortable"
+
This behaviour was added as optimisation, and of course can be relied on as well, but note that if people first load a world with your LBM being registered, then load it without the LBM and then load it with the LBM again, it will execute the LBM twice due to the introducement time being discarded.
!index
 
!description
 
|-
 
|<source enclose="none">name</source>
 
|an unique name for the LBM. It must be in "modname:something" notation. The name is used to distinguish the LBM from the others, thus changing the name resets the introducement time for the LBM.
 
|-
 
|<source enclose="none">nodenames</source>
 
|a list of the nodenames that should execute the function. <source enclose="none">"group:groupname"</source> is also possible, as well as names of non-registered nodes.
 
|-
 
|<source enclose="none">action</source>
 
|the function that is executed. The parameters are <source enclose="none">(pos, node)</source>
 
:* pos is the position of the node
 
:* node is the node
 
|}
 
  
== Use cases ==
+
The "introducement time" stays the same between engine restarts and only gets removed when you load the world without the LBM being registered.
  
Originally, LBMs were written for legacy replacement jobs like when a mod defines a new node or to remove nodes from a removed mod for the world. This is still the main use case for LBMs.
+
Setting run_at_every_load to true disables both tracking of the introducement time and the according optimisation.
  
 
== Example ==
 
== Example ==
Line 38: Line 23:
 
name = "modname:remove_fire",
 
name = "modname:remove_fire",
 
nodenames = {"fire:basic_flame", "fire:permanent_flame"},
 
nodenames = {"fire:basic_flame", "fire:permanent_flame"},
action = function(pos, node, active_object_count, active_object_count_wider)
+
action = function(pos, node)
 
minetest.set_node(pos, {name = "air:air"})
 
minetest.set_node(pos, {name = "air:air"})
 
end,
 
end,
Line 44: Line 29:
 
</source>
 
</source>
  
[[Category:Methods]]
+
[[Category:Methods|r]]

Latest revision as of 13:54, 25 October 2022

Mbox warning.png This page contains unofficial, low-quality Lua API documentation and is likely to be outdated or wrong. Do not rely on it!
For the official and up-to-date documentation, see Lua API Documentation.
Mbox warning.png This page has been proposed for deletion for the following reason: "Contains unofficial and potentially outdated, redundant and inconsistent Lua API information"
If you don't think that this page should be deleted, please explain why on the talk page.


Registers a LBM. See the Lua API documentation for information about the LBM definition.

Introducement time

Originally, LBMs were written for legacy replacement jobs like when a mod defines a newer node to replace an older one, or to remove nodes from a removed mod from the world. Such replacement jobs usually only need to be carried out on mapblocks that were stored before the node was removed or replaced, as the changes that remove the node usually make it impossible to place such nodes into the world.

LBMs use this property, for optimisation: The time you first load a world with a certain LBM gets stored by the engine as "introducement time" for the LBM to that world. As all mapblocks get stored with a timestamp, its easy to check whether the mapblock was stored before the introcuement time or after. In the default configuration, LBMs only get executed in mapblocks that were stored before the introducement.

This spares checking each node in the mapblock whether it matches one of the node and group names.

This behaviour was added as optimisation, and of course can be relied on as well, but note that if people first load a world with your LBM being registered, then load it without the LBM and then load it with the LBM again, it will execute the LBM twice due to the introducement time being discarded.

The "introducement time" stays the same between engine restarts and only gets removed when you load the world without the LBM being registered.

Setting run_at_every_load to true disables both tracking of the introducement time and the according optimisation.

Example

A cleanup LBM useful to execute after removal of the fire mod in order to clean up the world from the now unknown nodes:

minetest.register_lbm({
	name = "modname:remove_fire",
	nodenames = {"fire:basic_flame", "fire:permanent_flame"},
	action = function(pos, node)
		minetest.set_node(pos, {name = "air:air"})
	end,
})