Bank API Reference

The Bank plugin exposes a public API for other mods to integrate with the bank system. This includes custom events, a service API for adding items, and the event bus for listening to bank activity.

---

Events

The Bank uses a custom BankEventBus (singleton) for cross-mod event communication. Events are fired on the server thread.

BankDepositEvent

Fired when an item is deposited into the bank (via drag-and-drop, Shift+Click, or the addItemOrDrop API).

Property	Type	Description
playerRef	PlayerRef	The player who deposited the item
itemId	String	The item ID (e.g., Sword_Iron)
quantity	int	Number of items deposited
page	int	The bank page the item was placed on (-1 if placed via API)

BankWithdrawEvent

Fired when an item is withdrawn from the bank.

Property	Type	Description
playerRef	PlayerRef	The player who withdrew the item
itemId	String	The item ID
quantity	int	Number of items withdrawn
page	int	The bank page the item was taken from

---

Listening to Events

Register a listener via the BankEventBus singleton:

import com.hytale.bank.event.BankEventBus;
import com.hytale.bank.event.BankDepositEvent;
import com.hytale.bank.event.BankWithdrawEvent;

// Listen for deposits
BankEventBus.getInstance().register(BankDepositEvent.class, event -> {
    String player = event.getPlayerRef().getUsername();
    String item = event.getItemId();
    int qty = event.getQuantity();
    logger.info(player + " deposited " + qty + "x " + item);
});

// Listen for withdrawals
BankEventBus.getInstance().register(BankWithdrawEvent.class, event -> {
    // React to withdrawal...
});

warning

Event listeners are called synchronously on the server thread. Avoid blocking operations in your listeners.

---

BankService API

addItemOrDrop(PlayerRef playerRef, ItemStack itemStack)

Adds an item to the player's bank. If the bank is full and the player is online, the item is dropped at the player's feet.

Parameters:

Parameter	Type	Description
playerRef	PlayerRef	The player (must be online)
itemStack	ItemStack	The item to add

Returns: boolean — true if the item was added to the bank, false if it was dropped or failed.

Behavior:

1. Attempts to add the item to the first available slot across all unlocked pages
2. If successful, saves player data, logs the transaction, and fires a BankDepositEvent
3. If the bank is full, drops the item at the player's feet using SimpleItemContainer.addOrDropItemStack

Usage example (from another mod):

// Get the BankPlugin instance
BankPlugin bankPlugin = ...; // Obtain via mod registry or static reference

// Create an item stack
ItemStack reward = ItemStack.create("Ore_Gold", 10);

// Add to player's bank (or drop if full)
boolean added = bankPlugin.getBankService().addItemOrDrop(playerRef, reward);
if (added) {
    player.sendMessage(Message.raw("Reward added to your bank!"));
} else {
    player.sendMessage(Message.raw("Bank full — reward dropped at your feet."));
}

---

Event Bus Management

BankEventBus.getInstance()

Returns the singleton event bus instance.

register(Class<T> eventType, Consumer<T> listener)

Registers a listener for a specific event type. Thread-safe — can be called during mod initialization.

fire(T event)

Fires an event, notifying all registered listeners. Called internally by the Bank plugin.

clear()

Removes all registered listeners. Called on plugin shutdown.

---

Dependencies

The Bank plugin has an optional dependency on KyuubiSoft Core (kyuubisoft:core). When Core is present:

• Economy integration (VaultUnlocked) is available via CoreBridge
• NPC citizen interactions work for bank NPCs
• Localization uses the shared KsLang system
• Bank appears in the Core admin menu

When Core is not present, the Bank operates in standalone mode:

• Economy features (upgrades, coin deposits) are disabled
• Bank can only be opened via /ksbank command
• Localization uses built-in language files

---

Data Format

Player Data (JSON)

Player bank data is stored at data/players/<uuid>.json (or data/worlds/<group>/players/<uuid>.json for world banking):

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "Steve",
  "unlockedPages": 3,
  "sortMode": "DEFAULT",
  "pages": {
    "0": [
      { "itemId": "Sword_Iron", "amount": 1, "slot": 0 },
      { "itemId": "Ore_Gold", "amount": 64, "slot": 1 }
    ],
    "1": [],
    "2": []
  }
}

Transaction Database (SQLite)

Transactions are stored in transactions.db with the following schema:

Column	Type	Description
id	INTEGER (PK)	Auto-increment ID
uuid	TEXT	Player UUID
username	TEXT	Player username at time of transaction
action	TEXT	DEPOSIT or WITHDRAW
item_id	TEXT	Item ID
amount	INTEGER	Quantity
timestamp	INTEGER	Unix timestamp (milliseconds)