Birdlibraryapi

BirdLibraryApi turns your server into a live scripting platform — in JavaScript, Lua, or Python, whichever you already know. Drop a .js, .lua, or .py file into plugins/BirdApi/, and you've got a working plugin — events, commands, timers, and full access to the Bukkit API — with zero Maven, zero plugin.yml, zero restarts to test changes.

Powered by real language engines, not a custom pseudo-English DSL: GraalJS for JavaScript, LuaJ for Lua, and GraalPy for Python. If you already know any of the three, you already know how to write BirdLibraryApi scripts.

✨ Why BirdLibraryApi?

Skript-style scripting is great for quick edits, but it hits a ceiling fast. BirdLibraryApi is built for people who want that same "no compiling needed" convenience, without giving up real programming — and without being locked into one language:

• Pick your language — full JavaScript (ECMAScript), Lua, or Python, all loaded side by side. Mix and match across scripts, or stick to just one.
• Unlimited Bukkit/Paper API access — reach any class on the classpath instantly: Java.type("...") in JS, luajava.bindClass("...") in Lua, java.type("...") in Python. No addon required, ever.
• Safe, granular reloading — reload one script without touching the others. Every listener, command, and scheduled task a script registers is cleaned up automatically.
• Readable errors — syntax and runtime errors are reported straight to chat when you reload, with file name and line number. A broken script never takes down the plugin or your other scripts.
• Built-in internet access — Bird.fetch(...) for REST APIs, plus ready-made Discord webhook/embed support.

🔧 What you get out of the box

• Events & commands — register with a single function call, no plugin.yml entry needed
• Scheduler — sync/async tasks, auto-cancelled on reload, plus an async-only sleep() for Skript-style wait sequences
• Player & world helpers — health, food, potion effects, gamemode, teleport, nearby players, ping, UUIDs, and more
• Chat, action bar & titles — with &/§ color code support built in
• Items, sounds & particles — one-liners for custom-named items, sound effects, particle bursts
• Persistent storage — per-script key/value data store, plus sandboxed file read/write for JSON exports, logs, and small "databases"
• Cooldown system — for abilities, commands, anything you need to rate-limit per player

📦 Getting started

1. Drop BirdLibraryApi.jar into plugins/
2. Start your server once — plugins/BirdApi/ is created automatically
3. Add a .js, .lua, or .py script to that folder
4. Run /birdlib reload — no restart needed

Bird.onCommand("hello", function (sender, label, args) {
    sender.sendMessage("Hi " + args.length + " args");
});

Bird.onEvent("org.bukkit.event.player.PlayerJoinEvent", function (event) {
    Bird.sendTitle(event.getPlayer(), "&6&lWelcome!", "&7Glad you're here");
});

Bird:onCommand("hello", "", function(sender, label, args)
    sender:sendMessage("Hi " .. #args .. " args")
end, function(sender, alias, args) return nil end)

Bird:onEvent("org.bukkit.event.player.PlayerJoinEvent", function(event)
    Bird:sendTitle(event:getPlayer(), "&6&lWelcome!", "&7Glad you're here")
end)

def hello(sender, label, args):
    sender.sendMessage("Hi " + str(len(args)) + " args")

Bird.onCommand("hello", hello)

def on_join(event):
    Bird.sendTitle(event.getPlayer(), "&6&lWelcome!", "&7Glad you're here")

Bird.onEvent("org.bukkit.event.player.PlayerJoinEvent", on_join)

📖 Documentation & Wiki

Full API reference, examples, and guides: https://birdwiki.craftcloudnet.com

✅ Compatibility

• Server software: Paper (and forks)
• Requires: Java 17+
• No other plugin dependencies — GraalJS, LuaJ, and GraalPy are all shaded directly into the jar

💬 Support

Found a bug or have a feature request? Open an issue or drop by the Report issues linked above.