Differences

This shows you the differences between two versions of the page.

--- api:start [2019/10/21 16:32]
indyuce
+++ api:start [2020/07/01 03:13]
@@ Line 1: / Line 1: @@
-===== 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()''.
-<code>
-ItemManager itemManager = MMOItems.plugin.getItems();
-MMOItem mmoitem = itemManager.getMMOItem(MMOItems.plugin.getTypes().get("SWORD"), "CUTLASS");
-ItemStack item = mmoitem.newBuilder().build();
-</code>
-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:
-<code>MMOItems.plugin.getItems().getItem(MMOItems.plugin.getTypes().get("SWORD"), "CUTLASS")</code>
-===== 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:
-<code>
-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
-</code>
-===== 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.
-<code>
-// 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
-AttackResult result = new AttackResult(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);
-</code>
-===== 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=====
-<code>
-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
-</code>
-===== 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 **PlayerStats** class which can be obtained by first accessing the player's **PlayerData** using `PlayerData.get(Player)` and then using the `PlayerDara#getStats()` method.
-If you were to add 10 Atk Damage to a player, you would use ''pstats.getInstance(ItemStat.ATTACK_DAMAGE).setValue("<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 ''PlayerStats#getInstance(ItemStat)'' **always** returns a **StatInstance** (no need of null checks). If the stat isn't load 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.**