MMOItems - API

Jul 16, 2018
MMOItems - API

  • ItemManager
    #getItem(Type, String) returns the corresponding custom item (ItemStack) depending on the item type and ID.
    Code (Text):
    player.getInventory().addItem(ItemManager.getItem(Type.SWORD, "STEEL_SWORD"));
    player.sendMessage(ChatColor.YELLOW + "You received a " + ChatColor.GOLD + "Steel Sword" + ChatColor.YELLOW + "!");

    #castAbility(Player, Ability, ItemStack, HashMap<String, Double>) makes a player cast an ability. The ItemStack represents the item the player is clicking when casting the ability. The map corresponds to the ability modifiers.
    Code (Text):
    HashMap<String, Double> mods = new HashMap<String, Double>();
    mods.put("damage", 8);
    mods.put("mana", 30);

    PlayerAbilities.castAbility(player, Ability.FIREBOLT, player.getInventory().getItemInMainHand(), mods);
    player.sendMessage(ChatColor.YELLOW + "You successfully cast " + ChatColor.GOLD + "Firebolt" + ChatColor.YELLOW + "!");

    Accessing the item database
    To access the configuration files where the items are saved, use the method from the MIUtils class:
    This method will return the config file of the corresponding item type.
    To save the config file, use MIUtils#saveConfig(FileConfiguration, Type).
    You can also manually load the file configurations using the default YamlConfiguration util, but you'll need the MMOItems plugin class, which you can access with MIUtils#getPlugin().

    Example: Editing the attack damage from a staff called "OAK_BRANCH"
    Code (Text):
    // accessing the database
    FileConfiguration staffDataFile = MIUtils.getConfigFromType(Type.STAFF);

    // setting the attack-damage to 13.8
    staffDataFile.set("OAK_BRANCH.attack-damage", 13.8);

    // saving the config file
    MIUtils.saveConfig(staffDataFile, Type.STAFF);


    #openInv(Player) opens the advanced workbench to a player.
    Code (Text):

    Creating & registering new abilities
    Since 3.2.8, you now only need one class to create a fully functionnal item ability. You will then have to register your ability by adding a method in the onLoad() of your plugin.

    For this tutorial, we'll be recreating the Poison on-hit ability.
    Code (Text):
    public class Poison extends Ability {
        public Poison() {
            super("POISON", "Poison", Ability.Type.ON_HIT);

            addModifier("duration", 4);
            addModifier("cooldown", 10);
            addModifier("amplifier", 1);
            addModifier("mana", 0);
            addModifier("stamina", 0);

        public boolean onHit(Player p, LivingEntity t, HashMap<String, Double> mods, double damage, EntityDamageByEntityEvent e) {
            double duration = getValue(mods, "duration");
            double amplifier = getValue(mods, "amplifier");

            Eff.SLIME.display(1, 1, 1, 0, 32, t.getLocation().add(0, 1, 0), 200);
            Eff.VILLAGER_HAPPY.display(1, 1, 1, 0, 24, t.getLocation().add(0, 1, 0), 200);
            VersionUtils.sound(p.getLocation(), "BLOCK_BREWING_STAND_BREW", 2, 2);
            t.addPotionEffect(new PotionEffect(PotionEffectType.POISON, (int) (duration * 20), (int) amplifier));
            return true;
    Since this class extends Ability, you have to add a class constructor containing super(String, String, Ability.Type).

    • The first argument is the ability ID. Every ability should have a different ability ID. This is what you'll use in commands, when adding an ability to an item using the GUI.... to actually find the ability.
    • The second argument is the ability default name. The "dynamic" name can be changed in the abilities.yml language file.
    • The third argument is the ability type. If your ability is an on-hit ability, use Ability.Type.ON_HIT. Use Ability.Type.RIGHT_CLICK for right-click abilities.

    Once you have the super(...) method set up, you need to actually define the modifiers that your ability can accept. For the Poison ability, you can change the cooldown, the mana & stamina needed to cast this ability and the poison effect duration and amplifier.
    To add a possible modifier to your ability, use addModifier(String, double)

    • The first argument is the modifier name.
    • The second argument is the default modifier value. This value will be taken by the plugin if this modifier is not specified on the actual item.

    Now we have the general ability set up. We now have to define what the ability actually does. Because we are creating an on-hit ability, we'll have to override the onHit(....) method.

    • p corresponds to the player who casts the ability.
    • t is the entity that was hit by the player ; this is the target of the on-hit ability.
    • mods corresponds to the ability modifiers that are on the items. You'll be manipulating this map only indirectly using the getValue method.
    • damage is the event damage.
    • e is the instance of EntityDamageByEntityEvent that was triggered when the player hit the target.

    If you were to create a right-click ability, you would be overriding the rightClick(.........) method. Here is the code of the Leap right-click ability.
    Code (Java):
    public class Leap extends Ability {
        public Leap() {
            super("LEAP", "Leap", Ability.Type.RIGHT_CLICK);

            addModifier("force", 1);
            addModifier("cooldown", 10);
            addModifier("mana", 0);
            addModifier("stamina", 0);

        public boolean rightClick(Player p, HashMap<String, Double> mods, PlayerInteractEvent e) {
            if (!p.isOnGround())
                return false;

            double force = getValue(mods, "force");

            VersionUtils.sound(p.getLocation(), "ENTITY_ENDERDRAGON_FLAP", 1, 0);
            Eff.EXPLOSION_NORMAL.display(0, 0, 0, .1f, 16, p.getLocation(), 100);
            Vector v = p.getEyeLocation().getDirection().multiply(2 * force);
            v.setY(v.getY() / 2);
            new BukkitRunnable() {
                double ti = 0;

                public void run() {
                    if (ti > 20)
                    Eff.CLOUD.display(0, 0, 0, 0, 1, p.getLocation().add(0, 1, 0), 100);
            }.runTaskTimer(Main.plugin, 0, 1);
            return true;

    Notice how the two overriding methods return a boolean. If you return false, this would make it as if the player did not cast the ability : the cooldown will not apply, the player will not lose his mana/stamina...
    If you however return true, the player will lose his mana, stamina, and the cooldown will apply.

    Lastly, there is a method called getValue(HashMap<String, Double>, String) that returns the ability modifier value if specified on the item, or the default modifier value if not specified.

    Now that you have your ability class set up, you need to register it when the plugin loads.
    Code (Java):
    public void onLoad() {

            // do this for every ability you have
            new Poison().register();
    You can also define a list or an enum of all the abilities you created, loop through it and register every of item. You can also put every ability class in a package and register every ability by looping through all classes in the packages (kind of glitchy though).
  • Loading...
  • Loading...