fix(pocket-base): clear fall distance after portal travel

.gitea/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: gradle
 
       - name: Validate conventional commits

.gitea/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: gradle
 
       - name: Set up Node.js

README.md

@@ -1,6 +1,6 @@
 # Spigot Base
 
-A Spigot 26.2 plugin providing progression-gated player bases and quality-of-life unlocks.
+A Purpur 26.2 plugin providing progression-gated player bases and quality-of-life unlocks.
 
 Players begin by breaking Survival-mode grass blocks or dirt. The progression paths provide a persistent base, navigation particles, expanding base bounds, controlled flight, personal teleportation, and visitor teleportation.
 
@@ -8,8 +8,8 @@ The approved behavior is specified in the [OKF design bundle](design/index.md).
 
 ## Requirements
 
-- Spigot 26.2
-- Java 17 or newer
+- Purpur 26.2 build 2618
+- Java 25 or newer
 
 ## Build
 
@@ -48,7 +48,7 @@ After 250 Survival-mode block placements anywhere by default, the spawnable over
 
 `/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.
 
-Base IV owners can purchase and expand a persistent Pocket Base with `/basesettings pocket upgrade`. Activating a complete diamond-block portal frame inside the normal base with flint and steel opens one public entrance to the owner's grass platform in a private void world. The owner can move the return portal by building and igniting another complete frame inside the unlocked Pocket Base boundary; only the newly activated return portal remains functional. Natural hostile and passive mob spawning is disabled by default. Owners can control each category independently with `/basesettings pocket mobs <hostile|passive> <enable|disable>`.
+Base IV owners can purchase and expand a persistent Pocket Base with `/basesettings pocket upgrade`. Activating a complete diamond-block portal frame inside the normal base with flint and steel opens one public entrance to the owner's grass platform in a private void world. Players and non-player living mobs can travel through the entrance and active return portal; items, projectiles, and vehicles are not transported. The owner can move the return portal by building and igniting another complete frame inside the unlocked Pocket Base boundary; only the newly activated return portal remains functional. Natural hostile and passive mob spawning is disabled by default. Owners can control each category independently with `/basesettings pocket mobs <hostile|passive> <enable|disable>`.
 
 Owners can change biome metadata without altering Pocket Base blocks, entities, inventories, or portals by using `/basesettings pocket type <void|nether|overworld> <subtype>`. Void uses `the_void`; Nether and Overworld accept their compatible vanilla biome names, such as `crimson_forest` or `plains`. Each change defaults to 16 netherite blocks, is configurable, and affects applicable natural mob selection when spawning is enabled. The Pocket Base remains a void-generated normal-environment world; dimension-specific mechanics do not change.
 

build.gradle.kts

@@ -9,23 +9,23 @@ version = providers.gradleProperty("releaseVersion")
 
 repositories {
     mavenCentral()
-    maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
+    maven("https://repo.purpurmc.org/snapshots/")
 }
 
 java {
     toolchain {
-        languageVersion = JavaLanguageVersion.of(17)
+        languageVersion = JavaLanguageVersion.of(25)
     }
 }
 
 tasks.withType<JavaCompile>().configureEach {
-    options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror"))
+    options.compilerArgs.addAll(listOf("-Xlint:all,-deprecation,-removal", "-Werror"))
 }
 
 dependencies {
-    compileOnly("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
+    compileOnly("org.purpurmc.purpur:purpur-api:26.2.build.2618-stable")
 
-    testImplementation("org.spigotmc:spigot-api:26.2-R0.1-SNAPSHOT")
+    testImplementation("org.purpurmc.purpur:purpur-api:26.2.build.2618-stable")
     testImplementation(platform("org.junit:junit-bom:5.13.4"))
     testImplementation("org.junit.jupiter:junit-jupiter")
     testImplementation("org.mockito:mockito-core:5.18.0")

design/log.md

@@ -122,3 +122,30 @@ description: Chronological record of material decisions affecting the Spigot Bas
 - Retained the detailed chat report under `/basesettings status` and kept dialog actions routed through the existing validated command behavior.
 - Added dialog routing, autocomplete, alias, non-player, generated-control, locked-state, and purchase-confirmation coverage.
 - Verified the feature with `./gradlew clean check jar`.
+
+## 2026-08-24 — Purpur dialog runtime compatibility
+
+- Replaced the Spigot-only Bungee dialog types that were absent from production with Purpur's supported Paper dialog API.
+- Compiled and tested against the exact Purpur 26.2 build 2618 API with Java 25, and updated both CI workflows to use Java 25.
+- Preserved unit-test coverage through server-independent dialog specifications and adapted Bukkit test fixtures to Purpur's registry-aware API behavior.
+- Verified 128 tests and the Java 25 plugin artifact with `./gradlew clean check jar`.
+
+## 2026-08-25 — Static dialog command actions
+
+- Replaced macro command templates with static run-command actions for fixed dialog buttons.
+- Added regression coverage for the generated run-command action and its unchanged command payload.
+- Verified `/basesettings` opens without command exceptions on a local Purpur 26.2 build 2618 server.
+- Verified the plugin artifact with `./gradlew clean check jar`.
+
+## 2026-08-24 — Pocket Base mob portal travel
+
+- Added five-tick collision scanning that transports non-player living mobs through active Pocket Base entrance and return portals.
+- Reused safe player destinations and server-spawn fallback behavior while excluding items, projectiles, vehicles, and other non-living entities.
+- Applied the existing two-second portal cooldown to mobs to prevent immediate repeated transport.
+- Verified the feature and Java 25 plugin artifact with `./gradlew clean check jar`.
+
+## 2026-08-28 — Safe Pocket Base fall returns
+
+- Cleared accumulated fall distance whenever portal or void-return travel teleports an entity, preventing carried-over fall damage at the destination.
+- Added regression coverage for players falling out of a Pocket Base and returning to the server spawn.
+- Verified the fix and plugin artifact with `./gradlew clean check jar`.

design/user-stories/us-012-build-and-release-plugin.md

@@ -1,7 +1,7 @@
 ---
 type: User Story
 title: "US-012: Build and release the plugin"
-description: Give maintainers repeatable Spigot builds, automated verification, and versioned Gitea releases.
+description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases.
 status: done
 ---
 
@@ -11,7 +11,7 @@ As a **plugin maintainer**, I want automated builds and releases modeled on Trig
 
 ## Acceptance criteria
 
-- [x] The Gradle project compiles against Spigot API `26.2-R0.1-SNAPSHOT` using a Java 17 toolchain.
+- [x] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain.
 - [x] Compiler lint warnings fail the build.
 - [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
 - [x] Pushes and pull requests build and test the plugin in Gitea Actions.

design/user-stories/us-016-build-and-use-pocket-base-portals.md

@@ -19,8 +19,13 @@ As a **Pocket Base owner**, I want to connect my normal base to my Pocket Base w
 - [x] Activating another valid entrance deactivates the previous entrance without removing its frame blocks.
 - [x] Breaking any required frame block immediately deactivates the entrance.
 - [x] Any player can use an active entrance without a separate visitor setting, warm-up, or cooldown.
+- [x] Non-player living mobs entering an active entrance portal are teleported into that Pocket Base.
+- [x] Portal cooldown handling prevents transported mobs from immediately bouncing back.
+- [x] Items, projectiles, vehicles, and other non-living entities are not transported.
 - [x] Visitors can build, break blocks, open containers, and otherwise interact normally inside the Pocket Base.
 - [x] The generated return portal sends players safely to the owner's active entrance.
+- [x] Non-player living mobs entering the active, intact return portal are teleported safely outside the normal-world entrance.
+- [x] Mob return travel falls back safely to the server spawn when the owner has no valid normal-world entrance.
 - [x] Only the owner can activate a complete portal frame inside their own Pocket Base with flint and steel.
 - [x] Every required return-frame block must be within the owner's unlocked Pocket Base boundary.
 - [x] Each Pocket Base has at most one active return portal, and activating another valid frame moves the active return location without removing the old frame.
@@ -28,6 +33,7 @@ As a **Pocket Base owner**, I want to connect my normal base to my Pocket Base w
 - [x] Breaking the active return frame disables return travel through it.
 - [x] Return travel falls back to the server spawn when the owner has no valid normal-world entrance.
 - [x] Falling below Y -64 performs the same safe return without void damage.
+- [x] Portal and void-return travel clears accumulated fall distance so players do not take carried-over fall damage after landing at the destination.
 - [x] Players who disconnect inside a Pocket Base remain there when they reconnect.
 - [x] Moving the normal base deactivates its entrance while preserving the Pocket Base world and its contents.
 - [x] Portal ownership and the active entrance location persist through restarts.

design/user-stories/us-020-control-base-through-dialog-ui.md

@@ -21,6 +21,9 @@ As a **player**, I want a dialog-based base dashboard so that I can inspect prog
 - [x] `ui` is offered through command autocomplete.
 - [x] Non-player execution remains safely rejected.
 - [x] Automated tests verify dialog routing and generated controls.
+- [x] Fixed dialog commands use Purpur static run-command actions rather than macro templates.
+- [x] A rendering regression test verifies fixed command buttons do not throw `No variables in macro`.
+- [x] The dialog uses Purpur's supported Paper dialog API and opens on the production Purpur 26.2 runtime without missing-class or command exceptions.
 
 ## Related
 

settings.gradle.kts

@@ -1 +1,5 @@
+plugins {
+    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
+}
+
 rootProject.name = "spigot-base"

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

@@ -1,5 +1,6 @@
 package games.dmg.spigotbase;
 
+import io.papermc.paper.dialog.Dialog;
 import java.io.IOException;
 import java.util.List;
 import java.util.Locale;
@@ -28,6 +29,7 @@ final class BaseSettingsCommand implements CommandExecutor, TabCompleter {
     private final TeleportPolicy teleportPolicy;
     private final BaseFlightController flightController;
     private final PocketBaseManager pocketBases;
+    private final DialogProvider dialogProvider;
 
     BaseSettingsCommand(
         BaseStateManager stateManager,
@@ -42,12 +44,30 @@ final class BaseSettingsCommand implements CommandExecutor, TabCompleter {
         PluginSettingsProvider settings,
         BaseFlightController flightController,
         PocketBaseManager pocketBases
+    ) {
+        this(
+            stateManager,
+            settings,
+            flightController,
+            pocketBases,
+            (owner, pocket) -> new BaseSettingsDialogFactory(settings.current())
+                .create(owner, pocket)
+        );
+    }
+
+    BaseSettingsCommand(
+        BaseStateManager stateManager,
+        PluginSettingsProvider settings,
+        BaseFlightController flightController,
+        PocketBaseManager pocketBases,
+        DialogProvider dialogProvider
     ) {
         this.stateManager = stateManager;
         this.settings = settings;
         this.teleportPolicy = new TeleportPolicy(settings);
         this.flightController = flightController;
         this.pocketBases = pocketBases;
+        this.dialogProvider = dialogProvider;
     }
 
     @Override
@@ -449,7 +469,7 @@ final class BaseSettingsCommand implements CommandExecutor, TabCompleter {
         PocketBaseState pocket = pocketBases == null
             ? PocketBaseState.locked(state.playerId())
             : pocketBases.state(state.playerId());
-        player.showDialog(new BaseSettingsDialogFactory(settings.current()).create(state, pocket));
+        player.showDialog(dialogProvider.create(state, pocket));
     }
 
     private void showStatus(Player player, PlayerState state) {
@@ -672,6 +692,11 @@ final class BaseSettingsCommand implements CommandExecutor, TabCompleter {
         return met ? ChatColor.YELLOW : ChatColor.RED;
     }
 
+    @FunctionalInterface
+    interface DialogProvider {
+        Dialog create(PlayerState owner, PocketBaseState pocket);
+    }
+
     private static void sendUsage(Player player) {
         player.sendMessage(ChatColor.RED + "Usage: /basesettings "
             + "[ui|status|upgrade|pocket upgrade|pocket mobs "

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

@@ -1,19 +1,18 @@
 package games.dmg.spigotbase;
 
+import io.papermc.paper.dialog.Dialog;
+import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.data.dialog.ActionButton;
+import io.papermc.paper.registry.data.dialog.DialogBase;
+import io.papermc.paper.registry.data.dialog.action.DialogAction;
+import io.papermc.paper.registry.data.dialog.body.DialogBody;
+import io.papermc.paper.registry.data.dialog.type.DialogType;
+import io.papermc.paper.registry.set.RegistrySet;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Locale;
-import net.md_5.bungee.api.chat.BaseComponent;
-import net.md_5.bungee.api.chat.TextComponent;
-import net.md_5.bungee.api.dialog.ConfirmationDialog;
-import net.md_5.bungee.api.dialog.Dialog;
-import net.md_5.bungee.api.dialog.DialogBase;
-import net.md_5.bungee.api.dialog.DialogListDialog;
-import net.md_5.bungee.api.dialog.MultiActionDialog;
-import net.md_5.bungee.api.dialog.NoticeDialog;
-import net.md_5.bungee.api.dialog.action.ActionButton;
-import net.md_5.bungee.api.dialog.action.RunCommandAction;
-import net.md_5.bungee.api.dialog.body.PlainMessageBody;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.event.ClickEvent;
 
 final class BaseSettingsDialogFactory {
     private static final int DIALOG_WIDTH = 420;
@@ -24,8 +23,18 @@ final class BaseSettingsDialogFactory {
     }
 
     Dialog create(PlayerState owner, PocketBaseState pocket) {
-        return new DialogListDialog(
-            base(
+        return render(specification(owner, pocket));
+    }
+
+    DialogSpec specification(PlayerState owner, PocketBaseState pocket) {
+        List<DialogSpec> dialogs = List.of(
+            generalSettings(owner),
+            progressReport(),
+            baseUpgrade(owner),
+            pocketSettings(owner, pocket)
+        );
+        return new ListSpec(
+            content(
                 "Base Settings",
                 "Base Settings",
                 "Base " + owner.baseLevel() + "/4 • Size " + owner.sizeLevel() + "/3"
@@ -33,27 +42,14 @@ final class BaseSettingsDialogFactory {
                     + "Pocket Base " + pocket.level() + " • "
                     + humanize(pocket.biome().commandName())
             ),
-            List.of(
-                generalSettings(owner),
-                progressReport(),
-                baseUpgrade(owner),
-                pocketSettings(owner, pocket)
-            ),
-            null,
+            dialogs,
             2,
             190
         );
     }
 
-    private Dialog generalSettings(PlayerState owner) {
-        return new MultiActionDialog(
-            base(
-                "Base Controls",
-                "Base Controls",
-                "Select a setting to change it. Locked controls remain visible and explain "
-                    + "their requirement in chat when selected."
-            ),
-            List.of(
+    private DialogSpec generalSettings(PlayerState owner) {
+        List<ButtonSpec> actions = List.of(
             toggle(
                 "Visitors",
                 owner.baseLevel() >= 4,
@@ -69,8 +65,7 @@ final class BaseSettingsDialogFactory {
                 owner.navigationEnabled(),
                 "Enabled",
                 "Disabled",
-                    "basesettings navigation "
-                        + mode(!owner.navigationEnabled())
+                "basesettings navigation " + mode(!owner.navigationEnabled())
             ),
             toggle(
                 "Flight",
@@ -107,21 +102,31 @@ final class BaseSettingsDialogFactory {
                 "Disabled",
                 "basesettings bossbar " + mode(!owner.bossBarEnabled())
             )
+        );
+        return new MultiSpec(
+            content(
+                "Base Controls",
+                "Base Controls",
+                "Select a setting to change it. Locked controls remain visible and explain "
+                    + "their requirement in chat when selected."
             ),
-            2,
-            null
+            actions,
+            2
         );
     }
 
-    private Dialog progressReport() {
-        return new NoticeDialog(base(
+    private DialogSpec progressReport() {
+        return new NoticeSpec(
+            content(
                 "Progress Report",
                 "Progress Report",
                 "Display the detailed progression report in chat."
-        )).action(commandButton("Show in Chat", "basesettings status"));
+            ),
+            commandButton("Show in Chat", "basesettings status")
+        );
     }
 
-    private Dialog baseUpgrade(PlayerState owner) {
+    private DialogSpec baseUpgrade(PlayerState owner) {
         if (owner.baseLevel() >= 4) {
             return notice("Base IV", "Base IV and visitor access are already unlocked.");
         }
@@ -131,17 +136,22 @@ final class BaseSettingsDialogFactory {
                 "Unlock and establish Base III before purchasing Base IV visitor access."
             );
         }
-        int price = settings.visitorUnlockDiamondCost();
         return confirmation(
             "Unlock Base IV",
-            "Purchase visitor access for " + price + " diamonds?",
+            "Purchase visitor access for " + settings.visitorUnlockDiamondCost()
+                + " diamonds?",
             "basesettings upgrade"
         );
     }
 
-    private Dialog pocketSettings(PlayerState owner, PocketBaseState pocket) {
-        return new DialogListDialog(
-            base(
+    private DialogSpec pocketSettings(PlayerState owner, PocketBaseState pocket) {
+        List<DialogSpec> dialogs = List.of(
+            pocketUpgrade(owner, pocket),
+            pocketMobSettings(pocket),
+            pocketBiomeSettings(pocket)
+        );
+        return new ListSpec(
+            content(
                 "Pocket Base",
                 "Pocket Base " + pocket.level(),
                 pocket.level() == 0
@@ -151,18 +161,13 @@ final class BaseSettingsDialogFactory {
                         + enabled(pocket.hostileMobSpawningEnabled()) + " • Passive mobs: "
                         + enabled(pocket.passiveMobSpawningEnabled())
             ),
-            List.of(
-                pocketUpgrade(owner, pocket),
-                pocketMobSettings(pocket),
-                pocketBiomeSettings(pocket)
-            ),
-            null,
+            dialogs,
             1,
             260
         );
     }
 
-    private Dialog pocketUpgrade(PlayerState owner, PocketBaseState pocket) {
+    private DialogSpec pocketUpgrade(PlayerState owner, PocketBaseState pocket) {
         if (owner.baseLevel() < 4 || owner.base().isEmpty()) {
             return notice(
                 "Pocket Upgrade — Locked",
@@ -183,20 +188,14 @@ final class BaseSettingsDialogFactory {
         );
     }
 
-    private Dialog pocketMobSettings(PocketBaseState pocket) {
+    private DialogSpec pocketMobSettings(PocketBaseState pocket) {
         if (pocket.level() < 1) {
             return notice(
                 "Mob Spawning — Locked",
                 "Unlock Pocket Base I to control natural mob spawning."
             );
         }
-        return new MultiActionDialog(
-            base(
-                "Mob Spawning",
-                "Mob Spawning",
-                "Control natural spawning independently for each mob category."
-            ),
-            List.of(
+        List<ButtonSpec> actions = List.of(
             toggle(
                 "Hostile Mobs",
                 true,
@@ -215,25 +214,30 @@ final class BaseSettingsDialogFactory {
                 "basesettings pocket mobs passive "
                     + mode(!pocket.passiveMobSpawningEnabled())
             )
+        );
+        return new MultiSpec(
+            content(
+                "Mob Spawning",
+                "Mob Spawning",
+                "Control natural spawning independently for each mob category."
             ),
-            1,
-            null
+            actions,
+            1
         );
     }
 
-    private Dialog pocketBiomeSettings(PocketBaseState pocket) {
+    private DialogSpec pocketBiomeSettings(PocketBaseState pocket) {
         if (pocket.level() < 1) {
             return notice(
                 "Change Biome — Locked",
                 "Unlock Pocket Base I to purchase biome changes."
             );
         }
-        List<Dialog> worldTypes = Arrays.stream(PocketBaseWorldType.values())
+        List<DialogSpec> worldTypes = Arrays.stream(PocketBaseWorldType.values())
             .map(type -> pocketBiomeType(pocket, type))
-            .map(Dialog.class::cast)
             .toList();
-        return new DialogListDialog(
-            base(
+        return new ListSpec(
+            content(
                 "Change Biome",
                 "Change Biome",
                 "Current biome: " + pocket.biome().worldType().commandName() + "/"
@@ -242,35 +246,32 @@ final class BaseSettingsDialogFactory {
                     + humanize(settings.pocketBaseBiomeCurrencyMaterial()) + "."
             ),
             worldTypes,
-            null,
             1,
             220
         );
     }
 
-    private DialogListDialog pocketBiomeType(
+    private DialogSpec pocketBiomeType(
         PocketBaseState pocket,
         PocketBaseWorldType worldType
     ) {
-        List<Dialog> biomes = Arrays.stream(PocketBaseBiome.values())
+        List<DialogSpec> biomes = Arrays.stream(PocketBaseBiome.values())
             .filter(biome -> biome.worldType() == worldType)
             .map(biome -> biomeConfirmation(pocket, biome))
-            .map(Dialog.class::cast)
             .toList();
-        return new DialogListDialog(
-            base(
+        return new ListSpec(
+            content(
                 humanize(worldType.commandName()),
                 humanize(worldType.commandName()) + " Biomes",
                 "Choose a biome subtype. The active biome is marked as selected."
             ),
             biomes,
-            null,
             2,
             190
         );
     }
 
-    private Dialog biomeConfirmation(PocketBaseState pocket, PocketBaseBiome biome) {
+    private DialogSpec biomeConfirmation(PocketBaseState pocket, PocketBaseBiome biome) {
         String title = humanize(biome.commandName())
             + (pocket.biome() == biome ? " — Selected" : "");
         if (pocket.biome() == biome) {
@@ -285,16 +286,18 @@ final class BaseSettingsDialogFactory {
         );
     }
 
-    private static Dialog confirmation(String title, String message, String command) {
-        return new ConfirmationDialog(base(title, title, message))
-            .yes(commandButton("Confirm", command));
+    private static DialogSpec confirmation(String title, String message, String command) {
+        return new ConfirmationSpec(
+            content(title, title, message),
+            commandButton("Confirm", command)
+        );
     }
 
-    private static Dialog notice(String title, String message) {
-        return new NoticeDialog(base(title, title, message));
+    private static DialogSpec notice(String title, String message) {
+        return new NoticeSpec(content(title, title, message), null);
     }
 
-    private static ActionButton toggle(
+    private static ButtonSpec toggle(
         String name,
         boolean unlocked,
         boolean active,
@@ -306,29 +309,110 @@ final class BaseSettingsDialogFactory {
         String tooltip = unlocked
             ? "Click to change this setting."
             : "This setting has not been unlocked yet.";
-        return new ActionButton(
-            text(name + ": " + state),
-            text(tooltip),
-            190,
-            new RunCommandAction("/" + command)
+        return new ButtonSpec(name + ": " + state, tooltip, 190, "/" + command);
+    }
+
+    private static ButtonSpec commandButton(String label, String command) {
+        return new ButtonSpec(label, "", 150, "/" + command);
+    }
+
+    private static DialogContent content(
+        String title,
+        String externalTitle,
+        String message
+    ) {
+        return new DialogContent(title, externalTitle, message);
+    }
+
+    private static Dialog render(DialogSpec specification) {
+        DialogType type;
+        if (specification instanceof ListSpec list) {
+            List<Dialog> dialogs = list.dialogs().stream()
+                .map(BaseSettingsDialogFactory::render)
+                .toList();
+            type = DialogType.dialogList(
+                RegistrySet.valueSet(RegistryKey.DIALOG, dialogs),
+                null,
+                list.columns(),
+                list.buttonWidth()
             );
+        } else if (specification instanceof MultiSpec multi) {
+            List<ActionButton> actions = multi.actions().stream()
+                .map(BaseSettingsDialogFactory::render)
+                .toList();
+            type = DialogType.multiAction(actions, null, multi.columns());
+        } else if (specification instanceof ConfirmationSpec confirmation) {
+            ActionButton cancel = ActionButton.builder(Component.text("Cancel")).build();
+            type = DialogType.confirmation(render(confirmation.confirm()), cancel);
+        } else if (specification instanceof NoticeSpec notice) {
+            type = notice.action() == null
+                ? DialogType.notice()
+                : DialogType.notice(render(notice.action()));
+        } else {
+            throw new IllegalArgumentException("Unsupported dialog specification");
         }
-
-    private static ActionButton commandButton(String label, String command) {
-        return new ActionButton(text(label), new RunCommandAction("/" + command));
-    }
-
-    private static DialogBase base(String title, String externalTitle, String message) {
-        return new DialogBase(text(title))
-            .externalTitle(text(externalTitle))
-            .body(List.of(new PlainMessageBody(text(message), DIALOG_WIDTH)))
+        DialogContent content = specification.content();
+        DialogBase base = DialogBase.builder(Component.text(content.title()))
+            .externalTitle(Component.text(content.externalTitle()))
+            .body(List.of(DialogBody.plainMessage(
+                Component.text(content.message()), DIALOG_WIDTH
+            )))
             .canCloseWithEscape(true)
             .pause(false)
-            .afterAction(DialogBase.AfterAction.CLOSE);
+            .afterAction(DialogBase.DialogAfterAction.CLOSE)
+            .build();
+        return Dialog.create(factory -> factory.empty().base(base).type(type));
     }
 
-    private static BaseComponent text(String value) {
-        return new TextComponent(value);
+    private static ActionButton render(ButtonSpec button) {
+        ActionButton.Builder builder = ActionButton.builder(Component.text(button.label()))
+            .width(button.width())
+            .action(DialogAction.staticAction(commandClick(button.command())));
+        if (!button.tooltip().isEmpty()) {
+            builder.tooltip(Component.text(button.tooltip()));
+        }
+        return builder.build();
+    }
+
+    static ClickEvent<ClickEvent.Payload.Text> commandClick(String command) {
+        return ClickEvent.runCommand(command);
+    }
+
+    sealed interface DialogSpec permits ListSpec, MultiSpec, ConfirmationSpec, NoticeSpec {
+        DialogContent content();
+    }
+
+    record DialogContent(String title, String externalTitle, String message) {
+    }
+
+    record ListSpec(
+        DialogContent content,
+        List<DialogSpec> dialogs,
+        int columns,
+        int buttonWidth
+    ) implements DialogSpec {
+    }
+
+    record MultiSpec(
+        DialogContent content,
+        List<ButtonSpec> actions,
+        int columns
+    ) implements DialogSpec {
+    }
+
+    record ConfirmationSpec(
+        DialogContent content,
+        ButtonSpec confirm
+    ) implements DialogSpec {
+    }
+
+    record NoticeSpec(
+        DialogContent content,
+        ButtonSpec action
+    ) implements DialogSpec {
+    }
+
+    record ButtonSpec(String label, String tooltip, int width, String command) {
     }
 
     private static String mode(boolean active) {

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

@@ -5,6 +5,7 @@ import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
+import java.util.function.Consumer;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import org.bukkit.ChatColor;
@@ -15,6 +16,7 @@ import org.bukkit.Server;
 import org.bukkit.World;
 import org.bukkit.block.Block;
 import org.bukkit.entity.Entity;
+import org.bukkit.entity.Mob;
 import org.bukkit.entity.Player;
 import org.bukkit.event.EventHandler;
 import org.bukkit.event.EventPriority;
@@ -26,6 +28,7 @@ import org.bukkit.event.entity.EntityDamageEvent;
 import org.bukkit.event.player.PlayerInteractEvent;
 import org.bukkit.event.player.PlayerMoveEvent;
 import org.bukkit.event.player.PlayerTeleportEvent;
+import org.bukkit.util.BoundingBox;
 
 final class PocketBaseController implements Listener, Runnable {
     private static final int VOID_RETURN_Y = -64;
@@ -63,6 +66,7 @@ final class PocketBaseController implements Listener, Runnable {
                 showPortal(pocketBases.returnPortal(state.ownerId()));
             }
         }
+        scanMobPortals();
         long now = System.nanoTime();
         cooldownUntil.entrySet().removeIf(entry -> entry.getValue() <= now);
     }
@@ -235,23 +239,62 @@ final class PocketBaseController implements Listener, Runnable {
         deactivate(ownerId);
     }
 
-    private void leavePocket(Player player, UUID ownerId) {
+    void scanMobPortals() {
+        for (PocketBaseState state : pocketBases.knownStates().values()) {
+            if (state.entrance().isPresent()) {
+                PocketPortalLocation entrance = state.entrance().orElseThrow();
+                if (isIntact(entrance)) {
+                    transportMobs(
+                        entrance,
+                        mob -> teleport(mob, pocketBases.pocketArrival(state.ownerId()))
+                    );
+                }
+            }
+            if (state.level() > 0 && pocketBases.returnPortalIsIntact(state.ownerId())) {
+                transportMobs(
+                    pocketBases.returnPortal(state.ownerId()),
+                    mob -> leavePocket(mob, state.ownerId())
+                );
+            }
+        }
+    }
+
+    private void transportMobs(
+        PocketPortalLocation portal,
+        Consumer<Mob> transport
+    ) {
+        World world = server.getWorld(portal.worldId());
+        if (world == null) {
+            return;
+        }
+        for (Entity entity : world.getNearbyEntities(
+            portalBounds(portal),
+            candidate -> candidate instanceof Mob
+        )) {
+            if (entity instanceof Mob mob && !onCooldown(mob)) {
+                transport.accept(mob);
+            }
+        }
+    }
+
+    private void leavePocket(Entity entity, UUID ownerId) {
         PocketBaseState state = pocketBases.state(ownerId);
         if (state.entrance().isPresent() && isIntact(state.entrance().orElseThrow())) {
-            teleport(player, outsidePortal(state.entrance().orElseThrow()));
+            teleport(entity, outsidePortal(state.entrance().orElseThrow()));
             return;
         }
         World fallbackWorld = server.getWorlds().get(0);
-        teleport(player, fallbackWorld.getSpawnLocation());
+        teleport(entity, fallbackWorld.getSpawnLocation());
     }
 
-    private void teleport(Player player, Location destination) {
-        cooldownUntil.put(player.getUniqueId(), System.nanoTime() + PORTAL_COOLDOWN_NANOS);
-        player.teleport(destination, PlayerTeleportEvent.TeleportCause.PLUGIN);
+    private void teleport(Entity entity, Location destination) {
+        cooldownUntil.put(entity.getUniqueId(), System.nanoTime() + PORTAL_COOLDOWN_NANOS);
+        entity.setFallDistance(0.0F);
+        entity.teleport(destination, PlayerTeleportEvent.TeleportCause.PLUGIN);
     }
 
-    private boolean onCooldown(Player player) {
-        return cooldownUntil.getOrDefault(player.getUniqueId(), 0L) > System.nanoTime();
+    private boolean onCooldown(Entity entity) {
+        return cooldownUntil.getOrDefault(entity.getUniqueId(), 0L) > System.nanoTime();
     }
 
     private void validateEntrances() {
@@ -320,6 +363,26 @@ final class PocketBaseController implements Listener, Runnable {
             : new Location(world, portal.x() + 1.5, portal.y() + 1.0, portal.z() + 2.0);
     }
 
+    private static BoundingBox portalBounds(PocketPortalLocation portal) {
+        return portal.axis() == PocketPortalAxis.X
+            ? new BoundingBox(
+                portal.x() + 1.0,
+                portal.y() + 1.0,
+                portal.z(),
+                portal.x() + 3.0,
+                portal.y() + 4.0,
+                portal.z() + 1.0
+            )
+            : new BoundingBox(
+                portal.x(),
+                portal.y() + 1.0,
+                portal.z() + 1.0,
+                portal.x() + 1.0,
+                portal.y() + 4.0,
+                portal.z() + 3.0
+            );
+    }
+
     private static boolean isAir(Material material) {
         return material == Material.AIR || material == Material.CAVE_AIR
             || material == Material.VOID_AIR;

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

@@ -137,7 +137,7 @@ final class PocketBaseWorldService {
         World world = server.getWorld(name);
         boolean created = world == null;
         if (created) {
-            WorldCreator creator = new WorldCreator(name)
+            WorldCreator creator = new WorldCreator(NamespacedKey.minecraft(name))
                 .environment(World.Environment.NORMAL)
                 .generator(new VoidPocketChunkGenerator())
                 .generateStructures(false);

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

@@ -24,7 +24,7 @@ import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.PlayerInventory;
-import net.md_5.bungee.api.dialog.Dialog;
+import net.kyori.adventure.dialog.DialogLike;
 import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
 
@@ -186,10 +186,12 @@ final class BaseSettingsCommandTest {
         when(player.getUniqueId()).thenReturn(playerId);
         when(player.getName()).thenReturn("Host");
         PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack firstStack = item(Material.DIAMOND, 64);
+        ItemStack secondStack = item(Material.DIAMOND, 64);
         when(player.getInventory()).thenReturn(inventory);
         when(inventory.getStorageContents()).thenReturn(new ItemStack[] {
-            new ItemStack(Material.DIAMOND, 64),
-            new ItemStack(Material.DIAMOND, 64)
+            firstStack,
+            secondStack
         });
 
         PlayerState current = PlayerState.newPlayer(playerId, "Host")
@@ -227,10 +229,9 @@ final class BaseSettingsCommandTest {
         when(player.getUniqueId()).thenReturn(playerId);
         when(player.getName()).thenReturn("Builder");
         PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack currency = item(Material.DIAMOND_BLOCK, 64);
         when(player.getInventory()).thenReturn(inventory);
-        when(inventory.getStorageContents()).thenReturn(new ItemStack[] {
-            new ItemStack(Material.DIAMOND_BLOCK, 64)
-        });
+        when(inventory.getStorageContents()).thenReturn(new ItemStack[] {currency});
         PlayerState owner = PlayerState.newPlayer(playerId, "Builder")
             .withAdministrativeLevels(4, 0, 0, 0, 0, false, false, true)
             .withBase(
@@ -264,10 +265,9 @@ final class BaseSettingsCommandTest {
         when(player.getUniqueId()).thenReturn(playerId);
         when(player.getName()).thenReturn("Builder");
         PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack currency = item(Material.NETHERITE_BLOCK, 16);
         when(player.getInventory()).thenReturn(inventory);
-        when(inventory.getStorageContents()).thenReturn(new ItemStack[] {
-            new ItemStack(Material.NETHERITE_BLOCK, 16)
-        });
+        when(inventory.getStorageContents()).thenReturn(new ItemStack[] {currency});
         BaseStateManager stateManager = mock(BaseStateManager.class);
         when(stateManager.player(playerId, "Builder"))
             .thenReturn(PlayerState.newPlayer(playerId, "Builder"));
@@ -429,10 +429,9 @@ final class BaseSettingsCommandTest {
         when(player.getUniqueId()).thenReturn(playerId);
         when(player.getName()).thenReturn("Builder");
         PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack currency = item(Material.DIAMOND_BLOCK, 64);
         when(player.getInventory()).thenReturn(inventory);
-        when(inventory.getStorageContents()).thenReturn(new ItemStack[] {
-            new ItemStack(Material.DIAMOND_BLOCK, 64)
-        });
+        when(inventory.getStorageContents()).thenReturn(new ItemStack[] {currency});
         PlayerState owner = PlayerState.newPlayer(playerId, "Builder")
             .withAdministrativeLevels(4, 0, 0, 0, 0, false, false, true)
             .withBase(
@@ -554,14 +553,16 @@ final class BaseSettingsCommandTest {
         BaseSettingsCommand command = new BaseSettingsCommand(
             stateManager,
             new PluginSettingsProvider(PluginSettings.from(Map.of())),
-            mock(BaseFlightController.class)
+            mock(BaseFlightController.class),
+            null,
+            (owner, pocket) -> null
         );
 
         command.onCommand(player, null, "basesettings", new String[0]);
         command.onCommand(player, null, "homesettings", new String[] {"ui"});
         command.onCommand(player, null, "basesettings", new String[] {"status"});
 
-        verify(player, times(2)).showDialog(any(Dialog.class));
+        verify(player, times(2)).showDialog((DialogLike) null);
         verify(player).sendMessage(ChatColor.GOLD + "=== Base Progress ===");
         verify(player).sendMessage(
             org.mockito.ArgumentMatchers.<String>argThat(message ->
@@ -582,6 +583,18 @@ final class BaseSettingsCommandTest {
         );
     }
 
+    private static ItemStack item(Material material, int amount) {
+        ItemStack item = mock(ItemStack.class);
+        ItemStack copy = mock(ItemStack.class);
+        when(item.getType()).thenReturn(material);
+        when(item.getAmount()).thenReturn(amount);
+        when(item.clone()).thenReturn(copy);
+        when(copy.getType()).thenReturn(material);
+        when(copy.getAmount()).thenReturn(amount);
+        when(copy.clone()).thenReturn(copy);
+        return item;
+    }
+
     private static CommandResult execute(PlayerState current, String... arguments) {
         Player player = mock(Player.class);
         when(player.getUniqueId()).thenReturn(current.playerId());

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

@@ -1,5 +1,6 @@
 package games.dmg.spigotbase;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -9,17 +10,24 @@ import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
-import net.md_5.bungee.api.dialog.ConfirmationDialog;
-import net.md_5.bungee.api.dialog.Dialog;
-import net.md_5.bungee.api.dialog.DialogListDialog;
-import net.md_5.bungee.api.dialog.MultiActionDialog;
-import net.md_5.bungee.api.dialog.NoticeDialog;
-import net.md_5.bungee.api.dialog.action.Action;
-import net.md_5.bungee.api.dialog.action.ActionButton;
-import net.md_5.bungee.api.dialog.action.RunCommandAction;
+import net.kyori.adventure.text.event.ClickEvent;
 import org.junit.jupiter.api.Test;
 
 final class BaseSettingsDialogFactoryTest {
+    @Test
+    void createsStaticRunCommandActionWithoutMacroVariables() {
+        ClickEvent<ClickEvent.Payload.Text> action = BaseSettingsDialogFactory.commandClick(
+            "/basesettings status"
+        );
+
+        assertEquals(ClickEvent.Action.RUN_COMMAND, action.action());
+        ClickEvent.Payload.Text payload = assertInstanceOf(
+            ClickEvent.Payload.Text.class,
+            action.payload()
+        );
+        assertEquals("/basesettings status", payload.value());
+    }
+
     @Test
     void createsControlsForEveryBaseSettingAndConfirmedPurchase() {
         UUID playerId = UUID.randomUUID();
@@ -42,12 +50,15 @@ final class BaseSettingsDialogFactoryTest {
             PocketBaseBiome.PLAINS
         );
 
-        Dialog dialog = new BaseSettingsDialogFactory(
-            PluginSettings.from(Map.of())
-        ).create(owner, pocket);
+        BaseSettingsDialogFactory.DialogSpec specification =
+            new BaseSettingsDialogFactory(PluginSettings.from(Map.of()))
+                .specification(owner, pocket);
 
-        DialogListDialog root = assertInstanceOf(DialogListDialog.class, dialog);
-        assertTrue(root.getBase().body().get(0).toString().contains("Base 4/4"));
+        BaseSettingsDialogFactory.ListSpec root = assertInstanceOf(
+            BaseSettingsDialogFactory.ListSpec.class,
+            specification
+        );
+        assertTrue(root.content().message().contains("Base 4/4"));
         List<String> commands = commands(root);
         assertTrue(commands.contains("/basesettings status"));
         assertTrue(commands.contains("/basesettings visitors blocked"));
@@ -72,23 +83,19 @@ final class BaseSettingsDialogFactoryTest {
                 Instant.EPOCH
             );
 
-        DialogListDialog root = assertInstanceOf(
-            DialogListDialog.class,
-            new BaseSettingsDialogFactory(PluginSettings.from(Map.of())).create(
+        BaseSettingsDialogFactory.ListSpec root = assertInstanceOf(
+            BaseSettingsDialogFactory.ListSpec.class,
+            new BaseSettingsDialogFactory(PluginSettings.from(Map.of())).specification(
                 owner,
                 PocketBaseState.locked(playerId)
             )
         );
-        ConfirmationDialog upgrade = assertInstanceOf(
-            ConfirmationDialog.class,
+        BaseSettingsDialogFactory.ConfirmationSpec upgrade = assertInstanceOf(
+            BaseSettingsDialogFactory.ConfirmationSpec.class,
             root.dialogs().get(2)
         );
 
-        RunCommandAction action = assertInstanceOf(
-            RunCommandAction.class,
-            upgrade.yes().action()
-        );
-        assertTrue(action.template().equals("/basesettings upgrade"));
+        assertEquals("/basesettings upgrade", upgrade.confirm().command());
     }
 
     @Test
@@ -96,20 +103,19 @@ final class BaseSettingsDialogFactoryTest {
         UUID playerId = UUID.randomUUID();
         PlayerState owner = PlayerState.newPlayer(playerId, "Newcomer");
 
-        DialogListDialog root = assertInstanceOf(
-            DialogListDialog.class,
-            new BaseSettingsDialogFactory(PluginSettings.from(Map.of())).create(
+        BaseSettingsDialogFactory.ListSpec root = assertInstanceOf(
+            BaseSettingsDialogFactory.ListSpec.class,
+            new BaseSettingsDialogFactory(PluginSettings.from(Map.of())).specification(
                 owner,
                 PocketBaseState.locked(playerId)
             )
         );
-        MultiActionDialog controls = assertInstanceOf(
-            MultiActionDialog.class,
+        BaseSettingsDialogFactory.MultiSpec controls = assertInstanceOf(
+            BaseSettingsDialogFactory.MultiSpec.class,
             root.dialogs().get(0)
         );
         List<String> labels = controls.actions().stream()
-            .map(ActionButton::label)
-            .map(Object::toString)
+            .map(BaseSettingsDialogFactory.ButtonSpec::label)
             .toList();
 
         assertTrue(labels.stream().anyMatch(label -> label.contains("Visitors: Locked")));
@@ -119,34 +125,28 @@ final class BaseSettingsDialogFactoryTest {
         assertTrue(labels.stream().anyMatch(label -> label.contains("Spawnable Overlay: Locked")));
     }
 
-    private static List<String> commands(Dialog dialog) {
+    private static List<String> commands(
+        BaseSettingsDialogFactory.DialogSpec specification
+    ) {
         List<String> commands = new ArrayList<>();
-        collect(dialog, commands);
+        collect(specification, commands);
         return commands;
     }
 
-    private static void collect(Dialog dialog, List<String> commands) {
-        if (dialog instanceof DialogListDialog list) {
+    private static void collect(
+        BaseSettingsDialogFactory.DialogSpec specification,
+        List<String> commands
+    ) {
+        if (specification instanceof BaseSettingsDialogFactory.ListSpec list) {
             list.dialogs().forEach(child -> collect(child, commands));
-            collect(list.exitAction(), commands);
-        } else if (dialog instanceof MultiActionDialog actions) {
-            actions.actions().forEach(button -> collect(button, commands));
-            collect(actions.exitAction(), commands);
-        } else if (dialog instanceof ConfirmationDialog confirmation) {
-            collect(confirmation.yes(), commands);
-            collect(confirmation.no(), commands);
-        } else if (dialog instanceof NoticeDialog notice) {
-            collect(notice.action(), commands);
-        }
-    }
-
-    private static void collect(ActionButton button, List<String> commands) {
-        if (button == null) {
-            return;
-        }
-        Action action = button.action();
-        if (action instanceof RunCommandAction command) {
-            commands.add(command.template());
+        } else if (specification instanceof BaseSettingsDialogFactory.MultiSpec multi) {
+            multi.actions().forEach(button -> commands.add(button.command()));
+        } else if (specification
+                instanceof BaseSettingsDialogFactory.ConfirmationSpec confirmation) {
+            commands.add(confirmation.confirm().command());
+        } else if (specification instanceof BaseSettingsDialogFactory.NoticeSpec notice
+                && notice.action() != null) {
+            commands.add(notice.action().command());
         }
     }
 }

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

@@ -1,5 +1,6 @@
 package games.dmg.spigotbase;
 
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyInt;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.never;
@@ -8,20 +9,27 @@ import static org.mockito.Mockito.when;
 
 import java.time.Instant;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
 import java.util.logging.Logger;
+import org.bukkit.Location;
 import org.bukkit.Material;
 import org.bukkit.Server;
 import org.bukkit.World;
 import org.bukkit.block.Block;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.Mob;
 import org.bukkit.entity.Player;
 import org.bukkit.event.block.Action;
 import org.bukkit.event.block.BlockPlaceEvent;
 import org.bukkit.event.player.PlayerInteractEvent;
+import org.bukkit.event.player.PlayerMoveEvent;
+import org.bukkit.event.player.PlayerTeleportEvent;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.util.BoundingBox;
 import org.junit.jupiter.api.Test;
 
 final class PocketBaseControllerTest {
@@ -37,6 +45,7 @@ final class PocketBaseControllerTest {
         World world = mock(World.class);
         Block clicked = block(world, -2, 66, 0, Material.DIAMOND_BLOCK);
         PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        ItemStack activator = item(Material.FLINT_AND_STEEL);
         BaseStateManager baseStates = mock(BaseStateManager.class);
         PocketBaseManager pocketBases = mock(PocketBaseManager.class);
         PluginSettings settings = PluginSettings.from(Map.of());
@@ -49,7 +58,7 @@ final class PocketBaseControllerTest {
         when(event.getPlayer()).thenReturn(owner);
         when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
         when(event.getClickedBlock()).thenReturn(clicked);
-        when(event.getItem()).thenReturn(new ItemStack(Material.FLINT_AND_STEEL));
+        when(event.getItem()).thenReturn(activator);
         when(world.getUID()).thenReturn(worldId);
         when(world.getName()).thenReturn("world");
         when(world.getBlockAt(anyInt(), anyInt(), anyInt())).thenAnswer(invocation -> {
@@ -98,6 +107,7 @@ final class PocketBaseControllerTest {
         World world = mock(World.class);
         Block clicked = block(world, 8, 67, 8, Material.DIAMOND_BLOCK);
         PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        ItemStack activator = item(Material.FLINT_AND_STEEL);
         PocketBaseManager pocketBases = mock(PocketBaseManager.class);
         PluginSettings settings = PluginSettings.from(Map.of());
 
@@ -105,7 +115,7 @@ final class PocketBaseControllerTest {
         when(event.getPlayer()).thenReturn(owner);
         when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
         when(event.getClickedBlock()).thenReturn(clicked);
-        when(event.getItem()).thenReturn(new ItemStack(Material.FLINT_AND_STEEL));
+        when(event.getItem()).thenReturn(activator);
         when(world.getUID()).thenReturn(worldId);
         when(world.getName()).thenReturn("pocket");
         when(world.getBlockAt(anyInt(), anyInt(), anyInt())).thenAnswer(invocation -> {
@@ -152,6 +162,7 @@ final class PocketBaseControllerTest {
         World world = mock(World.class);
         Block clicked = block(world, 30, 67, 8, Material.DIAMOND_BLOCK);
         PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        ItemStack activator = item(Material.FLINT_AND_STEEL);
         PocketBaseManager pocketBases = mock(PocketBaseManager.class);
         PluginSettings settings = PluginSettings.from(Map.of());
 
@@ -159,7 +170,7 @@ final class PocketBaseControllerTest {
         when(event.getPlayer()).thenReturn(owner);
         when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
         when(event.getClickedBlock()).thenReturn(clicked);
-        when(event.getItem()).thenReturn(new ItemStack(Material.FLINT_AND_STEEL));
+        when(event.getItem()).thenReturn(activator);
         when(world.getUID()).thenReturn(worldId);
         when(world.getName()).thenReturn("pocket");
         when(world.getBlockAt(anyInt(), anyInt(), anyInt())).thenAnswer(invocation -> {
@@ -227,6 +238,188 @@ final class PocketBaseControllerTest {
         verify(event).setCancelled(true);
     }
 
+    @Test
+    void activeEntranceTransportsMobsOnceButNotOtherEntities() {
+        UUID ownerId = UUID.randomUUID();
+        UUID worldId = UUID.randomUUID();
+        PocketPortalLocation portal = new PocketPortalLocation(
+            worldId, "world", -2, 64, 0, PocketPortalAxis.X
+        );
+        PocketBaseState state = new PocketBaseState(ownerId, 1, Optional.of(portal));
+        Server server = mock(Server.class);
+        World world = intactPortalWorld(worldId, portal);
+        Mob mob = mock(Mob.class);
+        Entity item = mock(Entity.class);
+        Location arrival = new Location(mock(World.class), 0.5, 65.0, 5.5);
+        PocketBaseManager pocketBases = mock(PocketBaseManager.class);
+
+        when(mob.getUniqueId()).thenReturn(UUID.randomUUID());
+        when(item.getUniqueId()).thenReturn(UUID.randomUUID());
+        when(world.getNearbyEntities(any(BoundingBox.class), any()))
+            .thenReturn(List.of(mob, item));
+        when(server.getWorld(worldId)).thenReturn(world);
+        when(pocketBases.knownStates()).thenReturn(Map.of(ownerId, state));
+        when(pocketBases.pocketArrival(ownerId)).thenReturn(arrival);
+        PocketBaseController controller = controller(server, pocketBases);
+
+        controller.scanMobPortals();
+        controller.scanMobPortals();
+
+        verify(mob).teleport(arrival, PlayerTeleportEvent.TeleportCause.PLUGIN);
+        verify(item, never()).teleport(
+            any(Location.class),
+            any(PlayerTeleportEvent.TeleportCause.class)
+        );
+    }
+
+    @Test
+    void activeReturnPortalTransportsMobOutsideIntactEntrance() {
+        UUID ownerId = UUID.randomUUID();
+        UUID normalWorldId = UUID.randomUUID();
+        UUID pocketWorldId = UUID.randomUUID();
+        PocketPortalLocation entrance = new PocketPortalLocation(
+            normalWorldId, "world", -2, 64, 0, PocketPortalAxis.X
+        );
+        PocketPortalLocation returnPortal = new PocketPortalLocation(
+            pocketWorldId, "pocket", 8, 65, 8, PocketPortalAxis.Z
+        );
+        PocketBaseState state = new PocketBaseState(ownerId, 1, Optional.of(entrance));
+        Server server = mock(Server.class);
+        World normalWorld = intactPortalWorld(normalWorldId, entrance);
+        World pocketWorld = intactPortalWorld(pocketWorldId, returnPortal);
+        Mob mob = mock(Mob.class);
+        PocketBaseManager pocketBases = mock(PocketBaseManager.class);
+
+        when(mob.getUniqueId()).thenReturn(UUID.randomUUID());
+        when(normalWorld.getNearbyEntities(any(BoundingBox.class), any()))
+            .thenReturn(List.of());
+        when(pocketWorld.getNearbyEntities(any(BoundingBox.class), any()))
+            .thenReturn(List.of(mob));
+        when(server.getWorld(normalWorldId)).thenReturn(normalWorld);
+        when(server.getWorld(pocketWorldId)).thenReturn(pocketWorld);
+        when(pocketBases.knownStates()).thenReturn(Map.of(ownerId, state));
+        when(pocketBases.state(ownerId)).thenReturn(state);
+        when(pocketBases.returnPortalIsIntact(ownerId)).thenReturn(true);
+        when(pocketBases.returnPortal(ownerId)).thenReturn(returnPortal);
+        PocketBaseController controller = controller(server, pocketBases);
+
+        controller.scanMobPortals();
+
+        verify(mob).teleport(
+            new Location(normalWorld, 0.0, 65.0, 1.5),
+            PlayerTeleportEvent.TeleportCause.PLUGIN
+        );
+    }
+
+    @Test
+    void voidReturnClearsAccumulatedPlayerFallDistance() {
+        UUID ownerId = UUID.randomUUID();
+        UUID pocketWorldId = UUID.randomUUID();
+        World pocketWorld = mock(World.class);
+        World fallbackWorld = mock(World.class);
+        Location destination = new Location(pocketWorld, 0.5, -65.0, 0.5);
+        Location spawn = new Location(fallbackWorld, 10.5, 70.0, 10.5);
+        Player player = mock(Player.class);
+        PlayerMoveEvent event = mock(PlayerMoveEvent.class);
+        PocketBaseManager pocketBases = mock(PocketBaseManager.class);
+        Server server = mock(Server.class);
+
+        when(pocketWorld.getUID()).thenReturn(pocketWorldId);
+        when(player.getUniqueId()).thenReturn(UUID.randomUUID());
+        when(event.getPlayer()).thenReturn(player);
+        when(event.getTo()).thenReturn(destination);
+        when(server.getWorlds()).thenReturn(List.of(fallbackWorld));
+        when(fallbackWorld.getSpawnLocation()).thenReturn(spawn);
+        when(pocketBases.ownerForPocketWorld(pocketWorldId)).thenReturn(Optional.of(ownerId));
+        when(pocketBases.state(ownerId)).thenReturn(
+            new PocketBaseState(ownerId, 1, Optional.empty())
+        );
+        PocketBaseController controller = controller(server, pocketBases);
+
+        controller.onMove(event);
+
+        verify(player).setFallDistance(0.0F);
+        verify(player).teleport(spawn, PlayerTeleportEvent.TeleportCause.PLUGIN);
+    }
+
+    @Test
+    void mobReturnFallsBackToServerSpawnWithoutValidEntrance() {
+        UUID ownerId = UUID.randomUUID();
+        UUID pocketWorldId = UUID.randomUUID();
+        PocketPortalLocation returnPortal = new PocketPortalLocation(
+            pocketWorldId, "pocket", 8, 65, 8, PocketPortalAxis.Z
+        );
+        PocketBaseState state = new PocketBaseState(ownerId, 1, Optional.empty());
+        Server server = mock(Server.class);
+        World pocketWorld = intactPortalWorld(pocketWorldId, returnPortal);
+        World fallbackWorld = mock(World.class);
+        Location spawn = new Location(fallbackWorld, 10.5, 70.0, 10.5);
+        Mob mob = mock(Mob.class);
+        PocketBaseManager pocketBases = mock(PocketBaseManager.class);
+
+        when(mob.getUniqueId()).thenReturn(UUID.randomUUID());
+        when(pocketWorld.getNearbyEntities(any(BoundingBox.class), any()))
+            .thenReturn(List.of(mob));
+        when(server.getWorld(pocketWorldId)).thenReturn(pocketWorld);
+        when(server.getWorlds()).thenReturn(List.of(fallbackWorld));
+        when(fallbackWorld.getSpawnLocation()).thenReturn(spawn);
+        when(pocketBases.knownStates()).thenReturn(Map.of(ownerId, state));
+        when(pocketBases.state(ownerId)).thenReturn(state);
+        when(pocketBases.returnPortalIsIntact(ownerId)).thenReturn(true);
+        when(pocketBases.returnPortal(ownerId)).thenReturn(returnPortal);
+        PocketBaseController controller = controller(server, pocketBases);
+
+        controller.scanMobPortals();
+
+        verify(mob).teleport(
+            spawn,
+            PlayerTeleportEvent.TeleportCause.PLUGIN
+        );
+    }
+
+    private static PocketBaseController controller(
+        Server server,
+        PocketBaseManager pocketBases
+    ) {
+        PluginSettings settings = PluginSettings.from(Map.of());
+        return new PocketBaseController(
+            server,
+            mock(BaseStateManager.class),
+            new BaseBoundsService(settings),
+            pocketBases,
+            new PluginSettingsProvider(settings),
+            Logger.getAnonymousLogger()
+        );
+    }
+
+    private static World intactPortalWorld(
+        UUID worldId,
+        PocketPortalLocation portal
+    ) {
+        World world = mock(World.class);
+        Set<BlockPosition> frame = new HashSet<>(PocketPortalGeometry.frameBlocks(portal));
+        when(world.getUID()).thenReturn(worldId);
+        when(world.getBlockAt(anyInt(), anyInt(), anyInt())).thenAnswer(invocation -> {
+            BlockPosition position = new BlockPosition(
+                invocation.getArgument(0), invocation.getArgument(1), invocation.getArgument(2)
+            );
+            return block(
+                world,
+                position.x(),
+                position.y(),
+                position.z(),
+                frame.contains(position) ? Material.DIAMOND_BLOCK : Material.AIR
+            );
+        });
+        return world;
+    }
+
+    private static ItemStack item(Material material) {
+        ItemStack item = mock(ItemStack.class);
+        when(item.getType()).thenReturn(material);
+        return item;
+    }
+
     private static Block block(
         World world,
         int x,