LuaInMineBukkit II

Run Lua Script in Your Bukkit Server!

Compared with the previous generation, this generation will focus on native LuaVM and try to make it easier to use, more friendly . It supports Lua5.1(LuaJIT), Lua5.2, Lua5.3, Lua5.4.

Welcome to GitHub open issue!

What is this plugin?
=====
This plugin offers the possibility to “use Lua to interact with Bukkit”. Lua is a small scripting language with a very simple syntax and a good speed. Imagine how nice it would be to write a Bukkit plugin with a lightweight script that doesn't need to be compiled to run. If you want to change something, just change it and reload the script, it's like a dream.

Of course, the Lua script interpreter used by this plugin is not the Luaj project, but the native Lua virtual machine. Thanks to Kepler's luajava project, this plugin is possible. However, compared to the first LuaInMinecraftBukkit plugin, the luajava project used has been more thoroughly refurbished by me, and compared to Kepler's original repository, I've improved the reflection support for it, as well as providing very friendly exception hints on the C side.

What can it do now?
=====

There are basically two main functions supported.

Register commands: Register any command you want, and automatically generate help and command hierarchies.
Listening to events: Listen to any Bukkit event you want, even if it's a custom event from another plugin.

However , relying on Java's reflection mechanism and dynamic proxy mechanism , it can be realized in the lua script to inherit Java interfaces , call any public methods , public properties of Java types . That is to say, this plugin can dynamically load scripts, enjoying a subset of Java's functionality. Of course, reflection is not everything, there will still be a lot of Lua side can not handle the situation, then you need to use Java for Lua bridge. However, I will try to simplify the interaction between Lua and Java as much as possible during the development process.

In addition to the above, as with the first generation, it is also possible to load dynamic link libraries written in C/C++. Of course, this is all supported by the Lua language itself, and for those who don't like to write Java, you can try to use Lua + FFI to write server interaction scripts.

Next Plan
=====

Next, ffi module for Lua 5.2+
屏幕截图_20250705_105638.png

Installation
=====
Just put jar file to the plugins folder, and launch your server. Now, the plugin will detect your system and arch, auto download the pre-compiled native library for you!

QuickStart
=====
follow the quick start document, maka a lua terminal in your chat box!
QuickStart.1_compressed.png

Configuration
=====

edit "config.json", this file allow comment like "// comment".
the example configuration is(Config format is changed):

{
  // project resource base url
  "projectUrl": "https://raw.githubusercontent.com/SmileYik/LuaInMinecraftBukkitII/refs/heads/gh-page",
  // lua version
  "luaVersion": "lua-5.4.8",
  // always check native library hashes
  "alwaysCheckHashes": false,
  // enable debug
  "debug": false,
  // lua 环境
  "luaState": {
    // lua 环境 id
    "default": {
      // "/" means folder "/plugins/LuaInMinecraftBukkitII/luastate"
      "rootDir": "/",
      "ignoreAccessLimit": false,
      "initialization": [
        {
          // the file should exists in folder "/plugins/LuaInMinecraftBukkitII/luastate"
          "file": "test.lua",
          "autoReload": false,
          // depends java plugin name, for example: PlaceholderAPI
          "depends": []
        }
      ]
    }
  }
}

Example Lua Script file
=====

This lua script file can work with example configuration.
This example could run aysnc timer, subscribe bukkit event and register custom command in your server.

-- file location: /plugins/LuaInMinecraftBukkitII/luastate/default/test.lua
local monitorTask = nil

-- define command tables, will use it to build command class.
local commands = {
    {
        command = "hello",
        description = "Say Hello to you",
        args = {"msg"},
        handler = function (sender, args)
            sender:sendMessage("Hello, " .. args[1] .. "!")
        end
    },
    {
        command = "hi",
        description = "Say Hi to you",
        needPlayer = true,
        handler = function (sender, args)
            sender:sendMessage("Hello, " .. sender:getName() .. "!")
        end
    }
}

-- build a command class
local topCommandClass = luaBukkit.env:commandClassBuilder()
    :commands(commands)
    :command("say")
        :args({"msg"})
        :description("say something")
        :handler(function(sender, args)
            sender:sendMessage(args[1])
        end)
    :aliases({"tc", "testc"})
    :build("TestCommand")



-- register command class
-- after register, you can use "/TestCommand" or aliases "/tc", "/testc" to run command.
-- also you can use "/TestCommand help" to display command help information.
local result = luaBukkit.env:registerCommand("TestCommand", {"tc", "testc"}, {topCommandClass})
if result:isError() then luaBukkit.log:info("Register command failed!") end

-- define listeners
local listeners = {
    {
        event = "PlayerJoinEvent",
        handler = function(event) luaBukkit.log:info("event normal") end
    },
    {
        event = "org.bukkit.event.player.PlayerJoinEvent",
        priority = "HIGH",
        handler = function(event) luaBukkit.log:info("event high") end
    }
}

-- build listeners
luaBukkit.env:listenerBuilder()
    :subscribes(listeners)
    :subscribe({
        event = "PlayerJoinEvent",
        priority = "LOW",
        handler = function(event)
            luaBukkit.log:info("event low")
            if monitorTask ~= nil then
                monitorTask:cancel()
            end
        end
    })
    :build()
    :register("MyListeners")

-- global function variable, can be called by command
-- execute command in game: /lua call default test
function test()
    luaBukkit.log:info("Test")
end

monitorTask = luaBukkit.helper:asyncTimer(
    function()
        luaBukkit.log:info("Still not player join sever...?")
    end, 0, 20, nil
)

luaBukkit.helper:runnable(function() luaBukkit.log:info("runnable") end):run()

Commands
=====
After launched server, you just dispatch command: "/lua help", all command request op permission.

Global Variable
=====

"luaBukkit" is a global table variable.

luaBukkit.env: ILuaEnv
luaBukkit.helper: LuaHelper
luaBukkit.log: Logger
luaBukkit.bukkit: Bukkit
luaBukkit.plugin: Bukkit plugin instance.
luaBukkit.server: CraftServer

LuaInMineBukkit II

Configuration=====

Example Lua Script file=====

Commands=====After launched server, you just dispatch command: "/lua help", all command request op permission.Global Variable=====

Configuration
=====

Example Lua Script file
=====

Commands
=====
After launched server, you just dispatch command: "/lua help", all command request op permission.

Global Variable
=====