# 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 [![SparkedHost](https://i.imgur.com/22G8vsG.gif)](https://billing.sparkedhost.com/aff.php?aff=3360) --- ## ⚙️ 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: ```yaml 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: ```yaml vault-currency: enabled: true register-with-vault: false ``` Or completely disable the built-in Vault currency: ```yaml 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. ```yaml exchange: enabled: true rates: gems-to-coins: 10 tokens-to-gems: 0.5 ``` Players can exchange currencies with: ```text /coins exchange ``` Exchange transactions can also be affected by the configured exchange tax. --- ## 💸 Player Payments Players can transfer currencies directly between each other: ```text /coins pay ``` 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. ```yaml 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. ```yaml 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. ```text /coins gui ``` Alias: ```text /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: ```text /coins top ``` 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`. ```yaml 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: ```text /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 ` | Show one currency balance | | `/coins pay ` | Pay another player | | `/coins top ` | Open the currency leaderboard | | `/coins exchange ` | Exchange currencies | | `/coins admin give [amount]` | Give currency | | `/coins admin take [amount]` | Remove currency | | `/coins admin set [amount]` | Set a balance | | `/coins admin reset ` | Reset a balance | | `/coins reload` | Reload configuration | ### Aliases ```text /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: ```text plugins/CoinForge/data/ ``` Example: ```text 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: ```yaml log-transactions: true ``` CoinForge stores transaction history in: ```text 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. ```java 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 ```text %coinforge_balance_% ``` Returns the raw numerical balance. ### Formatted Balance ```text %coinforge_formatted_% ``` Example: ```text $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

PluggLAB