🎑 Customize Menus

#Shop Menus

Every shop has its own set of menus, in menus/<shop> inside the plugin folder. They are created the first time the shop loads, so two shops can look completely different.

File	Menu
main.yml	The categories of the shop, the first menu players see.
categories/<category>.yml	The items of one category. There is one file per category.
buy.yml	Picking how many of an item to buy.
sell.yml	Picking how many of an item to sell.
bulk-buy.yml	Buying up to nine stacks in one click.
bulk-sell.yml	Selling up to nine stacks in one click.
sell-menu.yml	The menu of /sell menu, where items are dropped in to be sold.
confirm.yml	The confirm screen shown before a purchase goes through.

The Premium search and preview menus are shared by every shop, so they sit on their own at menus/search.yml and menus/preview.yml.

Renaming a shop or a category renames its menu files, and deleting one deletes them. /pshop reload reads every menu file again.

#Menu Settings

Every menu starts with the same settings block: the title, the number of rows, how often the menu refreshes and the actions run when it opens.

settings:
  type: SHOP
  title: '%shop%'
  rows: 4
  refresh:
    enabled: false
    rate: 20
  on-open-actions: []

Leave type as it is, it tells the plugin which menu the file belongs to. The rate is in ticks, and a refreshing menu redraws its placeholders on that interval. The buy and sell menus refresh by default, so the balance they show stays current.

Titles, names and lore accept color codes and MiniMessage tags.

#Slots

Slots are counted from 0, starting at the top left of the menu, so the first row is 0 to 8 and the second is 9 to 17. A slot takes a single slot ('4'), a range ('0-8'), or a comma separated mix of both ('0, 8, 36-44').

#Items

The items section holds the decoration of the menu: glass borders, info items, anything that is not one of the plugin's own buttons. Add as many entries as you want, with any name.

items:
  info:
    slot: '4'
    material: NETHER_STAR
    amount: 1
    custom-model-data: 0
    glow: true
    hide-attributes: true
    display-name: '&6&lPhoenix Shop'
    lore:
    - '&7Pick a category below to start.'
    actions:
    - '[SOUND] BLOCK_AMETHYST_BLOCK_CHIME; 1; 1.4'
    hide-tooltip: false

Two more options are available on any entry and are not in the example above:

• item-model - The item model identifier to use, on server versions that support it.
• tooltip-style - The tooltip style of the item, such as minecraft:blue or one from a resource pack.

#Buttons

The plugin's own buttons, such as close, back or confirm, sit at the top level of the file rather than under items. They take slot, material, amount, custom-model-data, display-name, lore and actions. Their click does what the button is for, and its actions run on top of that.

A button cannot be deleted from the file, but it can be moved anywhere or restyled.

#Menu Actions

The actions of an item or button, and the on-open-actions of a menu, are written as [TYPE] arguments, with the arguments separated by ;.

Action	Arguments	Edition
[SOUND]	sound; volume; pitch	Lite
[TITLE]	title; subtitle; fade in; stay; fade out	Lite
[ACTION_BAR]	message	Lite
[CLOSE_INVENTORY]	None	Lite
[MESSAGE]	message	Premium
[COMMAND]	console or player; command	Premium
[GAMEMODE]	gamemode	Premium
[PARTICLE]	particle; count; spread x; spread y; spread z	Premium

#Main Menu

main.yml shows one tile per enabled category, in the order the categories are sorted. They fill the category slots in that order.

• category-slots - The slots the category tiles fill.
• category - The look of a category tile. It has no slot of its own, and its material is replaced by the category's icon.
• previous-page and next-page - Shown only when the shop has more categories than category-slots holds.
• close - Closes the menu.

Placeholder	Where	Description
%shop%	Everywhere	The display name of the shop, without colors.
%shop_colored%	Everywhere	The display name of the shop.
%category%	category	The display name of the category, without colors.
%category_colored%	category	The display name of the category.
%items%	category	How many items the category holds.
%items_word%	category	The word item or items, to match %items%.
%category_lore%	category	The category's lore, or its icon item's own lore when none is set, one line each. A category without either drops the line.
%sale%	category	The category sale badge while the sale runs, empty otherwise. ⭐
%sale_ends%	category	A line with the time left on the sale, counting down every second. Left out while no sale with an end is running. ⭐
%page%	Page buttons	The page the button leads to.
%pages%	Page buttons	How many pages there are.

#Category Menu

Each categories/<category>.yml lists the items of one category, page by page.

• pagination - The slots the items fill, how they are aligned, the fill-item for empty item slots, and the previous-item and next-item page buttons.
• item-lore - The lines added under every item's own lore, see below.
• back - Goes back to the main menu.

item-lore:
  buy:
  - '&7Buy: &c%buy_price%%sale%'
  sell:
  - '&7Sell: &a%sell_price%'
  stock:
  - '&7Stock: &f%stock%'
  hint: '&6%click%: &e%action%.'

The buy lines are added only when the item and its category can be bought from, the sell lines only when both can be sold to, and the stock lines only when the item has limited stock. The hint is repeated once per click in the click-mappings of config.yml, skipping clicks that do nothing and actions the item does not allow.

Placeholder	Where	Description
%shop%	Everywhere	The display name of the shop, without colors.
%shop_colored%	Everywhere	The display name of the shop.
%category%	Everywhere	The display name of the category, without colors.
%category_colored%	Everywhere	The display name of the category.
%player%	Everywhere	The name of the player viewing the menu.
%item%	item-lore	The name of the item, without colors.
%item_colored%	item-lore	The name of the item.
%buy_price%	item-lore	The buy price of the item.
%sell_price%	item-lore	The sell price of the item.
%buy_price_base%, %sell_price_base%	item-lore	The price before any price modifier. ⭐
%stock%	item-lore	The stock left of the item.
%sale%	item-lore	The category sale badge while the sale runs, empty otherwise. ⭐
%click%	hint	The name of the click, such as Left-Click.
%action%	hint	What that click does, such as buy.
%page%	Page buttons	The page the button leads to.

#Buy and Sell Menus

buy.yml and sell.yml open when a player picks an item, and let them choose the amount before confirming.

• remove-64, remove-16, remove-1, add-1, add-16 and add-64 - The step buttons. The amount of a step button is how far it moves the amount, so the names are only defaults: set add-16 to an amount of 10 and it adds 10.
• preview - Shows the item itself, with the button's lore added under the item's own.
• max - Fill Inventory on the buy menu, Sell All on the sell menu. It sets the amount to as many as fit in the inventory and off-hand, or as many as the player carries. It needs phoenixshop.buy.fill-inventory or phoenixshop.sell.all, and without it the button shows no-permission-material and no-permission-lore instead.
• confirm - Buys or sells the chosen amount, then goes back to the category.
• bulk - Opens the bulk menu.
• back - Goes back to the category.

Steps are counted in lots, a lot being the item's own amount. On an item sold in 16s, a step of 1 adds 16 items. The amount never goes below one lot or above nine full stacks.

Placeholder	Description
%amount%	How many items are chosen.
%lots%	How many lots are chosen.
%price%	The price of the chosen amount.
%unit_price%	The price of one lot.
%price_base%, %unit_price_base%	The price before any price modifier. ⭐
%max%	The most the player can buy or sell right now.
%max_price%	The price of %max%.
%item%	The name of the item, without colors.
%item_colored%	The name of the item.
%shop%	The display name of the shop, without colors.
%shop_colored%	The display name of the shop.
%balance%	The player's balance in the item's currency.
%stock%	The stock left of the item, or Unlimited.

#Bulk Menus

bulk-buy.yml and bulk-sell.yml offer whole stacks in one click.

• option-slots - The first slot offers one stack, the second two stacks, and so on up to nine. Slots past the ninth are left empty. An item that does not stack, such as armour or tools, is bought one at a time, so bulk buying offers only the first option.
• option - The look of each offer. Its material is replaced by the item, stacked to show how many stacks it is.
• back - Goes back to the buy or sell menu.

Placeholder	Where	Description
%item%	Everywhere	The name of the item, without colors.
%item_colored%	Everywhere	The name of the item.
%shop%	Everywhere	The display name of the shop, without colors.
%shop_colored%	Everywhere	The display name of the shop.
%stacks%	option	How many stacks the offer is.
%amount%	option	How many items the offer is.
%price%	option	The price of the offer.
%price_base%	option	The price before any price modifier. ⭐

#Confirm Menu

confirm.yml is the screen that asks before a purchase goes through: every Bulk Buy, and any other purchase above Confirm Above. Each shop has its own.

• disable - Set to true to never ask in this shop, Bulk Buy included.
• decline - Cancels and goes back to the menu the purchase came from. Closing the menu does the same.
• accept - Buys it.
• item - The item being bought. Its material is replaced by the item, stacked to the amount bought up to one stack.

Placeholder	Where	Description
%amount%	Everywhere	How many items are being bought.
%item%	Everywhere	The name of the item.
%price%	Everywhere	The total price.

#Sell Menu

sell-menu.yml is the menu of /sell menu. Players drop items into it, and everything a shop buys is sold, while the rest is given back. It is read from the first shop in the sell shop list that the player can open.

• drop-slots - The slots players can drop items into. Keep decoration and buttons out of them.
• confirm - Sells the contents and closes the menu.

Placeholder	Where	Description
%shop%	Everywhere	The display name of the shop, without colors.
%shop_colored%	Everywhere	The display name of the shop.
%total%	confirm	What the dropped items are worth.
%close_hint%	confirm	A line saying closing the menu also sells, shown only when it does.

#Search Menu ⭐

menus/search.yml is the menu of /pshop search. It is paginated like a category menu.

• terms - Left-click types a search, right-click clears it.
• filter - Click with an item on the cursor to search for that item, or with an empty cursor to clear it. See Search by Item.
• sort - Changes the order of the results.
• close - Closes the menu.
• result-lore - The buy, sell and footer lines added under every result.

Placeholder	Where	Description
%player%	Everywhere	The name of the player viewing the menu.
%terms%	terms, sort	What is being searched for.
%order%	terms, sort	The current order.
%filter%	filter	The name of the item searched for, or none.
%item%	result-lore	The name of the result.
%shop%	result-lore	The shop the result is in.
%category%	result-lore	The category the result is in.
%buy_price%	result-lore	The buy price of the result.
%sell_price%	result-lore	The sell price of the result.
%buy_price_base%, %sell_price_base%	result-lore	The price before any price modifier.

#Preview Menu ⭐

menus/preview.yml opens with the PREVIEW click action. Its list shows every purchase item, paginated like a category menu.

• info - The shop item. When the item runs purchase commands, the preview.commands translation lines are added under it.
• back - Goes back to the category.
• empty - Shown when the item gives no items and only runs commands.
• item-lore - The lines added under every purchase item.

Placeholder	Where	Description
%player%	Everywhere	The name of the player viewing the menu.
%item%, %item_colored%	Everywhere	The name of the shop item, without and with colors.
%shop%, %shop_colored%	Everywhere	The display name of the shop, without and with colors.
%price%	Everywhere	The price of one purchase for the player.
%count%	Everywhere	How many items one purchase gives.
%commands%	Everywhere	How many purchase commands the item runs.
%amount%	item-lore	How many of that item one purchase gives.