MC-JS Documentation

Example 1: Welcome Plugin

var pluginInfo = {
    name: "Welcome Plugin",
    version: "1.0.0",
    author: "YourName"
};

function onEnable() {
    api.registerEvent("player.PlayerJoinEvent", function(event) {
        var player = event.getPlayer();
        
        // Welcome message
        api.sendMessage(player, "&6Welcome to the server, &b" + player.getName() + "&6!");
        
        // Title
        api.sendTitle(player, "&aWelcome!", "&eEnjoy your stay!", 10, 70, 20);
        
        // Sound
        api.playSound(player, "ENTITY_PLAYER_LEVELUP", 1.0, 1.0);
        
        // Give welcome kit after 1 second
        api.runTaskLater(20, function() {
            var bread = api.createItemStack(api.getMaterial("BREAD"), 5);
            var sword = api.createItemStack(api.getMaterial("WOODEN_SWORD"), 1);
            api.giveItem(player, bread);
            api.giveItem(player, sword);
            api.sendMessage(player, "&aYou received a welcome kit!");
        });
    });
}

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

Example 2: Stats Plugin with Database

var pluginInfo = {
    name: "Stats Plugin",
    version: "1.0.0"
};

function onEnable() {
    // Create database
    api.createTable("stats", "player_stats", {
        "player_name": "TEXT PRIMARY KEY",
        "kills": "INTEGER DEFAULT 0",
        "deaths": "INTEGER DEFAULT 0",
        "playtime": "INTEGER DEFAULT 0"
    });
    
    // Stats command
    api.registerCommand("stats", "View your stats", "/stats [player]", 
        function(sender, args) {
            var targetName = args.length > 0 ? args[0] : sender.getName();
            
            var results = api.querySQL("stats", 
                "SELECT * FROM player_stats WHERE player_name = '" + targetName + "'");
            
            if (results.length > 0) {
                var stats = results[0];
                api.sendMessage(sender, "&6=== Stats for " + targetName + " ===");
                api.sendMessage(sender, "&eKills: &a" + stats.kills);
                api.sendMessage(sender, "&eDeaths: &c" + stats.deaths);
                api.sendMessage(sender, "&ePlaytime: &b" + Math.floor(stats.playtime / 3600) + " hours");
            } else {
                api.sendMessage(sender, "&cNo stats found for " + targetName);
            }
            
            return true;
        },
        function(sender, args) {
            return api.getPlayerNames();
        }
    );
    
    // Track player deaths
    api.registerEvent("entity.PlayerDeathEvent", function(event) {
        var killer = event.getEntity().getKiller();
        var victim = event.getEntity();
        
        if (killer) {
            // Update killer stats
            var killerStats = api.querySQL("stats", 
                "SELECT kills FROM player_stats WHERE player_name = '" + killer.getName() + "'");
            
            if (killerStats.length > 0) {
                api.updateData("stats", "player_stats", 
                    { "kills": killerStats[0].kills + 1 },
                    "player_name = '" + killer.getName() + "'");
            } else {
                api.insertData("stats", "player_stats", {
                    "player_name": killer.getName(),
                    "kills": 1,
                    "deaths": 0
                });
            }
        }
        
        // Update victim stats
        var victimStats = api.querySQL("stats",
            "SELECT deaths FROM player_stats WHERE player_name = '" + victim.getName() + "'");
        
        if (victimStats.length > 0) {
            api.updateData("stats", "player_stats",
                { "deaths": victimStats[0].deaths + 1 },
                "player_name = '" + victim.getName() + "'");
        } else {
            api.insertData("stats", "player_stats", {
                "player_name": victim.getName(),
                "kills": 0,
                "deaths": 1
            });
        }
    });
}

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

Example 3: Custom GUI Menu (Old Method)

var pluginInfo = {
    name: "Menu Plugin",
    version: "1.0.0"
};

function onEnable() {
    api.registerCommand("menu", "Open custom menu", "/menu", function(sender, args) {
        if (!(sender instanceof Player)) {
            api.sendMessage(sender, "&cOnly players can use this command!");
            return false;
        }
        
        var player = sender;
        var inv = api.createInventory(null, 27, "&6Custom Menu");
        
        // Option 1
        var item1 = api.createItemStack(api.getMaterial("DIAMOND"), 1);
        item1 = api.setItemDisplayName(item1, "&bOption 1");
        item1 = api.setItemLore(item1, ["&7Click to get diamonds!"]);
        api.setInventoryItem(inv, 10, item1);
        
        // Option 2
        var item2 = api.createItemStack(api.getMaterial("EMERALD"), 1);
        item2 = api.setItemDisplayName(item2, "&aOption 2");
        item2 = api.setItemLore(item2, ["&7Click to get emeralds!"]);
        api.setInventoryItem(inv, 16, item2);
        
        // Close button
        var close = api.createItemStack(api.getMaterial("BARRIER"), 1);
        close = api.setItemDisplayName(close, "&cClose Menu");
        api.setInventoryItem(inv, 22, close);
        
        // Register click handler
        api.registerInventoryClick(inv, function(event) {
            event.setCancelled(true);
            var slot = event.getSlot();
            
            if (slot === 10) {
                api.sendMessage(player, "&aYou clicked Option 1!");
                api.giveItem(player, api.createItemStack(api.getMaterial("DIAMOND"), 5));
            } else if (slot === 16) {
                api.sendMessage(player, "&aYou clicked Option 2!");
                api.giveItem(player, api.createItemStack(api.getMaterial("EMERALD"), 5));
            } else if (slot === 22) {
                player.closeInventory();
            }
        });
        
        player.openInventory(inv);
        return true;
    });
}

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

Example 4: GUI Builder Pattern (Recommended)

var pluginInfo = {
    name: "Shop Plugin",
    version: "1.0.0"
};

function onEnable() {
    api.registerCommand("shop", "Open shop", "/shop", function(sender, args) {
        if (!(sender instanceof Player)) {
            api.sendMessage(sender, "&cOnly players can use this command!");
            return false;
        }
        
        var player = sender;
        
        // Create GUI with builder pattern
        var gui = api.createGUI("&6&lShop Menu", 3);
        
        // Background item
        var bg = api.createItemStack(api.getMaterial("GRAY_STAINED_GLASS_PANE"), 1);
        bg = api.setItemDisplayName(bg, " ");
        gui.fillBorders(bg);
        gui.setBackground(bg);
        
        // Shop item 1 - Diamond Sword
        var sword = api.createItemStack(api.getMaterial("DIAMOND_SWORD"), 1);
        sword = api.setItemDisplayName(sword, "&bDiamond Sword");
        sword = api.setItemLore(sword, [
            "&7Price: &a100 Coins",
            "&7Click to purchase!"
        ]);
        gui.setItem(10, sword, function(event) {
            event.setCancelled(true);
            api.sendMessage(player, "&aYou purchased a Diamond Sword!");
            api.giveItem(player, sword);
        });
        
        // Shop item 2 - Golden Apple
        var apple = api.createItemStack(api.getMaterial("GOLDEN_APPLE"), 1);
        apple = api.setItemDisplayName(apple, "&eGolden Apple");
        apple = api.setItemLore(apple, [
            "&7Price: &a50 Coins",
            "&7Click to purchase!"
        ]);
        gui.setItem(13, apple, function(event) {
            event.setCancelled(true);
            api.sendMessage(player, "&aYou purchased a Golden Apple!");
            api.giveItem(player, apple);
        });
        
        // Shop item 3 - Enchanted Book
        var book = api.createItemStack(api.getMaterial("ENCHANTED_BOOK"), 1);
        book = api.setItemDisplayName(book, "&dEnchanted Book");
        book = api.setItemLore(book, [
            "&7Price: &a200 Coins",
            "&7Click to purchase!"
        ]);
        gui.setItem(16, book, function(event) {
            event.setCancelled(true);
            api.sendMessage(player, "&aYou purchased an Enchanted Book!");
            api.giveItem(player, book);
        });
        
        // Close button
        var close = api.createItemStack(api.getMaterial("BARRIER"), 1);
        close = api.setItemDisplayName(close, "&cClose Shop");
        gui.setItem(22, close, function(event) {
            event.setCancelled(true);
            player.closeInventory();
        });
        
        // Global click handler (optional)
        gui.onClick(function(event) {
            // Log all clicks for debugging
            // api.sendMessage(player, "&7Debug: Clicked slot " + event.getSlot());
        });
        
        // Close handler
        gui.onClose(function(event) {
            api.sendMessage(player, "&7Shop closed. Come back soon!");
        });
        
        // Build and open
        gui.buildAndOpen(player);
        return true;
    });
}

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

Example 4: Advanced Cooldown System

var pluginInfo = {
    name: "Cooldown Example",
    version: "1.0.0"
};

function onEnable() {
    api.registerCommand("heal", "Heal yourself", "/heal", function(sender, args) {
        if (!(sender instanceof Player)) {
            api.sendMessage(sender, "&cOnly players can use this!");
            return false;
        }
        
        var player = sender;
        var cooldownKey = "heal";
        
        if (api.hasCooldown(player.getName(), cooldownKey)) {
            var remaining = api.getCooldownRemaining(player.getName(), cooldownKey);
            api.sendMessage(player, "&cCooldown: " + Math.ceil(remaining / 1000) + " seconds");
            return false;
        }
        
        // Heal player
        api.setHealth(player, api.getMaxHealth(player));
        api.setFoodLevel(player, 20);
        api.sendMessage(player, "&aYou have been healed!");
        
        // Set 30 second cooldown
        api.setCooldown(player.getName(), cooldownKey, 30000);
        
        return true;
    });
}

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

Example 5: BossBar Progress Bar

var pluginInfo = {
    name: "BossBar Example",
    version: "1.0.0"
};

var bossBars = {};

function onEnable() {
    api.registerEvent("player.PlayerJoinEvent", function(event) {
        var player = event.getPlayer();
        
        // Create boss bar
        var bossBar = api.createBossBar("&aLoading...", "GREEN", "SOLID");
        bossBar.addPlayer(player);
        bossBars[player.getName()] = bossBar;
        
        // Animate progress
        var progress = 0;
        var task = api.runTaskTimer(0, 5, function() {
            if (!bossBars[player.getName()]) {
                api.cancelTask(task);
                return;
            }
            
            progress += 0.02;
            if (progress > 1) {
                progress = 1;
                bossBar.setTitle("&aWelcome!");
                api.cancelTask(task);
                
                // Remove after 3 seconds
                api.runTaskLater(60, function() {
                    bossBar.removeAll();
                    delete bossBars[player.getName()];
                });
            } else {
                bossBar.setProgress(progress);
                bossBar.setTitle("&aLoading... " + Math.floor(progress * 100) + "%");
            }
        });
    });
    
    api.registerEvent("player.PlayerQuitEvent", function(event) {
        var player = event.getPlayer();
        if (bossBars[player.getName()]) {
            bossBars[player.getName()].removeAll();
            delete bossBars[player.getName()];
        }
    });
}

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

Example 6: World Protection System

var pluginInfo = {
    name: "World Protection",
    version: "1.0.0"
};

var protectedRegions = [];

function onEnable() {
    // Define protected region (spawn area)
    var spawn = api.getWorlds()[0].getSpawnLocation();
    protectedRegions.push({
        center: spawn,
        radius: 50
    });
    
    // Protect blocks
    api.registerEvent("block.BlockBreakEvent", function(event) {
        var player = event.getPlayer();
        var block = event.getBlock();
        
        if (isInProtectedRegion(block.getLocation())) {
            if (!api.hasPermission(player, "protection.bypass")) {
                event.setCancelled(true);
                api.sendMessage(player, "&cYou cannot break blocks in the protected area!");
                api.playSound(player, "ENTITY_VILLAGER_NO", 1.0, 1.0);
            }
        }
    });
    
    api.registerEvent("block.BlockPlaceEvent", function(event) {
        var player = event.getPlayer();
        var block = event.getBlock();
        
        if (isInProtectedRegion(block.getLocation())) {
            if (!api.hasPermission(player, "protection.bypass")) {
                event.setCancelled(true);
                api.sendMessage(player, "&cYou cannot place blocks in the protected area!");
            }
        }
    });
    
    // Visual indicator
    api.registerEvent("player.PlayerMoveEvent", function(event) {
        var player = event.getPlayer();
        if (isInProtectedRegion(player.getLocation())) {
            api.sendActionBar(player, "&c⚠ Protected Area");
        }
    });
}

function isInProtectedRegion(location) {
    for (var i = 0; i < protectedRegions.length; i++) {
        var region = protectedRegions[i];
        var distance = api.getDistance(location, region.center);
        if (distance <= region.radius) {
            return true;
        }
    }
    return false;
}

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

All Available Methods

This is a comprehensive list of all API methods available in MC-JS. Click on a category to expand:

BossBar

// Create boss bar
var bossBar = api.createBossBar("&cBoss Fight!", "RED", "SOLID");
bossBar.addPlayer(player);
bossBar.setProgress(0.5); // 50%

// Update progress
var progress = 0;
var task = api.runTaskTimer(0, 20, function() {
    progress += 0.01;
    if (progress > 1) progress = 0;
    bossBar.setProgress(progress);
    bossBar.setTitle("&cBoss: " + Math.floor(progress * 100) + "%");
});

// Remove after 10 seconds
api.runTaskLater(200, function() {
    bossBar.removeAll();
    api.cancelTask(task);
});

Permissions & Player Management

// Check permissions
if (api.hasPermission(player, "myplugin.use")) {
    // Player has permission
}

// Add/remove permissions dynamically
api.addPermission(player, "myplugin.vip");
api.removePermission(player, "myplugin.vip");

// OP management
if (api.isOp(player)) {
    api.sendMessage(player, "You are OP!");
}
api.setOp(player, true);

// Player metadata
api.setPlayerMetadata(player, "lastLogin", api.getCurrentTimeMillis());
var lastLogin = api.getPlayerMetadata(player, "lastLogin");
if (api.hasPlayerMetadata(player, "lastLogin")) {
    logger.info("Last login: " + lastLogin);
}

// Whitelist management
api.addToWhitelist("PlayerName");
api.removeFromWhitelist("PlayerName");
if (api.isWhitelisted("PlayerName")) {
    logger.info("Player is whitelisted");
}
api.setWhitelistEnabled(true);

Particles & Sounds

// Spawn particles (string or enum)
api.spawnParticle(location, "FIREWORK", 10, 0.5, 0.5, 0.5, 0.1);
api.spawnParticle(location, Particle.FLAME, 5, 0, 0, 0);

// Play sounds
api.playSound(location, "ENTITY_PLAYER_LEVELUP", 1.0, 1.0);
api.playSound(player, Sound.ENTITY_EXPERIENCE_ORB_PICKUP, 0.5, 1.5);

// Particle effect at player location
api.registerEvent("player.PlayerMoveEvent", function(event) {
    var player = event.getPlayer();
    if (player.isSprinting()) {
        api.spawnParticle(player.getLocation(), "CLOUD", 3, 0, 0, 0);
    }
});

Entity Manipulation

// Spawn entity
var zombie = api.spawnEntity(location, "ZOMBIE");

// Set properties
api.setEntityCustomName(zombie, "&cBoss Zombie");
api.setEntityGlowing(zombie, true);
api.setEntityGravity(zombie, false);
api.setEntityInvulnerable(zombie, true);

// AI control
api.setEntityAI(zombie, false); // Disable AI
if (!api.hasEntityAI(zombie)) {
    logger.info("Zombie has no AI");
}

// Silent and collidable
api.setEntitySilent(zombie, true);
api.setEntityCollidable(zombie, false);

// Teleport entity
var targetLocation = api.createLocation(world, 100, 64, 200);
api.teleportEntity(zombie, targetLocation);

// Or teleport to another entity
api.teleportEntity(zombie, player);

// Get entity location
var entityLoc = api.getEntityLocation(zombie);

// Remove entity
api.removeEntity(zombie);

World Management

// Difficulty
api.setWorldDifficulty(world, "HARD");
var difficulty = api.getWorldDifficulty(world);

// PvP
api.setWorldPVP(world, true);
if (api.isWorldPVP(world)) {
    logger.info("PvP is enabled");
}

// Spawn location
var spawnLoc = api.createLocation(world, 0, 64, 0);
api.setWorldSpawnLocation(world, spawnLoc);
var currentSpawn = api.getWorldSpawnLocation(world);

// Auto-save
api.setWorldAutoSave(world, false);
if (!api.isWorldAutoSave(world)) {
    logger.info("Auto-save disabled");
}

// World info
var environment = api.getWorldEnvironment(world);
var seed = api.getWorldSeed(world);
logger.info("World: " + world.getName() + ", Seed: " + seed);

Validation & Error Handling

// Validate objects before use
var player = api.getPlayer("PlayerName");
if (api.isValidPlayer(player)) {
    // Safe to use player
    api.sendMessage(player, "Hello!");
} else {
    logger.warning("Player not found or offline");
}

// Validate locations
var location = api.createLocation(world, 0, 64, 0);
if (api.isValidLocation(location)) {
    api.teleport(player, location);
}

// Validate items
var item = api.getItemInMainHand(player);
if (api.isValidItemStack(item)) {
    api.addEnchantment(item, "SHARPNESS", 1);
}

// Safe async tasks with error handling
api.runTaskAsyncSafe(function() {
    // Async work here
    var data = api.loadYamlFile("data");
    // Process data...
}, function(error) {
    // Error handler
    logger.severe("Error in async task: " + error);
});

HTTP Requests

// GET request
api.runTaskAsync(function() {
    var response = api.httpGet("https://api.example.com/data");
    logger.info("Response: " + response);
    
    // Parse JSON response
    var data = JSON.parse(response);
    
    // Update on main thread
    api.runTask(function() {
        api.broadcast("&aData fetched: " + data.message);
    });
});

// POST request
api.runTaskAsync(function() {
    var jsonData = JSON.stringify({
        "player": "PlayerName",
        "action": "join"
    });
    var response = api.httpPost("https://api.example.com/log", jsonData);
    logger.info("POST response: " + response);
});

Utility Methods

// String utilities
var colored = api.colorize("&aHello &bWorld");
var stripped = api.stripColor(colored);
var formatted = api.format("Hello %s! You have %d items.", "Player", 5);

// Math utilities
var rounded = api.round(3.14159, 2); // 3.14
var clamped = api.clamp(150, 0, 100); // 100

// Encoding
var encoded = api.base64Encode("Hello World");
var decoded = api.base64Decode(encoded);
var md5 = api.md5("text");
var sha256 = api.sha256("text");

// Date/Time
var now = api.getCurrentTimeMillis();
var formatted = api.formatDate(now);
var customFormat = api.formatDate(now, "dd.MM.yyyy HH:mm");
var parsed = api.parseDate("2024-01-01 12:00:00");

// Distance
var distance = api.getDistance(loc1, loc2);
var midpoint = api.getMidpoint(loc1, loc2);

Error Handling

// Always wrap risky operations in try-catch
api.registerCommand("risky", "Risky command", "/risky", function(sender, args) {
    try {
        var player = api.getPlayer(args[0]);
        if (!player) {
            api.sendMessage(sender, "&cPlayer not found!");
            return false;
        }
        
        // Risky operation
        player.teleport(someLocation);
        api.sendMessage(sender, "&aSuccess!");
        return true;
    } catch (e) {
        logger.severe("Error in risky command: " + e);
        api.sendMessage(sender, "&cAn error occurred!");
        return false;
    }
});

// Event handlers should also have error handling
api.registerEvent("player.PlayerJoinEvent", function(event) {
    try {
        var player = event.getPlayer();
        // Your code here
    } catch (e) {
        logger.severe("Error in PlayerJoinEvent: " + e);
        // Don't let errors break the event system
    }
});

Performance Optimization

// ❌ BAD: Checking player every tick
api.runTaskTimer(0, 1, function() {
    var players = api.getOnlinePlayers();
    for (var i = 0; i < players.length; i++) {
        // Heavy operation
    }
});

// ✅ GOOD: Cache data and check less frequently
var cachedPlayers = [];
api.runTaskTimer(0, 20, function() { // Every second instead of every tick
    cachedPlayers = api.getOnlinePlayers();
    for (var i = 0; i < cachedPlayers.length; i++) {
        // Heavy operation
    }
});

// ✅ GOOD: Use async for heavy operations
api.runTaskAsync(function() {
    var data = api.httpGet("https://api.example.com/heavy");
    // Process data...
    
    // Update on main thread
    api.runTask(function() {
        api.broadcast("Data loaded!");
    });
});

// ✅ GOOD: Cancel tasks when not needed
var task = api.runTaskTimer(0, 20, function() {
    // Do something
});

// Later, when done:
api.cancelTask(task);

Code Organization

// ✅ GOOD: Organized plugin structure
var pluginInfo = {
    name: "My Plugin",
    version: "1.0.0"
};

// Configuration
var config = {
    enabled: true,
    cooldown: 5000
};

// Data storage
var playerData = {};

// Helper functions
function formatMessage(player, message) {
    return "&7[" + player.getName() + "] &f" + message;
}

function hasPermission(player, perm) {
    return api.hasPermission(player, "myplugin." + perm);
}

// Main functions
function onEnable() {
    logger.info("Loading " + pluginInfo.name + " v" + pluginInfo.version);
    
    // Initialize
    initializeDatabase();
    registerCommands();
    registerEvents();
    
    logger.info(pluginInfo.name + " enabled!");
}

function onDisable() {
    // Cleanup
    saveData();
    logger.info(pluginInfo.name + " disabled!");
}

// Exports
this.onEnable = onEnable;
this.onDisable = onDisable;
this.pluginInfo = pluginInfo;

Player Safety Checks

// Always check if player is online before using
api.registerEvent("player.PlayerQuitEvent", function(event) {
    var player = event.getPlayer();
    var playerName = player.getName();
    
    // Save data before player leaves
    savePlayerData(playerName);
});

// Check if player exists before operations
function giveReward(playerName) {
    var player = api.getPlayer(playerName);
    if (!player) {
        logger.warning("Player " + playerName + " is not online!");
        return false;
    }
    
    // Safe to use player object
    api.giveItem(player, reward);
    return true;
}

// Use instanceof to check player type
api.registerCommand("playeronly", "Player only command", "/playeronly", function(sender, args) {
    if (!(sender instanceof Player)) {
        api.sendMessage(sender, "&cThis command can only be used by players!");
        return false;
    }
    
    var player = sender;
    // Safe to use player methods
    player.teleport(location);
    return true;
});

Common Issues & Solutions

Plugin not loading

• Check file extension: Must be .js
• Check syntax: Use a JavaScript validator
• Check console: Look for error messages
• Check onEnable: Function must be defined and exported
• Check file location: Must be in plugins/MC-JS/js-plugins/

Events not firing

• Check event name: Use format player.PlayerJoinEvent
• Check registration: Must be in onEnable
• Check handler: Function must accept event parameter
• Check console: Look for registration errors
• Try reload: Use /jsreload <plugin>

Commands not working

• Check registration: Must be in onEnable
• Check return value: Must return true or false
• Check permissions: Use api.hasPermission()
• Check console: Look for JavaScript errors
• Try reload: Use /jsreload <plugin>

Player is null errors

• Always check: if (player) { ... }
• Use instanceof: if (sender instanceof Player)
• Check online status: api.getPlayer(name) returns null if offline
• Handle offline players: Use server.getOfflinePlayer() for UUID

Database errors

• Check table exists: Use api.createTable() first
• Check data types: Match column types
• Check NOT NULL: Provide values for required fields
• Check SQL syntax: Use proper SQL in queries
• Check file permissions: Database files need write access

Performance issues

• Avoid heavy operations: Use async tasks
• Cache data: Don't query database every tick
• Cancel tasks: Clean up repeating tasks
• Limit operations: Don't process all players every tick
• Use cooldowns: Prevent spam

Debug Mode

Enable debug mode in config.yml to see detailed logging:

settings:
  debug-mode: true

This will show:

• Event registration details
• Event execution logs
• Plugin loading information
• Command execution details

Common Error Messages

"ReferenceError: X is not defined"

Solution: Check if the variable/class is available. Use instanceof Player instead of checking for undefined properties.

"Cannot read property 'X' of null"

Solution: Always check if objects exist before accessing properties:

var player = api.getPlayer(name);
if (player) {
    player.teleport(location);
}

"SQLiteException: NOT NULL constraint failed"

Solution: Ensure all required fields are provided when inserting data:

api.insertData("db", "table", {
    "required_field": value, // Must not be null
    "optional_field": value || null
});

"Events being called multiple times"

Solution: This is fixed in MC-JS - events are only dispatched once per event instance, even if multiple plugins register the same event.

General Questions

Q: Can I use ES6+ features?

A: Yes! MC-JS uses Rhino with ES6 support. You can use arrow functions, let/const, template literals, etc.

Q: How do I reload my plugin?

A: Use /jsreload <plugin-name> or /jsreload to reload all plugins.

Q: Can I use npm packages?

A: No, MC-JS uses Rhino which doesn't support Node.js modules. Use the built-in API instead.

Q: How do I check if a player is online?

A: Use api.getPlayer(name) - it returns null if the player is offline.

Q: Can I access Bukkit API directly?

A: Yes! The server object gives you access to the Bukkit Server instance. Also, Bukkit classes like Player, Material, etc. are available.

Q: How do I handle offline players?

A: Use server.getOfflinePlayer(name) to get UUID and other data for offline players.

Q: Can multiple plugins register the same event?

A: Yes! Each plugin's handler will be called. MC-JS ensures events are only dispatched once per event instance.

Q: How do I create a config file?

A: Use api.getPluginConfig(pluginName) and api.savePluginConfig(pluginName, data).

Q: Can I use async/await?

A: No, but you can use api.runTaskAsync() for asynchronous operations.

Q: How do I prevent command spam?

A: Use the cooldown system: api.setCooldown(playerName, "command", 5000)

Player Utilities

// Check if player is online
function isPlayerOnline(name) {
    return api.getPlayer(name) !== null;
}

// Get player safely
function getPlayerSafe(name) {
    var player = api.getPlayer(name);
    if (!player) {
        logger.warning("Player " + name + " is not online!");
        return null;
    }
    return player;
}

// Get UUID for online or offline player
function getPlayerUUID(name) {
    var player = api.getPlayer(name);
    if (player) {
        return player.getUniqueId().toString();
    }
    try {
        var offline = server.getOfflinePlayer(name);
        return offline.getUniqueId().toString();
    } catch (e) {
        return null;
    }
}

Command Patterns

// Command with permission check
api.registerCommand("admin", "Admin command", "/admin", function(sender, args) {
    if (!api.hasPermission(sender, "myplugin.admin")) {
        api.sendMessage(sender, "&cNo permission!");
        return false;
    }
    
    if (!(sender instanceof Player)) {
        api.sendMessage(sender, "&cPlayers only!");
        return false;
    }
    
    // Command logic
    return true;
});

// Command with cooldown
api.registerCommand("cooldown", "Cooldown command", "/cooldown", function(sender, args) {
    if (!(sender instanceof Player)) return false;
    
    var player = sender;
    var playerName = player.getName();
    
    if (api.hasCooldown(playerName, "cooldown")) {
        var remaining = api.getCooldownRemaining(playerName, "cooldown");
        api.sendMessage(player, "&cCooldown: " + Math.ceil(remaining / 1000) + "s");
        return false;
    }
    
    api.setCooldown(playerName, "cooldown", 5000);
    api.sendMessage(player, "&aCommand executed!");
    return true;
});

Data Storage Patterns

// Save player data
var playerData = {};

function savePlayerData(playerName) {
    try {
        api.saveYamlFile("players/" + playerName, playerData[playerName] || {});
    } catch (e) {
        logger.severe("Error saving data for " + playerName + ": " + e);
    }
}

function loadPlayerData(playerName) {
    try {
        var data = api.loadYamlFile("players/" + playerName);
        if (data) {
            // Convert Java Map to JavaScript object
            var playerObj = {};
            if (data instanceof java.util.Map) {
                var keys = data.keySet().toArray();
                for (var i = 0; i < keys.length; i++) {
                    var key = keys[i];
                    var value = data.get(key);
                    // Handle nested Maps
                    if (value instanceof java.util.Map) {
                        var nestedObj = {};
                        var nestedKeys = value.keySet().toArray();
                        for (var j = 0; j < nestedKeys.length; j++) {
                            nestedObj[nestedKeys[j]] = value.get(nestedKeys[j]);
                        }
                        playerObj[key] = nestedObj;
                    } else {
                        playerObj[key] = value;
                    }
                }
            }
            playerData[playerName] = playerObj;
        }
    } catch (e) {
        logger.warning("No data found for " + playerName);
        playerData[playerName] = {};
    }
}

// Save on quit
api.registerEvent("player.PlayerQuitEvent", function(event) {
    var player = event.getPlayer();
    savePlayerData(player.getName());
    delete playerData[player.getName()];
});

GUI Patterns

// Simple GUI with GUI Builder
function openMenu(player) {
    var gui = api.createGUI("&6Menu", 3);
    
    // Background
    var bg = api.createItemStack(api.getMaterial("GRAY_STAINED_GLASS_PANE"), 1);
    bg = api.setItemDisplayName(bg, " ");
    gui.fillBorders(bg);
    
    // Items
    var item1 = api.createItemStack(api.getMaterial("DIAMOND"), 1);
    item1 = api.setItemDisplayName(item1, "&bOption 1");
    gui.setItem(10, item1, function(event) {
        event.setCancelled(true);
        api.sendMessage(player, "&aYou clicked Option 1!");
    });
    
    gui.buildAndOpen(player);
}

// GUI with data storage
var guiData = {};

function openShop(player) {
    var gui = api.createGUI("&6Shop", 3);
    var playerName = player.getName();
    
    guiData[playerName] = {
        page: 1,
        category: "weapons"
    };
    
    // Store data in holder
    var inv = gui.build();
    var holder = api.getInventoryHolder(inv);
    if (holder) {
        holder.setData("player", playerName);
        holder.setData("page", 1);
    }
    
    player.openInventory(inv);
}