New API

.gitignore

@@ -43,4 +43,6 @@ bin/
 .vscode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store
+
+run/

Rocket.md

@@ -0,0 +1,14 @@
+# Module Rocket Java API
+
+This is the documentation for the Rocket Java API.
+This documentation is generated using Dokka, and is not useful to script developers.
+
+## Who is this for?
+
+This documentation is for developers who are working on the Rocket Java API. If you are a script developer, you should refer to the [Rocket Scripting API](https://example.com).
+
+## Copyright
+
+This documentation is Copyright (c) 2025 znci. Licensed under the Apache License, Version 2.0.
+
+You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).

build.gradle.kts

@@ -1,3 +1,5 @@
+import org.jetbrains.dokka.gradle.DokkaTask
+
 /**
  * Copyright 2025 znci
  *
@@ -16,7 +18,9 @@
 
 plugins {
     kotlin("jvm") version "2.1.20-RC"
+    id("org.jetbrains.dokka") version "2.0.0"
     id("com.github.johnrengelman.shadow") version "8.1.1"
+    id("xyz.jpenilla.run-paper") version "2.3.1"
 }
 
 group = "dev.znci"
@@ -37,6 +41,7 @@ dependencies {
     implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
     implementation("org.luaj:luaj-jse:3.0.1")
     implementation("net.luckperms:api:5.4")
+    implementation("org.jetbrains.kotlin:kotlin-reflect")
 }
 
 val targetJavaVersion = 21
@@ -56,3 +61,28 @@ tasks.processResources {
         expand(props)
     }
 }
+
+tasks.withType<DokkaTask>().configureEach {
+    dokkaSourceSets {
+        named("main") {
+            moduleName.set("Rocket Java API")
+            includes.from("Rocket.md")
+
+        }
+    }
+}
+
+
+tasks.withType(xyz.jpenilla.runtask.task.AbstractRun::class) {
+    javaLauncher = javaToolchains.launcherFor {
+        @Suppress("UnstableApiUsage")
+        vendor = JvmVendorSpec.JETBRAINS // use JetBrains JVM
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+    jvmArgs("-XX:+AllowEnhancedClassRedefinition")
+}
+
+tasks.runServer {
+    minecraftVersion("1.21.4")
+    jvmArgs("-Dcom.mojang.eula.agree=true")
+}

src/main/kotlin/dev/znci/rocket/Rocket.kt

@@ -19,6 +19,7 @@ import dev.znci.rocket.commands.RocketCommand
 import dev.znci.rocket.i18n.LocaleManager
 import dev.znci.rocket.scripting.ScriptManager
 import dev.znci.rocket.scripting.events.EventListener
+import dev.znci.rocket.scripting.GlobalInitializer
 import org.bukkit.plugin.java.JavaPlugin
 import java.io.File
 
@@ -52,8 +53,17 @@ class Rocket : JavaPlugin() {
         this.getCommand("rocket")?.setExecutor(RocketCommand(this))
 
         // Register all events
-        logger.info("Rocket plugin enabled")
         EventListener.registerAllEvents()
+
+        // Register globals
+        val globalInitialized = GlobalInitializer.init()
+        if (globalInitialized) {
+            logger.info("Globals successfully initialized")
+        } else {
+            logger.severe("Globals failed to initialize")
+        }
+
+        logger.info("Rocket plugin enabled")
     }
 
     override fun onDisable() {

src/main/kotlin/dev/znci/rocket/i18n/LocaleManager.kt

@@ -21,23 +21,54 @@ import org.bukkit.configuration.file.YamlConfiguration
 import org.bukkit.plugin.java.JavaPlugin
 import java.io.File
 
+/**
+ * LocaleManager is responsible for managing internationalization support in the plugin.
+ * It loads language files from YAML configurations and provides the translated messages.
+ */
 object LocaleManager {
+    /**
+     * A map storing language keys and their corresponding translations.
+     */
     private val messages = mutableMapOf<String, Map<String, String>>()
+
+    /**
+     * Default language code.
+     */
     private const val DEFAULT_LANG: String = "en_GB"
 
+    /**
+     * The plugin instance.
+     */
     private var plugin: JavaPlugin? = null
+
+    /**
+     * Current language being used.
+     */
     private var lang: String = DEFAULT_LANG
 
+    /**
+     * Sets the plugin instance for LocaleManager.
+     *
+     * @param plugin The JavaPlugin instance.
+     */
     fun setPlugin(plugin: JavaPlugin) {
         this.plugin = plugin
     }
 
+    /**
+     * Sets the current locale.
+     *
+     * @param lang The language code to switch to.
+     */
     fun setLocale(lang: String) {
         if (messages.containsKey(lang)) {
             this.lang = lang
         }
     }
 
+    /**
+     * Loads all available language files from the plugin's locales directory.
+     */
     fun loadLanguages() {
         val langFolder = File(plugin?.dataFolder, "locales")
         if (!langFolder.exists()) langFolder.mkdirs()
@@ -56,6 +87,13 @@ object LocaleManager {
         }
     }
 
+    /**
+     * Retrieves a translated message for the given key.
+     * If the message contains placeholders in {key} format, they will be replaced recursively.
+     *
+     * @param key The translation key.
+     * @return The translated message or a fallback "MISSING_TRANSLATION" string.
+     */
     private fun getMessage(key: String): String {
         val message = messages[lang]?.get(key)
 
@@ -72,6 +110,13 @@ object LocaleManager {
         return message ?: "MISSING_TRANSLATION"
     }
 
+    /**
+     * Retrieves a translated message as a Component with optional formatting arguments.
+     *
+     * @param key The translation key.
+     * @param formatArgs Optional formatting arguments.
+     * @return The translated message as a Component
+     */
     fun getMessageAsComponent(key: String, vararg formatArgs: Any): Component {
         val message = getMessage(key)
 

src/main/kotlin/dev/znci/rocket/scripting/GlobalInitializer.kt

@@ -0,0 +1,30 @@
+package dev.znci.rocket.scripting
+
+import dev.znci.rocket.scripting.globals.tables.LuaLocations
+import dev.znci.rocket.scripting.globals.tables.LuaPlayers
+import dev.znci.rocket.scripting.globals.tables.SimpleTest
+import dev.znci.rocket.scripting.globals.values.TestValue
+
+/**
+ * The `GlobalInitializer` object is responsible for initializing and registering global objects
+ * with the `ScriptManager`. It ensures that necessary components are properly registered for use
+ * for the server admins.
+ */
+object GlobalInitializer {
+    /**
+     * Initializes the global objects and registers them with the `ScriptManager`.
+     *
+     * It returns `true` upon successful registration of these objects.
+     *
+     * @return `true` if the global objects were successfully initialized and registered.
+     */
+    fun init(): Boolean {
+        ScriptManager.registerGlobal(SimpleTest())
+        ScriptManager.registerGlobal(TestValue())
+        ScriptManager.registerGlobal(LuaPlayers())
+        ScriptManager.registerGlobal(LuaLocations())
+        //ScriptManager.registerGlobal(GamemodeEnum())
+
+        return true
+    }
+}

src/main/kotlin/dev/znci/rocket/scripting/PermissionsManager.kt

@@ -17,18 +17,49 @@ package dev.znci.rocket.scripting
 
 import org.bukkit.entity.Player
 
+/**
+ * The `PermissionsManager` object is responsible for managing player permissions and group memberships.
+ * It provides utility functions to check if a player belongs to a specific group and if they have specific permissions.
+ */
 object PermissionsManager {
+    /**
+     * Checks if a player belongs to a specific group.
+     *
+     * This method checks whether the player has the permission for the specified group in the format `group.<groupName>`.
+     *
+     * @param player The player whose group is being checked.
+     * @param group The name of the group to check.
+     * @return `true` if the player belongs to the specified group, `false` otherwise.
+     */
     fun isPlayerInGroup(player: Player, group: String): Boolean {
         return player.hasPermission("group.$group")
     }
 
+    /**
+     * Retrieves all the groups the player belongs to.
+     *
+     * This method checks all the player's effective permissions, filtering out those that are related to groups
+     * (permissions starting with `group.`), and returns a list of group names.
+     *
+     * @param player The player whose groups are being retrieved.
+     * @return A list of group names that the player is part of.
+     */
     @Suppress("unused") // TODO: This will be used in the future. Remove this decorator when it's used.
     fun getPlayerGroups(player: Player): List<String> {
         return player.effectivePermissions
             .filter { it.permission.startsWith("group.") }
             .map { it.permission.substring(6) }
     }
 
+    /**
+     * Checks if a player has a specific permission.
+     *
+     * This method checks whether the player has the specified permission.
+     *
+     * @param player The player whose permissions are being checked.
+     * @param permission The permission to check.
+     * @return `true` if the player has the specified permission, `false` otherwise.
+     */
     fun hasPermission(player: Player, permission: String): Boolean {
         return player.hasPermission(permission)
     }

src/main/kotlin/dev/znci/rocket/scripting/PlayerManager.kt

@@ -15,9 +15,9 @@
  */
 package dev.znci.rocket.scripting
 
-import dev.znci.rocket.scripting.functions.LuaLocation.Companion.fromBukkit
-import dev.znci.rocket.scripting.functions.toBukkitLocation
+import dev.znci.rocket.scripting.globals.tables.LuaLocation.Companion.fromBukkit
+import dev.znci.rocket.scripting.globals.tables.toBukkitLocation
 import dev.znci.rocket.scripting.util.defineProperty
 import dev.znci.rocket.util.MessageFormatter
 import net.kyori.adventure.text.Component
 import net.kyori.adventure.title.Title
@@ -150,39 +150,39 @@
         })
 
         // read-only properties
         defineProperty(table, "name", { LuaValue.valueOf(player.name) })
         defineProperty(table, "uuid", { LuaValue.valueOf(player.uniqueId.toString()) })
         defineProperty(table, "world", { LuaValue.valueOf(player.world.name) })
         defineProperty(table, "ip", { LuaValue.valueOf(player.address?.hostString) })
         defineProperty(table, "isFlying", { LuaValue.valueOf(player.isFlying) })
         defineProperty(table, "isSneaking", { LuaValue.valueOf(player.isSneaking) })
         defineProperty(table, "isSprinting", { LuaValue.valueOf(player.isSprinting) })
         defineProperty(table, "isBlocking", { LuaValue.valueOf(player.isBlocking) })
         defineProperty(table, "isSleeping", { LuaValue.valueOf(player.isSleeping) })
         val block = player.getTargetBlockExact(100)
         if (block != null) {
             defineProperty(table, "targetBlockType", { LuaValue.valueOf(block.type.toString()) })
             defineProperty(table, "targetBlockLocation", { fromBukkit(block.location) })
             defineProperty(table, "targetBlockLightLevel", { LuaValue.valueOf(block.lightLevel.toDouble()) })
             defineProperty(table, "targetBlockTemperature", { LuaValue.valueOf(block.temperature) })
             defineProperty(table, "targetBlockHumidity", { LuaValue.valueOf(block.humidity) })
         }
         // writable properties
         defineProperty(
             table, "health",
             getter = { LuaValue.valueOf(player.health) },
             setter = { value -> player.health = value.todouble() },
             validator = { value -> value.isnumber() && value.todouble() >= 0 }
         )
 
         defineProperty(
             table, "foodLevel",
             getter = { LuaValue.valueOf(player.foodLevel) },
             setter = { value -> player.foodLevel = value.toint() },
             validator = { value -> value.isint() && value.toint() >= 0 && value.toint() <= 20 }
         )
 
         defineProperty(
             table, "gameMode",
             getter = { LuaValue.valueOf(player.gameMode.toString()) },
             setter = { value -> player.gameMode = GameMode.valueOf(value.tojstring()) },
@@ -191,21 +191,21 @@
             }
         )
 
         defineProperty(
             table, "xp",
             getter = { LuaValue.valueOf(player.exp.toDouble()) },
             setter = { value -> player.exp = value.tofloat() },
             validator = { value -> value.isnumber() && value.todouble() >= 0 && value.todouble() <= 1 }
         )
 
         defineProperty(
             table, "level",
             getter = { LuaValue.valueOf(player.level) },
             setter = { value -> player.level = value.toint() },
             validator = { value -> value.isint() && value.toint() >= 0 }
         )
 
         defineProperty(
             table, "location",
             getter = { fromBukkit(player.location) },
             setter = { value ->
@@ -216,35 +216,35 @@
             }
         )
 
         defineProperty(
             table, "isOp",
             getter = { LuaValue.valueOf(player.isOp) },
             setter = { value -> player.isOp = value.toboolean() },
             validator = { value -> value.isboolean() }
         )
 
         defineProperty(
             table, "saturation",
             getter = { LuaValue.valueOf(player.saturation.toDouble()) },
             setter = { value -> player.saturation = value.tofloat() },
             validator = { value -> value.isnumber() && value.todouble() >= 0 }
         )
 
         defineProperty(
             table, "exhaustion",
             getter = { LuaValue.valueOf(player.exhaustion.toDouble()) },
             setter = { value -> player.exhaustion = value.tofloat() },
             validator = { value -> value.isnumber() && value.todouble() >= 0 }
         )
 
         defineProperty(
             table, "displayName",
             getter = { LuaValue.valueOf(player.displayName().toString()) },
             setter = { value -> player.displayName(Component.text(value.tojstring())) },
             validator = { value -> value.isstring() }
         )
 
         defineProperty(
             table, "tabListName",
             getter = { LuaValue.valueOf(player.playerListName().toString()) },
             setter = { value -> player.playerListName(Component.text(value.tojstring())) },