is_area_protected: Rename from intersects_protection (#7073)

* is_area_protected: Rename from intersects_protection
Return first protected position
Clarify docs: Mods may overwrite the function

diff --git a/builtin/game/misc.lua b/builtin/game/misc.lua
index 6e54dad5e253b5a7f6012c697cc75f37d0af5b78..2e05cdc41a803367e1e19480b9d627d6407e8dc4 100644 (file)
--- a/builtin/game/misc.lua
+++ b/builtin/game/misc.lua
@@ -175,7 +175,7 @@ end
 
 -- Checks if specified volume intersects a protected volume
 
-function core.intersects_protection(minp, maxp, player_name, interval)
+function core.is_area_protected(minp, maxp, player_name, interval)
        -- 'interval' is the largest allowed interval for the 3D lattice of checks.
 
        -- Compute the optimal float step 'd' for each axis so that all corners and
@@ -188,14 +188,18 @@ function core.intersects_protection(minp, maxp, player_name, interval)
        local d = {}
 
        for _, c in pairs({"x", "y", "z"}) do
+               if minp[c] > maxp[c] then
+                       -- Repair positions: 'minp' > 'maxp'
+                       local tmp = maxp[c]
+                       maxp[c] = minp[c]
+                       minp[c] = tmp
+               end
+
                if maxp[c] > minp[c] then
                        d[c] = (maxp[c] - minp[c]) /
                                math.ceil((maxp[c] - minp[c]) / interval) - 1e-4
-               elseif maxp[c] == minp[c] then
+               else
                        d[c] = 1 -- Any value larger than 0 to avoid division by zero
-               else -- maxp[c] < minp[c], print error and treat as protection intersected
-                       minetest.log("error", "maxp < minp in 'minetest.intersects_protection()'")
-                       return true
                end
        end
 
@@ -205,13 +209,13 @@ function core.intersects_protection(minp, maxp, player_name, interval)
                        local y = math.floor(yf + 0.5)
                        for xf = minp.x, maxp.x, d.x do
                                local x = math.floor(xf + 0.5)
-                               if core.is_protected({x = x, y = y, z = z}, player_name) then
-                                       return true
+                               local pos = {x = x, y = y, z = z}
+                               if core.is_protected(pos, player_name) then
+                                       return pos
                                end
                        end
                end
        end
-
        return false
 end
 

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 5f06a4ccc4f7f79a89f208dfb69edf7f10a6d079..962a56e10f67ffc3e06a2d31036ca5095b18ba3c 100644 (file)
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -3429,9 +3429,10 @@ These functions return the leftover itemstack.
 * `minetest.record_protection_violation(pos, name)`
     * This function calls functions registered with
       `minetest.register_on_protection_violation`.
-* `minetest.intersects_protection(minp, maxp, player_name, interval)
-    * Returns a boolean, returns true if the volume defined by `minp` and `maxp`
-      intersects a protected area not owned by `player_name`.
+* `minetest.is_area_protected(pos1, pos2, player_name, interval)
+    * Returns the position of the first node that `player_name` may not modify in
+      the specified cuboid between `pos1` and `pos2`.
+    * Returns `false` if no protections were found.
     * Applies `is_protected()` to a 3D lattice of points in the defined volume.
       The points are spaced evenly throughout the volume and have a spacing
       similar to, but no larger than, `interval`.
@@ -3439,6 +3440,8 @@ These functions return the leftover itemstack.
     * `interval` defaults to 4.
     * `interval` should be carefully chosen and maximised to avoid an excessive
       number of points being checked.
+    * Like `minetest.is_protected`, this function may be extended or overwritten by
+      mods to provide a faster implementation to check the cuboid for intersections.
 * `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)`
     * Attempt to predict the desired orientation of the facedir-capable node
       defined by `itemstack`, and place it accordingly (on-wall, on the floor, or