Placeholders

Currency Placeholders

Get player currency balances and display names.

Balance

%phantomdungeons_currency_balance_{currency_id}%

Shows the player's balance for a specific currency, formatted with default notation.

Example:

%phantomdungeons_currency_balance_money%
%phantomdungeons_currency_balance_souls%
%phantomdungeons_currency_balance_sword-xp%

Currency Name

%phantomdungeons_currency_name_{currency_id}%

Returns the display name of a currency as configured in its economy file.

Example:

%phantomdungeons_currency_name_money%

Zone Placeholders

Track player zone progression and status.

Current Zone

%phantomdungeons_zone_current%

Returns the ID of the zone the player is currently in or last played in.

Current Zone Name

%phantomdungeons_zone_current_name%

Returns the formatted display name of the player's current zone.

Zone Stage

%phantomdungeons_zone_stage_{zone_id}%

Returns the player's current stage number for a specific zone.

Example:

%phantomdungeons_zone_stage_barn-zone%

Zone Stage Unlocked

%phantomdungeons_zone_unlocked_{zone_id}_{stage_number}%

Returns true or false if the player has unlocked a specific zone stage.

Example:

%phantomdungeons_zone_unlocked_barn-zone_2%

Leveling Placeholders

Display progression system data like sword levels and experience.

Level

%phantomdungeons_leveling_{progression_id}_level%

Shows the player's current level for a specific progression system.

Example:

%phantomdungeons_leveling_sword-level_level%

Progress Percentage

%phantomdungeons_leveling_{progression_id}_progress%

Returns the percentage progress to the next level (e.g., 45.2).

Example:

%phantomdungeons_leveling_sword-level_progress%

Progress Bar

%phantomdungeons_leveling_{progression_id}_progressbar%

Displays a visual progress bar showing level progression.

Example:

%phantomdungeons_leveling_sword-level_progressbar%

Next Level Cost

%phantomdungeons_leveling_{progression_id}_cost_next%

Shows the currency cost required to reach the next level, formatted.

Example:

%phantomdungeons_leveling_sword-level_cost_next%

Sword Placeholders

Get information about player swords, tiers, and skins.

Current Sword Data

• %phantomdungeons_sword_damage% - Current sword's damage value

• %phantomdungeons_sword_skin% - Current sword's skin ID

• %phantomdungeons_sword_tier% - Current sword's tier level

• %phantomdungeons_sword_name% - Current sword's display name

Next Tier Info

• %phantomdungeons_sword_next_tier% - Next available tier number

• %phantomdungeons_sword_next_damage% - Damage value of next tier

• %phantomdungeons_sword_upgrade_cost% - Cost to upgrade (formatted)

• %phantomdungeons_sword_upgrade_cost_raw% - Raw upgrade cost value

Enchant Count

• %phantomdungeons_sword_enchant_total% - Total number of enchants on current sword

• %phantomdungeons_sword_enchant_count% - Alias for enchant_total

Sword Enchant Levels

• %phantomdungeons_sword_enchant_{enchant_id}_level% - Raw enchant level from sword NBT

• %phantomdungeons_sword_enchant_{enchant_id}_level_formatted_commas% - Level with comma formatting

• %phantomdungeons_sword_enchant_{enchant_id}_level_formatted_abbrev% - Level with abbreviated notation

Example:

%phantomdungeons_sword_enchant_speed_level%
%phantomdungeons_sword_enchant_critical_level_formatted_commas%

Performance Note: Enchant related placeholders on swords are done at lore compile (refresh) of the sword, that way we can improve performance by using caches. However if you use these enchant placeholders outside of the sword, there could be 1-2% performance increase due to fetching the players sword and NBT casting.

Sword Comparison

• %phantomdungeons_sword_has_{skin_id}% - Returns true if player has this sword equipped

• %phantomdungeons_sword_is_current_{skin_id}% - Alias for has

• %phantomdungeons_sword_higher_{skin_id}% - Returns true if player's sword is higher tier than specified

• %phantomdungeons_sword_is_higher_{skin_id}% - Alias for higher

• %phantomdungeons_sword_lower_{skin_id}% - Returns true if player's sword is lower tier than specified

• %phantomdungeons_sword_is_lower_{skin_id}% - Alias for lower

• %phantomdungeons_sword_unlocked_{skin_id}% - Returns true if player has unlocked this sword

• %phantomdungeons_sword_canupgrade_{skin_id}% - Returns true if player can upgrade to this sword

Example:

%phantomdungeons_sword_has_wooden-sword%
%phantomdungeons_sword_unlocked_iron-sword%

Specific Sword Data

• %phantomdungeons_sword_{skin_id}_name% - Display name of a specific sword

• %phantomdungeons_sword_{skin_id}_material% - Material type of the sword

• %phantomdungeons_sword_{skin_id}_model% - Custom model data number

• %phantomdungeons_sword_{skin_id}_damage% - Base damage of the sword

• %phantomdungeons_sword_{skin_id}_tier% - Player's current tier for this sword

• %phantomdungeons_sword_{skin_id}_max% - Maximum tier available for this sword

Example:

%phantomdungeons_sword_wooden-sword_name%
%phantomdungeons_sword_wooden-sword_max%

Tier Symbols

• %phantomdungeons_sword_{skin_id}_tiers_earned% - Visual symbols showing earned tiers

• %phantomdungeons_sword_{skin_id}_tiers_remaining% - Visual symbols showing remaining tiers

Specific Tier Data

• %phantomdungeons_sword_{skin_id}_tier_{number}_damage% - Damage at specific tier

• %phantomdungeons_sword_{skin_id}_tier_{number}_damage_formatted_abbrev% - Damage abbreviated

• %phantomdungeons_sword_{skin_id}_tier_{number}_price% - Upgrade cost for specific tier

• %phantomdungeons_sword_{skin_id}_tier_{number}_price_formatted_abbrev% - Price abbreviated

Example:

%phantomdungeons_sword_wooden-sword_tier_2_damage%
%phantomdungeons_sword_wooden-sword_tier_3_price_formatted_abbrev%

Tier Status Check

%phantomdungeons_sword_{skin_id}_tier_isequipped_{tier_number}%

Returns true if the player has this specific tier equipped.

Example:

%phantomdungeons_sword_wooden-sword_tier_isequipped_3%

Max Upgrade (Sword Related)

These placeholders describe the best upgrade the player can afford in a single purchase (skipping across multiple sword skins and tiers if possible).

• %phantomdungeons_sword_max_upgrade_available% - Returns true if the player can afford at least one upgrade

• %phantomdungeons_sword_max_upgrade_steps% - Number of upgrade steps the player can afford

• %phantomdungeons_sword_max_upgrade_target_skin% - Skin ID of the furthest upgrade the player can reach

• %phantomdungeons_sword_max_upgrade_target_name% - Display name of the target sword

• %phantomdungeons_sword_max_upgrade_target_tier% - Tier number of the target upgrade

• %phantomdungeons_sword_max_upgrade_target_damage% - Damage value at the target upgrade

Example:

%phantomdungeons_sword_max_upgrade_available%
%phantomdungeons_sword_max_upgrade_target_name%

Enchant Placeholders

Display enchant information from menus and the player's sword.

Important: Enchant placeholders read from the sword's NBT data, not from player progression. This means they show the actual enchant levels applied to the equipped sword. This design decision may be revised at a later stage for better performance.

Enchant Level

• %phantomdungeons_enchant_{enchant_id}_level% - Raw enchant level from sword

• %phantomdungeons_enchant_{enchant_id}_level_formatted_single% - Level with commas

• %phantomdungeons_enchant_{enchant_id}_level_formatted_abbrev% - Level abbreviated

Example:

%phantomdungeons_enchant_speed_level%
%phantomdungeons_enchant_critical_level_formatted_abbrev%

Max Level

• %phantomdungeons_enchant_{enchant_id}_maxlevel% - Maximum level for this enchant

• %phantomdungeons_enchant_{enchant_id}_maxlevel_formatted_single% - Max level with commas

Levels Remaining

%phantomdungeons_enchant_{enchant_id}_levels_remaining%

Returns how many levels remain until the enchant reaches its max level.

Purchasable Levels

%phantomdungeons_enchant_{enchant_id}_purchasable_levels%

Returns how many levels the player can afford to purchase with their current balance.

Upgrade Cost

• %phantomdungeons_enchant_{enchant_id}_cost_{amount}% - Cost to upgrade by X levels (raw)

• %phantomdungeons_enchant_{enchant_id}_cost_{amount}_formatted_single% - Cost with commas

• %phantomdungeons_enchant_{enchant_id}_cost_{amount}_formatted_abbrev% - Cost abbreviated

Purchasable Upgrade Cost

• %phantomdungeons_enchant_{enchant_id}_cost_purchasable% - Total cost for all levels the player can currently afford (raw)

• %phantomdungeons_enchant_{enchant_id}_cost_purchasable_formatted_single% - Purchasable cost with commas

• %phantomdungeons_enchant_{enchant_id}_cost_purchasable_formatted_abbrev% - Purchasable cost abbreviated

Example:

%phantomdungeons_enchant_speed_cost_1%
%phantomdungeons_enchant_speed_cost_5_formatted_abbrev%

Max Upgrade Cost

• %phantomdungeons_enchant_{enchant_id}_cost_max% - Total cost from current level to max

• %phantomdungeons_enchant_{enchant_id}_cost_max_formatted_single% - Max cost with commas

• %phantomdungeons_enchant_{enchant_id}_cost_max_formatted_abbrev% - Max cost abbreviated

Example:

%phantomdungeons_enchant_speed_cost_max_formatted_abbrev%

Enchant Prestige

• %phantomdungeons_enchant_{id}_prestige% - Player's current prestige tier for this enchant.

• %phantomdungeons_enchant_{id}_maxprestige% - Configured max prestige from the enchant file.

Enchant Properties

• %phantomdungeons_enchant_{enchant_id}_chance% - Activation chance as percentage

• %phantomdungeons_enchant_{enchant_id}_name% - Display name of the enchant

• %phantomdungeons_enchant_{enchant_id}_material% - Menu material for the enchant

• %phantomdungeons_enchant_{enchant_id}_currencyname% - Currency used for upgrades

Example:

%phantomdungeons_enchant_speed_name%
%phantomdungeons_enchant_critical_chance%

Booster Placeholders

Display active booster information. Only available if the Boosters module is enabled.

Booster Multiplier

%phantomdungeons_booster_{type}%

Returns the current multiplier for a booster type (returns 1.0 if none active).

Example:

%phantomdungeons_booster_money%
%phantomdungeons_booster_damage%
%phantomdungeons_booster_attack-speed%

Booster Time Remaining

%phantomdungeons_booster_{type}_time%

Shows formatted time remaining for the booster (returns None if not active).

Booster Status

• %phantomdungeons_booster_{type}_active% - Returns true or false if booster is active

• %phantomdungeons_booster_{type}_permanent% - Returns true if booster is permanent

• %phantomdungeons_booster_{type}_name% - Display name of the booster type

• %phantomdungeons_booster_id_{boosterId}_multiplier% - Returns multiplier for one exact booster ID

• %phantomdungeons_booster_id_{boosterId}_active% - Returns true/false for one exact booster ID

• %phantomdungeons_booster_id_{boosterId}_permanent% - Returns true/false for one exact booster ID

• %phantomdungeons_booster_id_{boosterId}_name% - Returns display name for one exact booster ID

Booster Count

• %phantomdungeons_booster_count% - Returns the total number of active boosters the player has.

Booster Lists

• %phantomdungeons_booster_list% - Formatted list of all active boosters

• %phantomdungeons_booster_list_permanent% - List of only permanent boosters

• %phantomdungeons_booster_list_permanent_{type}% - List of permanent boosters for a specific type

• %phantomdungeons_booster_list_temporary% - List of only temporary boosters

• %phantomdungeons_booster_list_temporary_{type}% - List of temporary boosters for a specific type

• %phantomdungeons_booster_list_currency_{currency_id}% - List of boosters for specific currency

• %phantomdungeons_booster_list_enchant% - List of enchant boosters

• %phantomdungeons_booster_list_damage% - List of damage boosters

• %phantomdungeons_booster_list_attack-speed% - List of attack-speed boosters

Example:

%phantomdungeons_booster_list_currency_money%
%phantomdungeons_booster_list_enchant%

Crystal Placeholders

Display information about crystals socketed into the player's sword. Only available if the Crystals module is enabled.

Crystal Count

%phantomdungeons_crystal_count%

Returns the total number of crystals applied to the player's equipped sword.

Damage Boost

%phantomdungeons_crystal_damage_boost%

Returns the total damage boost percentage from all crystals on the sword (e.g. 15.00%).

Boost by Type

%phantomdungeons_crystal_boost_{type}%

Returns the combined boost percentage for a specific boost type across all applied crystals.

Example:

%phantomdungeons_crystal_boost_damage%
%phantomdungeons_crystal_boost_speed%

Slot Data

• %phantomdungeons_crystal_slot_{index}_id% - Crystal ID in the given slot, or empty

• %phantomdungeons_crystal_slot_{index}_name% - Display name of the crystal in the slot, or empty

• %phantomdungeons_crystal_slot_{index}_display% - Full formatted display string, or "" if empty

• %phantomdungeons_crystal_slot_{index}_boost% - Boost amount in the slot (e.g. 5.00%), or 0.00%

• %phantomdungeons_crystal_slot_{index}_boost_raw% - Raw boost double value, or 0

• %phantomdungeons_crystal_slot_{index}_type% - Boost type in the slot, or none

Example:

%phantomdungeons_crystal_slot_0_id%
%phantomdungeons_crystal_slot_1_boost%
%phantomdungeons_crystal_slot_2_type%

Mask Placeholders

Display information about the player's equipped mask. Only available if the Masks module is enabled.

Equipped Mask

%phantomdungeons_mask_equipped%

Returns the ID of the mask the player currently has equipped, or none if no mask is equipped.

Equipped Mask Name

%phantomdungeons_mask_equipped_name%

Returns the display name of the player's equipped mask, or None.

Equipped Mask Material

%phantomdungeons_mask_equipped_material%

Returns the material type of the player's equipped mask, or AIR if none is equipped.

Has Equipped

%phantomdungeons_mask_has_equipped%

Returns true if the player has any mask equipped, otherwise false.

Example:

%phantomdungeons_mask_equipped%
%phantomdungeons_mask_equipped_name%
%phantomdungeons_mask_has_equipped%

Summary Placeholders

Display player gains over a tracking period. Only available if the Summary module is enabled.

Currency Gains

• %phantomdungeons_summary_{currency_id}_raw% - Raw gain value

• %phantomdungeons_summary_{currency_id}_formatted% - Default formatted gain

• %phantomdungeons_summary_{currency_id}_formatted_single% - Gain with commas

• %phantomdungeons_summary_{currency_id}_formatted_abbrev% - Gain abbreviated

Example:

%phantomdungeons_summary_money_formatted_abbrev%
%phantomdungeons_summary_souls_formatted_single%

Level Gains

%phantomdungeons_summary_level_{level_id}%

Shows how many levels gained in a specific progression system.

Example:

%phantomdungeons_summary_level_sword-level%

Math Placeholders

Utility placeholders for formatting, calculations, and random values.

Number Formatting

• %phantomdungeons_math_format_{value}% - Default format (abbreviated if over 1000)

• %phantomdungeons_math_format_abbrev_{value}% - Force abbreviated notation (k, M, B, T, etc.)

• %phantomdungeons_math_format_commas_{value}% - Force comma notation (1,234,567)

Example:

%phantomdungeons_math_format_1500000%
%phantomdungeons_math_format_abbrev_2500%
%phantomdungeons_math_format_commas_100000%

Tip: Use math_format_{value} in mob reward displays to dynamically format currency amounts based on their size.

Calculate Expression

%phantomdungeons_math_calculate_{expression}%

Evaluates a mathematical expression and returns the result. Supports basic operations (+, -, *, /, parentheses).

Example:

%phantomdungeons_math_calculate_10*5+2%
%phantomdungeons_math_calculate_(100-25)/5%

Random Numbers

%phantomdungeons_math_random_{min}_{max}%

Generates a random integer between min and max (inclusive).

Example:

%phantomdungeons_math_random_1_100%

Random Decimal

%phantomdungeons_math_random_decimal_{decimals}_{min}_{max}%

Generates a random decimal number with specified precision.

Example:

%phantomdungeons_math_random_decimal_2_0_1%

Random Position

%phantomdungeons_math_random_pos_{anchor_x}_{anchor_y}_{anchor_z}_{offset_x}_{offset_y}_{offset_z}%

Generates a random position relative to an anchor point with specified offsets. Returns format: x,y,z

Example:

%phantomdungeons_math_random_pos_0_100_0_10_5_10%

Using Placeholders

In Configuration Files

Placeholders work throughout all PhantomDungeons config files (YAML). They are automatically parsed when:

• Displaying item lore

• Showing menu titles

• Sending messages

• Processing conditions

Example from sword config:

lore:
  - "&7Damage: &c%phantomdungeons_sword_damage%"
  - "&7Tier: &e%phantomdungeons_sword_tier%/%phantomdungeons_sword_wooden-sword_max%"
  - "if(%phantomdungeons_sword_enchant_speed_level% > 0) then &r &#D27F51| &#434FF5Speed &#747CED%phantomdungeons_sword_enchant_speed_level_formatted_commas%"

In External Plugins

Other plugins can use PhantomDungeons placeholders through PlaceholderAPI:

Java

import me.clip.placeholderapi.PlaceholderAPI;

String formatted = PlaceholderAPI.setPlaceholders(player, 
    "You have %phantomdungeons_currency_balance_money% money!");

Conditional Placeholders

PhantomDungeons supports conditional placeholder displays using the if() syntax in configs:

Syntax:

if(CONDITION) then TEXT

Operators: >, <, >=, <=, =, !=, AND, OR

Examples:

lore:
  - "if(%phantomdungeons_sword_tier% = 1) then &e&lEQUIPPED"
  - "if(%phantomdungeons_currency_balance_money% >= 1000) then &a&lRICH PLAYER"
  - "if(%phantomdungeons_sword_unlocked_iron-sword% = true) then &aUnlocked Iron Sword"

Note: Conditional syntax only works in PhantomDungeons configuration files, not in external plugins.