headerimage

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

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

Quick Setup

Set your currency name -- open config.yml and set the currency-name-singular and currency-name-plural fields to your desired currency name
Configure the starting balance -- set starting-balance to the amount new players should receive
Set up the tax system -- adjust pay-tax-rate and choose whether taxed currency is voided or collected
Enable the bank -- ensure the bank system is enabled and configure interest settings to your liking
Configure the death penalty -- enable or disable and set the percentage, minimum, and maximum values
Choose your storage backend -- select JSON, SQLite, or MySQL based on your server size
Reload -- run /eco reload to apply changes without restarting
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.

Horizons Economy