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();

        api.sendMessage(player, "&6Welcome to the server, &b" + player.getName() + "&6!");

        api.sendTitle(player, "&aWelcome!", "&eEnjoy your stay!", 10, 70, 20);

        api.playSound(player, "ENTITY_PLAYER_LEVELUP", 1.0, 1.0);

        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() {

    api.createTable("stats", "player_stats", {
        "player_name": "TEXT PRIMARY KEY",
        "kills": "INTEGER DEFAULT 0",
        "deaths": "INTEGER DEFAULT 0",
        "playtime": "INTEGER DEFAULT 0"
    });

    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();
        }
    );

    api.registerEvent("entity.PlayerDeathEvent", function(event) {
        var killer = event.getEntity().getKiller();
        var victim = event.getEntity();

        if (killer) {

            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
                });
            }
        }

        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");

        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);

        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);

        var close = api.createItemStack(api.getMaterial("BARRIER"), 1);
        close = api.setItemDisplayName(close, "&cClose Menu");
        api.setInventoryItem(inv, 22, close);

        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;

        var gui = api.createGUI("&6&lShop Menu", 3);

        var bg = api.createItemStack(api.getMaterial("GRAY_STAINED_GLASS_PANE"), 1);
        bg = api.setItemDisplayName(bg, " ");
        gui.fillBorders(bg);
        gui.setBackground(bg);

        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);
        });

        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);
        });

        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);
        });

        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();
        });

        gui.onClick(function(event) {

        });

        gui.onClose(function(event) {
            api.sendMessage(player, "&7Shop closed. Come back soon!");
        });

        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 name = pluginInfo.name;
        var scope = "heal";

        if (!api.systems.claimCooldown(name, scope, player.getName(), 30)) {
            var remaining = api.systems.cooldownRemaining(name, scope, player.getName());
            api.sendMessage(player, "&cCooldown: " + Math.ceil(remaining) + " seconds");
            return false;
        }

        api.setHealth(player, api.getMaxHealth(player));
        api.setFoodLevel(player, 20);
        api.sendMessage(player, "&aYou have been healed!");

        return true;
    });
}

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

Example 5: Vault Economy

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

function onEnable() {
    api.registerCommand("balance", "Check your balance", "/balance", function(sender, args) {
        var player = sender;
        if (!(player instanceof Player)) {
            api.sendMessage(sender, "&cOnly players can use this!");
            return false;
        }

        if (!api.vault.isAvailable()) {
            api.sendMessage(player, "&cNo economy plugin found!");
            return false;
        }

        var balance = api.vault.balance(player);
        api.sendMessage(player, "&6Your balance: &e" + api.vault.format(balance));
        return true;
    });

    api.registerCommand("pay", "Pay another player", "/pay  ", function(sender, args) {
        var player = sender;
        if (!(player instanceof Player)) {
            api.sendMessage(sender, "&cOnly players can use this!");
            return false;
        }
        if (args.length < 2) {
            api.sendMessage(player, "&cUsage: /pay <player> <amount>");
            return false;
        }

        var target = api.getPlayer(args[0]);
        var amount = Number(args[1]);
        var result = api.vault.transfer(player, target, amount);

        if (result.isSuccess()) {
            api.sendMessage(player, "&aYou paid &e" + api.vault.format(amount) + " &ato " + target.getName());
            api.sendMessage(target, "&aYou received &e" + api.vault.format(amount) + " &afrom " + player.getName());
        } else {
            api.sendMessage(player, "&cPayment failed: " + result.getError());
        }
        return true;
    });
}

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

Example 6: World Protection System

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

var protectedRegions = [];

function onEnable() {

    var spawn = api.getWorlds()[0].getSpawnLocation();
    protectedRegions.push({
        center: spawn,
        radius: 50
    });

    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!");
            }
        }
    });

    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:

Systems & Cooldowns

var name = pluginInfo.name;

// Persistent per-player cooldowns
var scope = "vote";
if (api.systems.claimCooldown(name, scope, player.getName(), 300)) {
    api.sendMessage(player, "&aYou can vote again!");
} else {
    var remaining = api.systems.cooldownRemaining(name, scope, player.getName());
    api.sendMessage(player, "&cVote again in " + Math.ceil(remaining / 60) + " minutes");
}

// Storable data + counters
api.systems.writeData(name, "stats", "deaths-" + player.getName(),
    JSON.stringify({"deaths": 3}));
api.systems.changeNumber(name, "stats", "deaths-" + player.getName(), 1);

Permissions & Player Management

if (api.hasPermission(player, "myplugin.use")) {

}

api.addPermission(player, "myplugin.vip");
api.removePermission(player, "myplugin.vip");

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

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

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

Particles & Sounds

api.spawnParticle(location, "FIREWORK", 10, 0.5, 0.5, 0.5, 0.1);
api.spawnParticle(location, Particle.FLAME, 5, 0, 0, 0);

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

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

Entity Manipulation

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

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

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

api.setEntitySilent(zombie, true);
api.setEntityCollidable(zombie, false);

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

api.teleportEntity(zombie, player);

var entityLoc = api.getEntityLocation(zombie);

api.removeEntity(zombie);

World Management

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

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

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

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

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

Validation & Error Handling

var player = api.getPlayer("PlayerName");
if (api.isValidPlayer(player)) {

    api.sendMessage(player, "Hello!");
} else {
    logger.warning("Player not found or offline");
}

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

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

api.runTaskAsyncSafe(function() {

    var data = api.loadYamlFile("data");

}, function(error) {

    logger.severe("Error in async task: " + error);
});

HTTP Requests

api.runTaskAsync(function() {
    var response = api.httpGet("https://api.example.com/data");
    logger.info("Response: " + response);

    var data = JSON.parse(response);

    api.runTask(function() {
        api.broadcast("&aData fetched: " + data.message);
    });
});

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

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

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

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

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");

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

Error Handling

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;
        }

        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;
    }
});

api.registerEvent("player.PlayerJoinEvent", function(event) {
    try {
        var player = event.getPlayer();

    } catch (e) {
        logger.severe("Error in PlayerJoinEvent: " + e);

    }
});

Performance Optimization

api.runTaskTimer(0, 1, function() {
    var players = api.getOnlinePlayers();
    for (var i = 0; i < players.length; i++) {

    }
});

var cachedPlayers = [];
api.runTaskTimer(0, 20, function() {
    cachedPlayers = api.getOnlinePlayers();
    for (var i = 0; i < cachedPlayers.length; i++) {

    }
});

api.runTaskAsync(function() {
    var data = api.httpGet("https://api.example.com/heavy");

    api.runTask(function() {
        api.broadcast("Data loaded!");
    });
});

var task = api.runTaskTimer(0, 20, function() {

});

api.cancelTask(task);

Code Organization

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

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

var playerData = {};

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

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

function onEnable() {
    logger.info("Loading " + pluginInfo.name + " v" + pluginInfo.version);

    initializeDatabase();
    registerCommands();
    registerEvents();

    logger.info(pluginInfo.name + " enabled!");
}

function onDisable() {

    saveData();
    logger.info(pluginInfo.name + " disabled!");
}

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

Player Safety Checks

api.registerEvent("player.PlayerQuitEvent", function(event) {
    var player = event.getPlayer();
    var playerName = player.getName();

    savePlayerData(playerName);
});

function giveReward(playerName) {
    var player = api.getPlayer(playerName);
    if (!player) {
        logger.warning("Player " + playerName + " is not online!");
        return false;
    }

    api.giveItem(player, reward);
    return true;
}

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;

    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,
    "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.systems.claimCooldown(pluginInfo.name, "command", playerName, 5)

Player Utilities

function isPlayerOnline(name) {
    return api.getPlayer(name) !== null;
}

function getPlayerSafe(name) {
    var player = api.getPlayer(name);
    if (!player) {
        logger.warning("Player " + name + " is not online!");
        return null;
    }
    return 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

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;
    }

    return true;
});

api.registerCommand("cooldown", "Cooldown command", "/cooldown", function(sender, args) {
    if (!(sender instanceof Player)) return false;

    var player = sender;
    var playerName = player.getName();
    var scope = "cooldown";

    if (!api.systems.claimCooldown(pluginInfo.name, scope, playerName, 5)) {
        var remaining = api.systems.cooldownRemaining(pluginInfo.name, scope, playerName);
        api.sendMessage(player, "&cCooldown: " + Math.ceil(remaining) + "s");
        return false;
    }

    api.sendMessage(player, "&aCommand executed!");
    return true;
});

Data Storage Patterns

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) {

            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);

                    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] = {};
    }
}

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

GUI Patterns

function openMenu(player) {
    var gui = api.createGUI("&6Menu", 3);

    var bg = api.createItemStack(api.getMaterial("GRAY_STAINED_GLASS_PANE"), 1);
    bg = api.setItemDisplayName(bg, " ");
    gui.fillBorders(bg);

    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);
}

var guiData = {};

function openShop(player) {
    var gui = api.createGUI("&6Shop", 3);
    var playerName = player.getName();

    guiData[playerName] = {
        page: 1,
        category: "weapons"
    };

    var inv = gui.build();
    var holder = api.getInventoryHolder(inv);
    if (holder) {
        holder.setData("player", playerName);
        holder.setData("page", 1);
    }

    player.openInventory(inv);
}