Economy Configuration

The Economy module handles all currency systems in PhantomDungeons. Each economy file represents a unique currency that players can earn, spend, and manage.

---

Quick Start

Creating a New Economy

Creating a new economy is simple:

1

Create the file

Navigate to plugins/PhantomDungeons/economies/

2

Add a new YAML

Create a new file: {currency-id}.yml

3

Configure

Configure the currency settings

4

Reload

Restart or reload the plugin

Example: To create a "Souls" currency, create souls.yml in the economies folder.

---

Misc Configuration

Sword Currency Integration

is-sword-currency: true

What is a Sword Currency?

When is-sword-currency: true, this economy automatically increments by 1 for each sword swing. This is typically used for Sword XP-based progression systems.

Example: Sword XP Currency

currency-name: 'Sword XP'
is-sword-currency: true
starting-balance: 0

Players gain 1 Sword XP every time they swing their dungeon sword, enabling leveling progression.

---

Vault Integration

vault-currency: false

Vault Support

Set vault-currency: true to register this economy as the primary Vault economy. This allows other plugins to interact with your economy through Vault's API.

---

Command System

Root Command Configuration

commands:
  root:
    main:
      enabled: true
      command-name: 'money'
      aliases:
        - 'bal'
        - 'balance'
        - 'wallet'

Example Usage:

• /money - Opens help or checks balance

• /balance - Alias for /money

• /wallet - Another alias

---

Command Nodes

commands:
  nodes:
    balance:
      enabled: true
      permission: 'phantom.money.balance'
      check-others-permission: 'phantom.money.balance.others'
      require-online-player: false
    
    give:
      enabled: true
      permission: 'phantom.money.give'
      require-online-player: false
    
    set:
      enabled: true
      permission: 'phantom.money.set'
    
    remove:
      enabled: true
      permission: 'phantom.money.remove'

Node	Permission	Description	Example
balance	phantom.{currency}.balance	Check own balance	/money balance
balance (others)	phantom.{currency}.balance.others	Check other's balance	/money balance Player
give	phantom.{currency}.give	Give currency to player	/money give Player 1000
set	phantom.{currency}.set	Set player's balance	/money set Player 5000
remove	phantom.{currency}.remove	Remove currency from player	/money remove Player 500

Set require-online-player: false to allow commands to work on offline players (Who have previously logged on) (useful for admin management).

---

Messages Configuration

Each economy has fully customizable messages with sound effects:

messages:
  "BALANCE":
    Sound:
      Enable: false
      Value: ENTITY_PLAYER_LEVELUP;1.0;1.0
    Message:
      Enable: true
      Value: '&c&lPhantom&4&lDungeons &8&l→ &7You have &2$&a%amount%&7'

Available Message Keys

Every message automatically parses PlaceholderAPI if available, if you wish to have additional formatting, please use our built in math placeholders here or external ones.

Key	Placeholders	Description
BALANCE	%amount%	Shown when checking own balance
BALANCE_OTHERS	%player%, %amount%	Shown when checking another player's balance
GIVE_SUCCESS	%player%, %amount%	Sent to admin who gives currency
GIVE_RECEIVER	%sender%, %amount%	Sent to player receiving currency
SET_SUCCESS	%player%, %amount%	Sent when setting balance
REMOVE_SUCCESS	%player%, %amount%	Sent when removing currency
INVALID_PLAYER	%player%	Player not found
INVALID_AMOUNT	%amount%	Invalid amount specified
NOT_ENOUGH_FUNDS	-	Insufficient balance
CANNOT_SEND_TO_SELF	-	Attempted to send money to self
PLAYER_HELP	-	Player help menu
ADMIN_HELP	-	Admin help menu

---

Amount Format Placeholders

When you use %amount% in any message, the following utility placeholders are automatically available:

Placeholder	Description	Example
%amount%	Raw formatted amount with display format applied	&a1,000
%amount_formatted%	Amount with thousands separator but no display format	1,000
%amount_abbreviated%	Shortened notation (k, M, B, T)	1.2k
%amount_plain%	Amount with specified decimal places only	1000.50

Example Usage:

If you want to show the balance in multiple formats:

BALANCE:
  Message:
    Enable: true
    Value: '&7Full: &a%amount_formatted%&7 | Short: &e%amount_abbreviated%'

Output: Full: 1,000,000 | Short: 1.2M

---

Complete Example

Here's a fully configured "Souls" currency:

currency-name: 'Soul'
currency-name-plural: 'Souls'

max-balance: 0
starting-balance: 0
prevent-negative-balance: true
is-sword-currency: false

decimal-places: 0
use-thousands-separator: true
thousands-separator: ','

commands:
  root:
    main:
      enabled: true
      command-name: 'souls'
      aliases:
        - 'soul'

  nodes:
    balance:
      enabled: true
      permission: 'phantom.souls.balance'
      check-others-permission: 'phantom.souls.balance.others'

    give:
      enabled: true
      permission: 'phantom.souls.give'

    set:
      enabled: true
      permission: 'phantom.souls.set'

    remove:
      enabled: true
      permission: 'phantom.souls.remove'

messages:
  "BALANCE":
    Sound:
      Enable: true
      Value: ENTITY_EXPERIENCE_ORB_PICKUP;1.0;1.2
    Message:
      Enable: true
      Value: '&c&lPhantom&4&lDungeons &8&l→ &7You have &5%amount% &dSouls'

---