Main-API-Features.md

+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.**
\ No newline at end of file