HimDSL

HimDSL is a scripting language plugin for Minecraft Java servers. It lets server administrators and map makers write event listeners, scheduled tasks, GUI menus, numeric logic, and state machines using a concise, Java-like syntax — without writing or compiling a Java plugin.

Scripts use the .himdsl extension, live in plugins/HimDSL/, and run through a single command or automatically on server startup and shutdown.

---

Why HimDSL?

Most Minecraft servers need small pieces of logic all the time: welcome new players, autosave data, build a shop menu, run a countdown, check health. Writing a Java plugin for each of these is overkill. Existing scripting options are either too limited, too tied to a specific feature, or too far from a language you already know.

HimDSL sits in the middle. It gives you real variables, typed functions, structs, enums, lambdas, and function overloading — pieces Java programmers already know — plus Minecraft-aware tools built into the language itself:

• Selectors (@p, @a, @r, @s, @e) as first-class expressions.
• Event annotations for hooking into Bukkit events.
• Scheduler annotations for recurring or delayed tasks.
• GUI primitives with click and close callbacks.
• PlaceholderAPI integration without any Java.
• Direct Java interop: create objects from other plugins with new <fully-qualified-name>(...), call static methods, read static fields — no wrappers, no registration.

---

Features

Language

• int / double / bool / string / var with runtime type checks
• Full control flow: if / else, for, while, do-while, break, continue, return
• Typed functions with overloading, lambdas, and closures
• Structs with fields and member methods (instance + static)
• User-defined enums, comparable directly with strings
• Arrays, vector (list), set, map, stack, queue
• JSON serialization via toJson / fromJson

Minecraft integration

• Entity selectors with filters (limit, distance, level, name, world, gamemode, type)
• EntityRef with live fields (p.name, p.health, p.x) and reflected methods
• Placeholders ($player$, $world$, $server$, $boss$) for soft-dependency features
• @EventHandler for Bukkit events, @BukkitRunnable for scheduled tasks
• runcmd(executor, command) for dispatching commands (player or console)
• GUI system: create menus, assign icons, register click and close callbacks

Built-ins

• Math: abs, max, min, sqrt, pow, sin, rand, and many more
• BigDecimal: bigAdd, bigSub, bigMul, bigDiv, bigDivExact for money-precision arithmetic
• File I/O: fopen, fread, fwrite, fclose, freadlines, fwritelines, fexists, fdelete
• PlaceholderAPI bridge: papi, papiSet, papiRegister, papiUnregister, papiHas

Reliability

• Parser errors point to line and column.
• Runtime errors log with a stack trace without crashing the server.
• Optional dependencies (PlaceholderAPI, HimDungeons, WorldEdit) degrade gracefully — scripts still load when they are missing.

---

Example: Welcome new players

plugins/HimDSL/onServerLoad.himdsl:

@EventHandler
void onJoin(event(PlayerJoinEvent)) {
    player p = @s;
    runcmd("CONSOLE", "say Welcome " + p.name + " to the server！");
    runcmd(p.name, "title @s title {\"text\":\"Welcome\"}");
}

int main() {
    start("onJoin");
}

Example: Scheduled autosave

@BukkitRunnable
void autosave() sche = 300s {
    var lines = vector();
    lines.add("saved at tps=" + $server(tps)$);
    fwritelines("last_save.txt", lines);
}

int main() {
    start("autosave");
}

Example: Simple shop GUI

int main() {
    var gui = new GUI(3, "§6Shop");

    var diamond = new GUISlot(Material.DIAMOND);
    diamond.name = "§bDiamond";
    diamond.lore = {"§7Price: §e100", "§aLeft-click to buy"};
    diamond.onLeftClick = () -> {
        player p = @s;
        runcmd("CONSOLE", "eco take " + p.name + " 100");
        runcmd("CONSOLE", "give " + p.name + " diamond 1");
        runcmd(p.name, "msg §aPurchased");
        gui.close(p);
    };
    gui1 = diamond;

    gui.updateAll();
    gui.open(@p);
}

---

Commands and Permissions

Command	Description	Permission
/himdsl compile <path>	Syntax check only	himdsl.use
/himdsl run <path> [args]	Execute a script	himdsl.run
`/himdsl debug on\	off`	Toggle verbose logs
`/himdsl debug codeon\	codeoff`	Print script content before each run

All paths are relative to plugins/HimDSL/. All three permissions default to OP.

---

Requirements

• Server: Bukkit / Spigot / Paper 1.21+ (Paper 1.21+ recommended)
• Java: 25 or later (The newest version allows 17+)
• Optional:
  • PlaceholderAPI — enables papi(...) family
  • HimDungeons — enables $boss(...)$ and dungeon placeholders
  • WorldEdit — enables some world placeholders

---

Auto-run Scripts

Drop these files into plugins/HimDSL/ and they run automatically:

• onServerLoad.himdsl — after the server finishes loading
• onServerShutdown.himdsl — on plugin unload / server shutdown

---

Documentation

Full documentation is available on the project Wiki:

• Getting Started, Language Basics, Control Flow
• Functions, Lambdas, Functional Interfaces
• Data Structures, Custom Types, Java Interop
• Minecraft Integration, Events & Scheduling, GUI System
• Built-ins Reference, Advanced Topics, Pitfalls
• Example Scripts (recursion, loops, GUI shop, state machine, mini-game)

---

For Java Developers

HimDSL exposes a HimDSLAPI through Bukkit's ServicesManager so other plugins can compile, run, and generate scripts:

HimDSLAPI api = Bukkit.getServicesManager().load(HimDSLAPI.class);
if (api != null) {
    api.run(new File(himdslFolder, "script.himdsl"));
}

Add softdepend: [HimDSL] to your plugin.yml.

You can see the whole wiki at https://github.com/HimxhMC/HimDSL/wiki

---

License

See the LICENSE file.

Issues & Feedback

Bug reports and feature requests are welcome on the issue tracker.