Add a lethal buffer so builds far past the border are safe

README.md

@@ -11,6 +11,7 @@ Each covered world can have its own boundary, allowing the playable space to fol
 - **Per-world boundaries** — rectangular regions define the playable area in each covered world.
 - **Advance warnings** — on-screen titles alert players while they are still inside the border's warning zone.
 - **Out-of-bounds damage** — players beyond the region take repeated damage until they return.
+- **Lethal buffer** — optionally, players further out are killed outright, and past the buffer nothing happens, so builds far from the map are safe for players teleported to them while no one can walk, ride or fly there, as long as the lethal band (buffer-width minus lethal-depth) is wider than a player can travel between two border checks. The plugin logs a warning on load when it is not. Respawn points inside the lethal band send players to the world spawn instead, and ender pearls, chorus fruit, Nether portals and End gateways cannot jump a player over the band.
 - **Gameplay-aware enforcement** — survival and adventure players are affected, with creative and spectator modes exempt.
 - **Staff bypass** — a permission allows authorized players to cross the boundary without warnings or damage.
 

src/main/java/net/tfminecraft/worldborder/WorldBorder.java

@@ -9,6 +9,8 @@
 
 import net.tfminecraft.worldborder.cache.Cache;
 import net.tfminecraft.worldborder.border.BorderManager;
+import net.tfminecraft.worldborder.border.RespawnGuard;
+import net.tfminecraft.worldborder.border.TeleportGuard;
 import net.tfminecraft.worldborder.command.CommandManager;
 import net.tfminecraft.worldborder.loader.ConfigLoader;
 
@@ -33,6 +35,8 @@ public void onEnable() {
         } else {
             getLogger().severe("Command 'worldborder' missing from plugin.yml");
         }
+        getServer().getPluginManager().registerEvents(new RespawnGuard(), this);
+        getServer().getPluginManager().registerEvents(new TeleportGuard(), this);
         borderManager.start();
         getLogger().info("WorldBorder enabled.");
     }

src/main/java/net/tfminecraft/worldborder/border/BorderManager.java

@@ -7,6 +7,7 @@
 
 import org.bukkit.Bukkit;
 import org.bukkit.GameMode;
+import org.bukkit.Location;
 import org.bukkit.entity.Player;
 import org.bukkit.scheduler.BukkitTask;
 
@@ -80,7 +81,24 @@ private void tick() {
                             15,
                             0);
                 }
-                case SAFE -> clearWarning(player);
+                case LETHAL -> {
+                    clearWarning(player);
+                    // Health straight to zero: no damage event, so armour, totems and
+                    // plugins that cancel damage can't carry anyone across the band.
+                    player.setHealth(0);
+                    if (!player.isDead()) {
+                        // Another plugin cancelled the death; don't let them walk on in the band.
+                        Location safe = RespawnGuard.safeSpot(player.getWorld(), region);
+                        if (player.teleport(safe)) {
+                            plugin.getLogger().info("Moved " + player.getName() + " out of the lethal band to "
+                                    + RespawnGuard.describe(player.getWorld(), safe) + " after their death was cancelled.");
+                        } else {
+                            plugin.getLogger().warning("Could not move " + player.getName()
+                                    + " out of the lethal band after their death was cancelled.");
+                        }
+                    }
+                }
+                case SAFE, BEYOND -> clearWarning(player);
             }
         }
     }
@@ -102,7 +120,7 @@ private void clearWarning(Player player) {
         }
     }
 
-    private boolean affects(Player player) {
+    static boolean affects(Player player) {
         GameMode mode = player.getGameMode();
         if (mode != GameMode.SURVIVAL && mode != GameMode.ADVENTURE) {
             return false;

src/main/java/net/tfminecraft/worldborder/border/Region.java

@@ -2,36 +2,81 @@
 
 public final class Region {
 
+    /** No lethal band: everything past the edge only takes the regular damage. */
+    public static final int NO_LETHAL_DEPTH = -1;
+    /** No outer limit: the damage (and lethal) band reaches out forever. */
+    public static final int ENDLESS_BUFFER = 0;
+
     public final String world;
     public final int minX;
     public final int maxX;
     public final int minZ;
     public final int maxZ;
+    /** Blocks past the edge where the lethal band starts, or {@link #NO_LETHAL_DEPTH}. */
+    public final int lethalDepth;
+    /** Blocks past the edge where the buffer ends and nothing happens, or {@link #ENDLESS_BUFFER}. */
+    public final int bufferWidth;
 
     public Region(String world, int minX, int maxX, int minZ, int maxZ) {
+        this(world, minX, maxX, minZ, maxZ, NO_LETHAL_DEPTH, ENDLESS_BUFFER);
+    }
+
+    public Region(String world, int minX, int maxX, int minZ, int maxZ, int lethalDepth, int bufferWidth) {
         this.world = world;
         this.minX = minX;
         this.maxX = maxX;
         this.minZ = minZ;
         this.maxZ = maxZ;
+        this.lethalDepth = lethalDepth;
+        this.bufferWidth = bufferWidth;
     }
 
     public enum Zone {
         SAFE,
         WARNING,
-        OUTSIDE
+        OUTSIDE,
+        LETHAL,
+        BEYOND
     }
 
     public Zone zoneAt(double x, double z, int graceInset) {
         double dist = Math.min(
                 Math.min(x - minX, maxX - x),
                 Math.min(z - minZ, maxZ - z));
         if (dist < 0) {
-            return Zone.OUTSIDE;
+            return outsideZone(-dist);
         }
         if (dist <= graceInset) {
             return Zone.WARNING;
         }
         return Zone.SAFE;
     }
+
+    /**
+     * Band for a player {@code depth} blocks past the edge, measured along the furthest
+     * axis so the bands are square like the border itself.
+     */
+    private Zone outsideZone(double depth) {
+        if (bufferWidth > ENDLESS_BUFFER && depth > bufferWidth) {
+            return Zone.BEYOND;
+        }
+        if (lethalDepth >= 0 && depth >= lethalDepth) {
+            return Zone.LETHAL;
+        }
+        return Zone.OUTSIDE;
+    }
+
+    /**
+     * Width of the lethal band in blocks, {@code 0} when there is none,
+     * or {@link Double#POSITIVE_INFINITY} when it never ends.
+     */
+    public double lethalBandWidth() {
+        if (lethalDepth < 0) {
+            return 0;
+        }
+        if (bufferWidth <= ENDLESS_BUFFER) {
+            return Double.POSITIVE_INFINITY;
+        }
+        return Math.max(0, bufferWidth - lethalDepth);
+    }
 }

src/main/java/net/tfminecraft/worldborder/border/RespawnGuard.java

@@ -0,0 +1,54 @@
+package net.tfminecraft.worldborder.border;
+
+import org.bukkit.Location;
+import org.bukkit.World;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.Listener;
+import org.bukkit.event.player.PlayerRespawnEvent;
+
+import net.tfminecraft.worldborder.WorldBorder;
+import net.tfminecraft.worldborder.cache.Cache;
+
+/**
+ * A bed or anchor in the lethal band would kill the player again every border check,
+ * so respawns that would land there go to the world spawn instead.
+ */
+public final class RespawnGuard implements Listener {
+
+    // Runs after other plugins have picked the respawn point.
+    @EventHandler(priority = EventPriority.HIGHEST)
+    public void onRespawn(PlayerRespawnEvent event) {
+        if (!BorderManager.affects(event.getPlayer())) {
+            return;
+        }
+        Location to = event.getRespawnLocation();
+        World world = to.getWorld();
+        Region region = world == null ? null : Cache.borderForWorld(world.getName());
+        if (region == null || region.zoneAt(to.getX(), to.getZ(), Cache.graceInset) != Region.Zone.LETHAL) {
+            return;
+        }
+        Location safe = safeSpot(world, region);
+        event.setRespawnLocation(safe);
+        WorldBorder.plugin.getLogger().info("Moved " + event.getPlayer().getName()
+                + "'s respawn out of the lethal band (" + to.getBlockX() + ", " + to.getBlockZ()
+                + ") to " + describe(world, safe) + ".");
+    }
+
+    /** The world spawn, or the middle of the border when the spawn is out in the lethal band too. */
+    static Location safeSpot(World world, Region region) {
+        Location spawn = world.getSpawnLocation();
+        if (region.zoneAt(spawn.getX(), spawn.getZ(), Cache.graceInset) != Region.Zone.LETHAL) {
+            return spawn;
+        }
+        int x = (int) Math.floorDiv((long) region.minX + region.maxX, 2L);
+        int z = (int) Math.floorDiv((long) region.minZ + region.maxZ, 2L);
+        return new Location(world, x + 0.5, world.getHighestBlockYAt(x, z) + 1, z + 0.5);
+    }
+
+    static String describe(World world, Location safe) {
+        return safe.equals(world.getSpawnLocation())
+                ? "the spawn of " + world.getName()
+                : "the centre of the " + world.getName() + " border";
+    }
+}

src/main/java/net/tfminecraft/worldborder/border/TeleportGuard.java

@@ -0,0 +1,70 @@
+package net.tfminecraft.worldborder.border;
+
+import java.util.EnumSet;
+import java.util.Set;
+
+import org.bukkit.Location;
+import org.bukkit.World;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.Listener;
+import org.bukkit.event.player.PlayerPortalEvent;
+import org.bukkit.event.player.PlayerTeleportEvent;
+import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause;
+
+import net.tfminecraft.worldborder.WorldBorder;
+import net.tfminecraft.worldborder.cache.Cache;
+
+/**
+ * The border is only checked every few ticks, so a jump that lands past the lethal band
+ * (an ender pearl cannon, chorus fruit, a portal) would never be seen inside it. Teleports
+ * players set off themselves can't land in the lethal band or past the buffer; staff and
+ * plugin teleports (COMMAND, PLUGIN) still can, which is how players reach far builds.
+ * Leaving the End (END_PORTAL) is left alone: it only goes to a bed or the world spawn, and
+ * a bed past the buffer means the player was sent out there.
+ */
+public final class TeleportGuard implements Listener {
+
+    static final Set<TeleportCause> PLAYER_TELEPORTS = EnumSet.of(
+            TeleportCause.ENDER_PEARL,
+            TeleportCause.CONSUMABLE_EFFECT,
+            TeleportCause.NETHER_PORTAL,
+            TeleportCause.END_GATEWAY);
+
+    @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)
+    public void onTeleport(PlayerTeleportEvent event) {
+        check(event);
+    }
+
+    // Portal events have their own handler list, so they need their own handler.
+    @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)
+    public void onPortal(PlayerPortalEvent event) {
+        check(event);
+    }
+
+    private void check(PlayerTeleportEvent event) {
+        if (!PLAYER_TELEPORTS.contains(event.getCause()) || !BorderManager.affects(event.getPlayer())) {
+            return;
+        }
+        Location to = event.getTo();
+        World world = to == null ? null : to.getWorld();
+        Region region = world == null ? null : Cache.borderForWorld(world.getName());
+        if (region == null) {
+            return;
+        }
+        Region.Zone zone = region.zoneAt(to.getX(), to.getZ(), Cache.graceInset);
+        if (zone != Region.Zone.LETHAL && zone != Region.Zone.BEYOND) {
+            return;
+        }
+        Location from = event.getFrom();
+        if (world.equals(from.getWorld())
+                && region.zoneAt(from.getX(), from.getZ(), Cache.graceInset) == Region.Zone.BEYOND) {
+            // Already out past the buffer, e.g. a pearl thrown around a far build.
+            return;
+        }
+        event.setCancelled(true);
+        WorldBorder.plugin.getLogger().info("Stopped " + event.getPlayer().getName() + "'s "
+                + event.getCause() + " teleport to " + zone + " (" + to.getBlockX() + ", " + to.getBlockZ()
+                + ") in " + world.getName() + ".");
+    }
+}

src/main/java/net/tfminecraft/worldborder/cache/Cache.java

@@ -19,6 +19,14 @@ private Cache() {}
     public static int graceInset = 20;
     public static String titleWarning = "§cTurn back";
     public static String subtitleWarning = "§cYou feel continuing further would be very dangerous...";
+    /**
+     * Fastest a player can travel, in blocks per second. Only used to warn when a
+     * lethal band is narrow enough to cross between two border checks. The default
+     * is roughly the most the server's movement check normally accepts from an elytra
+     * flight (about 17 blocks a tick). It is a guideline, not a hard limit: lag or a
+     * client that holds back packets can move further, so keep bands well above it.
+     */
+    public static double maxTravelSpeed = 350.0;
 
     /**
      * When empty, borders apply to any world with an entry in {@link #borders}.

src/main/java/net/tfminecraft/worldborder/command/CommandManager.java

@@ -68,6 +68,19 @@ private void sendDebug(Player player) {
         player.sendMessage("§7Zone: " + formatZone(zone));
         player.sendMessage("§7Border: §fx " + region.minX + "-" + region.maxX
                 + ", z " + region.minZ + "-" + region.maxZ);
+        player.sendMessage("§7Buffer: §f" + describeBuffer(region));
+    }
+
+    private static String describeBuffer(Region region) {
+        boolean lethalBand = region.lethalDepth != Region.NO_LETHAL_DEPTH
+                && (region.bufferWidth == Region.ENDLESS_BUFFER || region.lethalDepth <= region.bufferWidth);
+        String lethal = lethalBand
+                ? "lethal from " + region.lethalDepth + " blocks out"
+                : "no lethal band";
+        String end = region.bufferWidth == Region.ENDLESS_BUFFER
+                ? "no outer limit"
+                : "ends " + region.bufferWidth + " blocks out";
+        return lethal + ", " + end;
     }
 
     private static String formatCoord(double value) {
@@ -82,6 +95,8 @@ private static String formatZone(Region.Zone zone) {
             case SAFE -> "§aSAFE";
             case WARNING -> "§cWARNING";
             case OUTSIDE -> "§cOUTSIDE";
+            case LETHAL -> "§4LETHAL";
+            case BEYOND -> "§bBEYOND";
         };
     }
 

src/main/java/net/tfminecraft/worldborder/loader/ConfigLoader.java

@@ -29,6 +29,7 @@ public void load(File configFile) {
         Cache.graceInset = Math.max(0, config.getInt("grace-inset", 20));
         Cache.titleWarning = config.getString("title-warning", Cache.titleWarning);
         Cache.subtitleWarning = config.getString("subtitle-warning", Cache.subtitleWarning);
+        Cache.maxTravelSpeed = Math.max(0.0, config.getDouble("max-travel-speed", 350.0));
 
         Cache.worlds = new java.util.ArrayList<>(config.getStringList("worlds"));
 
@@ -48,9 +49,48 @@ public void load(File configFile) {
                                     + ", z: " + minZ + "-" + maxZ + ")");
                     continue;
                 }
-                borders.put(worldKey, new Region(worldKey, minX, maxX, minZ, maxZ));
+                int lethalDepth = config.getInt(path + "lethal-depth", Region.NO_LETHAL_DEPTH);
+                if (lethalDepth < 0) {
+                    lethalDepth = Region.NO_LETHAL_DEPTH;
+                }
+                int bufferWidth = Math.max(Region.ENDLESS_BUFFER,
+                        config.getInt(path + "buffer-width", Region.ENDLESS_BUFFER));
+                Region region = new Region(worldKey, minX, maxX, minZ, maxZ, lethalDepth, bufferWidth);
+                warnIfBufferCanBeCrossed(region);
+                borders.put(worldKey, region);
             }
         }
         Cache.borders = borders;
     }
+
+    /**
+     * The border is only checked every tick-interval-ticks, so a lethal band narrower than
+     * one check's worth of travel can be flown across without ever being seen inside it.
+     */
+    private void warnIfBufferCanBeCrossed(Region region) {
+        if (region.bufferWidth == Region.ENDLESS_BUFFER) {
+            return;
+        }
+        if (region.lethalDepth == Region.NO_LETHAL_DEPTH) {
+            WorldBorder.plugin.getLogger().warning(
+                    "Border for world '" + region.world + "' has buffer-width " + region.bufferWidth
+                            + " but no lethal-depth: anyone who survives the damage can cross the buffer.");
+            return;
+        }
+        if (region.lethalDepth > region.bufferWidth) {
+            WorldBorder.plugin.getLogger().warning(
+                    "Border for world '" + region.world + "' has lethal-depth " + region.lethalDepth
+                            + " past buffer-width " + region.bufferWidth
+                            + ", so there is no lethal band: anyone who survives the damage can cross the buffer.");
+            return;
+        }
+        double minimum = Cache.maxTravelSpeed * Cache.tickIntervalTicks / 20.0;
+        if (region.lethalBandWidth() < minimum) {
+            WorldBorder.plugin.getLogger().warning(
+                    "Border for world '" + region.world + "' has a lethal band of " + region.lethalBandWidth()
+                            + " blocks (lethal-depth " + region.lethalDepth + " to buffer-width " + region.bufferWidth
+                            + "): at max-travel-speed " + Cache.maxTravelSpeed + " it needs at least "
+                            + minimum + " blocks so no one crosses it between checks.");
+        }
+    }
 }