Creating Custom Balance Handlers

Creating a Custom HoldingsHandler for TheNewEconomy

TheNewEconomy allows developers to extend its functionality by creating custom HoldingsHandler implementations. These handlers enable the integration of various storage sources for player holdings, such as virtual wallets, inventory, experience levels, or external systems like banks.

---

What is a HoldingsHandler?

A HoldingsHandler is an interface that provides methods to:

1. Set holdings for a player or account.

2. Retrieve holdings from a specific source.

3. Determine whether the handler supports specific currencies or accounts.

---

Steps to Create a Custom HoldingsHandler

1. Implement the HoldingsHandler Interface

Your custom class must implement the HoldingsHandler interface. Below is a template example:

import net.tnemc.core.account.Account;
import net.tnemc.core.account.holdings.HoldingsEntry;
import net.tnemc.core.account.holdings.HoldingsHandler;
import net.tnemc.core.currency.Currency;
import net.tnemc.core.currency.CurrencyType;
import net.tnemc.core.utils.Identifier;

import java.math.BigDecimal;

public class CustomHandler implements HoldingsHandler {

  @Override
  public Identifier identifier() {
    return new Identifier("custom_handler"); // Unique identifier for this handler
  }

  @Override
  public boolean supports(Currency currency, CurrencyType type) {
    // Define the logic for supported currencies or types
    return true;
  }

  @Override
  public boolean setHoldings(Account account, String region, Currency currency, CurrencyType type, BigDecimal amount) {
    // Define how holdings are stored for the account
    return true;
  }

  @Override
  public HoldingsEntry getHoldings(Account account, String region, Currency currency, CurrencyType type) {
    // Define how holdings are retrieved for the account
    return new HoldingsEntry(region, currency.getUid(), BigDecimal.ZERO, identifier());
  }
}

---

2. Register the Handler with TNE

After implementing the HoldingsHandler interface, register your custom handler with TNE:

TNECore.eco().addHandler(new CustomHandler());

This ensures that TNE uses your handler when interacting with supported currencies or account types.

---

Example Implementations

EnderChestHandler

The EnderChestHandler manages holdings stored in a player's Ender Chest:

@Override
public boolean setHoldings(Account account, String region, Currency currency, CurrencyType type, BigDecimal amount) {
  account.getWallet().setHoldings(new HoldingsEntry(region, currency.getUid(), amount, identifier()));
  // Logic to update items in Ender Chest
  return true;
}

ExperienceHandler

The ExperienceHandler handles player holdings based on their experience points:

@Override
public boolean setHoldings(Account account, String region, Currency currency, CurrencyType type, BigDecimal amount) {
  if(account instanceof PlayerAccount player && player.isOnline()) {
    Experience.setExperience(player.getPlayer().get(), amount.intValueExact());
  }
  return true;
}

---

Key Points

1. Identifier: Each handler must have a unique identifier returned by the identifier() method.

2. Compatibility: Use the supports() method to restrict the handler to specific currencies or types.

3. Data Handling: Decide whether holdings should be saved in TNE's database or managed externally via the database() method.

4. Integration: Handlers can interact with specific storage systems, such as inventory or external databases.

---

Notes

• Use existing handlers like VirtualHandler, InventoryHandler, or ExperienceHandler as references.

• Always register your custom handler with TNECore.eco().addHandler() to make it active in TNE.

---

By creating a custom HoldingsHandler, you can expand TheNewEconomy to integrate with diverse systems and provide unique gameplay experiences.