MMOItems - API

Jun 2, 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"));

    #castAbility(Player, Ability, ItemStack, ValueCouple...) makes a player cast an ability. The ItemStack represents the item the player is clicking when casting the ability. The ValueCouple... are the ability modifiers.
    Code (Text):
    PlayerAbilities.castAbility(player, Ability.FIREBOLT, player.getInventory().getItemInMainHand(), new ValueCouple("damage", 5.6), new ValueCouple("cooldown", 10.3));
    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):

    Adding new right-click/on-hit abilities
    Since MI 3.2, abilities are now registered in an HashMap located in the main plugin class. This hashmap is public, which means you can register and unregister any ability at any moment. Here is a tutorial on how to add new abilities.
    Make sure you have MMOItems.jar as a library and as a plugin dependency!
    • We will have to create at least two classes: one enumeration to list all the abilities we want added, and one class for every ability.
    • Then we'll have to add a method to the onLoad() method of your plugin to actually register the abilities you created when your plugin will be loading.

    Let's create the enum first.
    This enum will list all abilities you want to register. In this enum, an ability is defined by its name, its type, its modifiers and its personnal class which implements the Castable interface.

    For this tutorial, we'll be creating a right-click ability called "Water Bolt" and an on-hit ability called "Super Knockback".
    Code (Java):

    public enum AddonAbility {
        WATER_BOLT(new Water_Bolt(), "Water Bolt", Type.RIGHT_CLICK, "damage", "slow-duration", "cooldown"),
        SUPER_KNOCKBACK(new Super_Knockback(), "Super Knockback", Type.ON_HIT, "force",  "cooldown"),

        private Castable castClass;
        private String name;
        private Type type;
        private String[] mods;

        private AddonAbility(Castable castClass, String name, Type type, String... mods) {
            this.castClass = castClass;
   = name;
            this.type = type;
            this.mods = mods;

        public Castable getCastClass() {
            return castClass;

        public String getName() {
            return name;

        public Type getType() {
            return type;

        public String[] getModifiers() {
            return mods;
    You can add as many abilities as you want, just make sure you follow the right format.
    The string array called mods corresponds to the ability modifiers that your ability will be able to handle. In this case, the Water Bolt ability can have a cooldown, damage and a slow-duration modifier. The Super Knockback ability handles cooldown and force (the knockback force). You can use any name you want, because you can actually translate them using the MMOItems language files.
    The type corresponds to the ability type : it can be RIGHT_CLICK or ON_HIT.

    You should have two errors that says the classes Water_Bolt and Super_Knockback are undefined. These classes are the classes we had to create additionally for each ability we added. You must create one class for each ability, because these will define what the abilities will do. These must implements the Castable interface, and therefore need an overriding method.
    Code (Text):
    public class Water_Bolt implements Castable {
        public void rightClick(Player p, HashMap<String, Double> mods, PlayerInteractEvent e) {
          // ability stuff here
    Code (Text):
    public class Super_Knockback implements Castable {
        public void onHit(Player p, LivingEntity t, HashMap<String, Double> mods, double damage, EntityDamageByEntityEvent e) {
          // ability stuff here
    Notice how the method you have to override is called rightClick for the right-click ability and onHit for the on-hit abilities.
    Now that you have the base class, you can actually code the ability, using the variables the method gives you :

    • p always returns the player who casts the ability.
    • The actual ability modifier values are stored in the HashMap<String, Double>. To get the ability modifier value, check if the map contains the modifier you want and get the corresponding numeric value. You can also use this method which returns the map value if the map contains the modifier, or the default value which you can set as the third argument :
      Code (Text):
      public static double getMapValue(HashMap<String, Double> mods, String name, double defaultValue) {
              return mods.containsKey(name) ? mods.get(name) : defaultValue;
    • t returns the target the player hits (on-hit abilities).
    • e returns the event called when the player casts the ability (item click/physical attack)
    • damage returns the actual damage dealt by the player (on-hit abilities).

    Once you have all these classes set up, head back to your main plugin class and add this following method to your onLoad() method.
    Code (Text):
    for (AddonAbility ability : AddonAbility.values())
                me.Indyuce.mmo.Main.plugin.abilities.put(, new Ability.Constructor(ability.getCastClass(), ability.getName(), ability.getType(), ability.getModifiers()));
    There you go! Now your abilities should be registered: to test them, create an item and give it the ability you created. Don't forget these abilities really behave as default plugin abilities, e.g you can translate their name & their modifier names in the MMOItems language folder.
  • Loading...
  • Loading...