BankZZ

Important Beta Dependency Notice

This new beta line of BankZZ now requires CoreZZ.

Older public BankZZ files on CurseForge did not require CoreZZ. That is no longer true for this beta branch.

If you upload or install this beta file, you must install ZZCore.jar first. Without CoreZZ, this BankZZ beta line will not work correctly.

What ZZBank Does

• Gives each player a persistent page-based bank.
• Adds an optional shared bank for each compatible clan or guild.
• Uses dedicated custom UIs instead of plain chat output.
• Lets admins manage player banks and shared banks in-game.
• Supports optional economy-backed page purchases for personal banks and, when organization support exists, for shared banks too.
• Stores audit history for sensitive actions and item movement.

How Personal Banks Work

Players use /bank to open their own storage or /bank <page> to jump directly to a page.

Each page is a real 9x9 bank page with 81 slots, and each account is stored persistently per player. If a page is already being edited by another viewer, ZZBank locks that page to prevent conflicts and data loss.

Admins can open other players' banks with commands or from the admin directory. The player dashboard is built for normal storage use, while admin access is designed for moderation and support workflows.

How Page Purchases Work

ZZBank can use economy-backed purchases to expand pages, but the flow depends on the bank type.

Personal Bank Purchases

If economy support is enabled, players can buy more pages with:

• /bank buy
• /bank buy <pages>
• the Buy +1 button inside the personal bank dashboard

Shared Bank Purchases

If the shared bank is available and the active organization allows it, players can also buy pages for that shared bank with:

• /guildbank buy
• /guildbank buy <pages>

Before charging anything, the mod checks permissions, current limits, configured caps, economy availability, and, for shared banks, whether a valid organization account exists for the purchase flow.

How Shared Clan And Guild Banks Work

Shared banks are optional.

ZZBank first tries to resolve this feature through ZZClan, using ZZCore OrganizationService with the zzclan provider.

If that provider is not available, ZZBank keeps legacy compatibility with HyGuild / GuildPlugin.

When clan or guild support is available:

• /guildbank opens a dedicated shared bank UI
• /guildbank <page> opens a specific shared bank page
• /guildbank npc <player> [page] opens that player's shared bank from NPC or server flows

Each clan or guild gets its own separate account stored by an internal organization identifier, exposed in the current storage model as guildId, so shared storage stays isolated from personal storage and from other organizations.

Shared bank permissions can be resolved in two ways:

• with ZZClan, access can come directly from internal clan permissions such as bank_deposit, bank_withdraw, and manage_bank
• if there is no explicit organization permission override, ZZBank falls back to the configured minimum ranks in guildDepositMinRank and guildWithdrawMinRank
• with HyGuild / GuildPlugin, access follows the detected guild hierarchy and those same minimum-rank config values

If neither ZZClan nor HyGuild / GuildPlugin is available, /guildbank remains disabled and reports that clearly.

How Audit Works

ZZBank includes lightweight audit history for both player banks and shared clan or guild banks.

The audit system records:

• deposits
• withdrawals
• admin opens
• NPC opens
• admin deletions

Audit history is shown in dedicated UIs:

• /bank audit [player] [limit]
• /guildbank audit [player] [limit]

Audit files are stored in:

• audit/players/
• audit/guilds/

Retention is controlled with:

• auditEnabled
• auditMaxEntries

How The Admin UI Works

/bank admin opens the in-game admin panel.

From there, staff can:

• browse known player bank accounts
• open a player bank
• audit a player bank
• open the live config editor
• switch to a shared bank list
• open a shared bank
• audit a shared bank

The shared-bank section uses the same admin workflow style as the player section: each row exposes the same Open and Audit actions.

NPC And Server Usage

If you use HyCitizens, bank commands can be executed from server or console style triggers.

Examples:

• bank {PlayerName}
• bank npc {PlayerName} 2
• guildbank npc {PlayerName} 1

The bankAccessSourceMode config controls whether personal bank access is allowed from:

• PLAYER_ONLY
• NPC_ONLY
• BOTH

Commands

Personal Bank

• /bank
• /bank <page>
• /bank buy [pages]
• /bank menu [player]
• /bank admin
• /bank open <player> [page]
• /bank audit [player] [limit]
• /bank info [player]
• /bank reload
• /bankpages <player> <pages>

Shared Clan / Guild Bank

• /guildbank
• /guildbank <page>
• /guildbank buy [pages]
• /guildbank npc <player> [page]
• /guildbank audit [player] [limit]

Configuration Files

• config.json: real runtime configuration file used by the mod.
• config.example.json: sample documentation file included as a readable template.
• messages.json: editable message catalog if your runtime setup exports it.

Storage Paths

ZZBank stores its runtime data under the shared ZonaZero bank data path.

Main paths:

• accounts/: personal bank accounts
• guild-accounts/: shared clan or guild bank accounts
• audit/players/: player bank audit history
• audit/guilds/: shared bank audit history

Visible Config Example

{
  "version": 17,
  "prefix": "&6[&eZZBank&6] &r",
  "defaultMaxPages": 1,
  "hardMaxPages": 8,
  "guildBankEnabled": true,
  "guildDefaultMaxPages": 1,
  "guildHardMaxPages": 8,
  "guildDepositMinRank": "recruit",
  "guildWithdrawMinRank": "leader",
  "pageSize": 81,
  "saveOnEveryChange": true,
  "notifyTargetOnAdminAccess": true,
  "allowConsoleCommands": true,
  "auditEnabled": true,
  "auditMaxEntries": 200,
  "itemTransferMode": "ONE_CLICK",
  "bankAccessSourceMode": "BOTH",
  "economyProviderMode": "ZZ_ECONOMY",
  "pagePurchaseEnabled": false,
  "pagePurchaseCurrencyMode": "AUTO",
  "pagePurchaseBaseCost": 1000.0,
  "pagePurchaseCostMultiplier": 1.0,
  "pagePermissionScanLimit": 128,
  "purchasePermissionScanLimit": 128,
  "updateCheckEnabled": true,
  "updateCheckMode": "AUTO",
  "updateCheckUrl": "",
  "updateCheckInfoUrl": "",
  "updateCheckIntervalMinutes": 360,
  "updateCheckNotifyAdmins": true,
  "updateCheckLogToConsole": true,
  "grantSingleplayerOwnerAdmin": true,
  "usePermissionNodes": ["bank.use", "bank.admin"],
  "adminPermissionNodes": ["bank.admin"],
  "purchasePermissionNodes": ["bank.buy", "bank.admin"],
  "blockedStorageItemIds": [],
  "purchaseLimitPermissionTemplates": ["bank.buy.max.{pages}"],
  "pagePermissionTemplates": ["bank.pages.{pages}"],
  "adminPlayers": [],
  "adminRanks": [],
  "rankPermissionTemplates": ["rank.{rank}", "group.{rank}"]
}

This shows the current default config structure used by the module.

Full Config Reference

Core Settings

• version (number): internal config schema version. Leave it alone unless you are migrating on purpose.
• prefix (text): chat prefix used by ZZBank messages.
• defaultMaxPages (number): default personal bank pages. 0 means none. -1 means unlimited.
• hardMaxPages (number): hard personal page cap. -1 removes the cap.
• pageSize (number): slots per page. ZZBank normalizes this to a valid multiple of 9 between 9 and 81.
• saveOnEveryChange (true/false): if true, ZZBank writes changes after each inventory edit.
• notifyTargetOnAdminAccess (true/false): if true, a player is notified when staff opens that player's bank.
• allowConsoleCommands (true/false): if true, console and server-triggered command flows are allowed.
• itemTransferMode (text): item handling behavior in the UI. Common values are ONE_CLICK and PICKUP_DROP.
• bankAccessSourceMode (text): controls where personal bank access is allowed from. Supported values are PLAYER_ONLY, NPC_ONLY, and BOTH.
• grantSingleplayerOwnerAdmin (true/false): convenience admin behavior for singleplayer-style ownership setups.

Shared Bank Settings

• guildBankEnabled (true/false): enables or disables the shared clan or guild bank feature.
• guildDefaultMaxPages (number): starting page count for each shared bank. 0 means none. -1 means unlimited.
• guildHardMaxPages (number): hard cap for shared bank pages. -1 removes the cap.
• guildDepositMinRank (text): minimum rank allowed to deposit when no explicit organization permission override exists. Common values: recruit, member, officer, leader.
• guildWithdrawMinRank (text): minimum rank allowed to withdraw when no explicit organization permission override exists.

Audit Settings

• auditEnabled (true/false): enables or disables audit logging.
• auditMaxEntries (number): maximum audit entries kept per history file.

Economy And Page Purchase Settings

• economyProviderMode (text): selects the economy bridge. Runtime values are normalized by the mod according to the current branch.
• pagePurchaseEnabled (true/false): enables page purchases.
• pagePurchaseCurrencyMode (text): chooses which currency source is used for purchases.
• pagePurchaseBaseCost (number): base price of the first purchased page.
• pagePurchaseCostMultiplier (number): scaling multiplier for later purchased pages. 1.0 means flat pricing.
• pagePermissionScanLimit (number): how far ZZBank scans permission nodes like bank.pages.<n>.
• purchasePermissionScanLimit (number): how far ZZBank scans purchase limit nodes like bank.buy.max.<n>.

Update Checker Settings

• updateCheckEnabled (true/false): enables periodic update checks.
• updateCheckMode (text): tells ZZBank how to interpret the update response.
• updateCheckUrl (text): URL used to fetch the latest version.
• updateCheckInfoUrl (text): URL shown to admins as the info or download page.
• updateCheckIntervalMinutes (number): minutes between update checks. ZZBank normalizes this to at least 15.
• updateCheckNotifyAdmins (true/false): if true, online admins receive update notices.
• updateCheckLogToConsole (true/false): if true, update notices are also written to the server log.

Permission And Admin Lists

• usePermissionNodes (list): any matching node allows normal bank use.
• adminPermissionNodes (list): any matching node grants admin access.
• purchasePermissionNodes (list): any matching node allows page purchases.
• purchaseLimitPermissionTemplates (list): templates used to read purchase caps. {pages} is replaced with numbers.
• pagePermissionTemplates (list): templates used to read personal page counts. {pages} is replaced with numbers.
• blockedStorageItemIds (list): item ids that should not be stored in ZZBank.
• adminPlayers (list): exact player names that should always count as admins.
• adminRanks (list): rank names that should count as admins.
• rankPermissionTemplates (list): templates used to test rank-based permissions with {rank} replacement.

Installation

1. Copy ZZCore.jar into the server mods folder first.
2. Copy ZZBank.jar into the same server mods folder after that.
3. If you want clan-based shared banks, also add ZZClan.jar.
4. If you do not use ZZClan, you can keep legacy compatibility with HyGuild / GuildPlugin.
5. Start Hytale.
6. Configure permissions, economy, and optional clan or guild support.

License

All Rights Reserved.

Redistribution, reposting, resale edits, or reuploading forks is not allowed without written permission from the author.