Add on_flood() callback.

This callback is called if a liquid definitely floods a non-air
node on the map. The callback arguments are (pos, oldnode, newnode)
and can return a `bool` value indicating whether flooding the
node should be cancelled (`return true` will prevent the node
from flooding).

Documentation is added, the callback function was tested with a
modified minetest_game.

Note that `return true` will likely cause the node's `on_flood()`
callback to be called every second until the node gets removed,
so care must be taken to prevent many callbacks from using this
return value. The current default liquid update interval is 1.0
seconds, which isn't unmanageable.

The larger aim of this patch is to remove the lava cooling ABM,
which is a significant cost to idle servers that have lava on their
map. This callback will be much more efficient.

2 files changed, 22 insertions, 0 deletions

diff --git a/src/script/cpp_api/s_node.cpp b/src/script/cpp_api/s_node.cpp
index adad01e45..2723f84e1 100644
--- a/src/script/cpp_api/s_node.cpp
+++ b/src/script/cpp_api/s_node.cpp
@@ -178,6 +178,27 @@ void ScriptApiNode::node_on_destruct(v3s16 p, MapNode node)
 	lua_pop(L, 1);  // Pop error handler
 }
 
+bool ScriptApiNode::node_on_flood(v3s16 p, MapNode node, MapNode newnode)
+{
+	SCRIPTAPI_PRECHECKHEADER
+
+	int error_handler = PUSH_ERROR_HANDLER(L);
+
+	INodeDefManager *ndef = getServer()->ndef();
+
+	// Push callback function on stack
+	if (!getItemCallback(ndef->get(node).name.c_str(), "on_flood"))
+		return false;
+
+	// Call function
+	push_v3s16(L, p);
+	pushnode(L, node, ndef);
+	pushnode(L, newnode, ndef);
+	PCALL_RES(lua_pcall(L, 3, 1, error_handler));
+	lua_remove(L, error_handler);
+	return (bool) lua_isboolean(L, -1) && (bool) lua_toboolean(L, -1) == true;
+}
+
 void ScriptApiNode::node_after_destruct(v3s16 p, MapNode node)
 {
 	SCRIPTAPI_PRECHECKHEADER
diff --git a/src/script/cpp_api/s_node.h b/src/script/cpp_api/s_node.h
index fe1180cb3..eb127909d 100644
--- a/src/script/cpp_api/s_node.h
+++ b/src/script/cpp_api/s_node.h
@@ -42,6 +42,7 @@ public:
 			ServerActiveObject *digger);
 	void node_on_construct(v3s16 p, MapNode node);
 	void node_on_destruct(v3s16 p, MapNode node);
+	bool node_on_flood(v3s16 p, MapNode node, MapNode newnode);
 	void node_after_destruct(v3s16 p, MapNode node);
 	bool node_on_timer(v3s16 p, MapNode node, f32 dtime);
 	void node_on_receive_fields(v3s16 p,