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

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 43748dfba3f0d3105ac967cf06ff70421e9c8833..8a80303947c25ac41820bc8ca6fed8d726cfe2bc 100644 (file)
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -3590,6 +3590,12 @@ Helper functions
 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
   position.
     * returns the exact position on the surface of a pointed node
+* `minetest.get_tool_wear_after_use(uses [, initial_wear])`
+    * Simulates a tool being used once and returns the added wear,
+      such that, if only this function is used to calculate wear,
+      the tool will break exactly after `uses` times of uses
+    * `uses`: Number of times the tool can be used
+    * `initial_wear`: The initial wear the tool starts with (default: 0)
 * `minetest.get_dig_params(groups, tool_capabilities [, wear])`:
     Simulates an item that digs a node.
     Returns a table with the following fields:
@@ -6525,7 +6531,13 @@ an itemstring, a table or `nil`.
   or those of the hand if none are defined for this item type
 * `add_wear(amount)`
     * Increases wear by `amount` if the item is a tool, otherwise does nothing
+    * Valid `amount` range is [0,65536]
     * `amount`: number, integer
+* `add_wear_by_uses(max_uses)`
+    * Increases wear in such a way that, if only this function is called,
+      the item breaks after `max_uses` times
+    * Valid `max_uses` range is [0,65536]
+    * Does nothing if item is not a tool or if `max_uses` is 0
 * `add_item(item)`: returns leftover `ItemStack`
     * Put some item or stack onto this stack
 * `item_fits(item)`: returns `true` if item or stack can be fully added to

diff --git a/src/script/lua_api/l_item.cpp b/src/script/lua_api/l_item.cpp
index 27c1b887592c48cb02ebf11b5ddabc064c5d83cd..13d046d00f14474d1e9e7427cb4c71dcd34873cd 100644 (file)
--- a/src/script/lua_api/l_item.cpp
+++ b/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),

diff --git a/src/script/lua_api/l_item.h b/src/script/lua_api/l_item.h
index 180975061317225a04929fcc97d271dbbc1b1265..a392555d2c4beae7b0bda7a7eb9ed9d416f65a23 100644 (file)
--- a/src/script/lua_api/l_item.h
+++ b/src/script/lua_api/l_item.h
@@ -108,11 +108,20 @@ class LuaItemStack : public ModApiBase {
        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);

diff --git a/src/script/lua_api/l_util.cpp b/src/script/lua_api/l_util.cpp
index 97068ce4c36c9b1a8a2cdb6683e4c2785b5defe9..f774daf974b6ed3af7634feed009df2a54fa9d3b 100644 (file)
--- a/src/script/lua_api/l_util.cpp
+++ b/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);
 

diff --git a/src/script/lua_api/l_util.h b/src/script/lua_api/l_util.h
index cc55635776bddb00f03b0e0e43ba3c20ebb24a93..ec86c663229736ff0cac5c608d2c696ef3b635bf 100644 (file)
--- a/src/script/lua_api/l_util.h
+++ b/src/script/lua_api/l_util.h
@@ -50,6 +50,9 @@ class ModApiUtil : public ModApiBase
        // 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);
 

diff --git a/src/tool.cpp b/src/tool.cpp
index 075c6b3c5ff13f8bb5e5ada473d85d7c8e80f7ca..821ddf07d6b9a9289dc5f5eee086a2f99c399d9d 100644 (file)
--- a/src/tool.cpp
+++ b/src/tool.cpp
@@ -183,7 +183,7 @@ void ToolCapabilities::deserializeJson(std::istream &is)
        }
 }
 
-static u32 calculateResultWear(const u32 uses, const u16 initial_wear)
+u32 calculateResultWear(const u32 uses, const u16 initial_wear)
 {
        if (uses == 0) {
                // Trivial case: Infinite uses

diff --git a/src/tool.h b/src/tool.h
index 8409f59afcd234da41fb2b2b58bdd0b7738abde3..c2444a834c0100eee6b91cdbb40cd4fece03ead8 100644 (file)
--- a/src/tool.h
+++ b/src/tool.h
@@ -142,4 +142,5 @@ PunchDamageResult getPunchDamage(
                u16 initial_wear = 0
 );
 
+u32 calculateResultWear(const u32 uses, const u16 initial_wear);
 f32 getToolRange(const ItemDefinition &def_selected, const ItemDefinition &def_hand);