Main API Features

Join the Discord support channel if you need further info about MMOItems API.

Checking if an ItemStack is from MI

First, get the NBTItem of your ItemStack using NBTItem.get(ItemStack). This class lets you manipulate NBTTags from your item easily (1.14 has a new API which lets you do that using the ItemMeta, but for <1.14 support MI handles NBTs using NMS code). Use nbtItem.hasType() to see if the NBTItem can find the tag which corresponds to an MMOItems type. This method basically checks whether or not the plugin is from MI.

You can get the item type using nbtItem.getType(). This method calls a map checkup through all the plugin item types, so save its result in a field to save calculations.

Generating an item

Since 4.6 you now have to load an item before generating it. Loaded items are stored into MMOItem instances. By using the newBuilder() method (from the MMOItem class), you can create an MMOItemBuilder which can build an ItemStack instance out of an MMOItem. Items may be loaded & generated using the ItemManager instance saved in the main java plugin class. You can access the item manager using MMOItems.plugin.getItems().

ItemManager itemManager = MMOItems.plugin.getItems();
MMOItem mmoitem = itemManager.getMMOItem(MMOItems.plugin.getTypes().get("SWORD"), "CUTLASS");
ItemStack item = mmoitem.newBuilder().build();

Make sure you don't use the same MMOItemBuilder twice to build an ItemStack using the build() method. This method scrambles a lot of item data and thus can't be used twice. However you can use the same MMOItem instance to generate as many MMOItemBuilders as you want.

The following method directly returns the ItemStack instance:
MMOItems.plugin.getItems().getItem(MMOItems.plugin.getTypes().get("SWORD"), "CUTLASS")

Retrieving item type instances

Since 4.6, types are not stored in an enum anymore since you can add as many as you want. Type instances are now stored in a TypeManager class instance, which can be accessed using the following method:

TypeManager types = MMOItems.plugin.getTypes();
Type sword = types.get("SWORD") // e.g get the type which ID is SWORD
Collection<Type> all = types.getAll() // get all loaded types

Casting an ability

You need to use the cast method from the PlayerData class to make a player cast an ability. You also need to specify the ability modifiers, and eventually the ability target, if your ability is an on-hit ability. If you don't want the ability to display any message when cast/not successfully cast, you will have to toggle off a boolean value.

// the ability modifiers
AbilityData data = new AbilityData(ability);
data.setModifier("damage", 8);
data.setModifier("mana", 30);

// get player data
PlayerData playerData = PlayerData.get(player);

// damage -> some abilities change the event damage, abilities calculate the ability extra damage based on that value
ItemAttackResult result = new ItemAttackResult(damage);

// caches player stats so they are not changed later
TemporaryStats stats = playerData.getStats().newTemporary();

playerData.cast(stats, target, result, data, true);

// an easier way of casting abilities WITH NO TARGET
playerData.cast(data);

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(String) method from the AbilityManager class and specify the ability ID as argument. Ability ability = MMOItems.plugin.getAbilities().get("FIREBOLT");

Opening plugin GUIs

new AdvancedTypeList(player, 1).open(); // opens the recipe list at type selection
new AdvancedRecipeList(player, MMOItems.plugin.getTypes().get("SWORD")).open(); // opens the recipe list (after selecting item type)
new AdvancedRecipeWorkbench(player).open(); // opens the advanced workbench
new ItemEdition(player, MMOItems.plugin.getTypes().get("STAFF"), "EARTH_STAFF").open(); // opens the edition gui for a specific item

Checking if a GUI is from MI

Every GUI from MMOItems is created used a custom inventory holder which extends PluginInventory. To check if a GUI is a GUI for MI, just retrieve the inventory holder and check if it's an instance of that class: inventory.getHolder() instanceof PluginInventory

Adding extra stats

You may add temporary numeric stats like crit chance, attack damage, etc. to players. These stats function a bit like attribute modifiers but are reset on server restart. Extra stats can be added using the StatMap class which can be obtained by first accessing the player's MMOData using MMOData.get(Player) and then using the MMOData#getStatMap() method.

If you were to add 10 Atk Damage to a player, you would use pstats.getInstance(SharedStat.ATTACK_DAMAGE).addModifier("<externalSourceName>", 10); which essentially stores the value 10 in a map using a specific key. When calculating stats, MMOItems simply sums up every value in the map. If you want something like per-level stat rewards, you will have to handle calculations on your end and then apply the stats everytime the player data is loaded (e.g on login).

The StatMap#getInstance(ItemStat) always returns a StatInstance (no need of null checks). If the stat isn't loaded in the map yet, it creates a new one and saves it for you. Just make sure you only use this system for numeric stats, because other stats are not supported.