💻Developer API

For developers, here you will have a mini basic guide to some of the uses you have, it assumes some knowledge about java and plugins in general. Any doubt you can contact me in the discord

Implementation

First of all, to get as dependency, you will need in the root folder a folder called libs and the .jar should be there

In your gradle project

compileOnly files("libs/TopMinion.jar")

In your maven project

<dependencies>
    <dependency>
        <groupId>com.sarry20</groupId>
        <artifactId>TopMinion</artifactId>
        <version>VERSION</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/libs/TopMinion.jar</systemPath>
    </dependency>
</dependencies>

Events

You will now have access to our classes and you can start modifying things, first, let's go to the easiest thing of all, the events, you can listen to all these events:

• MinionPlaceEvent

• MinionBreakEvent

• MinionUpgradeEvent

• MinionAddMemberEvent

• MinionTakeInventoryItemsEvent

• ChestPlaceEvent

• ChestBreakEvent

• ChestTakeItemsEvent

ItemProvider

Another thing you can do is to set up your own item provider to do the upgrades, this is the interface you must implement for it

package com.sarry20.topminion.hook.interfaces;

import org.bukkit.inventory.ItemStack;

public interface ItemProvider {
    ItemStack getItem(String itemID, int amount);

    boolean checkItem(ItemStack item);

    String getMetadata(ItemStack item);
}

Once you have your class, what you will have to do is to put it as the item provider for it you can do it with the following line:

TopMinion.getInstance().getHookManager().setItemProvider(new YourCustomProvider());

Now you will be able to use the item plugin that you have implemented, for this in the configuration of the items you must put: identifier#item_id#quantity

String	explanation
identifier	it is not used for anything in the plugin, it is simply for you as a configurator to know which plugin it comes from or whatever you want to put.
item_id	this is the name by which the ItemProvider#getItem method will get the item you need for the enhancement.
amount	the amount needed to level up the minion.

Upgrades

Also, you can create your own upgrades for the minions, for this you will need to create 2 classes, one that implements Upgrade and another that implements DataHolder. Let's see this in a little more detail

Upgrade

This is the Upgrade class that you must implement to create a new upgrade

package com.sarry20.topminion.upgrades;

import com.sarry20.topminion.models.minion.MinionObj;
import com.sarry20.topminion.upgrades.dataHandler.Datahandler;
import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.inventory.ItemStack;

public interface Upgrade extends ConfigurationSerializable {

    /**
     * @return the item that represent the upgrade
     * */
    ItemStack getItem();

    /**
     * @param objects the objects that should be used to get the data handler, can be null
     *                these can be integers, strings, etc
     *                used to create a data handler with the specific data, not with the default data
     * @return the data handler of the upgrade
     * */
    Datahandler getDataHandler(Object... objects);

    /**
     * Called when tries to add the upgrade to the minion
     * @param minionObj the minion that the upgrade is being added
     * @return true if the upgrade should be added
     * */
    boolean onAdd(MinionObj minionObj);

    /**
     * Called every time the minion work
     * @param minionObj the minion that is working
     * @return (only used when upgrade is a fuel) the time to the next tick
     * */
    int onTick(MinionObj minionObj);

    /**
     * Called when the player give the item to the minion
     * @param item the item that the minion is going to add to the inventory
     *             this item can be modified
     * @param minionObj the minion that is going to receive the item
     * @return the item that should be given to the minion
     * */
    ItemStack onGiveItemToMinion(MinionObj minionObj, ItemStack item);

    /**
     * Called when the player click on the item
     * @param shiftClick true if the player is shift clicking
     * @param minionObj the minion that the upgrade is being clicked
     * @return true if the upgrade should be removed
     * */
    boolean onClick(boolean shiftClick, MinionObj minionObj);

    /**
     * @return true if should be on fuel slot
     * */
    boolean isFuel();

    /**
     * @return the remaining uses of the upgrade
     * */
    int getRemainingUses();
}

NOTE about getDataHolder: for the upgrades that are done I am using the parameter, for when the upgrade with LIMITED uses is removed, to store the remaining uses in the item

DataHolder

This is the DataHolder class that you must implement for the minion to store the necessary information, it is quite basic, if you need more methods for your implementation do not hesitate to enter discord to suggest what methods you need.

package com.sarry20.topminion.upgrades.dataHandler;

import org.bukkit.configuration.serialization.ConfigurationSerializable;

public interface Datahandler extends ConfigurationSerializable {

    /**
     * @return the remaining uses of the upgrade
     * */
    int getRemainingUses();

    /**
     * remove much actions as you want
     * @param actions the actions to remove
     * */
    void takeActions(int actions);
}

Once you have the classes created, when you want to add the upgrade, you must add the following line

TopMinion.getInstance().getUpgradeManager().addUpgrade(key, upgrade)

Also for it to work you must register your two classes in the serializer

ConfigurationSerialization.registerClass(YourCustomUpgrade.class);

ConfigurationSerialization.registerClass(YourCustomDataHolder.class);

These are the functions that we have contemplated to do, any other function is not tested and you will do it under your responsibility (these functions here explained, also will be done under your responsibility, but these are explained), you can always ask for help in discord or ask to add a function to the api

Examples

ItemProvider Implementation

package com.sarry20.topminion.hook.items;

import com.sarry20.topminion.hook.interfaces.ItemProvider;
import org.bukkit.Bukkit;
import org.bukkit.NamespacedKey;
import org.bukkit.inventory.ItemStack;
import org.bukkit.persistence.PersistentDataType;

public class EcoItems implements ItemProvider {

    public EcoItems(){
        //No need to init anything
    }
    @Override
    public ItemStack getItem(String itemID, int amount) {
        try{
            ItemStack item = com.willfp.ecoitems.items.EcoItems.INSTANCE.getByID(itemID).getItemStack();
            if (item.hasItemMeta()) {
                item.setAmount(amount);
                return item;
            }
        }catch (Exception e){
            Bukkit.getLogger().severe("Invalid item ID: " + itemID);
        }
        return null;
    }
    @Override
    public boolean checkItem(ItemStack item){
        if(item == null || item.getItemMeta() == null)
            return false;
        return item.getItemMeta()
                .getPersistentDataContainer()
                .has(new NamespacedKey(Bukkit.getServer().getPluginManager().getPlugin("EcoItems"), "item"), PersistentDataType.STRING);
    }
    @Override
    public String getMetadata(ItemStack item) {
        return item.getItemMeta()
                .getPersistentDataContainer()
                .get(
                        new NamespacedKey(Bukkit.getServer().getPluginManager().getPlugin("EcoItems"), "item"),
                        PersistentDataType.STRING);
    }
}

Upgrade Implementation

FuelUpgrade.class

package com.sarry20.topminion.upgrades;

import com.sarry20.topminion.TopMinion;
import com.sarry20.topminion.models.minion.MinionObj;
import com.sarry20.topminion.upgrades.dataHandler.Datahandler;
import com.sarry20.topminion.upgrades.dataHandler.FuelData;
import org.bukkit.configuration.serialization.SerializableAs;
import org.bukkit.inventory.ItemStack;
import org.bukkit.inventory.meta.ItemMeta;
import org.jetbrains.annotations.NotNull;

import java.util.*;

@SerializableAs("fuel")
public class FuelUpgrade implements Upgrade {

    private final String key;
    private final int tier;
    private final ItemStack item;
    private final int percent;
    private final int fuelActions;
    private final String CustomModelData;

    public FuelUpgrade(String key,int tier, ItemStack item, int percent, int fuelActions, String CustomModelData) {
        this.key = key;
        this.tier = tier;
        this.item = item;
        this.percent = percent;
        this.fuelActions = fuelActions;
        this.CustomModelData = CustomModelData;

    }

    public FuelUpgrade(Map<String, Object> map) {
        key = (String) map.get("key");
        tier = (int) map.get("tier");
        item = (ItemStack) map.get("item");
        percent = (int) map.get("percent");
        fuelActions = (int) map.get("fuelActions");
        CustomModelData = (String) map.get("CustomModelData");
    }

    @Override
    public ItemStack getItem() {
        ItemStack is = item.clone();
        ItemMeta meta = is.getItemMeta();
        List<String> newLore = new ArrayList<>();
        for (String string : meta.getLore()) {
            newLore.add(string.replaceAll("%remaining_actions%",fuelActions+""));
        }
        meta.setLore(newLore);
        is.setItemMeta(meta);
        is.setAmount(1);
        return is;
    }

    @Override
    public Datahandler getDataHandler(Object... objects) {
        if (objects.length != 0 && objects[0] instanceof Integer){
            return new FuelData((int) objects[0]);
        }
        return new FuelData(fuelActions);

    }
    
    @Override
    public boolean onAdd(MinionObj minionObj) {
        for (String upgrade : minionObj.getUpgrades().keySet()) {
            Upgrade upgradeObj = TopMinion.getInstance().getUpgradeManager().getUpgrade(upgrade);
            if (upgradeObj.isFuel()){
                return false;
            }
        }
        return true;
    }

    @Override
    public int onTick(MinionObj minionObj) {
        int fuelTime = minionObj.getTime() - (minionObj.getTime() * percent / 100);
        Datahandler data = minionObj.getUpgrades().get(key);
        if (data.getRemainingUses() != -1){
            data.takeActions(1);
            if (data.getRemainingUses() == 0){
                minionObj.getUpgrades().remove(key);
            }
        }
        return fuelTime;


    }

    @Override
    public ItemStack onGiveItemToMinion(MinionObj minionObj, ItemStack item) {
        return item;
    }

    @Override
    public boolean onClick(boolean shiftClick, MinionObj minionObj) {
        return true;
    }

    @Override
    public boolean isFuel() {
        return true;
    }

    @Override
    public int getRemainingUses() {
        return fuelActions;
    }

    @NotNull
    @Override
    public Map<String, Object> serialize() {
        Map<String, Object> map = new HashMap<>();
        map.put("key", key);
        map.put("tier", tier);
        map.put("item", item);
        map.put("percent", percent);
        map.put("fuelActions", fuelActions);
        map.put("CustomModelData", CustomModelData);

        return map;
    }
}

SmelterUpgrade.class

package com.sarry20.topminion.upgrades;

import com.sarry20.topminion.models.minion.MinionObj;
import com.sarry20.topminion.models.minionConfig.ConfigClass;
import com.sarry20.topminion.models.minionConfig.ConfigClassManager;
import com.sarry20.topminion.upgrades.dataHandler.Datahandler;
import com.sarry20.topminion.upgrades.dataHandler.SmelterData;
import org.bukkit.Material;
import org.bukkit.configuration.serialization.SerializableAs;
import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;

import java.util.HashMap;
import java.util.Map;

@SerializableAs("smelter")
public class SmelterUpgrade implements Upgrade {

    private final String key;
    private final ItemStack item;
    private final int smelterActions;
    private final String customModelData;

    public SmelterUpgrade(String key, ItemStack item,int smelterActions, String customModelData) {
        this.key = key;
        this.item = item;
        this.smelterActions = smelterActions;
        this.customModelData = customModelData;
    }

    public SmelterUpgrade(Map<String, Object> map) {
        key = (String) map.get("key");
        item = (ItemStack) map.get("item");
        smelterActions = (int) map.get("smelterActions");
        customModelData = (String) map.get("customModelData");
    }

    @NotNull
    @Override
    public Map<String, Object> serialize() {
        Map<String, Object> map = new HashMap<>();
        map.put("key", key);
        map.put("item", item);
        map.put("smelterActions", smelterActions);
        map.put("customModelData", customModelData);

        return map;
    }

    @Override
    public ItemStack getItem() {
        return item;
    }

    @Override
    public Datahandler getDataHandler(Object... objects) {
        if (objects.length != 0 && objects[0] instanceof Integer){
            return new SmelterData((int) objects[0]);
        }
        return new SmelterData(smelterActions);
    }

    @Override
    public boolean onAdd(MinionObj minionObj) {
        return true;
    }

    @Override
    public int onTick(MinionObj minionObj) {
        return 0;
    }

    @Override
    public ItemStack onGiveItemToMinion(MinionObj minionObj, ItemStack itemStack) {
        Datahandler data = minionObj.getUpgrades().get(key);
        if (data.getRemainingUses() != -1){
            data.takeActions(1);
            if (data.getRemainingUses() == 0) {
                minionObj.getUpgrades().remove(key);
            }
        }
        ConfigClass configClass = ConfigClassManager.getConfigClass(minionObj.getMaterial(), minionObj.getType());
        if (configClass != null && !configClass.getSmeltedMaterial().isEmpty()) {
            Material smelterMaterial = Material.getMaterial(configClass.getSmeltedMaterial());
            itemStack.setType(smelterMaterial);
        }
        return itemStack;
    }

    @Override
    public boolean onClick(boolean shiftClick, MinionObj minionObj) {

        return true;
    }

    @Override
    public boolean isFuel() {
        return false;
    }

    @Override
    public int getRemainingUses() {
        return smelterActions;
    }
}

DataHolder Implementation

FuelData.class

package com.sarry20.topminion.upgrades.dataHandler;

import org.bukkit.configuration.serialization.SerializableAs;
import org.jetbrains.annotations.NotNull;

import java.util.Map;

@SerializableAs("fuelData")
public class FuelData implements Datahandler {
    private int fuelActions;

    public FuelData(int fuelActions) {
        this.fuelActions = fuelActions;
    }
    public FuelData(Map<String, Object> map) {
        fuelActions = (int) map.get("fuelActions");
    }

    @NotNull
    @Override
    public Map<String, Object> serialize() {
        return Map.of("fuelActions", fuelActions);
    }

    @Override
    public int getRemainingUses() {
        return fuelActions;
    }

    @Override
    public void takeActions(int actions) {
        fuelActions -= actions;
    }
}

SmelterData.class

package com.sarry20.topminion.upgrades.dataHandler;

import org.bukkit.configuration.serialization.SerializableAs;
import org.jetbrains.annotations.NotNull;

import java.util.Map;

@SerializableAs("smelterData")
public class SmelterData implements Datahandler {
    private int fuelActions;

    public SmelterData(int fuelActions) {
        this.fuelActions = fuelActions;
    }
    public SmelterData(Map<String, Object> map) {
        fuelActions = (int) map.get("fuelActions");
    }

    @Override
    public int getRemainingUses() {
        return fuelActions;
    }

    @Override
    public void takeActions(int actions) {
        fuelActions -= actions;
    }

    @NotNull
    @Override
    public Map<String, Object> serialize() {
        return Map.of("fuelActions", fuelActions);


    }
}