reflection_api.md

Reflection API Documentation

The Reflection API provides Lua scripts with the ability to load Java classes, create instances, call static methods, and cast objects to specific types.

Global Access

These functions are available globally in Lua scripts without any prefix.

Functions

class

Load a Java class by its fully qualified name.

Syntax:

local classObj = class(className)

Parameters:

• className (string): The fully qualified class name (e.g., "org.bukkit.Bukkit")

Returns:

• classObj (userdata): The loaded class object, or nil on failure

Example:

local bukkit = class("org.bukkit.Bukkit")
local server = class("org.bukkit.Server")
local material = class("org.bukkit.Material")

---

castTo

Cast a Java object to a specific class type. This is useful when you need to access methods or fields that are specific to a subclass.

Syntax:

local castObject = castTo(object, className)

Parameters:

• object (userdata): The Java object to cast
• className (string): The fully qualified class name to cast to (e.g., "org.bukkit.entity.Player")

Returns:

• castObject (userdata): The cast object as userdata, or nil if the object is not an instance of the target class

Example:

local material = class("org.bukkit.Material")

registerCommand("giveitem", "myplugin.giveitem", function(sender, args)
    -- Cast CommandSender to Player to access player-specific methods
    local player = castTo(sender, "org.bukkit.entity.Player")
    if not player then
        AdventureApi:sendColored(sender, "red", "You must be a player to use this command!")
        return
    end
    -- Create an ItemStack using newInstance and add it to the player's inventory
    local itemStack = newInstance("org.bukkit.inventory.ItemStack", material.DIAMOND, 3)
    player:getInventory():addItem({itemStack})
    AdventureApi:sendColored(player, "green", "You got 3 diamonds!")
end)

---

callStatic

Call a static method on a Java class.

Syntax:

local result = callStatic(className, methodName, ...)

Parameters:

• className (string): The fully qualified class name
• methodName (string): The name of the static method to call
• ... (varargs): Arguments to pass to the method

Returns:

• result (various): The method's return value coerced to Lua, or nil on failure

Example:

local uuid = callStatic("java.util.UUID", "randomUUID")
print(uuid:toString())

local list = callStatic("java.util.Arrays", "asList", "a", "b", "c")

---

newInstance

Create a new instance of a Java class using a matching constructor.

Syntax:

local instance = newInstance(className, ...)

Parameters:

• className (string): The fully qualified class name
• ... (varargs): Arguments to pass to the constructor

Returns:

• instance (userdata): The new instance as userdata, or nil on failure

Example:

local material = class("org.bukkit.Material")
local itemStack = newInstance("org.bukkit.inventory.ItemStack", material.DIAMOND, 64)

local list = newInstance("java.util.ArrayList")
list:add("hello")

---

Notes

• All class names must be fully qualified (e.g., "org.bukkit.Bukkit", not just "Bukkit")
• Class loading is cached for performance, and every script that loads the same class gets the same cached value
• All four functions are safe to call from an asynchronous scheduler callback as well as from the main thread. They hold no mutable state of their own beyond that cache, and Lua only ever runs one callback at a time, which is what keeps the underlying Java coercion safe
• That guarantee stops at the Lua boundary: the class you load is only as thread-safe as the Java it belongs to. Reflecting your way to a Bukkit World or Player from an asynchronous callback is exactly as unsafe as calling WorldApi there would be
• castTo returns nil if the object is not an instance of the target class
• newInstance finds a constructor matching the provided argument types
• callStatic can only call public static methods