minetest.register lbm

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,
})