MMOItems - API

Oct 21, 2018 at 3:29 PM
MMOItems - API

  • Generating an item
    You can use the static method from the MMOItems class to instantly generate an item from MI. You need to specify the item type (e.g Type.SWORD) and the item ID (e.g STEEL_SWORD).
    Code (Text):
    ItemStack item = MMOItems.getItem(Type.SWORD, "STEEL_SWORD");

    Casting an ability
    You can use the static method from the PlayerAbilities class to force a player to cast an ability. You need the player, the ability, the ability modifiers and the item used to cast the ability as the arguments. Ability modifiers are stored in a map that associates the modifier name to the mod value.
    Code (Text):
    Map<String, Double> mods = new HashMap<String, Double>();
    mods.put("damage", 8);
    mods.put("mana", 30);

    PlayerAbilities.cast(player, ability, mods, event); // event can be null

    Getting an ability instance
    Abilities are stored in an instance of the AbilityManager class that is accessible using a static method from the MMOItems class. To get the ability class instance, simply use the get method from the AbilityManager class and give the method the ability ID as the argument.
    Code (Text):
    Ability ability = MMOItems.getAbilities().get("FIREBOLT");

    Opening custom GUIs
    Code (Text):
    Player player = Bukkit.getPlayer("PlayerName");
    new AdvancedRecipeList(player, 1).open(); // opens at page
    new AdvancedRecipeWorkbench(player).open();
    new ItemEdition(player, Type.STAFF, "EARTH_STAFF").open(); // opens the edition gui for the staff which ID is EARTH _STAFF

    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 AbilityResult onHit(Player player, LivingEntity target, Map<String, Double> mods, double damage) {
            double duration = getValue(mods, "duration");
            double amplifier = getValue(mods, "amplifier");

            ParticleEffect.SLIME.display(1, 1, 1, 0, 32, target.getLocation().add(0, 1, 0), 200);
            ParticleEffect.VILLAGER_HAPPY.display(1, 1, 1, 0, 24, target.getLocation().add(0, 1, 0), 200);
            target.getWorld().playSound(target.getLocation(), VersionSound.BLOCK_BREWING_STAND_BREW.getSound(), 2, 2);
            target.getWorld().playSound(target.getLocation(), VersionSound.ENTITY_SHEEP_DEATH.getSound(), 1, 2);
            target.addPotionEffect(new PotionEffect(PotionEffectType.POISON, (int) (duration * 20), (int) amplifier));
            return new AbilityResult(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.

    • player corresponds to the player who casts the ability.
    • target 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.

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

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

        public AbilityResult rightClick(Player player, Map<String, Double> mods) {
            if (!player.isOnGround())
                return new AbilityResult(false);

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

            player.getWorld().playSound(player.getLocation(), VersionSound.ENTITY_ENDERDRAGON_FLAP.getSound(), 1, 0);
            ParticleEffect.EXPLOSION_NORMAL.display(0, 0, 0, .1f, 16, player.getLocation(), 100);
            Vector v = player.getEyeLocation().getDirection().multiply(2 * force);
            v.setY(v.getY() / 2);
            new BukkitRunnable() {
                double ti = 0;

                public void run() {
                    if (ti > 20)
                    ParticleEffect.CLOUD.display(0, 0, 0, 0, 1, player.getLocation().add(0, 1, 0), 100);
            }.runTaskTimer(MMOItems.plugin, 0, 1);
            return new AbilityResult(true);

    Notice how the two overriding methods return an instance of AbilityResult. An ability result is defined by two parameters: a boolean and a double. The boolean defines if the ability was successfully cast or not. The double shall only be used in on-hit abilities since it will return the new value of the EntityDamageByEntityEvent damage.
    Here's how you can create a new ability result:
    Code (Text):
    return new AbilityResult(true); // the ability was successfully cast
    return new AbilityResult(false); // the ability was not cast, and the cooldown & other effects will not be applied.
    return new AbilityResult(true, 10); // the ON-HIT ability was successfully cast and the event damage is now 10

    Lastly, there is a method called getValue(Map<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...