# Developer API

ExcellentEconomy provides a robust and easy-to-use API for developers looking to integrate their plugins with it.

# 📦 Importing the API

To get started, add the dependency to your project. Replace {VERSION} with the latest version shown on the badge below:

Repository:

<repository>
  <id>nightexpress-releases</id>
  <url>https://repo.nightexpressdev.com/releases</url>
</repository>

Dependency:

<dependency>
  <groupId>su.nightexpress.coinsengine</groupId>
  <artifactId>CoinsEngine</artifactId>
  <version>{VERSION}</version>
  <scope>provided</scope>
</dependency>

Repository:

maven { url = 'https://repo.nightexpressdev.com/releases' }

Dependency:

compileOnly("su.nightexpress.coinsengine:CoinsEngine:{VERSION}")

# 🔔 Events

You can listen to the following events to track certain economy changes:

ChangeBalanceEvent Cancellable - Triggered when a player's currency balance is about to be modified.

# 🛠️ API Usage Guide

# 🔑 Accessing the API

Use the Bukkit ServiceManager to get the API instance:

RegisteredServiceProvider<ExcellentEconomyAPI> provider = Bukkit.getServer().getServicesManager().getRegistration(ExcellentEconomyAPI.class);
if (provider != null) {
    ExcellentEconomyAPI api = provider.getProvider();
}

# 💰 Handling Balances

The API offers both Asynchronous methods (for database calls) and Cached methods (for active players).

If user data is cached, Async methods will not call database and immediately return completed CompletableFuture result.

# 🏷️ Operation Context

I highly recommend you to create your own OperationContext and pass it to API methods:

OperationContext myContext = OperationContext.custom("YourPlugin").silentFor(NotificationTarget.USER, NotificationTarget.EXECUTOR, NotificationTarget.CONSOLE_LOGGER);

This will log currency operations performed via the API under your plugin name, which might be useful for server owners to investigate any economy-related issues on their server.

# 🔒 Operations Lockdown

You can also check whether currency operations are allowed before you call API methods. For example, operations are disabled during data migration or balance reset process.

boolean canPerformOperations = api.canPerformOperations();

When using Async API methods, make sure to check whether OperationResult is successful before proceed with your code.

# 🔍 Retrieve Balance

// Asynchronous
CompletableFuture<Double> future = api.getBalanceAsync(UUID playerId, String currencyName);
CompletableFuture<Double> future = api.getBalanceAsync(UUID playerId, ExcellentCurrency currency);

// Cached
double balance = api.getBalance(Player player, String currencyId);
double balance = api.getBalance(Player player, ExcellentCurrency currency);

# 📥 Deposit Currency

// Asynchronous
CompletableFuture<OperationResult> future = api.depositAsync(UUID playerId, String currencyName, double amount);
CompletableFuture<OperationResult> future = api.depositAsync(UUID playerId, String currencyName, double amount, OperationContext context);
CompletableFuture<OperationResult> future = api.depositAsync(UUID playerId, ExcellentCurrency currency, double amount);
CompletableFuture<OperationResult> future = api.depositAsync(UUID playerId, ExcellentCurrency currency, double amount, OperationContext context);

// Cached
boolean result = api.deposit(Player player, String currencyId, double amount);
boolean result = api.deposit(Player player, String currencyId, double amount, OperationContext context);
boolean result = api.deposit(Player player, ExcellentCurrency currency, double amount);
boolean result = api.deposit(Player player, ExcellentCurrency currency, double amount, OperationContext context);

# 📤 Withdraw Currency

// Asynchronous
CompletableFuture<OperationResult> future = api.withdrawAsync(UUID playerId, String currencyId, double amount);
CompletableFuture<OperationResult> future = api.withdrawAsync(UUID playerId, String currencyId, double amount, OperationContext context);
CompletableFuture<OperationResult> future = api.withdrawAsync(UUID playerId, ExcellentCurrency currency, double amount);
CompletableFuture<OperationResult> future = api.withdrawAsync(UUID playerId, ExcellentCurrency currency, double amount, OperationContext context);

// Cached
boolean result = api.withdraw(Player player, String currencyId, double amount);
boolean result = api.withdraw(Player player, String currencyId, double amount, OperationContext context);
boolean result = api.withdraw(Player player, ExcellentCurrency currency, double amount);
boolean result = api.withdraw(Player player, ExcellentCurrency currency, double amount, OperationContext context);

# 💳 Set Currency Balance

// Asynchronous
CompletableFuture<OperationResult> future = api.setBalanceAsync(UUID playerId, String currencyId, double amount);
CompletableFuture<OperationResult> future = api.setBalanceAsync(UUID playerId, String currencyId, double amount, OperationContext context);
CompletableFuture<OperationResult> future = api.setBalanceAsync(UUID playerId, ExcellentCurrency currency, double amount);
CompletableFuture<OperationResult> future = api.setBalanceAsync(UUID playerId, ExcellentCurrency currency, double amount, OperationContext context);

// Cached
boolean result = api.setBalance(Player player, String currencyId, double amount);
boolean result = api.setBalance(Player player, String currencyId, double amount, OperationContext context);
boolean result = api.setBalance(Player player, ExcellentCurrency currency, double amount);
boolean result = api.setBalance(Player player, ExcellentCurrency currency, double amount, OperationContext context);

# 💎 Currency Management

// Check if currency exists
boolean hasCurrency = api.hasCurrency(String id);

// Get all registered currencies
Set<ExcellentCurrency> currencies = api.getCurrencies();

// Get currency by ID
ExcellentCurrency currency = api.getCurrency(String id);
Optional<ExcellentCurrency> optionalCurrency = api.currencyById(String id);

// Register custom currency (with commands).
api.currencyManager().injectCurrency(myCurrency);

// Register custom currency (without commands).
api.currencyManager().registerCurrency(myCurrency);

# 👤 User Data Management

// Get Cached User Data
CoinsUser = api.getCachedUserData(Player player);
Optional<CoinsUser> optionalUser = api.getCachedUserData(String name);
Optional<CoinsUser> optionalUser = api.getCachedUserData(UUID uuid);

// Fetch From Database (or instant cached result)
CompletableFuture<Optional<CoinsUser>> future = api.loadUserDataByName(String name);
CompletableFuture<Optional<CoinsUser>> future = api.loadUserDataById(UUID uuid);

// Manage balance
user.setBalance(currency, amount);
user.addBalance(currency, amount);.
user.removeBalance(currency, amount);

// Mark user for save
user.markDirty();