From 4c03befec97a8d16fdeca8eec9f035bbcabde97d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 14 Oct 2026 11:53:23 +0000
Subject: [PATCH] Add basics-top module with /top command

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EE9ZFuiZvhoWuGuZx6MPxV
---
 modules/basics-top/README.md                  |  4 ++
 modules/basics-top/build.gradle.kts           |  3 +
 .../modules/basicstop/BasicsTopModule.kt      | 69 +++++++++++++++++++
 .../src/main/resources/basics-module.yml      |  3 +
 .../src/main/resources/messages.yml           |  2 +
 5 files changed, 81 insertions(+)
 create mode 100644 modules/basics-top/README.md
 create mode 100644 modules/basics-top/build.gradle.kts
 create mode 100644 modules/basics-top/src/main/kotlin/com/github/spigotbasics/modules/basicstop/BasicsTopModule.kt
 create mode 100644 modules/basics-top/src/main/resources/basics-module.yml
 create mode 100644 modules/basics-top/src/main/resources/messages.yml

diff --git a/modules/basics-top/README.md b/modules/basics-top/README.md
new file mode 100644
index 00000000..213ab57d
--- /dev/null
+++ b/modules/basics-top/README.md
@@ -0,0 +1,4 @@
+| Command         | Permission        |
+|-----------------|-------------------|
+| `/top`          | basics.top        |
+| `/top <player>` | basics.top.others |
diff --git a/modules/basics-top/build.gradle.kts b/modules/basics-top/build.gradle.kts
new file mode 100644
index 00000000..c1fb740e
--- /dev/null
+++ b/modules/basics-top/build.gradle.kts
@@ -0,0 +1,3 @@
+plugins {
+    id("basics.module")
+}
diff --git a/modules/basics-top/src/main/kotlin/com/github/spigotbasics/modules/basicstop/BasicsTopModule.kt b/modules/basics-top/src/main/kotlin/com/github/spigotbasics/modules/basicstop/BasicsTopModule.kt
new file mode 100644
index 00000000..301a34c1
--- /dev/null
+++ b/modules/basics-top/src/main/kotlin/com/github/spigotbasics/modules/basicstop/BasicsTopModule.kt
@@ -0,0 +1,69 @@
+package com.github.spigotbasics.modules.basicstop
+
+import com.github.spigotbasics.core.Spiper
+import com.github.spigotbasics.core.command.parsed.CommandContextExecutor
+import com.github.spigotbasics.core.command.parsed.arguments.SelectorSinglePlayerArg
+import com.github.spigotbasics.core.command.parsed.context.MapContext
+import com.github.spigotbasics.core.module.AbstractBasicsModule
+import com.github.spigotbasics.core.module.loader.ModuleInstantiationContext
+import com.github.spigotbasics.core.util.TeleportUtils
+import org.bukkit.World
+import org.bukkit.command.CommandSender
+import org.bukkit.entity.Player
+import org.bukkit.event.player.PlayerTeleportEvent.TeleportCause
+
+class BasicsTopModule(context: ModuleInstantiationContext) : AbstractBasicsModule(context) {
+    private val permission =
+        permissionManager.createSimplePermission(
+            "basics.top",
+            "Allows the player to teleport to the highest block above them",
+        )
+    private val permissionOthers =
+        permissionManager.createSimplePermission(
+            "basics.top.others",
+            "Allows the player to teleport other players to the highest block above them",
+        )
+
+    private val msgTop
+        get() = messages.getMessage("top")
+
+    private fun msgTopOthers(player: Player) = messages.getMessage("top-others").concerns(player)
+
+    override fun onEnable() {
+        commandFactory.parsedCommandBuilder("top", permission).mapContext {
+            usage = "[player]"
+            description("Teleports to the highest block at your position")
+
+            path {
+                playerOnly()
+            }
+
+            path {
+                permissions(permissionOthers)
+                arguments {
+                    named("player", SelectorSinglePlayerArg("player"))
+                }
+            }
+        }.executor(
+            object : CommandContextExecutor<MapContext> {
+                override fun execute(
+                    sender: CommandSender,
+                    context: MapContext,
+                ) {
+                    val target = context["player"] as Player? ?: sender as Player
+                    val location = target.location
+                    val block = target.world.getHighestBlockAt(location)
+                    // The highest block in the nether is the bedrock roof
+                    if (target.world.environment == World.Environment.NETHER || !TeleportUtils.isSafeToStandOn(block.type)) {
+                        coreMessages.noSafeLocationFound.sendToSender(sender)
+                        return
+                    }
+
+                    val destination = block.location.add(0.5, 1.0, 0.5).setDirection(location.direction)
+                    Spiper.teleportAsync(target, destination, TeleportCause.COMMAND)
+                    (if (sender == target) msgTop else msgTopOthers(target)).sendToSender(sender)
+                }
+            },
+        ).register()
+    }
+}
diff --git a/modules/basics-top/src/main/resources/basics-module.yml b/modules/basics-top/src/main/resources/basics-module.yml
new file mode 100644
index 00000000..a4bd0754
--- /dev/null
+++ b/modules/basics-top/src/main/resources/basics-module.yml
@@ -0,0 +1,3 @@
+main-class: com.github.spigotbasics.modules.basicstop.BasicsTopModule
+name: basics-top
+version: ${moduleVersion}
diff --git a/modules/basics-top/src/main/resources/messages.yml b/modules/basics-top/src/main/resources/messages.yml
new file mode 100644
index 00000000..e71f84dc
--- /dev/null
+++ b/modules/basics-top/src/main/resources/messages.yml
@@ -0,0 +1,2 @@
+top: "<def_text>Teleported to the <lite_text>top</lite_text>!</def_text>"
+top-others: "<def_text>Teleported <player-dm> to the <lite_text>top</lite_text>!</def_text>"