Configuration

Bank Configuration

The bank configuration is stored in config.json inside the plugin’s data folder. On first launch, if no config file exists, the default is extracted from the plugin JAR.

Config Fields

`defaultPages`

Type	Default	Min
Integer	`1`	`1`

Number of bank pages each player starts with. New players automatically receive this many pages when their bank is first created.

`maxPages`

Type	Default	Min
Integer	`5`	Must be >= `defaultPages`

Maximum number of bank pages a player can unlock. Once a player reaches this limit, further upgrades are denied.

`slotsPerPage`

Type	Default	Min
Integer	`45`	`1`

Number of item slots per bank page. This determines the capacity of each SimpleItemContainer created for the bank pages.

`upgrade`

Type	Default
Object	See below

Configuration for the page upgrade system.

{
  "upgrade": {
    "enabled": true,
    "defaultCosts": [0, 250, 500, 1000, 2500],
    "defaultCurrencyName": "Gold",
    "providerCosts": {
      "Ecotale": [0, 250, 500, 1000, 2500],
      "EconomySystem": [0, 100, 200, 500, 1000]
    },
    "providerDisplayNames": {
      "Ecotale": "Ecotale Coins",
      "EconomySystem": "Gems"
    }
  }
}

enabled — Whether players can purchase page upgrades. Default: true.
defaultCosts — Fallback cost array used when no provider-specific costs are defined. Each array index corresponds to the page number (index 0 = cost for page 1, index 1 = cost for page 2, etc.). Pages beyond the array length are not buyable by players (only grantable via admin).
defaultCurrencyName — Display name for the default/fallback currency. Default: "Gold". Shown in upgrade cost labels when no provider-specific display name is configured.
providerCosts — A map of economy provider name to cost array. Provider-specific costs override defaultCosts for that provider. Pages beyond the array length are not buyable.
providerDisplayNames — A map of economy provider name to a custom display name. Used in the UI to show a human-readable name (e.g., "Ecotale" displays as "Ecotale Coins").

`permissions`

Type	Default
Object	See below

Feature-level permission gating and rank-based page limits using LuckPerms permissions.

{
  "permissions": {
    "upgrade": { "permission": "", "lockedMessage": "Requires VIP rank to upgrade!" },
    "transfer": { "permission": "", "lockedMessage": "" },
    "withdraw": { "permission": "", "lockedMessage": "" },
    "deposit": { "permission": "", "lockedMessage": "" },
    "rankPages": {
      "bank.pages.3": 3,
      "bank.pages.5": 5,
      "bank.pages.7": 7,
      "bank.pages.10": 10
    }
  }
}

upgrade, transfer, withdraw, deposit — Each feature can be gated behind a permission string. If empty (""), every player can use the feature. If set, players without the permission see the lockedMessage.
rankPages — A map of permission string to max buyable page count. The player gets the highest matching value across all their permissions. Falls back to defaultPages (no upgrades) if no permission matches. Capped at the global maxPages value.

`coinProviders`

Type	Default
Object	`{}` (empty)

Defines which in-game coin items map to currency values for the coin deposit feature. When a player drags matching coin items into the bank, they are automatically converted to currency.

{
  "coinProviders": {
    "EcotaleCoins": {
      "Copper_Coin": 1,
      "Silver_Coin": 10,
      "Gold_Coin": 100
    }
  }
}

The outer key (EcotaleCoins) is the economy provider name (auto-detected via VaultUnlocked).
The inner keys are item IDs, and the values are the currency amount per coin item.
Ecotale coin types are auto-detected via reflection on the CoinType enum if the Ecotale plugin is present.

:::warning Legacy: coinItems The flat coinItems map (without provider grouping) is still supported for backward compatibility. Coins defined in coinItems are assigned to the "default" provider internally. New setups should use coinProviders for per-provider grouping. :::

`shopInfo`

Type	Default
Object	See below

Configuration for the “Want more pages?” info button shown in the page overview when a player has reached their buyable page limit.

{
  "shopInfo": {
    "enabled": false,
    "buttonText": "Want more pages?",
    "chatMessage": "Visit our shop for more bank pages!",
    "link": "https://your-server-shop.com/bank"
  }
}

enabled — Whether the shop info button is shown. Default: false.
buttonText — The label on the info button in the page overview.
chatMessage — The message sent to the player’s chat when they click the button.
link — A clickable URL included in the chat message. If empty, no link is added.

`worldBanking`

Type	Default
Object	See below

Enables separate bank inventories per world group. Worlds not assigned to any group share the global bank.

{
  "worldBanking": {
    "enabled": false,
    "separateWorlds": {
      "pvp": ["arena", "battleground"],
      "creative": ["creative_world", "build_zone"]
    }
  }
}

enabled — Whether world banking is active. Default: false. When disabled, all worlds share the same bank.
separateWorlds — A map of group name to a list of world name patterns. Pattern matching uses case-insensitive contains — a pattern "arena" matches a world named "PvP_Arena_Kx8hs9d". This accommodates dynamic world name suffixes (UUIDs, hashes).
Data for separate world groups is stored in data/worlds/<groupName>/players/<uuid>.json.

`restrictionMode`

Type	Default	Options
String	`"blacklist"`	`"blacklist"`, `"whitelist"`

Controls how the restrictedItems list is interpreted:

blacklist — Items matching the list are blocked from being stored in the bank. Everything else is allowed.
whitelist — Only items matching the list are allowed. Everything else is blocked.

Restrictions are enforced server-side via DelegateItemContainer slot validation.

`restrictedItems`

Type	Default
String Array	`[]` (empty)

List of item ID patterns for the restriction system. Supports wildcard matching:

Exact match: "Quest_Item_Key" — blocks/allows only this specific item
Wildcard: "Quest_Item_*" — matches all items starting with Quest_Item_

Example — blacklist quest items and soulbound gear:

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

Example — whitelist only crafting materials:

{
  "restrictionMode": "whitelist",
  "restrictedItems": [
    "Ingot_*",
    "Ore_*",
    "Wood_*",
    "Gem_*"
  ]
}

`historyMaxEntries`

Type	Default	Min
Integer	`100`	`0`

Maximum number of transaction log entries stored per player in the SQLite database. Older entries are pruned when this limit is exceeded.

Set to 0 to disable history tracking.

Full Example

{
  "defaultPages": 1,
  "maxPages": 10,
  "slotsPerPage": 45,
  "upgrade": {
    "enabled": true,
    "defaultCosts": [0, 250, 500, 1000, 2500],
    "defaultCurrencyName": "Gold",
    "providerCosts": {
      "Ecotale": [0, 250, 500, 1000, 2500],
      "EconomySystem": [0, 100, 200, 500, 1000]
    },
    "providerDisplayNames": {
      "Ecotale": "Ecotale Coins",
      "EconomySystem": "Gems"
    }
  },
  "permissions": {
    "upgrade": { "permission": "", "lockedMessage": "Requires VIP rank to upgrade!" },
    "transfer": { "permission": "", "lockedMessage": "" },
    "withdraw": { "permission": "", "lockedMessage": "" },
    "deposit": { "permission": "", "lockedMessage": "" },
    "rankPages": {
      "bank.pages.3": 3,
      "bank.pages.5": 5,
      "bank.pages.7": 7,
      "bank.pages.10": 10
    }
  },
  "coinProviders": {
    "Ecotale": {
      "Copper_Coin": 1,
      "Silver_Coin": 10,
      "Gold_Coin": 100
    },
    "CustomMod": {
      "CustomToken": 500,
      "PremiumGem": 2500
    }
  },
  "shopInfo": {
    "enabled": true,
    "buttonText": "Want more pages?",
    "chatMessage": "Visit our shop for more bank pages!",
    "link": "https://your-server-shop.com/bank"
  },
  "worldBanking": {
    "enabled": false,
    "separateWorlds": {
      "pvp": ["arena", "battleground"],
      "creative": ["creative_world"]
    }
  },
  "restrictionMode": "blacklist",
  "restrictedItems": [
    "Quest_Item_*",
    "Soulbound_*",
    "Admin_Tool_*"
  ],
  "historyMaxEntries": 100
}

Validation

The config is validated on load. Invalid values are corrected automatically:

Field	Correction
`defaultPages < 1`	Set to `1`
`maxPages < 1`	Set to `5`
`maxPages < defaultPages`	Set to `defaultPages`
`slotsPerPage < 1`	Set to `45`
`pageCosts` is null	Set to `[0, 250, 500, 1000, 2500]`
`currency` is null/empty	Set to `"gold"`
`upgrade` is null	Set to default `UpgradeConfig`
`upgrade.defaultCosts` is null	Set to `[0, 250, 500, 1000, 2500]`
`upgrade.defaultCurrencyName` is null	Set to `"Gold"`
`upgrade.providerCosts` is null	Set to `{}`
`upgrade.providerDisplayNames` is null	Set to `{}`
`permissions` is null	Set to default `FeaturePermissions`
`coinProviders` is null	Set to `{}`
`coinItems` is null	Set to `{}`
`shopInfo` is null	Set to default `ShopInfoConfig` (disabled)
`worldBanking` is null	Set to default `WorldBankingConfig` (disabled)
`restrictionMode` is null	Set to `"blacklist"`
`restrictedItems` is null	Set to `[]`
`historyMaxEntries < 0`	Set to `100`

Hot Reload

The configuration can be reloaded at runtime without a server restart using:

/ksbank reload

This reloads config.json, revalidates all fields, and recompiles the restriction patterns. Requires the bank.admin permission.