CoinForge

CoinForge is a flexible multi-currency economy plugin for Minecraft servers, designed to provide a complete and scalable economy system for survival, RPG, and community-focused servers.

Create custom currencies, configure exchange rates, add taxes and interest systems, manage player balances through a clean GUI, and integrate other plugins through a simple developer API. CoinForge can work alongside your existing Vault economy or completely replace it.

⚡ Recommended Hosting

---

⚙️ Dependencies

REQUIRED

Vault Provides economy integration with Minecraft server plugins.

https://www.spigotmc.org/resources/vault.34315/

Economy Plugin (Vault-compatible) Required when using CoinForge as a Vault economy provider. Compatible options include:

• EssentialsX Economy
• Any other Vault-compatible economy plugin

CoinForge can also operate with its own internal currency system without registering a currency with Vault.

---

OPTIONAL (Soft Dependency)

PlaceholderAPI Provides expanded placeholder support for balances and formatted currencies.

https://www.spigotmc.org/resources/placeholderapi.6245/

---

✨ Features

• Fully configurable multi-currency economy
• Unlimited custom currencies
• Vault economy integration
• Ability to override existing Vault economy providers
• Internal currency mode
• Configurable currency symbols and decimal precision
• Custom Material icons for currencies
• Currency exchange system
• Player-to-player payments
• Configurable payment cooldowns
• Economy taxation system
• Interest and passive income system
• Chest-based wallet GUI
• Currency leaderboards
• Persistent per-currency data storage
• Transaction logging
• PlaceholderAPI support
• Developer API for external integrations
• Reloadable configuration
• Lightweight and optimized architecture

---

💰 Multi-Currency System

CoinForge allows servers to run multiple currencies simultaneously.

Create currencies such as:

• Coins
• Gems
• Tokens
• Credits
• Points
• Any custom currency you define

Each currency can have its own:

• Display name
• Symbol
• Decimal precision
• Starting balance
• GUI icon

There is no fixed limit on how many custom currencies can be configured.

---

💳 Vault Economy Integration

CoinForge can either replace your existing Vault economy provider or operate independently.

When registered with Vault using HIGHEST priority, CoinForge becomes the primary economy provider:

vault-currency:
  enabled: true
  register-with-vault: true
  priority: HIGHEST

Use NORMAL priority if CoinForge should act as a fallback provider.

CoinForge can also operate without registering with Vault:

vault-currency:
  enabled: true
  register-with-vault: false

Or completely disable the built-in Vault currency:

vault-currency:
  enabled: false

This allows CoinForge to fit into different server economy setups without forcing a specific architecture.

---

🔄 Currency Exchange

Players can exchange currencies using configurable conversion rates.

exchange:
  enabled: true
  rates:
    gems-to-coins: 10
    tokens-to-gems: 0.5

Players can exchange currencies with:

/coins exchange <from> <to> <amount>

Exchange transactions can also be affected by the configured exchange tax.

---

💸 Player Payments

Players can transfer currencies directly between each other:

/coins pay <player> <currency> <amount>

The payment system supports:

• Configurable payment cooldowns
• Transaction logging
• Payment taxation
• Permission-based tax bypass

This makes CoinForge suitable for player-driven economies where currencies are actively exchanged between players.

---

🧾 Tax System

CoinForge includes a configurable economy-sink tax system for payments and currency exchanges.

tax:
  pay-percent: 0
  exchange-percent: 0

When taxation is enabled:

• The sender pays the full transaction amount
• The recipient receives the amount after tax
• The tax difference is permanently removed from the economy
• Players with coinforge.tax.bypass can bypass configured taxes

This can be used to help control inflation on economy-heavy servers.

---

📈 Interest System

CoinForge can periodically reward eligible accounts with interest based on their current balance.

interest:
  enabled: false
  interval-minutes: 60
  rate-percent: 1.0
  minimum-balance: 1.0
  only-online-players: false
  currencies: [coins]

The system supports configuration for:

• Payment intervals
• Interest percentage
• Minimum required balance
• Online-only payouts
• Selected currencies

The interest system automatically restarts when /coins reload is executed.

---

🖥️ Chest GUI Wallet

CoinForge provides a clean Bukkit inventory-based wallet interface.

/coins gui

Alias:

/coins wallet

The wallet provides:

• One icon for each configured currency
• Current balances displayed in item lore
• Custom Material icons
• Direct access to currency leaderboards

The GUI uses standard Bukkit inventories and does not require a Paper-specific GUI framework.

---

🏆 Currency Leaderboards

Players can view the richest accounts for any configured currency:

/coins top <currency>

The leaderboard GUI includes:

• Up to 28 ranked players
• Player heads
• Top 3 highlighting
• Refresh button
• Back button
• Balance-based ranking

When executed from the console, CoinForge automatically falls back to a chat-based leaderboard.

---

⚙️ Configuration

CoinForge is fully configurable through config.yml.

vault-currency:
  enabled: true
  register-with-vault: true
  priority: HIGHEST
  id: coins
  display-name: "Coins"
  symbol: "$"
  decimal-places: 2
  starting-balance: 0
  icon: GOLD_INGOT

custom-currencies:
  gems:
    display-name: "Gems"
    symbol: "✦"
    decimal-places: 0
    starting-balance: 0
    icon: EMERALD
  tokens:
    display-name: "Tokens"
    symbol: "⛃ "
    decimal-places: 0
    starting-balance: 100
    icon: SUNFLOWER

exchange:
  enabled: true
  rates:
    gems-to-coins: 10
    tokens-to-gems: 0.5

pay-cooldown-seconds: 3
log-transactions: true

tax:
  pay-percent: 0
  exchange-percent: 0

interest:
  enabled: false
  interval-minutes: 60
  rate-percent: 1.0
  minimum-balance: 1.0
  only-online-players: false
  currencies: [coins]

The icon option controls the Material displayed for a currency in the wallet and leaderboard interfaces.

After changing the configuration, use:

/coins reload

to apply the changes.

---

📋 Commands

Command	Description
/coins	Show all of your balances
/coins gui	Open the wallet GUI
/coins wallet	Open the wallet GUI
/coins <currency>	Show one currency balance
/coins pay <player> <currency> <amount>	Pay another player
/coins top <currency>	Open the currency leaderboard
/coins exchange <from> <to> <amount>	Exchange currencies
/coins admin give <player> <currency> [amount]	Give currency
/coins admin take <player> <currency> [amount]	Remove currency
/coins admin set <player> <currency> [amount]	Set a balance
/coins admin reset <player> <currency>	Reset a balance
/coins reload	Reload configuration

Aliases

/coin
/wallet
/balance
/bal

---

🔐 Permissions

Permission	Default	Description
coinforge.use	true	Check your own balances
coinforge.pay	true	Pay other players
coinforge.top	true	View balance leaderboards
coinforge.exchange	true	Exchange currencies
coinforge.admin	op	Manage balances and configuration
coinforge.tax.bypass	false	Bypass payment and exchange taxes

---

💾 Data Storage

CoinForge stores each currency in its own data file:

plugins/CoinForge/data/

Example:

data/coins.yml
data/gems.yml
data/tokens.yml

Each currency file contains a format-version: '1.0' marker to support future data migrations.

Transaction Logging

When enabled:

log-transactions: true

CoinForge stores transaction history in:

plugins/CoinForge/transactions.log

Logged actions include:

• Currency transfers
• Currency exchanges
• Interest payouts

---

🔌 Developer API

CoinForge includes a lightweight API designed for integrations with other plugins and systems such as ShopForge.

CoinForgeAPI api = CoinForgeAPI.get();

if (api != null && api.has(player, "coins", 100)) {
    api.withdraw(player, "coins", 100);
}

Available API methods include:

• currencyExists
• getCurrencyIds
• getDisplayName
• getSymbol
• format
• getBalance
• has
• deposit
• withdraw

The API returns null when CoinForge is not loaded, allowing integrations to fail safely.

---

🔗 PlaceholderAPI

CoinForge supports PlaceholderAPI when installed.

Balance

%coinforge_balance_<currency>%

Returns the raw numerical balance.

Formatted Balance

%coinforge_formatted_<currency>%

Example:

$1,250.00

Placeholders can be used with:

• Scoreboards
• Holograms
• Menus
• Chat systems
• Other PlaceholderAPI-compatible plugins

---

🎮 Gameplay Experience

CoinForge is designed to make server economies easy to understand while providing enough flexibility for advanced economy systems.

The system focuses on:

• Simple player-facing commands
• Fast GUI-based balance management
• Clear currency presentation
• Flexible economy configuration
• Reliable transactions
• Easy integration with other server systems

Whether a server needs one primary currency or a complete multi-currency economy, CoinForge provides the tools to build around that system.

---

⚙️ System Design

CoinForge is built around a modular economy architecture designed for scalability and external integrations.

Core design goals include:

• Persistent and isolated currency storage
• Flexible Vault integration
• Safe transaction handling
• Simple configuration
• Developer-friendly API
• Support for future economy features
• Lightweight server-side operation

The system is designed to integrate naturally with existing Minecraft server ecosystems without forcing server owners to replace their entire economy setup.

---

🚀 Planned Features

CoinForge is actively maintained and can be expanded with future economy functionality.

Potential future updates may include:

• Additional economy management tools
• Expanded GUI customization
• More advanced transaction management
• Additional economy mechanics
• Expanded API functionality
• Further PlaceholderAPI integrations
• Performance and storage optimizations

---

🔗 Links

Official Website: https://plugglab.pl/wip

Documentation: https://plugglab.pl/wip