fix(teleport): require same dimension for visits

README.md

@@ -36,6 +36,8 @@ The plugin JAR is written to `build/libs/`.
 /basesettings bossbar <enable|disable>
 ```
 
+Navigation particles appear only in the base's world and when the player is more than 25 blocks beyond the current base border.
+
 After 250 Survival-mode block placements anywhere by default, the spawnable overlay can mark nearby dark hostile-mob spawning surfaces inside the player's base with owner-only red particles. The threshold is configurable.
 
 `/base` has a stationary warm-up. Looking around is allowed, while movement between blocks, damage, teleportation, world changes, death, logout, and conflicting teleport commands cancel it without consuming the cooldown.

design/log.md

@@ -84,3 +84,10 @@ description: Chronological record of material decisions affecting the Spigot Bas
 - Added admin controls for total placement progress, the unlock threshold, and each unlocked player's overlay preference.
 - Added owner-only red particles for nearby dark spawning surfaces inside base bounds, using bounded incremental scanning and rendering budgets.
 - Verified the feature with `./gradlew clean check jar`.
+
+## 2026-08-10 — Navigation visibility buffer
+
+- Limited enabled base navigation particles to the base's world and positions more than 25 horizontal blocks beyond the current base border.
+- Used the live size-tier radius so expansion and relocation immediately update the visibility threshold.
+- Added exact-boundary and controller integration coverage.
+- Verified the change with `./gradlew clean check jar`.

design/user-stories/us-002-unlock-base-navigation.md

@@ -14,7 +14,9 @@ As a **player with Base I**, I want visual guidance toward my base so that I can
 - [x] Base II requires Base I and an established base.
 - [x] Base II unlocks at a configurable cumulative grass-or-dirt threshold that defaults to 500 blocks, 250 more than Base I.
 - [x] Base II provides particle-based navigation and does not grant or require a physical compass item.
-- [x] While enabled and in the base's world, particles are drawn along the ground to indicate the direction toward the base.
+- [x] While enabled and in the base's world, particles are drawn along the ground only when the player is horizontally more than 25 blocks beyond the current base border.
+- [x] No navigation particles appear inside the base, exactly 25 blocks beyond its border, or anywhere within that buffer.
+- [x] Expansion and relocation update the navigation visibility threshold immediately.
 - [x] Particle generation is bounded to avoid excessive server or client load.
 - [x] A player in another world receives a clear message instead of a misleading particle direction.
 - [x] `/basesettings navigation enable` enables guidance idempotently after Base II is unlocked, and `/basesettings navigation disable` disables it idempotently.

design/user-stories/us-004-unlock-and-control-base-flight.md

@@ -21,7 +21,7 @@ As a **player with Base I**, I want to unlock controlled flight around my base s
 - [x] Flight II expands the vertical range to 100 blocks below and above base Y by default.
 - [x] Flight III expands the vertical range to the world's minimum and maximum build heights.
 - [x] A configurable five-block horizontal warning buffer extends beyond the current base radius.
-- [x] Plugin-granted flight remains active in the warning buffer and displays prominent on-screen notice that the player is leaving the base.
+- [x] Plugin-granted flight remains active in the warning buffer, and a prominent on-screen notice that the player is leaving the base appears only while the player is actively flying.
 - [x] Passing beyond the warning buffer removes only flight granted by this plugin.
 - [x] Flight is not granted outside the unlocked vertical range.
 - [x] `/basesettings flight enable` enables unlocked flight idempotently, and `/basesettings flight disable` disables it idempotently.

design/user-stories/us-008-unlock-visitor-access.md

@@ -21,7 +21,8 @@ As a **player with Base III**, I want to open my base to visitors so that other
 - [x] `/gotobase <owner>` autocompletes bases that the requesting player is currently eligible to visit.
 - [x] `/visit <owner>` aliases `/gotobase <owner>` with identical autocomplete, including eligible bases whose owners are offline.
 - [x] Enabled bases remain visitable while their owners are offline.
-- [x] A visitor teleport uses the destination owner's current warm-up tier.
+- [x] `/visit` and `/gotobase` require the visitor to be in the destination base's recorded world; cross-dimension requests are rejected before warm-up with a clear message and without consuming cooldown.
+- [x] A visitor teleport uses the destination owner's current warm-up tier, but always requires at least a one-second stationary warm-up; `/visit` and `/gotobase` never teleport instantly.
 - [x] Looking around is permitted, while movement between block coordinates, damage, teleportation, world change, death, logout, or a conflicting teleport cancels the visitor warm-up.
 - [x] Cancellation or destination failure does not consume a visitor cooldown.
 - [x] A safe destination is resolved at or near the owner's recorded base center.

src/main/java/games/dmg/spigotbase/BaseFlightController.java

@@ -112,7 +112,7 @@ final class BaseFlightController implements Runnable {
             player.setAllowFlight(true);
             grantedFlight.add(player.getUniqueId());
         }
-        if (distanceSquared > (double) radius * radius) {
+        if (distanceSquared > (double) radius * radius && player.isFlying()) {
             if (warned.add(player.getUniqueId())) {
                 player.sendTitle(
                     ChatColor.RED + "Leaving Your Base",

src/main/java/games/dmg/spigotbase/BaseNavigationController.java

@@ -10,6 +10,7 @@ final class BaseNavigationController implements Runnable {
     private final Server server;
     private final BaseStateManager stateManager;
     private final PluginSettingsProvider settings;
+    private final BaseBoundsService boundsService;
 
     BaseNavigationController(
         Server server,
@@ -19,6 +20,7 @@ final class BaseNavigationController implements Runnable {
         this.server = server;
         this.stateManager = stateManager;
         this.settings = settings;
+        this.boundsService = new BaseBoundsService(settings);
     }
 
     @Override
@@ -32,7 +34,16 @@ final class BaseNavigationController implements Runnable {
             if (!player.getWorld().getUID().equals(base.worldId())) {
                 continue;
             }
-            Location origin = player.getLocation().clone().add(0.0, 0.15, 0.0);
+            Location playerLocation = player.getLocation();
+            if (!BaseNavigationVisibility.isBeyondBorderBuffer(
+                    base,
+                    boundsService.radius(state),
+                    playerLocation.getX(),
+                    playerLocation.getZ()
+            )) {
+                continue;
+            }
+            Location origin = playerLocation.clone().add(0.0, 0.15, 0.0);
             Vector direction = new Vector(
                 base.x() + 0.5 - origin.getX(),
                 0.0,

src/main/java/games/dmg/spigotbase/BaseNavigationVisibility.java

@@ -0,0 +1,26 @@
+package games.dmg.spigotbase;
+
+final class BaseNavigationVisibility {
+    static final int BORDER_BUFFER = 25;
+
+    private BaseNavigationVisibility() {
+    }
+
+    static boolean isBeyondBorderBuffer(
+        BaseLocation base,
+        int radius,
+        double playerX,
+        double playerZ
+    ) {
+        if (base == null) {
+            throw new IllegalArgumentException("base is required");
+        }
+        if (radius <= 0) {
+            throw new IllegalArgumentException("base radius must be positive");
+        }
+        double deltaX = playerX - (base.x() + 0.5);
+        double deltaZ = playerZ - (base.z() + 0.5);
+        double minimumDistance = radius + BORDER_BUFFER;
+        return deltaX * deltaX + deltaZ * deltaZ > minimumDistance * minimumDistance;
+    }
+}

src/main/java/games/dmg/spigotbase/BaseTeleportManager.java

@@ -83,6 +83,13 @@ final class BaseTeleportManager implements Listener {
             visitor.sendMessage(ChatColor.RED + "That base is not accepting visitors.");
             return;
         }
+        BaseLocation destination = owner.base().orElseThrow();
+        if (!visitor.getWorld().getUID().equals(destination.worldId())) {
+            visitor.sendMessage(
+                ChatColor.RED + "You must be in the same dimension as that base to visit it."
+            );
+            return;
+        }
         PlayerState visitorState = stateManager.player(visitor.getUniqueId(), visitor.getName());
         Optional<Duration> remaining = visitorPolicy.remaining(
             visitorState, owner.playerId(), clock.instant()
@@ -94,8 +101,8 @@ final class BaseTeleportManager implements Listener {
         }
         begin(
             visitor,
-            owner.base().orElseThrow(),
-            policy.warmup(owner),
+            destination,
+            policy.visitorWarmup(owner),
             owner.playerId(),
             policy.cooldown(owner),
             "visit " + owner.latestName() + "'s base"

src/main/java/games/dmg/spigotbase/TeleportPolicy.java

@@ -25,6 +25,13 @@ public final class TeleportPolicy {
         };
     }
 
+    public Duration visitorWarmup(PlayerState owner) {
+        Duration warmup = warmup(owner);
+        return warmup.compareTo(Duration.ofSeconds(1)) < 0
+            ? Duration.ofSeconds(1)
+            : warmup;
+    }
+
     public Duration cooldown(PlayerState player) {
         return switch (player.cooldownLevel()) {
             case 0 -> Duration.ofSeconds(settings.current().initialTeleportCooldownSeconds());

src/test/java/games/dmg/spigotbase/BaseFlightControllerTest.java

@@ -0,0 +1,93 @@
+package games.dmg.spigotbase;
+
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import org.bukkit.Location;
+import org.bukkit.Server;
+import org.bukkit.World;
+import org.bukkit.entity.Player;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+final class BaseFlightControllerTest {
+    private final UUID playerId = UUID.randomUUID();
+    private final UUID worldId = UUID.randomUUID();
+    private final Server server = mock(Server.class);
+    private final BaseStateManager stateManager = mock(BaseStateManager.class);
+    private final Player player = mock(Player.class);
+    private final PlayerState state = PlayerState.newPlayer(playerId, "Alex")
+        .withGrassAndDirtProgress(250, 1)
+        .withBase(new BaseLocation(worldId, "world", 0, 64, 0, 0, 0), Instant.EPOCH)
+        .withFlightLevel(1, true);
+    private final BaseFlightController controller = new BaseFlightController(
+        server,
+        stateManager,
+        new SecondaryProgressionService(PluginSettings.from(Map.of())),
+        new BaseBoundsService(PluginSettings.from(Map.of())),
+        new PluginSettingsProvider(PluginSettings.from(Map.of()))
+    );
+
+    @BeforeEach
+    void setUp() {
+        World world = mock(World.class);
+        Location location = mock(Location.class);
+        PlayerInventory inventory = mock(PlayerInventory.class);
+
+        doReturn(List.of(player)).when(server).getOnlinePlayers();
+        when(player.getUniqueId()).thenReturn(playerId);
+        when(player.getName()).thenReturn("Alex");
+        when(player.getGameMode()).thenReturn(org.bukkit.GameMode.SURVIVAL);
+        when(player.getInventory()).thenReturn(inventory);
+        when(inventory.getStorageContents()).thenReturn(new ItemStack[0]);
+        when(stateManager.player(playerId, "Alex")).thenReturn(state);
+        when(player.getWorld()).thenReturn(world);
+        when(world.getUID()).thenReturn(worldId);
+        when(player.getLocation()).thenReturn(location);
+        when(location.getX()).thenReturn(12.5);
+        when(location.getZ()).thenReturn(0.5);
+        when(location.getBlockY()).thenReturn(64);
+        when(player.getAllowFlight()).thenReturn(true);
+    }
+
+    @Test
+    void walkingInWarningBufferDoesNotShowLeavingBaseWarning() {
+        when(player.isFlying()).thenReturn(false);
+
+        controller.run();
+
+        verify(player, never()).sendTitle(anyString(), anyString(), anyInt(), anyInt(), anyInt());
+    }
+
+    @Test
+    void flyingInWarningBufferShowsLeavingBaseWarning() {
+        when(player.isFlying()).thenReturn(true);
+
+        controller.run();
+
+        verify(player).sendTitle(anyString(), anyString(), anyInt(), anyInt(), anyInt());
+    }
+
+    @Test
+    void warningCanAppearAgainAfterPlayerStopsAndResumesFlyingInBuffer() {
+        when(player.isFlying()).thenReturn(true, false, true);
+
+        controller.run();
+        controller.run();
+        controller.run();
+
+        verify(player, times(2)).sendTitle(anyString(), anyString(), anyInt(), anyInt(), anyInt());
+    }
+}

src/test/java/games/dmg/spigotbase/BaseNavigationControllerTest.java

@@ -0,0 +1,60 @@
+package games.dmg.spigotbase;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.time.Instant;
+import java.util.Map;
+import java.util.UUID;
+import org.bukkit.Location;
+import org.bukkit.Particle;
+import org.bukkit.Server;
+import org.bukkit.World;
+import org.bukkit.entity.Player;
+import org.junit.jupiter.api.Test;
+
+final class BaseNavigationControllerTest {
+    @Test
+    void showsParticlesOnlyMoreThanTwentyFiveBlocksBeyondBorder() {
+        UUID playerId = UUID.randomUUID();
+        UUID worldId = UUID.randomUUID();
+        PlayerState state = PlayerState.newPlayer(playerId, "Builder")
+            .withAdministrativeLevels(2, 0, 0, 0, 0, true, false, false)
+            .withBase(new BaseLocation(worldId, "world", 0, 64, 0, 0, 0), Instant.EPOCH);
+        World world = mock(World.class);
+        when(world.getUID()).thenReturn(worldId);
+        Player player = mock(Player.class);
+        when(player.getUniqueId()).thenReturn(playerId);
+        when(player.getName()).thenReturn("Builder");
+        when(player.getWorld()).thenReturn(world);
+        when(player.getLocation()).thenReturn(new Location(world, 35.5, 64.0, 0.5));
+        Server server = mock(Server.class);
+        doReturn(java.util.List.of(player)).when(server).getOnlinePlayers();
+        BaseStateManager stateManager = mock(BaseStateManager.class);
+        when(stateManager.player(playerId, "Builder")).thenReturn(state);
+        PluginSettingsProvider settings = new PluginSettingsProvider(
+            PluginSettings.from(Map.of())
+        );
+
+        new BaseNavigationController(server, stateManager, settings).run();
+
+        verify(player, never()).spawnParticle(
+            eq(Particle.END_ROD), any(Location.class), eq(1),
+            eq(0.0), eq(0.0), eq(0.0), eq(0.0)
+        );
+
+        when(player.getLocation()).thenReturn(new Location(world, 35.51, 64.0, 0.5));
+        new BaseNavigationController(server, stateManager, settings).run();
+
+        verify(player, times(settings.current().navigationParticleCount())).spawnParticle(
+            eq(Particle.END_ROD), any(Location.class), eq(1),
+            eq(0.0), eq(0.0), eq(0.0), eq(0.0)
+        );
+    }
+}

src/test/java/games/dmg/spigotbase/BaseNavigationVisibilityTest.java

@@ -0,0 +1,26 @@
+package games.dmg.spigotbase;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.UUID;
+import org.junit.jupiter.api.Test;
+
+final class BaseNavigationVisibilityTest {
+    private static final BaseLocation BASE = new BaseLocation(
+        UUID.randomUUID(), "world", 0, 64, 0, 0, 0
+    );
+
+    @Test
+    void hidesNavigationAtAndWithinTwentyFiveBlocksBeyondBorder() {
+        assertFalse(BaseNavigationVisibility.isBeyondBorderBuffer(BASE, 10, 35.5, 0.5));
+        assertFalse(BaseNavigationVisibility.isBeyondBorderBuffer(BASE, 10, 20.5, 0.5));
+    }
+
+    @Test
+    void showsNavigationMoreThanTwentyFiveBlocksBeyondCurrentBorder() {
+        assertTrue(BaseNavigationVisibility.isBeyondBorderBuffer(BASE, 10, 35.51, 0.5));
+        assertFalse(BaseNavigationVisibility.isBeyondBorderBuffer(BASE, 75, 100.5, 0.5));
+        assertTrue(BaseNavigationVisibility.isBeyondBorderBuffer(BASE, 75, 100.51, 0.5));
+    }
+}

src/test/java/games/dmg/spigotbase/BaseTeleportManagerTest.java

@@ -0,0 +1,64 @@
+package games.dmg.spigotbase;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Optional;
+import java.util.UUID;
+import org.bukkit.ChatColor;
+import org.bukkit.World;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
+import org.junit.jupiter.api.Test;
+
+final class BaseTeleportManagerTest {
+    @Test
+    void visitFromAnotherWorldIsRejectedBeforeWarmupAndCooldownChecks() {
+        UUID visitorId = UUID.randomUUID();
+        UUID ownerId = UUID.randomUUID();
+        UUID baseWorldId = UUID.randomUUID();
+        BaseStateManager stateManager = mock(BaseStateManager.class);
+        TeleportPolicy teleportPolicy = mock(TeleportPolicy.class);
+        VisitorPolicy visitorPolicy = mock(VisitorPolicy.class);
+        Player visitor = mock(Player.class);
+        World visitorWorld = mock(World.class);
+        PlayerState owner = PlayerState.newPlayer(ownerId, "Owner")
+            .withGrassAndDirtProgress(500, 4)
+            .withBase(
+                new BaseLocation(baseWorldId, "world", 0, 64, 0, 0, 0),
+                Instant.EPOCH
+            )
+            .withVisitorsEnabled(true);
+        PlayerState visitorState = PlayerState.newPlayer(visitorId, "Visitor");
+        BaseTeleportManager manager = new BaseTeleportManager(
+            mock(Plugin.class),
+            stateManager,
+            teleportPolicy,
+            visitorPolicy,
+            mock(SafeBaseDestination.class),
+            Clock.systemUTC()
+        );
+
+        when(visitor.getUniqueId()).thenReturn(visitorId);
+        when(visitor.getName()).thenReturn("Visitor");
+        when(visitor.getWorld()).thenReturn(visitorWorld);
+        when(visitorWorld.getUID()).thenReturn(UUID.randomUUID());
+        when(stateManager.player(visitorId, "Visitor")).thenReturn(visitorState);
+        when(visitorPolicy.remaining(eq(visitorState), eq(ownerId), any()))
+            .thenReturn(Optional.of(Duration.ofSeconds(1)));
+
+        manager.startVisit(visitor, owner);
+
+        verify(visitor).sendMessage(
+            ChatColor.RED + "You must be in the same dimension as that base to visit it."
+        );
+        verifyNoInteractions(stateManager, teleportPolicy, visitorPolicy);
+    }
+}

src/test/java/games/dmg/spigotbase/TeleportPolicyTest.java

@@ -22,6 +22,17 @@ final class TeleportPolicyTest {
         assertEquals(Duration.ZERO, policy.warmup(player.withTeleportLevels(3, 0)));
     }
 
+    @Test
+    void visitorWarmupHasOneSecondMinimum() {
+        PlayerState player = baseThreePlayer();
+
+        assertEquals(Duration.ofSeconds(30), policy.visitorWarmup(player));
+        assertEquals(
+            Duration.ofSeconds(1),
+            policy.visitorWarmup(player.withTeleportLevels(3, 0))
+        );
+    }
+
     @Test
     void cooldownLevelsUseApprovedDurations() {
         PlayerState player = baseThreePlayer();