Add helper functions to make tool usable n times (#12047)

src/script/lua_api/l_item.cpp

@@ -343,7 +343,7 @@ int LuaItemStack::l_get_tool_capabilities(lua_State *L)
 }
 
 // add_wear(self, amount) -> true/false
-// The range for "amount" is [0,65535]. Wear is only added if the item
+// The range for "amount" is [0,65536]. Wear is only added if the item
 // is a tool. Adding wear might destroy the item.
 // Returns true if the item is (or was) a tool.
 int LuaItemStack::l_add_wear(lua_State *L)
@@ -357,6 +357,25 @@ int LuaItemStack::l_add_wear(lua_State *L)
 	return 1;
 }
 
+// add_wear_by_uses(self, max_uses) -> true/false
+// The range for "max_uses" is [0,65536].
+// Adds wear to the item in such a way that, if
+// only this function is called to add wear, the item
+// will be destroyed exactly after `max_uses` times of calling it.
+// No-op if `max_uses` is 0 or item is not a tool.
+// Returns true if the item is (or was) a tool.
+int LuaItemStack::l_add_wear_by_uses(lua_State *L)
+{
+	NO_MAP_LOCK_REQUIRED;
+	LuaItemStack *o = checkobject(L, 1);
+	ItemStack &item = o->m_stack;
+	u32 max_uses = readParam<int>(L, 2);
+	u32 add_wear = calculateResultWear(max_uses, item.wear);
+	bool result = item.addWear(add_wear, getGameDef(L)->idef());
+	lua_pushboolean(L, result);
+	return 1;
+}
+
 // add_item(self, itemstack or itemstring or table or nil) -> itemstack
 // Returns leftover item stack
 int LuaItemStack::l_add_item(lua_State *L)
@@ -532,6 +551,7 @@ const luaL_Reg LuaItemStack::methods[] = {
 	luamethod(LuaItemStack, get_definition),
 	luamethod(LuaItemStack, get_tool_capabilities),
 	luamethod(LuaItemStack, add_wear),
+	luamethod(LuaItemStack, add_wear_by_uses),
 	luamethod(LuaItemStack, add_item),
 	luamethod(LuaItemStack, item_fits),
 	luamethod(LuaItemStack, take_item),

src/script/lua_api/l_item.h

@@ -108,11 +108,20 @@ private:
 	static int l_get_tool_capabilities(lua_State *L);
 
 	// add_wear(self, amount) -> true/false
-	// The range for "amount" is [0,65535]. Wear is only added if the item
+	// The range for "amount" is [0,65536]. Wear is only added if the item
 	// is a tool. Adding wear might destroy the item.
 	// Returns true if the item is (or was) a tool.
 	static int l_add_wear(lua_State *L);
 
+	// add_wear_by_uses(self, max_uses) -> true/false
+	// The range for "max_uses" is [0,65536].
+	// Adds wear to the item in such a way that, if
+	// only this function is called to add wear, the item
+	// will be destroyed exactly after `max_uses` times of calling it.
+	// No-op if `max_uses` is 0 or item is not a tool.
+	// Returns true if the item is (or was) a tool.
+	static int l_add_wear_by_uses(lua_State *L);
+
 	// add_item(self, itemstack or itemstring or table or nil) -> itemstack
 	// Returns leftover item stack
 	static int l_add_item(lua_State *L);

src/script/lua_api/l_util.cpp

@@ -159,6 +159,17 @@ int ModApiUtil::l_write_json(lua_State *L)
 	return 1;
 }
 
+// get_tool_wear_after_use(uses[, initial_wear])
+int ModApiUtil::l_get_tool_wear_after_use(lua_State *L)
+{
+	NO_MAP_LOCK_REQUIRED;
+	u32 uses = readParam<int>(L, 1);
+	u16 initial_wear = readParam<int>(L, 2, 0);
+	u16 wear = calculateResultWear(uses, initial_wear);
+	lua_pushnumber(L, wear);
+	return 1;
+}
+
 // get_dig_params(groups, tool_capabilities[, wear])
 int ModApiUtil::l_get_dig_params(lua_State *L)
 {
@@ -586,6 +597,7 @@ void ModApiUtil::Initialize(lua_State *L, int top)
 	API_FCT(parse_json);
 	API_FCT(write_json);
 
+	API_FCT(get_tool_wear_after_use);
 	API_FCT(get_dig_params);
 	API_FCT(get_hit_params);
 

src/script/lua_api/l_util.h

@@ -50,6 +50,9 @@ private:
 	// write_json(data[, styled])
 	static int l_write_json(lua_State *L);
 
+	// get_tool_wear_after_use(uses[, initial_wear])
+	static int l_get_tool_wear_after_use(lua_State *L);
+
 	// get_dig_params(groups, tool_capabilities[, wear])
 	static int l_get_dig_params(lua_State *L);