on_deactivate: distinguish removal and unloading (#11931)

Sometimes you need to be able to do removal-related cleanup, such as removing files from disk, or entries from a database. staticdata obviously isn't suitable for large data. The data shouldn't be removed if the entity is unloaded, only if it is removed.

doc/lua_api.txt

@@ -4551,8 +4551,14 @@ Callbacks:
     * Called when the object is instantiated.
     * `dtime_s` is the time passed since the object was unloaded, which can be
       used for updating the entity state.
-* `on_deactivate(self)
+* `on_deactivate(self, removal)
     * Called when the object is about to get removed or unloaded.
+	* `removal`: boolean indicating whether the object is about to get removed.
+	  Calling `object:remove()` on an active object will call this with `removal=true`.
+	  The mapblock the entity resides in being unloaded will call this with `removal=false`.
+	* Note that this won't be called if the object hasn't been activated in the first place.
+	  In particular, `minetest.clear_objects({mode = "full"})` won't call this,
+	  whereas `minetest.clear_objects({mode = "quick"})` might call this.
 * `on_step(self, dtime)`
     * Called on every server tick, after movement and collision processing.
       `dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting

games/devtest/mods/testentities/callbacks.lua

@@ -31,8 +31,8 @@ minetest.register_entity("testentities:callback", {
 	on_activate = function(self, staticdata, dtime_s)
 		message("Callback entity: on_activate! pos="..spos(self).."; dtime_s="..dtime_s)
 	end,
-	on_deactivate = function(self)
-		message("Callback entity: on_deactivate! pos="..spos(self))
+	on_deactivate = function(self, removal)
+		message("Callback entity: on_deactivate! pos="..spos(self) .. "; removal=" .. tostring(removal))
 	end,
 	on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir, damage)
 		local name = get_object_name(puncher)

src/script/cpp_api/s_entity.cpp

@@ -103,7 +103,7 @@ void ScriptApiEntity::luaentity_Activate(u16 id,
 	lua_pop(L, 2); // Pop object and error handler
 }
 
-void ScriptApiEntity::luaentity_Deactivate(u16 id)
+void ScriptApiEntity::luaentity_Deactivate(u16 id, bool removal)
 {
 	SCRIPTAPI_PRECHECKHEADER
 
@@ -120,9 +120,9 @@ void ScriptApiEntity::luaentity_Deactivate(u16 id)
 	if (!lua_isnil(L, -1)) {
 		luaL_checktype(L, -1, LUA_TFUNCTION);
 		lua_pushvalue(L, object);
-
+		lua_pushboolean(L, removal);
 		setOriginFromTable(object);
-		PCALL_RES(lua_pcall(L, 1, 0, error_handler));
+		PCALL_RES(lua_pcall(L, 2, 0, error_handler));
 	} else {
 		lua_pop(L, 1);
 	}

src/script/cpp_api/s_entity.h

@@ -33,7 +33,7 @@ public:
 	bool luaentity_Add(u16 id, const char *name);
 	void luaentity_Activate(u16 id,
 			const std::string &staticdata, u32 dtime_s);
-	void luaentity_Deactivate(u16 id);
+	void luaentity_Deactivate(u16 id, bool removal);
 	void luaentity_Remove(u16 id);
 	std::string luaentity_GetStaticdata(u16 id);
 	void luaentity_GetProperties(u16 id,

src/server/luaentity_sao.cpp

@@ -117,13 +117,13 @@ void LuaEntitySAO::addedToEnvironment(u32 dtime_s)
 	}
 }
 
-void LuaEntitySAO::dispatchScriptDeactivate()
+void LuaEntitySAO::dispatchScriptDeactivate(bool removal)
 {
 	// Ensure that this is in fact a registered entity,
 	// and that it isn't already gone.
 	// The latter also prevents this from ever being called twice.
 	if (m_registered && !isGone())
-		m_env->getScriptIface()->luaentity_Deactivate(m_id);
+		m_env->getScriptIface()->luaentity_Deactivate(m_id, removal);
 }
 
 void LuaEntitySAO::step(float dtime, bool send_recommended)

src/server/luaentity_sao.h

@@ -80,9 +80,9 @@ public:
 	bool collideWithObjects() const;
 
 protected:
-	void dispatchScriptDeactivate();
-	virtual void onMarkedForDeactivation() { dispatchScriptDeactivate(); }
-	virtual void onMarkedForRemoval() { dispatchScriptDeactivate(); }
+	void dispatchScriptDeactivate(bool removal);
+	virtual void onMarkedForDeactivation() { dispatchScriptDeactivate(false); }
+	virtual void onMarkedForRemoval() { dispatchScriptDeactivate(true); }
 
 private:
 	std::string getPropertyPacket();