Menu Actions

Actions are commands that execute when players interact with menu items. They use the format: [action-type] arguments

Action Syntax

any-click-actions:
  - '[action-type] arguments here'
  - '[another-action] more arguments'

Click Types

You can assign different actions to different click types:

Click Type	Description
any-click-actions	Executes on any click (left, right, shift, etc.)
left-click-actions	Only on left-click
right-click-actions	Only on right-click
shift-click-actions	Only on shift-click (left or right)

Example:

menu-items:
  'multi-action':
    slot: '13'
    material: 'EMERALD'
    name: '&aMulti-Action Item'
    lore:
      - '&7Left Click: Buy 1'
      - '&7Right Click: Buy 10'
      - '&7Shift Click: Buy max'
    
    left-click-actions:
      - '[console] eco take %player% 100'
      - '[message] &aPurchased 1 item!'
    
    right-click-actions:
      - '[console] eco take %player% 1000'
      - '[message] &aPurchased 10 items!'
    
    shift-click-actions:
      - '[console] eco take %player% 10000'
      - '[message] &aPurchased maximum items!'

Core Actions

[menu] - Open Menu

Opens another menu and optionally passes variables to it.

Syntax

[menu] menu-id [key1 value1 key2 value2...]

Simple Example

With Variables

Using Variables

[close] - Close Menu

Closes the current menu for the player.

Syntax

[close]

Example

[command] - Execute Command

Runs a command as if the player typed it (player permission required).

Syntax

[command] command string

Examples

The player must have permission to run the command!

[console] - Console Command

Executes a command from console (useful for giving items, currency, etc.).

Syntax

[console] command string

Examples

With Variables

[sound] - Play Sound

Plays a sound effect to the player.

Syntax

[sound] SOUND_NAME [volume] [pitch]

Simple

Common Sounds

Parameter	Required	Description
SOUND_NAME	Yes	The sound to play (see https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html)
volume	No	Sound volume (0.0 to 1.0, default: 1.0)
pitch	No	Sound pitch (0.5 to 2.0, default: 1.0)

[message] - Send Message

Sends a message to the player who clicked.

Syntax

[message] message text

Examples

With Placeholders

[broadcast] - Server Broadcast

Sends a message to all online players.

Syntax

[broadcast] message text

Example

PhantomDungeons Actions

These are custom actions specific to PhantomDungeons.

[buy-sword-tier] - Purchase Sword Upgrade

Handles sword tier upgrades with validation and economy checks.

Syntax

[buy-sword-tier] sword-id tier

Examples

[buy-sword-max] - Buy the full affordable sword path

Purchases as many sequential sword upgrades as the player can currently afford.

This action starts from the player's currently equipped dungeon sword, upgrades tier-by-tier, and if the player reaches the end of that skin it will automatically continue into the next sword skin when affordable.

This is the simplest way to make a one-click "buy max sword" button in a menu.

Syntax

[buy-sword-max]

Example

Useful placeholders for [buy-sword-max]

Placeholder	Description
%phantomdungeons_sword_max_upgrade_available%	Returns true if the player can afford at least one more sword upgrade right now.
%phantomdungeons_sword_max_upgrade_steps%	How many sword upgrades will be bought by the max action.
%phantomdungeons_sword_max_upgrade_target_skin%	The final sword skin ID the player will end on after max purchase.
%phantomdungeons_sword_max_upgrade_target_name%	The final sword display name after max purchase.
%phantomdungeons_sword_max_upgrade_target_tier%	The final sword tier after max purchase.
%phantomdungeons_sword_max_upgrade_target_damage%	The final sword damage after max purchase.

[buy-sword-max] has no parameters. It always follows the player's live sword progression path, which keeps menu configuration simple and avoids hardcoding tier numbers.

[upgrade-enchant] - Upgrade Enchantment

Upgrades an enchant level on the player's equipped sword.

Syntax

[upgrade-enchant] enchant-id levels

Examples

With Menu Refresh

[buy-level] - Buy a level

Buys/increments the specified level for the player

Syntax

[buy-level] rebirth

Examples

[upgrade-permanent-booster] - Upgrade an existing perm booster

Upgrades a stored permanent booster directly, without charging currency.

Use this when you already know the permanent booster ID and just want to increase it. If you need the menu click to also charge an economy before upgrading, use [buy-permanent-booster-upgrade] instead.

Syntax

[upgrade-permanent-booster] booster-id increase-amount
[upgrade-permanent-booster] booster-id type base-multiplier increase-amount display-name...

Examples

Parameter	Required	Description
booster-id	Yes	The stored booster ID to target, such as rebirth-attack-speed.
increase-amount	Yes	How much to add to the current permanent multiplier.
type	Conditional	Required only in the longer grant or upgrade form. This is the booster type, such as souls, money, or attack-speed.
base-multiplier	Conditional	Required only in the longer form. Used when the booster does not exist yet and needs to be created first.
display-name...	Conditional	Required only in the longer form. This is the booster name shown to players. It can contain spaces because everything after increase-amount is treated as the name.

Optional vs conditional:

[upgrade-permanent-booster] has two valid formats. The extra arguments are not truly optional on the longer format — they are only required when you want the action to create the permanent booster if it does not already exist.

[buy-permanent-booster-upgrade] - Buy a permanent booster upgrade

Charges a currency, then creates or upgrades a permanent booster for the player.

This is the menu-friendly version of a permanent booster upgrade. It is ideal for rebirth shops, prestige menus, or any system where players spend a custom currency to buy permanent multiplier tiers.

Syntax

[buy-permanent-booster-upgrade] booster-id type base-multiplier increase-amount currency-id starting-cost scaling-method scaling-data display-name...

Examples

Parameter	Required	Description
booster-id	Yes	The permanent booster ID to create or upgrade, such as rebirth-souls.
type	Yes	The booster type. This must match the stored booster type if the player already has one.
base-multiplier	Yes	The multiplier used on the very first purchase, such as 1.05 for a starting 1.05x booster.
increase-amount	Yes	How much each additional purchase adds, such as 0.05.
currency-id	Yes	The economy ID to charge, such as rebirth-points, souls, or money.
starting-cost	Yes	The cost of tier 1 — the player's first purchase of this permanent upgrade.
scaling-method	Yes	One of LINEAR, EXPONENTIAL, or CUSTOM.
scaling-data	Yes	The value used by the selected scaling method. Its format changes depending on scaling-method.
display-name...	Yes	The booster name sent in messages. It can contain spaces because everything after scaling-data is joined into the display name.

Scaling Methods

Method	scaling-data format	How cost is calculated
LINEAR	Number	starting-cost + (scaling-data × (tier - 1))
EXPONENTIAL	Number	starting-cost × scaling-data^(tier - 1)
CUSTOM	tier=cost,tier=cost,...	Uses the configured tier map

Are any params optional?

For [buy-permanent-booster-upgrade], no — every argument is required in the current implementation.

What is conditional is the format of scaling-data:

• For LINEAR and EXPONENTIAL, scaling-data must be a number.

• For CUSTOM, scaling-data must be a comma-separated tier map like 1=1,2=1,3=2.

Want no scaling at all?

Use LINEAR 0.

That keeps every purchase at the exact same starting-cost, which is what your current rebirth menu does:

- '[buy-permanent-booster-upgrade] rebirth-attack-speed attack-speed 1.05 0.05 rebirth-points 1 LINEAR 0 &7Rebirth Upgrade'

How tiers work

• No existing booster: the first purchase creates the permanent booster at base-multiplier, and the player pays starting-cost.

• Existing booster at base multiplier: the next purchase is treated as tier 2 and adds increase-amount.

• Each later purchase: adds increase-amount again and recalculates the cost for the next tier.

Example with base-multiplier: 1.10, increase-amount: 0.10, starting-cost: 1, and LINEAR 0:

• 1st purchase → 1.10x, cost 1

• 2nd purchase → 1.20x, cost 1

• 3rd purchase → 1.30x, cost 1

Custom map notes

• Do not put spaces inside the map: use 1=1,2=1,3=2, not 1=1, 2=1, 3=2.

• If a tier is listed exactly, that exact cost is used.

• If a higher tier is missing between configured entries, the action keeps using the most recent lower configured cost.

• If purchases go beyond your highest configured tier, the action continues by extending the last cost jump.

That means CUSTOM is best when you want explicit tier pricing behavior and are comfortable defining the path carefully.

Action Chaining

You can chain multiple actions together — they execute in order:

any-click-actions:
  - '[sound] UI_BUTTON_CLICK 1.0 1.0'
  - '[console] eco take %player% 1000'
  - '[console] give %player% diamond 64'
  - '[message] &a&lPurchased! &7You received 64 diamonds'
  - '[broadcast] &e%player% &7just bought the diamond pack!'
  - '[menu] shop'  # Refresh the menu

Tip: Actions stop executing if one returns a "close menu" or "open menu" result.

Quick Reference

Action	Purpose	Example
[menu]	Open another menu	[menu] shop-menu
[close]	Close current menu	[close]
[command]	Run command as player	[command] spawn
[console]	Run command as console	[console] give %player% diamond 1
[sound]	Play sound effect	[sound] UI_BUTTON_CLICK 1.0 1.0
[message]	Send player message	[message] &aSuccess!
[broadcast]	Broadcast to all players	[broadcast] &eEvent started!
[buy-sword-tier]	Purchase sword upgrade	[buy-sword-tier] wooden-sword 2
[buy-sword-max]	Buy full affordable sword path	[buy-sword-max]
[upgrade-enchant]	Upgrade sword enchant	[upgrade-enchant] speed 1
[buy-level]	Buy a level/rebirth	[buy-level] rebirth
[upgrade-permanent-booster]	Upgrade a permanent booster directly	[upgrade-permanent-booster] rebirth-attack-speed 0.05
[buy-permanent-booster-upgrade]	Charge currency, then create/upgrade a permanent booster	[buy-permanent-booster-upgrade] rebirth-souls souls 1.10 0.10 rebirth-points 1 LINEAR 0 &dRebirth Souls