Authored by Devon Thome 🖥

MelonCore ReadMe 1/21/19


MelonCore contains several components for making launching servers as easy as possible. Simply add MelonCore as a dependency to your project to get started.


  • Economy Management
  • Ban and Mute Management
  • Chat Management
  • Time Formatting Tools
  • Combat Management
  • Basic Commands Built-In
  • Extensible Command API
  • Database Management
  • Entity and Item Tools
  • Warp Management
  • Spawn Management


    automatic-restart: false
    restart-after-minutes: 360
    start-countdown-minutes: 15
    prevent-login-minutes: 3
    default-reason: 'Automatic Maintenance Restart'

Housekeeping contains general tasks to ensure your server is running as well as it should.


  • automatic-restart Whether or not your server should restart automatically a period of time after starting up
  • restart-after-mintes The amount of minutes to wait after starting until a restart should happen
  • start-countdown-minutes The amount of notice to give players prior to the automatic restart
  • prevent-login-mintes The amount of time prior to a restart to begin rejecting logins. (This is not specific to just automatic restarts, but ALL queued restarts.)
  • default-reason If a restart reason is not specified, this text will be used.
  date-format: MM/dd/yy
  time-format: hh:mm:ss a

Controls the formatting for AbsoluteTimeFormatting.

  • date-format The date format to use
    • Default: MM/dd/yy for 12/14/96
  • time-format The time format to use
    • Default: hh:mm:ss a for 12:34:19 PM
  global-world-respawn: NONE
  home-beds-enabled: true

Controls respawn points for when players die.

  • global-world-respawn The worldname to use for players to always respawn to. If set to NONE, then they'll always respawn at the spawn point of their current world
  • home-beds-enabled whether or not to respect home beds when considering where to respawn a player
 enable-combat-tag: true
 tag-seconds: 20
   flying: true
   block-editing: true
   pearls: true
 - chat
   enabled: true
   check-radius: 10
   material: BARRIER

Controls combat tag management of MelonCore.

  • enable-combat-tag Whether or not to allow MelonCore to handle combat tags
  • tag-seconds the duration in which a user should be tagged when in combat


Controls what should be prevented when in combat

  • flying Will cancel any flight that users have when they enter combat
  • block-editing Will prevent building or breaking blocks while in combat
  • pearls Will prevent throwing or teleporting via pearls while in combat

Allowed Commands

A list of allowed commands while in combat. If a command is not on this list, it will not work. NOTE: When given a MelonCore-registered command, all associated aliases will automatically also be allowed.


Prevents users from entering PVP-free areas (as decided by WorldGuard) while in combat.

  • enabled Whether or not to enable forcefield functionality
  • check-radius The radius around the player to check for PVP-safe area. Higher numbers let the player see the barrier earlier, but will increase required server resrouces.
  • material The material for the client-side block to use.
  gradual-world-time-change: true

Controls various cosmetics in MelonCore.

  • gradual-world-time-change whether or not to instantly change the time when using the /time command or to move the sky gradually
    • NOTE: WHen enabled, you can append the -i flag to your /time command to force the time to change instantly. (ie /time day -i)
  use-reserved-slots: true
  reserved-slots: 25
  kick-message: 'Upgrade your rank at to use reserved slots!'

MelonCore can enable a reserved slots feature when your server becomes full. When in reserved slots mode, only users with the permission core.join.reservedslots will be able to join

  • use-reserved-slots Whether or not to enable the reserved slots feature.
  • reserved-slots The amount of reserved slots (from the max count) to use.
    • EXAMPLE: If set to 25, and your server has 100 slots, then 75 of the slots will be usable by any but the final 25 will only be usable by those with the permission.
  • kick-message The message to kick a player with if they don't have permission to use the reserved slots.
  starting-balance: 0
  currency-singular: 'Gold'
  currency-plural: 'Gold'

Manages the eco settings for MelonCore

  • starting-balance The default balance that all users start with
  • currency-singular The singular word for your currency (like, "Dollar")
  • currency-plural The plural word for your currency (like, "Dollars")
  broadcast-afk-changes: true
  broadcast-format: '&c&l[Broadcast] &c'
  pm-format-to: '&3&lTo %name: &b'
  pm-format-from: '&3&lFrom %name: &b'
  pm-format-spy: '&7[Spy] %from > %to: '
  chat-format: '&7%name&8: &f'
  emote-format: '&7&o ** %name '

Handles formatting for various messages

  • broadcast-afk-changes Whether or not to announce to the server when someone toggles /afk
  • broadcast-format The default format to use for the /broadcast command. Formatting can be hidden by appending -n to your broadcast message.
  • pm-format-to How outgoing PMs are shown to a user. Use %name to reference the name of the user being messaged.
  • pm-format-from How incoming PMs are shown to a user. Use %name to reference the name of the user sending the message.
  • pm-format-spy How messages sent over the spy channel should be formatted. Use %from and %to to refernece the respective senders
  • chat-format How chat messages should be formatted
  • emote-format How to format /me messages
  host: localhost
  port: 3306
  username: root
  password: ''
  db: meloncore


The default commands contained in MelonCore

Command Scope Description Permission Aliases Arguments Flags
afk Players Toggles AFK status mc.command.afk away, unafk, unaway N/A N/A
back Players Return to your last teleport position mc.command.back return, ret [player] N/A
balance Console/Players View balance info mc.command.balance bal, currency-singular, currency-plural [player] N/A
baltop Players Show the top 100 balanaces on the server mc.command.baltop ecotop, moneytop [page] N/A
ban Console/Players Ban a player from the server mc.command.ban N/A <player> <reason> N/A
banhistory Players View the ban history for a player mc.command.banhistory N/A <player> N/A
biome Players View your current biome mc.command.biome N/A N/A N/A
break Players Break the block you're looking at mc.command.break N/A N/A N/A
broadcast Console/Players Broadcast a message mc.command.broadcast say, bc <message> -n to remove pre-configured formatting
butcher Players Kill mobs in a radius mc.command.butcher killall <radius> -a to include animals, -v to include villagers
chat Players Change chat channels c, ch [channel] N/A
clear Players Clear your inventory mc.command.clear ci, clearinventory [target] N/A
combat Players View combat tag status mc.command.combat combattag, ct N/A N/A
cure Console/Players Remove negative potion effects mc.command.cure N/A [target] N/A
delspawn Players Delete world spawn mc.command.delspawn deletespawn, removespawn, remspawn [permission] N/A
delwarp Console/Players Delete a warp mc.command.delwarp unsetwarp <warp> N/A
docs Players View server docs N/A [name] N/A
docs reload Console/Players Reload docs file N/A N/A N/A
ecoadmin grant Console/Players Grant money to a player mc.command.ecoadmin.grant N/A <player> <amount> N/A
ecoadmin take Console/Players Take money from a player mc.command.ecoadmin.take N/A <player> <amount> N/A
ecoadmin reset Console/Players Reset a player's balance mc.command.ecoadmin.reset N/A <player> N/A
editbook Players Make a completed book writable again mc.command.editbook N/A N/A N/A
enderchest Players Access your ender chest mc.command.enderchest echest, ec [target] N/A
feed Players/Console Feed a player mc.command.feed N/A [target] N/A
fly Players Toggle flight N/A [player] N/A
freeze Players Prevent a player from moving mc.command.freeze unfreeze <player> N/A
gamemode Players/Console Change the gamemode of a player mc.command.gamemode gm <gamemode> [player] N/A
getpos Players Get your current location mc.command.getpos whereami, coords, pos [target] N/A
give Players/Console Give another player an item mc.command.give N/A <player> <item> [amount] [data] N/A
god Players Toggle invincibility mc.command.god ungod [target] N/A
hat Players Put the held item on your head mc.command.hat N/A N/A N/A
heal Players/Console Restore a player to full health and hunger mc.command.heal N/A [target] N/A
help Players/Console View the server help menu commands, ? N/A N/A
invsearch Player Search online player inventories and ender chests for the currently held item mc.command.invsearch N/A N/A N/A
isbanned Playes/Console Check if a player is banned mc.command.isbanned N/A <player> N/A
ismuted Players/Console Chedkc if a player is muted mc.command.ismuted N/A <player> N/A
item Players Give yourself an item mc.command.item i <item> [amount] [data] N/A
jump Players Teleport to the target block mc.command.jump j N/A N/A
kick Players/Console Kick a player from the server mc.command.kick N/A <player> <reason> N/A
lag Players/Console Display server lag details mc.command.lag gc, tps, uptime, ram, memory, mem N/A N/A
setmaxplayers Players/Console Change the maximum player slots mc.command.setmaxplayers N/A <slots> N/A
me Players Emote a message emote <message> N/A
more Players Max out your held item mc.command.more N/A [target] -a to max out your entire inventory
motd Players View the server welcome message mc.command.motd N/A N/A N/A
motd reload Players Reload the server welcome message file mc.command.motd.reload N/A N/A N/A
msg Players Send a private message mc.command.msg message, whisper, w, tell, t, m <player> <message> N/A
mute Players/Console Mute a player from public channels mc.command.mute N/A <player> <reason> N/A
mutehistory Players View the mute history of a player mc.command.mutehistory N/A <player> N/A
openinv Players Open another player's inventory mc.command.openinv inv, invsee <player> N/A
pay Players Pay another player money N/A <player> <amount> N/A
ping Players/Console Test server response N/A N/A N/A
playertime Players Set your personal world time mc.command.playertime ptime <time> [target] N/A
pluginmanager Players/Console View help for server plugin manager mc.command.pluginmanager pm ... N/A
pluginmanager enable Players/Console Enable a disabled plugin mc.command.pluginmanager.enable pm <plugin> N/A
pluginmanager disable Players/Console Disable an enabled plugin mc.command.pluginmanager.disable pm <plugin> N/A
pluginmanager load Players/Console Load a new plugin mc.command.pluginmanager.load pm <file> N/A
pluginmanager unload Players/Console Disable and unload a plugin mc.command.pluginmanager.unload pm <plugin> N/A
pluginmanager reload Players/Console Reload a plugin mc.command.pluginmanager.relaod pm <plugin> N/A
pluginmanager reloadall Players/Console Reload all plugins (except MelonCore) mc.command.pluginmanager.reloadall pm N/A N/A
togglepms Players Toggle receiving private messages mc.command.pmtoggle togglemsg, msgtoggle, pmtoggle N/A N/A
reboot now Players/Console Queue a server reboot for 5s from now N/A N/A N/A
reboot schedule Players/Console Schedule a server reboot mc.command.reboot.schedule N/A <time> [reason] N/A
reboot postpone Players/Console Postpone a queued reboot mc.command.reboot.postpone N/A <time> N/A
reboot cancel Players/Console Cancel a queued reboot mc.command.reboot.cancel N/A N/A N/A
reboot info Players/Console View details of a pending reboot N/A N/A N/A
reply Players Reply to last received PM mc.command.msg r <message> N/A
resettime Players Resync your personal time with the server mc.command.playertime rt [target] N/A
rocket Players Launch a player into the sky mc.command.rocket launch [target] -h to launch higher, -v to launch very high
setspawn Plaers Set spawn of current world mc.command.setspawn N/A [permission] N/A
setwarp Players Set a new warp mc.command.setwarp N/A <name> N/A
skull Players Give yourself a player head mc.command.skull head, playerhead <name> N/A
slap Players Slap a player mc.command.slap N/A [target] -h to slap a player head, -v for very hard, -d to deal damage
slay Players Kill a player mc.command.slay suicide [target] N/A
spawn Players Teleport to world spawn mc.command.spawn N/A [world] N/A
spawnmob Players Spawn a mob mc.command.spawnmob N/A <mob> [amount] [target] -e to spawn on target, not where they're looking
spy Players Toggle spying on PMs mc.command.spy socialspy, pmspy N/A N/A
strike Players Strike a player with lightning mc.command.strike lughtning, smite [target] [count] -d to deal damage, -k to kill the player
sudo Players/Console Force a player to chat or use a command mc.command.sudo N/A <player> <message> N/A
tempban Players/Console Temporarily ban a player mc.command.tempban tb <player> <time> <reason> N/A
tempmute Players/Console Temporarily mute a player mc.command.tempmute tm <player> <time> <reason> N/A
thor Players Greant the power of Thor's hammer mc.command.thor unthor [target] N/A
thunder Players/Console Change world thunder status mc.command.thunder N/a <boolean> [duration] [world] N/A
time Players/Console Change world time mc.command.time N/A <time> [world] -i to instantly change the time
toggleglobal Players Toggle seeing global chat mc.command.toggleglobal globaltoggle N/A N/A
togglelocal Players Toggle seeing local chat mc.command.togglelocal localtoggle N/A N/A
togglemarket Players Toggle seeing market chat mc.command.togglemarket markettoggle N/A N/A
tool Players Bind a command to an item mc.command.tool powertool <command> N/A
tpa Players Ask to teleport to a player mc.command.tpa call <player> N/A
tpall Players Teleport all player sot you mc.command.tpall N/A N/A -s to not messgae players, -l to make all players look where you are
tp Players Teleport to a player N/A <player> [other] -s to not message players
tpcoords Players Teleport to specific coordinates mc.command.tpcoords tppos <x> <y> <z> [world] [player] -s to not message players
tphere Players Teleport a player to you mc.command.tphere tph, tptome <player> -s to not message players, -l to make them look where you are
toggletp Players Toggle receiving teleport requests mc.command.toggletp toggletpa, tptoggle, tpatoggle N/A N/A
tree Players Grow a tree where you're looking mc.command.tree N/A <tree> N/A
unban Players/Console Unban a player mc.command.unban N/A <player> N/A
unmute Players/Console Unmute a player mc.command.unmute N/A <player> N/A
unstuck Players Unstuck youeself mc.command.unstuck N/A N/A N/A
vanish Players Become invisible to non-staff mc.command.vanish v, uv [target] N/A
warp Players Warp to a provided point mc.command.warp N/A <warp> N/A
warplist Players View a list of warps mc.command.warplist warps N/A N/A
warpprice Players Set a price to use a warp mc.command.warpprice wprice <warp> <price> N/A
warpwelcome Players Set a welcome message for a warp mc.command.warpwelcome wwelcome <warp> <message> N/A
weather PLayers/Console Set the weather N/A <weather> [duration] [world] N/A
who Players/Console View online players mc.command.who players, playerlist, list, online, pl, players N/A N/A
whois Players/Console View info about a player mc.command.whois N/A <player> N/A
workbench Players Open a workbench mc.command.workbench wb, craft N/A N/A

Controls settings for your database

Custom Events

MelonCore contains 4 additional events that can be listened for.


Fired when a user moves asyncronously. Not recommended when the bounds of a player needs to be restricted, but is made for notification or logging purposes.


Fired when a user is combat tagged. Can be cancelled.


Fired when a user receives currency.


Fired when a user spends money.


MelonCore uses a channel based messaging-system. It comes with a handful of channels out of the box and more can be added by other plugisn via the ChannelManager.


  • Global can be seen by everyone on the server. /c g
  • Local can be seen by players within 30 blocks of you. /c l
  • Market is like global, but it's designed for trading purposes. /c m
  • Staff is designed as a private channel for server moderators. /c s

Adding Channels

Simply create a new class that extends ChatChannel. Override the canSeeChannel() and sendMessage() methods to control who can see and type into this channel.

When your channel is ready for use, just call ChannelManager.register(channel).

Messaging Formatting

Our chat package also contains tools for formatting text. For example, sending a centered message could be done by calling ChatFormatting.centerMessage(string).

Time Formatting

These two classes allow you to format unix time for a human-readable format easily.

Absolute Time Format

  • Call AbsoluteTimeFormatting.format(time, type) to get a human-readable date or time. Type in this case would be Type.DATE or Type.TIME.
  • Call AbsoluteTimeFormatting.parse(string, type) to parse your time back to unix time.

Relative Time Format

This class is used much more frequently. Use this to format countdown timers.

  • Call RelativeTimeFormatting.parseDateDiff(string, future) to parse a string to unix time, where future is whether or not to go forewards in time or go back.
    • Throws an Exception when the provided string is not a valid relative time.
  • Call RelativeTimeFormatting.formatDateDiff(time, shrink) to transform a unix timestamp into a countdown, where shrink is whether or not to return time in a short format.
    • Not Shrunk: 5 days, 4 hours, 33 minutes, 5 seconds
    • Shrunk: 5d4h33m5s


MelonCore can act as a combat tag manager as well, if configured to do so.

Putting a Player in Combat

Combat tags are initialized automatically when plauyers are fighting. You can register a combat tag manually as well, though.

// Start by getting the CoreUsers for the victim and the attacker

CoreUser coreAttacker = MelonCore.getCoreUserManager().getUser(attacker.getUniqueId());
CoreUser coreVictim = MelonCore.getCoreUserManager().getUser(victim.getUniqueId());

// Next, we create the combat tag
CombatTag tag = new CombatTag(coreAttacker.getCoreIdentifier(), coreVictim.getCoreIdentifier(), System.currentTimeMillis(),
                        System.currentTimeMillis() + (combatManager.getTagSeconds() * 1000));
// Finally, we register it

That's it!

Getting a Combat Tag

Combat tags can be retrieved by CoreUser or Player

CombatTag tag = MelonCore.getCombatManager().getTag(player);
if (tag != null){
  // user is in combat


MelonCore offers an extensible command API to make creating commands a dream.

A command in MelonCore looks something like this:

public class BalanceCommand extends ServerCommand {

    public BalanceCommand() {
        super("balance", AllowedUserScope.ANY, "View balance info", PERM_PREFIX + "balance", new ArrayList<>());
        registerArgument(new PlayerArgument("player", false, false));

    protected void runCommand(CommandSender sender, ImmutableMap<String, Object> arguments, ImmutableMap<Character, CommandFlag> flags) {

        Player target = null;
        if (arguments.containsKey("target")) {
            target = (Player) arguments.get("target");
        } else if ((sender instanceof Player)) {
            target = (Player) sender;

        if (target == null) {
            sender.sendMessage("§cYou must specify a player.");

        CoreUser user = MelonCore.getCoreUserManager().getUser(target.getUniqueId());

        double balance = user.getBalance();
        sender.sendMessage("§e" + (sender.getName().equals(target.getName()) ? "You have " : target.getName() + " has ") + "§f" + MelonCore.getEcoManager().format(balance) + "§e.");



We include a bundle of argument types to work with, but you can always make your own:

  • BooleanArgument
  • ChannelArgument
  • CommandArgument
  • DoubleArgument
  • EntityTypeArgument
  • GameModeArgument
  • IntegerArgument
  • MaterialArgument
  • PlayerArgument
  • RelativeTimeArgument
  • StringArgument
  • TimeArgument
  • WarpArgument
  • WorldArgument
  • WorldTimeArgument

A CommandArgument in MelonCore handles all the validation before it ever hits your command. We'll also handle formatting your command usage and help menu accordingly. You can build new CommandArguments just by extending from our CommandArgument class.

Here's the WarpArgument class:

public class WarpArgument extends CommandArgument {

    public WarpArgument(String label, boolean required) {
        super(label, required);

    public List<String> getTabCompletionResults(CommandSender sender, String lastWord) {

        List<String> results = new ArrayList<>();
        for (Warp warp : MelonCore.getWarpManager().getWarps()) {
            if (warp.getName().toLowerCase().startsWith(lastWord.toLowerCase())) {

        return results;


    protected Warp parse(String input) {

        Warp warp = MelonCore.getWarpManager().getWarp(input);
        if (warp == null) {
            throw new IllegalArgumentException("Warp doesn't exist: §f" + input);

        return warp;

For any errors in data, just throw an IllegalArgumentException.

Registering Commands

When you finsih your new command, just register it with CommandManager.register(). There is no need to report it to the plugin.yml.

Command Controllers

Access to commands can be restricted using Command Controllers. Instead of listng for string in PlayerCommandPreprocessEvent, just get your instance of a ServerCommand...

ServerCommand cmd = CommandManager.getCommand("ping");

then call...


Return FALSE in the command controller to deny execution of the command. It's that simple!

15 Bytes
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment