Difference between revisions of "minetest.register lbm"

From Minetest Developer Wiki
Jump to navigation Jump to search
(Created the page)
 
Line 7: Line 7:
 
== Description ==
 
== Description ==
 
The Loading Block Modifier consists of a function that is executed when the server loads nodes that match a passed filter.
 
The Loading Block Modifier consists of a function that is executed when the server loads nodes that match a passed filter.
 
The LBM registered with the callback will only take effect if register_lbm gets called while the mod is loading.
 
  
 
<source enclose="none">lbm_defintion_table</source> is a table which can contain following fields:
 
<source enclose="none">lbm_defintion_table</source> is a table which can contain following fields:
Line 21: Line 19:
 
|<source enclose="none">nodenames</source>  
 
|<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.
 
|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">run_at_every_load</source>
 +
|whether to run the LBM at every load of matching nodes, and not just for nodes that were last stored before the LBM got introduced.
 
|-
 
|-
 
|<source enclose="none">action</source>
 
|<source enclose="none">action</source>
Line 28: Line 29:
 
|}
 
|}
  
== Use cases ==
+
The LBM will only take effect if register_lbm gets called while the mod is loading.
 +
 
 +
== 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.
 +
 
 +
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.
+
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.
  
 
== Example ==
 
== Example ==

Revision as of 02:22, 10 March 2016

Syntax

minetest.register_lbm(lbm_defintion_table)

Description

The Loading Block Modifier consists of a function that is executed when the server loads nodes that match a passed filter.

lbm_defintion_table is a table which can contain following fields:

index description
name 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.
nodenames a list of the nodenames that should execute the function. "group:groupname" is also possible, as well as names of non-registered nodes.
run_at_every_load whether to run the LBM at every load of matching nodes, and not just for nodes that were last stored before the LBM got introduced.
action the function that is executed. The parameters are (pos, node)
  • pos is the position of the node
  • node is the node

The LBM will only take effect if register_lbm gets called while the mod is loading.

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.

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

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.

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, active_object_count, active_object_count_wider)
		minetest.set_node(pos, {name = "air:air"})
	end,
})