🚀 MC-JS - JavaScript Plugin System for Minecraft

Write Minecraft Server Plugins in JavaScript - No Java Required!

MC-JS is a powerful plugin system that allows you to develop server plugins using modern JavaScript (ES6+) instead of Java. Perfect for developers who already know JavaScript or want to quickly create plugins without having to learn Java.

✨ Key Features

🎯 Core Capabilities

• 📝 Full JavaScript Support - Develop plugins in modern JavaScript using the Rhino Engine
• ⚡ Hot Reload - Reload plugins without server restart (/jsreload)
• 🔧 Complete API Access - Access to virtually all Bukkit/Spigot/Paper API functions
• 🎮 Event System - Register listeners for any Minecraft event with priority support
• 💬 Command System - Create custom commands with full tab completion support
• ⏰ Task Scheduling - Synchronous and asynchronous task scheduling
• 📦 Inventory Management - Create and manage custom GUI menus using standard Bukkit inventories (9-54 slots) with click handlers
• 🗄️ Database Support - Built-in SQLite database operations (INSERT, UPDATE, DELETE, SELECT)
• 🌐 HTTP Requests - Make HTTP GET/POST requests (api.network.httpGet / api.network.httpPost)
• 🔐 Encryption - MD5, SHA256, Base64 encoding/decoding
• 📁 File I/O - YAML, JSON, and text file support
• 🗂️ Persistent Data - Per-player storage, kits, prices and cooldowns that survive restarts (api.systems)
• ⏱️ Cooldown System - Built-in per-player cooldowns (api.systems.claimCooldown / cooldownRemaining)
• ⚙️ Config System - Per-plugin configuration files (YAML)
• 🌍 World Management - Control weather, time, world border, explosions
• 🎯 Entity Management - Spawn, control, and customize entities
• 🔒 Player Management - Ban, kick, teleport, health, food, gamemode

🛠️ Advanced Features

• 🎨 Particle Effects - Spawn particles with string or enum support
• 🔊 Sound System - Play sounds at locations or for players
• 📊 Scoreboard System - Create and manage scoreboards, teams, objectives
• 📝 Item Manipulation - Create, modify, and manage items with custom names and lore
• 🔒 Permission System - Check and manage player permissions
• 🎨 Color Support - Minecraft color codes and formatting utilities
• 🌐 HTTP Integration - Make external API calls and web requests
• 📊 Economy Integration - Vault economy support for server economies (api.vault)

📦 Installation

Requirements

• Minecraft Server: Paper 26.1 or higher (recommended: Paper)
• Java: Version 25 or higher
• Minecraft Version: 26.1

Steps

1. Download the latest release from the Releases page
2. Place the JAR file in your server's plugins/ folder
3. Start or restart your server
4. Create JS plugins in plugins/MC-JS/js-plugins/ directory

The plugin will automatically create the js-plugins directory and copy an example plugin on first run.

🚀 Quick Start

Creating Your First Plugin

1. Navigate to plugins/MC-JS/js-plugins/ directory
2. Create a new file with .js extension (e.g., myplugin.js)
3. Add the following code:

var pluginInfo = {
    name: "My First Plugin",
    version: "1.0.0",
    author: "YourName",
    description: "My awesome plugin!"
};


function onEnable() {
    logger.info("My plugin is enabled!");

    // Register a command
    api.registerCommand("hello", "Say hello", "/hello", function(sender, args) {
        api.sendMessage(sender, "&aHello from JavaScript!");
        return true;
    });

    // Register an event
    api.registerEvent("player.PlayerJoinEvent", function(event) {
        var player = event.getPlayer();
        api.sendMessage(player, "&6Welcome to the server!");
    });
}


function onDisable() {
    logger.info("My plugin is disabled!");
}


this.onEnable = onEnable;
this.onDisable = onDisable;
this.pluginInfo = pluginInfo;

4. Save the file - The plugin will auto-load on server start, or use /jsreload to reload
5. Test your command - Type /hello in-game or in console
6. Check console - Look for "My plugin is enabled!" message

💡 Tip: Use /jslist to see all loaded JavaScript plugins and /jsreload <plugin> to reload a specific plugin.

🖥️ Web Dashboard & Block Editor

MC-JS ships with a full web-based Plugin Studio — no separate Node process needed, all editor assets (CodeMirror, Blockly) are served locally from the JAR.

Access

Run /mjs dashboard in-game (permission mcjs.dashboard; operators and mcjs.admin have it by default) to receive a one-time login link. Open that link in your browser, then run the shown /mjs dashboard <verify-code> command with the same player to grant access.

The default listener is 127.0.0.1:8765 — only reachable on the server computer. For remote access, put an HTTPS reverse proxy in front of that port and set its address as dashboard.public-url in config.yml. Links expire after 5 minutes by default, sessions after 30 minutes; access is revoked on sign-out, game quit, or server restart.

Editor Features

• Create, search, open, save, start, stop and delete plugins in plugins/MC-JS/js-plugins/
• JavaScript editor with syntax highlighting, line numbers, search, indentation, undo/redo, API suggestions and Ctrl+S
• Syntax checking with the same Rhino version the server uses — checking and saving never execute your code
• Drag-and-drop block editor (Blockly) with lifecycle events, player events, commands and permissions, messages, titles, items, player values, sounds, teleportation, timers, conditions, loops, variables, functions, text, lists and persistent configuration values
• Complete, editable block systems out of the box: coins shop, daily kit, mining quest and player homes, plus welcome, command and empty projects
• Block search, flow navigator, auto-arrange, live connection diagnostics and a step-by-step builder guide
• Import/export for JavaScript and complete .mcjs.json block projects

Building Complete Systems

Templates use normal editable blocks — commands and reusable functions included:

System	Commands	What it shows
Coins shop	/shop, /coins	3-row menu, welcome balance, diamond purchase with funds + inventory checks
Daily kit	/kit, /kits	Reusable kit function, 24-hour restart-safe cooldown, full-inventory handling
Mining quest	/quest	Sidebar progress, 10 stone breaks → diamond + quest coins, cancelled breaks ignored
Player homes	/sethome, /home	Saved world, coordinates and facing, teleport with 10-second cooldown

Player data (by UUID) and coins survive restarts in configs/<plugin-id>.yml. Each plugin has its own data and currency — this storage is not a Vault economy. Menu slots start at 0 with 9 per row; buttons can open another menu or call any reusable function.

Note: Block data lives in .dashboard/<name>.json next to each .js file. If the JavaScript changes externally, the dashboard opens it as source so stale blocks can't silently overwrite your changes.

📚 Available Objects

These objects are automatically available in all JavaScript plugins:

Object	Description	Usage
api	Complete JS API wrapper - main interface for all operations	api.registerCommand(...)
server	Minecraft server instance	server.getOnlinePlayers()
plugin	Main plugin instance	plugin.getName()
logger	Plugin logger	logger.info("Message")
scheduler	Server scheduler	scheduler.runTask(...)
Bukkit	Direct Bukkit API access	Bukkit.getServer()

🎮 Commands

Command	Description	Permission
/mjs dashboard	Open and verify the MC-JS plugin editor	mcjs.dashboard
/jsreload	Reload all JS plugins	mcjs.admin
/jsreload <plugin>	Reload specific plugin	mcjs.admin
/jslist	List all loaded JS plugins	mcjs.admin
/jsconfig	View or reload plugin configuration	mcjs.admin

📖 Documentation

📖 Full Documentation: Visit our complete documentation website for detailed API reference, examples, and guides.

💡 Example Applications

• Welcome Plugins - Greet players with messages, titles, and sounds
• Statistics Systems - Track player statistics with SQLite databases
• Custom GUI Menus - Create interactive menus using standard Bukkit inventories with custom layouts and click handlers
• Mini-Games - Develop simple games with event handling
• Utility Plugins - Create helpful tools and commands
• Integration Plugins - Connect your server with external APIs

🛠️ Technical Details

• JavaScript Engine: Rhino (Mozilla)
• MC-JS Version: 2.1.0
• API Version: 26.1
• Compatibility: Paper (Vault optional, soft-dependency)
• License: MIT

🤝 Support

• GitHub: LootingVI/MC-JS
• Issues: GitHub Issues
• Documentation: lootingvi.github.io/MC-JS

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ for the Minecraft Community