Skip to main content

FAQ & Troubleshooting

General​

How do players open the bank?​

Players can open the bank in two ways:

  1. NPC Interaction: Walk up to a bank NPC and press F to interact
  2. Command: Use /ksbank (works if the config allows command-based opening)

The recommended setup is using a bank NPC via the KyuubiSoft Citizens system.

How many pages can a player have?​

This is configured via defaultPages (starting pages) and maxPages (maximum) in config.json. Players start with defaultPages and can unlock more via /ksbank upgrade (costs currency) or /ksbank adminupgrade (free, admin only).

Can I change the number of slots per page?​

Yes — set slotsPerPage in config.json. Default is 45. Changes apply to all pages. Note: changing this on a live server may cause items to shift if reducing the slot count.

Are items safe if the server crashes?​

Yes. The bank uses an auto-save system with a configurable interval (autoSaveIntervalSeconds). Additionally, player data is saved on disconnect and server shutdown. The dirty-flag system ensures only modified data is written.

Can players trade bank items?​

Not directly from the bank. Players need to withdraw items to their inventory first, then trade normally. The bank uses DelegateItemContainer with server-side validation — items can only enter/leave through the bank UI.

Economy & Upgrades​

Which economy plugins are supported?​

The bank integrates with VaultUnlocked — any economy provider registered through VaultUnlocked works automatically. This includes:

  • EcotaleCoins
  • Custom economy plugins
  • Multiple providers simultaneously (multi-currency)

The integration uses reflection, so VaultUnlocked is optional — the bank works without it (upgrades are disabled).

How do coin deposits work?​

If configured, players can drag coin items (e.g., Coin_Gold) into the bank. The bank detects them and converts them to the matching economy currency automatically. Configure coins in the coins section of config.json or via the admin panel (Coins tab).

Can I set different upgrade costs per page?​

Yes — use the upgrade.defaultCosts array in config.json:

"upgrade": {
  "defaultCosts": [0, 100, 250, 500, 1000]
}

Index 0 = cost for page 1 (usually 0), index 1 = cost for page 2, etc. If a player unlocks a page beyond the array length, the last value is used.

Can different ranks have different page limits?​

Yes — use LuckPerms permissions. Configure rank-based limits in the permissions.rankPages section:

"permissions": {
  "rankPages": {
    "bank.pages.7": 7,
    "bank.pages.10": 10
  }
}

The bank checks LuckPerms permissions and applies the highest matching value, capped at maxPages.

How do I add a new economy provider?​

Use the admin panel (/ksbank admin → Economy tab) or add it to config.json:

"upgrade": {
  "providerCosts": {
    "MyProvider": [0, 50, 100, 200]
  },
  "providerDisplayNames": {
    "MyProvider": "Gold Coins"
  }
}

Items & Restrictions​

How do I prevent certain items from being stored?​

Use the restriction system. Two modes available:

  • Blacklist (default): Block specific items — everything else allowed
  • Whitelist: Only allow specific items — everything else blocked

Configure via admin panel (Restrict tab) or in config.json:

{
  "restrictionMode": "blacklist",
  "restrictedItems": ["Lootbag_*", "Quest_Item_*", "Pet_Egg_*"]
}

Wildcard patterns (*) are supported.

Why can't I store a specific item?​

Check these causes:

  1. Restriction list: The item might be blacklisted (or not whitelisted). Check /ksbank admin → Restrict tab
  2. Slot validation: The DelegateItemContainer enforces restrictions server-side — even drag-and-drop is validated
  3. Item type: Some special engine items may not be storable

Can I restrict items per page?​

Currently restrictions are global (all pages share the same rules). Per-page restrictions are not yet implemented.

World Banking​

What is World Banking?​

World Banking creates separate bank inventories per world group. A player's bank in "survival" worlds is completely separate from their bank in "creative" worlds.

How do I set up world groups?​

In config.json under worldGroups:

"worldGroups": {
  "survival": ["flat_world", "adventure"],
  "creative": ["creative_*"]
}

Pattern matching is case-insensitive and uses contains logic. Worlds not assigned to any group share the global bank.

What happens if a player switches worlds?​

If the new world belongs to a different world group, the bank UI automatically shows that group's inventory. The player's items in the previous group are untouched.

NPC Integration​

How do I set up a bank NPC?​

  1. Create a citizen in citizens.json (KyuubiSoft Core):
{
  "id": "Banker",
  "displayName": "Banker",
  "position": [100, 95, 100],
  "npcRoleId": "KS_Citizen_Idle",
  "dialogId": "bank_dialog"
}
  1. The bank plugin automatically registers a page opener for bank NPCs
  2. Players press F on the NPC to open the bank

Can I have multiple bank NPCs?​

Yes — create as many citizen entries as needed. All bank NPCs open the same bank UI for the interacting player.

Admin Panel​

How do I access the admin panel?​

Use /ksbank admin. Requires the bank.admin permission.

What can I do in the admin panel?​

The admin panel has 8 tabs:

TabFeatures
GeneralDefault pages, max pages, slots per page, auto-save interval
EconomyAdd/edit/remove economy providers, display names
RanksConfigure rank-based page limits (LuckPerms)
CoinsAdd/edit/remove coin-to-currency definitions
RestrictBlacklist/whitelist mode, add/remove restricted items
PlayersSearch players, view stats, add/remove pages, inspect banks
HistoryView transaction logs per player with timestamps
WorldsConfigure world groups for separate bank inventories

Can I edit another player's bank?​

Yes — use /ksbank open <player> to open their bank in read/write mode. You can add, remove, and rearrange items.

How do I reset a player's bank?​

Use /ksbank reset <player>. This removes ALL items and resets page count to defaultPages.

danger

Bank resets are irreversible. There is no undo or item recovery.

Troubleshooting​

Bank UI doesn't open​

  • Check if the bank plugin is loaded: look for [KyuubiSoft Bank] in server logs
  • Verify the bank NPC exists and has the correct dialog/page opener
  • Check permissions if using LuckPerms

Items disappear from bank​

  • Check auto-save interval — if the server crashes between saves, recent changes may be lost
  • Verify data/ folder has write permissions
  • Check transaction history (/ksbank log <player>) for withdrawal entries

Economy balance shows 0​

  • Ensure VaultUnlocked is installed and has an active economy provider
  • Check provider name matches exactly (case-sensitive)
  • Verify the economy plugin is loaded before the bank plugin

Drag-and-drop doesn't work​

  • The bank uses native Hytale ItemGrid — ensure no other plugins interfere with inventory containers
  • Try /ksbank reload to refresh the configuration
  • Restart the server if the issue persists

"Maximum pages reached" but player should have more​

  • Check rank-based limits in the admin panel (Ranks tab)
  • Verify the player has the correct LuckPerms permission (bank.rank.<rank>)
  • The effective limit is the HIGHEST matching rank limit or maxPages, whichever is greater

Transaction history is empty​

  • Transactions are stored in transactions.db (SQLite)
  • Verify the file exists and has write permissions
  • History only records actions AFTER the transaction system was enabled

Bank data not loading for offline players​

  • Offline player lookup requires UUID — usernames may not resolve if the player has never joined
  • Use /ksbank open <uuid> with the player's UUID for reliable access