HorizonsEconomy

A full-featured economy plugin for Paper servers with Vault integration, a physical banknote system, bank accounts, and much more. HorizonsEconomy goes beyond a simple balance manager -- it provides a complete economic framework with interest-bearing bank accounts, a death penalty system, physical banknotes, and a configurable tax system for player-to-player payments. Built for performance with multiple storage backends and designed for customization with full message localization.

---

Key Highlights

• Full Vault economy provider -- works seamlessly with any Vault-compatible plugin
• Physical banknote system for tangible in-game currency
• Bank account system with interest and a dedicated GUI
• Death penalty with configurable cash loss
• Multiple storage backends: JSON, SQLite, MySQL (with HikariCP connection pooling)
• Multilingual support (English and German included)
• Deep integration with 8+ custom item plugins for GUI elements

---

Features

Vault Economy Provider

HorizonsEconomy registers as a full Vault economy provider. Once installed, any plugin that uses Vault for economy will automatically work with HorizonsEconomy. This includes shop plugins, auction houses, minigame plugins, crate plugins, and more. Your server's entire economy runs through one unified system.

Configurable Currency

Customize every aspect of how your currency looks and feels:

• Currency name -- set singular and plural forms (e.g., "Dollar" / "Dollars", "Coin" / "Coins")
• Display format -- control how balances are shown to players
• Decimal places -- configure precision (0 for whole numbers, 2 for cents, etc.)
• Number abbreviations -- large balances are displayed with human-readable abbreviations:
  • K for thousands
  • M for millions
  • B for billions
  • T for trillions
• Starting balance -- set how much currency new players receive
• Maximum balance -- enforce a cap to prevent runaway inflation

Pay System

The /pay command allows players to send currency to each other with safety features built in:

• Large payment confirmation -- when a payment exceeds a configurable threshold, the sender is prompted to confirm, preventing accidental overpayments
• Confirmation bypass permission -- trusted players can skip the confirmation step
• Pay toggle -- players can enable or disable incoming payments with /paytoggle, useful for streamers or players who don't want unsolicited transfers
• Tax on payments -- a configurable percentage is deducted from every payment
  • Tax revenue can either be voided (removed from the economy, acting as a money sink) or sent to a specific player (e.g., a server bank account)
  • Tax-exempt permission available for designated players

Physical Banknote System

HorizonsEconomy includes a unique banknote feature that bridges digital balances and physical in-game items:

• Creating banknotes -- use /withdraw <amount> to convert balance into a physical item
• Redeeming banknotes -- right-click a banknote to deposit it back into your balance
• Banknotes are fully functional items that can be traded, stored in chests, dropped, and exchanged
• Each banknote displays its value and is tamper-proof
• Useful for physical shops, trading, events, and adding immersion to your server's economy

Bank Account System

Players have access to a separate bank account, functioning as a savings account, accessible through an intuitive GUI:

• Deposit and withdraw funds between wallet and bank
• Dedicated GUI -- open with /bank for a clean, visual interface
• Separate from main balance -- bank funds are tracked independently
• Bank accounts serve as protected savings that are excluded from the death penalty

Bank Interest System

Encourage saving by rewarding players with interest on their bank balance:

• Configurable interest rate -- set the percentage earned per interval
• Configurable interval -- define how often interest is paid (e.g., every hour, every day)
• Interest cap -- set a maximum interest payout per interval to prevent abuse
• Minimum balance requirement -- only balances above a threshold earn interest
• Interest is calculated and distributed automatically in the background

Death Penalty System

Add economic consequences to death, creating a meaningful survival incentive:

• Percentage-based loss -- players lose a configurable percentage of their wallet balance on death
• Minimum loss -- set a floor for the penalty amount
• Maximum loss -- set a ceiling to prevent devastating losses
• Bank exclusion -- funds stored in the bank account are safe from the death penalty, encouraging players to use the banking system
• Bypass permission -- exempt specific players or ranks from the death penalty

Balance Top Leaderboard

A paginated leaderboard showing the wealthiest players on the server:

• Pagination -- browse through the full ranking with page controls
• Configurable update interval -- the leaderboard refreshes on a schedule to reduce performance impact
• Exclusion permission -- hide staff or specific players from the leaderboard using horizonseco.balancetop.exclude
• Accessible via /balancetop or /baltop

Offline Payment Notifications

When a player receives a payment while offline, they are notified upon their next login. Players always know when their balance has changed, even if they weren't online to see it happen.

Transaction Logging

Every economic transaction is recorded for auditing and dispute resolution:

• File-based logging -- all transactions are written to a log file with timestamps, involved players, amounts, and transaction types
• Console logging -- optionally output transactions to the server console for real-time monitoring
• Covers payments, bank operations, admin commands, banknote creation and redemption, death penalties, and interest payouts

Auto-Save System

Player data is automatically saved in the background on a configurable interval. This ensures data safety without impacting server performance during regular gameplay. The auto-save runs on a separate thread to avoid blocking the main server thread.

---

Commands

Player Commands

Command	Aliases	Description
/balance	/bal, /money	Check your current balance
/balance <player>	/bal <player>	Check another player's balance
/balancetop	/baltop	View the server wealth leaderboard
/pay <player> <amount>		Send currency to another player
/paytoggle		Toggle whether you can receive payments
/withdraw <amount>		Convert balance into a physical banknote item
/bank		Open the bank account GUI

Admin Commands

Command	Description
/economy set <player> <amount>	Set a player's balance to an exact amount
/economy give <player> <amount>	Add currency to a player's balance
/economy take <player> <amount>	Remove currency from a player's balance
/economy reset <player>	Reset a player's balance to the starting balance
/economy reload	Reload the plugin configuration and language files

The /economy command can also be used as /eco.

---

Permissions

Player Permissions

Permission	Description
horizonseco.balance	Check your own balance
horizonseco.balance.others	Check other players' balances
horizonseco.balancetop	View the balance top leaderboard
horizonseco.balancetop.exclude	Exclude yourself from the leaderboard
horizonseco.pay	Send payments to other players
horizonseco.pay.taxexempt	Exempt from the payment tax
horizonseco.pay.confirmbypass	Skip the large payment confirmation prompt
horizonseco.paytoggle	Toggle incoming payments on or off
horizonseco.withdraw	Create physical banknotes
horizonseco.redeem	Redeem (right-click) physical banknotes
horizonseco.bank	Access the bank account GUI
horizonseco.bank.deposit	Deposit funds into the bank
horizonseco.bank.withdraw	Withdraw funds from the bank
horizonseco.deathpenalty.bypass	Bypass the death penalty system

Admin Permissions

Permission	Description
horizonseco.admin.*	Grants access to all admin economy commands

---

Configuration

HorizonsEconomy provides extensive configuration options. Key settings include:

Economy Settings

• Starting balance -- the amount of currency new players receive on first join
• Maximum balance -- the highest balance a player can hold
• Decimal places -- number of decimal places for currency display (0-4)
• Currency name -- singular and plural forms of your currency
• Display format -- how balances are formatted and shown to players

Payment Settings

• Tax rate -- percentage deducted from player-to-player payments
• Tax destination -- choose to void taxed currency or send it to a designated player
• Confirmation threshold -- the payment amount above which confirmation is required
• Pay toggle default -- whether payments are enabled or disabled by default for new players

Banknote Settings

• Minimum withdrawal -- the smallest amount that can be withdrawn as a banknote
• Maximum withdrawal -- the largest amount for a single banknote

Bank Settings

• Interest rate -- percentage earned per interval on bank balances
• Interest interval -- how frequently interest is paid out (in minutes)
• Interest cap -- maximum interest earned per payout
• Minimum balance for interest -- the threshold balance required to earn interest

Death Penalty Settings

• Enabled/disabled -- toggle the entire death penalty system
• Loss percentage -- what fraction of wallet balance is lost on death
• Minimum loss -- floor for the penalty
• Maximum loss -- ceiling for the penalty

Storage Settings

• Storage type -- choose between JSON, SQLite, or MySQL
• MySQL connection details -- host, port, database, username, password
• Auto-save interval -- how often data is saved to disk (in minutes)

Leaderboard Settings

• Update interval -- how often the balance top leaderboard is recalculated
• Entries per page -- how many players are shown per leaderboard page

All configuration files are generated with sensible defaults and include inline comments for every option.

---

Database Support

JSON (Default)

Player data is stored in individual JSON files within the plugin's data folder. Simple and easy to inspect manually. Suitable for small to medium servers.

SQLite

A single-file relational database stored in the plugin's data folder. No external setup required. Better performance than JSON for servers with many players. Recommended for most single-server setups.

MySQL

Full MySQL support with HikariCP connection pooling for optimal performance under load. Recommended for large servers or networks where multiple servers need to share economy data. Configure your connection details in the config file and the plugin handles the rest, including automatic table creation and schema management.

---

Compatibility

Server Requirements

Requirement	Version
Server Software	Paper 1.21 or newer
Java	Java 21 or newer
Vault	Required (provides the economy API bridge)

Supported Custom Item Plugins (GUI)

HorizonsEconomy supports custom items from the following plugins for use in GUI elements such as the bank interface:

Plugin	Support
ItemsAdder	Full support
Oraxen	Full support
Nexo	Full support
HeadDatabase	Full support
MMOItems	Full support
Slimefun	Full support
ExecutableItems	Full support
EcoItems	Full support

Optional Integrations

Plugin	Integration
PlaceholderAPI	Exposes economy placeholders (balance, currency name, rank, etc.) for use in scoreboards, holograms, tab lists, chat formats, and more
bStats	Anonymous usage metrics to support ongoing development

---

Getting Started

Installation

1. Download the latest version of HorizonsEconomy
2. Place the .jar file in your server's plugins folder
3. Ensure you have Paper 1.21+, Java 21, and Vault installed
4. Start or restart your server
5. Configuration and language files are generated automatically on first launch

Quick Setup

1. Set your currency name -- open config.yml and set the currency-name-singular and currency-name-plural fields to your desired currency name
2. Configure the starting balance -- set starting-balance to the amount new players should receive
3. Set up the tax system -- adjust pay-tax-rate and choose whether taxed currency is voided or collected
4. Enable the bank -- ensure the bank system is enabled and configure interest settings to your liking
5. Configure the death penalty -- enable or disable and set the percentage, minimum, and maximum values
6. Choose your storage backend -- select JSON, SQLite, or MySQL based on your server size
7. Reload -- run /eco reload to apply changes without restarting
8. Grant permissions -- give players the appropriate permissions for their rank

Recommended Permission Setup

For a typical server, consider the following permission structure:

Default players:

horizonseco.balance
horizonseco.balancetop
horizonseco.pay
horizonseco.paytoggle
horizonseco.withdraw
horizonseco.redeem
horizonseco.bank
horizonseco.bank.deposit
horizonseco.bank.withdraw

Staff members (in addition to defaults):

horizonseco.balance.others
horizonseco.pay.taxexempt
horizonseco.pay.confirmbypass
horizonseco.deathpenalty.bypass
horizonseco.balancetop.exclude
horizonseco.admin.*

Customizing Messages

All player-facing messages are fully customizable. Language files are located in the plugin's lang folder. HorizonsEconomy ships with complete English and German translations. You can edit existing translations or create your own language file.

---

PlaceholderAPI

HorizonsEconomy provides an extensive set of placeholders (requires PlaceholderAPI):

Player Placeholders

Placeholder	Description
%horizonseconomy_balance%	Player's wallet balance (formatted with currency symbol)
%horizonseconomy_balance_raw%	Player's wallet balance (raw number)
%horizonseconomy_balance_compact%	Player's wallet balance in compact format (e.g., 1.5K)
%horizonseconomy_accepting_payments%	Whether the player accepts payments (true/false)
%horizonseconomy_bank_balance%	Player's bank balance (formatted)
%horizonseconomy_bank_balance_raw%	Player's bank balance (raw number)
%horizonseconomy_bank_balance_compact%	Player's bank balance in compact format
%horizonseconomy_player_total_balance%	Sum of wallet + bank balance (formatted)
%horizonseconomy_player_total_balance_raw%	Sum of wallet + bank balance (raw number)

Server Placeholders

Placeholder	Description
%horizonseconomy_interest_rate%	Current interest rate (e.g., "2.5%")
%horizonseconomy_interest_rate_raw%	Interest rate as raw number
%horizonseconomy_interest_interval%	Interest payout interval in minutes
%horizonseconomy_total_balance%	Total economy balance across all players (formatted)
%horizonseconomy_combined_total_balance%	Total economy balance across all players (raw)
%horizonseconomy_combined_total_balance_formatted%	Total economy balance (formatted)

Balance Top Placeholders

Use <N> as the rank position (e.g., 1 for richest player):

Placeholder	Description
%horizonseconomy_richest_<N>_name%	Name of the Nth richest player
%horizonseconomy_richest_<N>_uuid%	UUID of the Nth richest player
%horizonseconomy_richest_<N>_balance%	Balance of the Nth richest player (raw)
%horizonseconomy_richest_<N>_balance_formatted%	Balance of the Nth richest player (formatted)

---

Frequently Asked Questions

Does this replace Essentials Economy? Yes. HorizonsEconomy is a standalone Vault economy provider. If you are currently using Essentials for economy, you can switch to HorizonsEconomy by removing Essentials' economy component and installing this plugin. All Vault-compatible plugins will automatically use HorizonsEconomy.

Can players dupe banknotes? Banknotes are protected against common duplication methods. Each banknote contains unique metadata that is validated on redemption. However, as with any item-based system, ensure your server has proper anti-dupe protections in place.

Is bank money safe from the death penalty? Yes. The death penalty only affects the player's wallet balance. Funds stored in the bank account are explicitly excluded, which gives players a meaningful reason to use the banking system.

What happens if a player is paid while offline? The payment is processed normally and their balance is updated. When they next log in, they receive a notification informing them of the payment, including who sent it and the amount.

Can I migrate from another economy plugin? HorizonsEconomy provides admin commands to set player balances manually. For large-scale migration, you can use the /eco set command or modify the storage files directly while the server is offline.

Does the interest system work while players are offline? Interest is calculated and distributed at the configured interval for all accounts that meet the minimum balance requirement, regardless of whether the player is online.

What is HikariCP? HikariCP is a high-performance JDBC connection pool library. When using MySQL, HorizonsEconomy uses HikariCP to manage database connections efficiently, reducing overhead and improving performance under load.

---

Support

If you encounter any issues, have feature requests, or need help with configuration:

• Issue Tracker -- report bugs and request features on the project's issue tracker
• Discord -- join our community Discord server for live support and discussion
• Documentation -- check the plugin's wiki for detailed guides and examples

When reporting issues, please include:

• Your Paper server version
• Your Java version
• The HorizonsEconomy version
• Your Vault version
• A list of other economy-related plugins on your server
• Relevant log output or error messages
• Steps to reproduce the issue

---

HorizonsEconomy is built for performance, reliability, and flexibility. It provides a solid economic foundation for any Paper server, from small communities to large networks. Thank you for choosing HorizonsEconomy.