Refactor package structure for better maintainability and UX

README.md

@@ -32,6 +32,23 @@ class MyPlugin : KPlugin() {
 }
 ```
 
+## Package Structure
+
+KPaper is organized into several focused packages:
+
+- **`util`** - Utility functions including console output, logging, random number generation, and text processing
+- **`extensions`** - Kotlin extension functions for Bukkit/Paper classes
+- **`event`** - Event handling system with custom events and listeners
+- **`inventory`** - Inventory management, item builders, and GUI systems
+- **`command`** - Command framework and argument parsing
+- **`main`** - Core plugin functionality and feature configuration
+- **`world`** - World generation and manipulation utilities
+- **`messages`** - Message formatting and translation support
+- **`visuals`** - Visual effects and display systems
+- **`game`** - Game mechanics like countdowns and player management
+- **`file`** - File I/O and configuration management
+- **`coroutines`** - Kotlin coroutines integration for async operations
+
 Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on the [GitHub repository](https://github.com/ModLabsCC/KPaper).
 
 ## Acknowledgments

src/main/kotlin/cc/modlabs/kpaper/extensions/InventoryExtensions.kt

@@ -1,7 +1,5 @@
 package cc.modlabs.kpaper.extensions
 
-import cc.modlabs.kpaper.consts.NAMESPACE_GUI_IDENTIFIER
-import cc.modlabs.kpaper.consts.NAMESPACE_ITEM_IDENTIFIER
 import cc.modlabs.kpaper.coroutines.taskRunLater
 import cc.modlabs.kpaper.inventory.ItemBuilder
 import cc.modlabs.kpaper.inventory.toItemBuilder
@@ -18,6 +16,10 @@ import org.bukkit.inventory.InventoryHolder
 import org.bukkit.inventory.ItemStack
 import org.bukkit.inventory.PlayerInventory
 import org.bukkit.inventory.meta.ItemMeta
+
+// Constants for inventory namespaces
+val NAMESPACE_GUI_IDENTIFIER = pluginKey("gui_identifier")
+val NAMESPACE_ITEM_IDENTIFIER = pluginKey("item_identifier")
 import org.bukkit.persistence.PersistentDataType
 import org.jetbrains.annotations.ApiStatus.Experimental
 import java.util.UUID

src/main/kotlin/cc/modlabs/kpaper/extensions/JDKExtensions.kt

@@ -1,10 +1,10 @@
 package cc.modlabs.kpaper.extensions
 
-import cc.modlabs.kpaper.functions.getInternalKPaperLogger
-import cc.modlabs.kpaper.functions.getLogger
+import cc.modlabs.kpaper.util.getInternalKPaperLogger
+import cc.modlabs.kpaper.util.getLogger
 
-@Deprecated("Moved into functions folder", replaceWith = ReplaceWith("getLogger()", "cc.modlabs.kpaper.functions"))
+@Deprecated("Moved into util folder", replaceWith = ReplaceWith("getLogger()", "cc.modlabs.kpaper.util"))
 fun getLogger(): org.slf4j.Logger = getLogger()
 
-@Deprecated("Moved into functions folder", replaceWith = ReplaceWith("getInternalKPaperLogger()", "cc.modlabs.kpaper.functions"))
+@Deprecated("Moved into util folder", replaceWith = ReplaceWith("getInternalKPaperLogger()", "cc.modlabs.kpaper.util"))
 fun getInternalKPaperLogger(): org.slf4j.Logger = getInternalKPaperLogger()

src/main/kotlin/cc/modlabs/kpaper/inventory/AnvilGUI.kt

@@ -1,6 +1,6 @@
 package cc.modlabs.kpaper.inventory
 
-import cc.modlabs.kpaper.inventory._internal.AnvilListener
+import cc.modlabs.kpaper.inventory.internal.AnvilListener
 import dev.fruxz.stacked.text
 import org.bukkit.Bukkit
 import org.bukkit.entity.Player

src/main/kotlin/cc/modlabs/kpaper/inventory/InventoryBuilder.kt

@@ -1,6 +1,6 @@
 package cc.modlabs.kpaper.inventory
 
-import cc.modlabs.kpaper.inventory._internal.ItemClickListener
+import cc.modlabs.kpaper.inventory.internal.ItemClickListener
 import net.kyori.adventure.text.Component
 import org.bukkit.Bukkit
 import org.bukkit.entity.Player

src/main/kotlin/cc/modlabs/kpaper/inventory/ItemBuilder.kt

@@ -3,12 +3,12 @@
 package cc.modlabs.kpaper.inventory
 
 import cc.modlabs.kpaper.coroutines.taskRunLater
-import cc.modlabs.kpaper.inventory._internal.ItemClickListener
+import cc.modlabs.kpaper.inventory.internal.ItemClickListener
 import cc.modlabs.kpaper.inventory.mineskin.MineSkinFetcher
 import cc.modlabs.kpaper.inventory.mineskin.MinecraftSkin
 import cc.modlabs.kpaper.inventory.mineskin.SKIN
 import cc.modlabs.kpaper.inventory.mineskin.Textures
-import cc.modlabs.kpaper.inventory.mineskin.models.texture.MineSkinResponse
+import cc.modlabs.kpaper.inventory.mineskin.MineSkinResponse
 import com.destroystokyo.paper.profile.ProfileProperty
 import com.google.gson.Gson
 import dev.fruxz.ascend.extension.forceCastOrNull

src/main/kotlin/cc/modlabs/kpaper/inventory/_internal/AnvilListener.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/internal/AnvilListener.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory._internal
+package cc.modlabs.kpaper.inventory.internal
 
 import cc.modlabs.kpaper.inventory.AnvilGUI
 import cc.modlabs.kpaper.inventory.AnvilSlot

src/main/kotlin/cc/modlabs/kpaper/inventory/_internal/ItemClickListener.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/internal/ItemClickListener.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory._internal
+package cc.modlabs.kpaper.inventory.internal
 
 import cc.modlabs.kpaper.event.EventHandler
 import cc.modlabs.kpaper.event.listen
@@ -54,4 +54,4 @@ object ItemClickListener: EventHandler() {
         itemClick.register()
         inventoryClick.register()
     }
-}
+}

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/MineSkinBaseResponse.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinBaseResponse.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinBaseResponse(
     val success: Boolean,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinFetcher.kt

@@ -1,8 +1,8 @@
 package cc.modlabs.kpaper.inventory.mineskin
 
 import cc.modlabs.klassicx.tools.Environment
-import cc.modlabs.kpaper.inventory.mineskin.models.texture.MineSkinResponse
-import cc.modlabs.kpaper.inventory.mineskin.models.texture.MineSkinSingleSkinResponse
+import cc.modlabs.kpaper.inventory.mineskin.MineSkinResponse
+import cc.modlabs.kpaper.inventory.mineskin.MineSkinSingleSkinResponse
 import com.google.gson.Gson
 import okhttp3.OkHttpClient
 import okhttp3.Request

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/MineSkinLinks.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinLinks.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinLinks(
     val self: String,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/MineSkinPagination.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinPagination.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinPagination(
     val current: After? = null,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/MineSkinRawSkinResponse.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinRawSkinResponse.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinRawSkinResponse(
     val uuid: String,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/texture/MineSkinResponse.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinResponse.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models.texture
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinResponse(
     val uuid: String,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/texture/MineSkinSingleSkinResponse.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinSingleSkinResponse.kt

@@ -1,7 +1,7 @@
-package cc.modlabs.kpaper.inventory.mineskin.models.texture
+package cc.modlabs.kpaper.inventory.mineskin
 
-import cc.modlabs.kpaper.inventory.mineskin.models.MineSkinLinks
-import cc.modlabs.kpaper.inventory.mineskin.models.MineSkinWarning
+import cc.modlabs.kpaper.inventory.mineskin.MineSkinLinks
+import cc.modlabs.kpaper.inventory.mineskin.MineSkinWarning
 
 
 data class MineSkinSingleSkinResponse(

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/texture/MineSkinTexture.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinTexture.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models.texture
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinTexture(
     val `data`: MineSkinTextureData,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/MineSkinWarning.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/MineSkinWarning.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class MineSkinWarning(
     val code: String,

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/models/texture/Texture.kt → src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/Texture.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.inventory.mineskin.models.texture
+package cc.modlabs.kpaper.inventory.mineskin
 
 data class Texture(
     val signature: String = "",

src/main/kotlin/cc/modlabs/kpaper/inventory/mineskin/Urls.kt

@@ -0,0 +1,5 @@
+package cc.modlabs.kpaper.inventory.mineskin
+
+data class Urls(
+    val skin: String = "",
+)

src/main/kotlin/cc/modlabs/kpaper/main/KPlugin.kt

@@ -1,8 +1,8 @@
 package cc.modlabs.kpaper.main
 
 import cc.modlabs.kpaper.event.CustomEventListener
-import cc.modlabs.kpaper.inventory._internal.AnvilListener
-import cc.modlabs.kpaper.inventory._internal.ItemClickListener
+import cc.modlabs.kpaper.inventory.internal.AnvilListener
+import cc.modlabs.kpaper.inventory.internal.ItemClickListener
 import cc.modlabs.kpaper.inventory.simple.SimpleGUIListener
 import org.bukkit.Bukkit
 import org.bukkit.plugin.java.JavaPlugin

src/main/kotlin/cc/modlabs/kpaper/functions/ConsoleFunctions.kt → src/main/kotlin/cc/modlabs/kpaper/util/ConsoleFunctions.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.functions
+package cc.modlabs.kpaper.util
 
 const val ANSI_RESET = "\u001B[0m"
 const val ANSI_BLACK = "\u001B[30m"

src/main/kotlin/cc/modlabs/kpaper/utils/ConversationAPI.kt → src/main/kotlin/cc/modlabs/kpaper/util/ConversationAPI.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.utils
+package cc.modlabs.kpaper.util
 
 import cc.modlabs.kpaper.main.PluginInstance
 import net.kyori.adventure.text.Component

src/main/kotlin/cc/modlabs/kpaper/utils/Identity.kt → src/main/kotlin/cc/modlabs/kpaper/util/Identity.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.utils
+package cc.modlabs.kpaper.util
 
 import net.kyori.adventure.key.Key
 import org.bukkit.Keyed

src/main/kotlin/cc/modlabs/kpaper/functions/LoggerFunctions.kt → src/main/kotlin/cc/modlabs/kpaper/util/LoggerFunctions.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.functions
+package cc.modlabs.kpaper.util
 
 import cc.modlabs.kpaper.main.PluginInstance
 import org.slf4j.Logger
@@ -10,4 +10,4 @@ fun getLogger(): Logger {
 
 fun getInternalKPaperLogger(): Logger {
     return LoggerFactory.getLogger("cc.modlabs.kpaper")
-}
+}

src/main/kotlin/cc/modlabs/kpaper/functions/RandomFunctions.kt → src/main/kotlin/cc/modlabs/kpaper/util/RandomFunctions.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.functions
+package cc.modlabs.kpaper.util
 
 import kotlin.math.abs
 import kotlin.random.Random

src/main/kotlin/cc/modlabs/kpaper/utils/TextUtils.kt → src/main/kotlin/cc/modlabs/kpaper/util/TextUtils.kt

@@ -1,4 +1,4 @@
-package cc.modlabs.kpaper.utils
+package cc.modlabs.kpaper.util
 
 import net.kyori.adventure.text.Component
 import net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer