For developers

For developers

Requires Java 21

Replace "VERSION" with the Jitpack version

Gradle:

plugins {
  id 'com.gradleup.shadow' version '8.3.0'
}

repositories {
  mavenCentral()
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation 'com.github.xef5000:ItemsAPI:VERSION'
}

tasks {
    shadowJar {
        // Replace "com.yourplugin" with your plugin's package name.
        relocate "com.github.xef5000.itemsapi", "com.yourplugin.libs.itemsapi"
        archiveClassifier.set('')
    }

    build {
        dependsOn shadowJar
    }
}

API Usage

Once the API is properly installed and shaded into your plugin, here's how you can use the API:

ConfigurationSection itemSection = getConfig().getConfigurationSection("item");
ItemStack item = ItemsAPI.fromConfiguration(itemSection);

Example of the "item" section in the config:

item:
  material: stone

This would return one stone block

Every item must have its own section

Example 1: GUI configuration

gui:
  title: "test"
  rows: 3
  items:
    10:
      material: stone
      name: '&cClose'
      lore:
        - '&7Close the GUI'

In Example 1, the item must be loaded from "gui.items.10". To load this item, you would use:

ConfigurationSection itemSection = getConfig().getConfigurationSection("gui.items.10");
ItemStack item = ItemsAPI.fromConfiguration(itemSection);

Currency usage

A currency can be loaded from the a configuration section:

ConfigurationSection currencySection = getConfig().getConfigurationSection("currency");
Currency currency = ItemsAPICurrency.fromConfigurationSection(currencySection);

Example CurrencyManager class

Main config:

currencies:
  money:
    integration: vault
    symbol: $

public class CurrencyManager {

    private final JavaPlugin plugin;
    private final Map<String, Currency> currencies;

    public CurrencyManager(JavaPlugin plugin) {
        this.plugin = plugin;
        this.currencies = new HashMap<>();
    }

    public boolean initialize() {
        // Load currencies from config
        currencies.clear();
        ConfigurationSection currenciesSection = plugin.getConfig().getConfigurationSection("currencies");
        if (currenciesSection == null) {
            plugin.getLogger().warning("No currencies defined in config.yml!");
            return false;
        }

        for (String currencyId : currenciesSection.getKeys(false)) {
            ConfigurationSection currencySection = currenciesSection.getConfigurationSection(currencyId);
            if (currencySection == null) continue;

            Currency currency = ItemsAPICurrency.fromConfigurationSection(currencySection);
            currencies.put(currencyId, currency);

            plugin.getLogger().info("Loaded currency: " + currencyId);
        }

        return true;
    }


    /**
     * Get a currency by ID
     */
    public Currency getCurrency(String id) {
        return currencies.get(id);
    }

    /**
     * Check if a player has enough of a currency
     */
    public boolean has(Player player, String currencyId, double amount) {
        Currency currency = getCurrency(currencyId);
        if (currency == null) {
            plugin.getLogger().warning("Unknown currency: " + currencyId);
            return false;
        }

        return currency.getIntegration().getBalance(player) >= amount;
    }

    /**
     * Withdraw currency from a player
     */
    public boolean withdraw(Player player, String currencyId, double amount) {
        Currency currency = getCurrency(currencyId);
        if (currency == null) {
            plugin.getLogger().warning("Unknown currency: " + currencyId);
            return false;
        }

        if (has(player, currencyId, amount)) {
            currency.getIntegration().withdraw(player, amount);
            return true;
        } else {
            return false;
        }
    }

    /**
     * Deposit currency to a player
     */
    public void deposit(Player player, String currencyId, double amount) {
        Currency currency = getCurrency(currencyId);
        if (currency == null) {
            plugin.getLogger().warning("Unknown currency: " + currencyId);
            return;
        }

        currency.getIntegration().deposit(player, amount);
    }

    /**
     * Get a player's balance
     */
    public double getBalance(Player player, String currencyId) {
        Currency currency = getCurrency(currencyId);
        if (currency == null) {
            plugin.getLogger().warning("Unknown currency: " + currencyId);
            return 0;
        }

        return currency.getIntegration().getBalance(player);
    }

    /**
     * Format a currency amount
     */
    public String format(String currencyId, double amount) {
        Currency currency = getCurrency(currencyId);
        if (currency == null) {
            return String.valueOf(amount);
        }
        return currency.getSymbol() + amount;
    }

    public Map<String, Currency> getCurrencies() {
        return new HashMap<>(currencies);
    }
}