Physical Currency

What is PhysicalCurrency?

PhysicalCurrency replaces invisible account balances with real coin items that players can carry, trade, deposit and spend.

Players keep their money in two places:

• Coins carried in their inventory
• Coins stored safely with a banker

Both are combined into one balance for Vault-compatible plugins. This means shops, rewards and other economy features can continue using Vault while your players interact with actual currency items.

The plugin was made for servers that want a more immersive economy without requiring a database or a complicated setup.


Core Features

• Physical Copper, Silver and Gold Coin items
• Full Vault economy provider
• Combined inventory and bank balance
• Persistent banker NPCs
• Deposit and withdrawal menus
• Automatic change when spending larger coins
• Online and offline player support
• Optional MythicMobs coin items and banker models
• Vanilla item and NPC fallbacks
• Configurable denominations, names, materials and lore
• Essentials-compatible money and economy commands
• Configurable command interception

Physical Coin Economy

By default, PhysicalCurrency uses the following exchange rate:

• 10 Copper Coins = 1 Silver Coin
• 10 Silver Coins = 1 Gold Coin

Every denomination and coin value can be changed in the configuration.

When a player spends part of a larger coin, the plugin automatically returns the correct change. For example, spending 35 Copper while carrying a Gold Coin will return the remaining value in Silver and Copper Coins.

Vault balances always use whole base units. Decimal transactions are rejected so players cannot gain invisible fractions of a coin.


Banker NPCs

Bankers give players a safe place to store their coins.

Right-clicking a banker opens a simple menu where players can:

• Deposit a selected coin denomination
• Withdraw a selected coin denomination
• Deposit every recognised coin in their inventory
• Withdraw as much of their stored balance as their inventory can hold

Bankers are persistent and return after server restarts or chunk reloads.

By default, bankers use a stationary Wandering Trader. Servers with MythicMobs can use a custom MythicMob instead.


Vault Integration

PhysicalCurrency registers itself as a Vault economy provider.

For online players, their Vault balance is calculated from:

When another plugin deposits money into an online player's account, PhysicalCurrency gives them physical coins. Coins that do not fit in their inventory are placed into safekeeping.

When money is withdrawn, carried coins are used first. The remaining amount is taken from safekeeping.

Offline transactions are stored safely until the player returns because an offline inventory cannot be edited reliably.

The command below can be used to check which economy provider Vault is currently using:


MythicMobs Support

MythicMobs is completely optional.

When enabled, PhysicalCurrency can use custom MythicMobs item templates for its coins and a MythicMob as the banker NPC.

The default MythicMobs item IDs are:

When a configured MythicMobs item cannot be found, the plugin automatically uses the configured vanilla fallback item instead.

Existing recognised coin items are tagged by PhysicalCurrency for faster and more reliable detection in the future.


Player Commands

Command aliases:


Banker Commands

Command descriptions:

• create – Creates a banker at your current location
• move – Moves an existing banker to your current location
• delete – Deletes a banker and its loaded entities
• open – Opens a banker menu directly for testing
• list – Shows all saved bankers and their locations
• cleanup – Removes duplicate and orphaned banker entities

Economy Administration

Aliases:

Supported selectors:

• @a or * – Every online player
• @p – Nearest player
• @r – Random online player
• @s – The executing player

Amounts can be entered in several formats:

The take command never creates a negative balance.


Administration Commands

• /coins reload – Reloads the configuration, coin definitions and Vault registration
• /coins vault – Displays the current Vault provider and balance diagnostics

Permissions

• physicalcurrency.command.coins – Use /coins and view your own balance
• physicalcurrency.command.money – Use /money and view your own balance
• physicalcurrency.balance.others – View another player's balance
• physicalcurrency.banker.use – Use banker NPC menus
• physicalcurrency.diagnostics – Use /coins vault
• physicalcurrency.admin – Manage bankers and reload the plugin
• physicalcurrency.admin.eco – Use the economy administration commands

The plugin also accepts essentials.eco for compatibility with existing staff permission setups.

Player commands and banker usage are available to everyone by default. Administrative permissions default to operators.


Configuration

PhysicalCurrency is designed to work with its default configuration, while still allowing servers to customise the important parts.

Configurable options include:

• Coin values
• Coin materials
• Coin display names
• Coin lore
• MythicMobs item IDs
• Banker name and appearance
• Banker tracking behaviour
• Vault currency names
• Menu titles and messages
• Command interception
• Economy reset balance

All public messages support standard & colour codes.

The default configuration uses neutral Banker wording. A separate Royal Treasury preset is included for servers that prefer a more fantasy-themed presentation.


Command Conflicts

Commands such as /money and /eco are commonly registered by EssentialsX and other economy plugins.

PhysicalCurrency can intercept these commands so they always use the physical currency economy. This can be enabled or disabled separately for each command in the configuration.

When interception is disabled, normal Bukkit command priority determines which plugin receives the command.

PhysicalCurrency remains accessible through its namespaced commands:


Data Storage

PhysicalCurrency stores its data locally inside the plugin folder.

• config.yml – General configuration, coins and messages
• banks.yml – Safeguarded player balances
• bankers.yml – Banker NPC locations and settings

No external database is required.


Installation

1. Install Vault
2. Optionally install MythicMobs
3. Place PhysicalCurrency in your server's plugins folder
4. Start the server
5. Run /coins vault to confirm that PhysicalCurrency is active
6. Create your first banker with /coins banker create main

Avoid running multiple economy providers unless you know which provider your Vault-dependent plugins will select.


Requirements

Required:

• Spigot or Paper 26.1.2 or newer within the 26.x line
• Vault

Optional:

• MythicMobs for custom coin items and banker models

Why PhysicalCurrency?

• Makes currency visible and tradeable
• Keeps compatibility with Vault-based systems
• Does not force players to carry every coin they own
• Supports both simple and custom-modelled setups
• Requires no database
• Provides straightforward in-game administration
• Works well for RPG, survival and economy-focused servers

Suitable For

• RPG servers
• Survival servers
• Town and nation servers
• Roleplay servers
• Economy servers
• Servers using custom shops and rewards

Support and Feedback

When reporting a problem, please include:

• Your exact server software and version
• Your Java version
• Your PhysicalCurrency and Vault versions
• Your MythicMobs version, when used
• The output of /coins vault
• The complete console error
• Steps that reproduce the problem

Suggestions and feedback are welcome through the resource discussion page.