# 🏬 Player Shops

> **Info:**
Every player shop is stored in the database, SQLite or MySQL as set in config.yml. A player-shops.yml from an older version is moved into the database on the first start and renamed to player-shops.yml.migrated. Its settings are in the player-shops section of config.yml.

## Information

A player shop is a sign on a container that the player owns. The container is the stock: buyers take items out of it, sellers put items into it, and the money goes straight between the two players. The server never stands in the middle of a trade.

<figure><img src="../../.gitbook/assets/chest-shops/chest-shops.png" alt="" width="563"><figcaption><p>Editor (Chest Shops)</p></figcaption></figure>

On Lite each player can own up to 25 player shops, and [admin shops](#admin-shops) are capped at 25 across the server. Everything else on these pages works on Lite too.

## Create a Player Shop

Player shops are off until they are turned on with [Enabled](settings.md#enabled). Then hold the item to sell and Shift + Left-Click a chest, trapped chest, barrel or shulker box you can open. [Click Creation](settings.md#click-creation) changes that click. The shop is made straight away: a [sign](settings.md#sign-material) goes up on the side you clicked, or on another free side, the [Creation Cost](settings.md#creation-cost) is charged, and the shop sells one item per click to players.

The shop's editor opens straight away to pick the [mode](edit-player-shop.md#mode) and the prices. Its prices start at 0, so set them there before anyone trades; right-click the sign to come back to it later. See [Edit Player Shop](edit-player-shop.md).

A normal Left-Click breaks the container as usual. In creative mode the click no longer breaks the container when a shop is made from it.

An ender chest makes an ender chest shop. Its stock is the owner's own ender chest, so they can restock it from any ender chest in the world, and several ender chests can each carry a shop. The shop only trades while the owner is online, since an offline player's ender chest cannot be reached. Staff cannot restock it, because opening the ender chest shows them their own. An admin shop on an ender chest works like any other admin shop.

Nothing happens at all while player shops are turned off (except for admin shops on Lite), for a player without `phoenixshop.sign.create`, or on a container that already has a shop. Otherwise the player is told why no shop was made when:

* The world is one of the [Blocked Worlds](settings.md#blocked-worlds). A player with `phoenixshop.sign.bypass` can still make one.
* The block is turned off in [Shop Blocks](settings.md#shop-blocks).
* The item is on the [Blocked Items](settings.md#blocked-items) list.
* The item is a renamed lookalike of a real plugin item, or uses one of the [Protected Names](settings.md#protected-names). See [Fake Items](#fake-items).
* The player cannot open the container, for example because a lock plugin or a claim keeps them out.
* [Require Claim](settings.md#require-claim) is on and the container is not inside a claim the player can build in.
* The player already owns as many shops as their [limit](settings.md#max-per-player) allows.
* The player cannot pay the [Creation Cost](settings.md#creation-cost).
* The container has no free side for the sign, or the player is not allowed to build where it would go.

## Fake Items

A renamed item that does not come from a supported item plugin cannot be sold, bought or used as a payment when its name matches a real plugin item. Colors, case, accents, small caps and word order are ignored, and the real item's id counts as a name too, so a paper renamed **Vote Key** is refused because of the PhoenixCrates key `phoenixcrates:key:vote`, whatever that key is called on the server.

The real items it knows are every item of the installed item plugins: PhoenixCrates keys and crates, Nexo, ItemsAdder, MMOItems, MythicMobs, ExecutableItems, ExecutableBlocks, CraftEngine and Slimefun. The list is built a few seconds after startup and after `/pshop reload`, and again every 10 minutes. Head plugins are not checked. Add any other name to [Protected Names](settings.md#protected-names). Items that were only renamed, such as a sword called Bob's Sword, are still allowed. A shop that was set up with a fake item before stops trading.

## Admin Shops

An admin shop never runs out or fills up, pays and takes no one's money, and shows Admin Shop as its owner. A player with `phoenixshop.sign.admin` turns any shop into one with [Admin Shop](edit-player-shop.md#admin-shop) in its editor.

<figure><img src="../../.gitbook/assets/chest-shops/admin-shops.png" alt="" width="563"><figcaption><p>Chest Shops (Admin Shops)</p></figcaption></figure>

For a player with `phoenixshop.sign.admin` but not `phoenixshop.sign.create`, the left-click makes an admin shop straight away. It costs nothing and does not count towards the limit. Lite has no Admin Shop toggle, so this is the only way to make one there.

## Sign Text

The four lines are the owner's name in green, then the mode with the amount traded per click, the item, and the price, with buy prices in red and sell prices in green. The mode reads `Selling: 16`, `Buying: 32` or `Buy & Sell: 16`. A shop that buys and sells shows both prices with what they are paid in, such as `B $2 S $1`, or `B2 S1 Diamond` when it is paid in an item. An admin shop shows Admin Shop as its owner. Prices of 1,000 and up are shortened on the sign, such as `$100k`, `$10m` or `$1.5q`, while chat messages show the full price.

The mode line of a Buy shop also shows how many are left, such as **Selling: 1 - 58**, shortened from 1,000 up, such as **Selling: 1 - 1.2k**. Buy & Sell shops and admin shops leave the count out. A [disabled](edit-player-shop.md#enabled) shop shows \[Disabled] on the mode line. When a shop that sells to players no longer holds enough for one trade, the mode line turns into a bold \[Out of Stock] and the owner's name turns red until it is restocked. A shop that buys from players shows \[Chest Full] the same way when its container has no room for one more trade. The price hologram shows the same two states. The sign is checked after every trade, when the shop's container is closed, a second after a hopper or hopper minecart moves items in or out, and when its chunk loads.

A sign line holds 15 characters, so a longer line is cut short and the owner is told which one. The text comes from the player-shops.sign section of the translations file.

## Navigation

| Features | Description |
| --- | --- |
| [Item](edit-player-shop.md#item) | The item the sign trades. |
| [Amount](edit-player-shop.md#amount) | How many change hands in one click. |
| [Mode](edit-player-shop.md#mode) | Whether players buy, sell or both. |
| [Enabled](edit-player-shop.md#enabled) | Stop every trade without removing the shop. |
| [Buy Price](edit-player-shop.md#buy-price) | What a player pays the owner. |
| [Sell Price](edit-player-shop.md#sell-price) | What the owner pays a player. |
| [Currency](edit-player-shop.md#currency) | What an admin shop is priced in. |
| [Remove](edit-player-shop.md#remove) | Break the sign to take it down. |
| [Trading](trading.md) | Buying and selling on a sign. |
| [Protection](trading.md#protection) | Who can break or open the shop. |
| [Owner Notices](trading.md#owner-notices) | The messages an owner gets about their trades. |
| [Shop List](#shop-list) | Every player shop in one menu. |
| [Find a Shop](#find-a-shop) | The nearest shops that sell or buy an item. |
| [Market](#market) | Every traded item with its cheapest seller and best buyer. |
| [Discount](edit-player-shop.md#discount) | A timed price cut on a shop. |
| [Edit By Command](#edit-by-command) | Change the shop you look at without the editor. |
| [Map Markers](settings.md#map-markers) | Player shops on BlueMap, dynmap and squaremap. |
| [Transfer](#transfer) | Hand a shop to another player. |
| [Inactive Owners](#inactive-owners) | Remove the shops of players who stopped playing. |
| [Bulk Removal](#bulk-removal) | Remove empty shops, or every shop of a player or a world. |
| [Settings](settings.md) | Turn player shops on or off, the creation cost and the limit. |

## Shop List

The player shop commands are under `/chestshop`, or `/cs`, which can be renamed or turned off with [Chest Shop Command](settings.md#chest-shop-command).

`/chestshop list` lists every player shop with an item, with its [name](edit-player-shop.md#name), owner, amount and prices. Where a shop is stays hidden from players; admins see it in the [Player Shops Editor](#player-shops-editor). `/chestshop list <search>` keeps only the shops whose item, owner or name contains the search. It needs `phoenixshop.sign.list`, which everyone has by default.

Each entry also shows the item's own enchantments and lore.

Left-click a shop to teleport in front of its sign. That needs [Teleport](settings.md#teleport) on and `phoenixshop.sign.teleport`, given to everyone by default, and the shop's [Allow Teleport](edit-player-shop.md#allow-teleport) on. A shop with it off does not offer the click and says so instead, unless you own it or hold `phoenixshop.sign.admin`. Right-click it to trade with it from where you stand, which needs [Remote Trading](settings.md#remote-trading) on and `phoenixshop.sign.remote`, given to everyone by default.

The **Filter** button at the bottom shows all shops, only the ones selling, or only the ones buying. The **Order** button sorts them by their price for one item, lowest or highest first; on All, a shop that sells is sorted by its buy price and one that only buys by its sell price. **Show Only My Own** next to it lists only your own shops.

## Find a Shop

`/chestshop find <search>` opens a menu of the shops that sell the item and the shops that buy it, the ones in your world first and closest first, with the owner, amount, price and location. Add `selling` or `buying` at the end to open it with the Filter already set to that side. It needs `phoenixshop.sign.find`, which everyone has by default.

The search matches every word you type against the item's name, its material and its custom item id, so `/chestshop find vote key` finds a PhoenixCrates vote key (`phoenixcrates:key:vote`), and `/chestshop find adamantium` or `/chestshop find nexo:adamantium_ingot` finds a Nexo item. Shops whose item matches through its plugin id are listed before shops that only match by name, so the real item comes first. Without a search it looks for what you hold in your main hand. Tab completion offers the names of the items that are in shops, and the id of a custom item you hold.

Each shop also shows how many items it has in stock, or how much room is left in a shop that buys. Shops in a loaded area show the live count, and the others the count from their last trade or restock. Its clicks and its Filter and Order buttons work like the [Shop List](#shop-list). A Buy & Sell shop is listed under Selling only while it has stock, and under Buying only while its container has room.

A shop that sells is listed only while it holds enough for one trade, and a shop that buys only while its container has room. Admin shops always pass this check, and [disabled](edit-player-shop.md#enabled) shops are left out. A shop whose chunk is not loaded is listed without the check, since its container cannot be read.

The **Price Overview** at the top sums up the item for one piece: how many shops sell it and the lowest and average price, how many buy it and the best and average offer, and the average price it actually traded at over the last 30 days. Only shops priced in the currency most of them use count, and shops paid in items are left out. Trades made before this overview existed carry no price and are not counted.

## Market ⭐

`/chestshop market` lists every item that is in a chest shop once, with the cheapest shop selling it and the shop paying the most for it, both for one piece, and how many shops sell and buy it. Left-click an item to open [Find a Shop](#find-a-shop) for it. The **Order** button sorts by the number of shops, by name, or cheapest first. The same item priced in two currencies shows as two entries, and shops paid in items, disabled shops and shops without a price are left out. It needs `phoenixshop.sign.find`, and the menu can be changed in menus/chest-shops/market.yml.

## Edit By Command

Look at a chest shop's sign or container and run `/chestshop editor` to open its [editor](edit-player-shop.md), or change it without opening the editor:

| Command | Changes |
| --- | --- |
| `/chestshop price <buy\|sell> <price>` | The [Buy Price](edit-player-shop.md#buy-price) or [Sell Price](edit-player-shop.md#sell-price). |
| `/chestshop amount <amount>` | The [Amount](edit-player-shop.md#amount). |
| `/chestshop mode <buy\|sell\|both>` | The [Mode](edit-player-shop.md#mode). |
| `/chestshop name <name>` | The [Name](edit-player-shop.md#name), `-` clears it. |
| `/chestshop discount <percent> <length>` | Starts a [Discount](edit-player-shop.md#discount), such as `20 2h`; `off` ends it. |

Only the owner, or a player with `phoenixshop.sign.admin`, can use them, and they need `phoenixshop.sign.create`. When an admin changes another player's shop this way, the owner is told who changed what if they are online; add `-s` at the end, such as `/chestshop discount 20 2h -s`, to change it without telling them. The same checks as the editor apply, so a price outside the [Price Limits](settings.md#price-limits) is refused with the reason.

## Player Shops Editor

**Chest Shops** on the main editor menu first asks for **Player Shops**, **Admin Shops** or the server-wide [Settings](settings.md). The first two list every shop of that type on the server, including imported shops still waiting for their chunk to load. Its Status toggle turns player shops on or off. Filter the list by mode, or by text in the item, owner or shop name. From there an admin can open any shop's editor, teleport to it, take a copy of its item, or remove it, with the usual refund rules. The shop editor opened from here leaves out the Admin Shop toggle.

<figure><img src="../../.gitbook/assets/chest-shops/player-shops-editor.png" alt="" width="563"><figcaption><p>Player Shops (Iron Ingot)</p></figcaption></figure>

Each entry also shows whether a custom item from Nexo, ItemsAdder, MMOItems or another supported item plugin still matches that plugin's current version of it. **Outdated** means the plugin changed the item after the shop was made. Trades still work, since custom items match by id, but the shop's sign, display and menus keep showing the old copy. **Item or plugin missing** means the plugin no longer has that item, or the item carries the tags of a plugin that is not installed. Not every item plugin leaves such tags, so an item from an uninstalled plugin can still show as up to date. An item payment is checked the same way. When the shop's chunk is loaded, the entry also counts the old copies sitting in its container; an ender chest shop is only counted while its owner is online. The Item Status filter narrows the list to outdated or missing shops.

Press the drop key (Q) on an outdated entry to replace the shop's item, and its payment item if that is outdated too, with the current version. The trade amount stays the same. Items already in the container are not touched.

## Transfer

An owner hands a shop to another player by looking at its sign or container and running `/chestshop transfer <player>`. It needs `phoenixshop.sign.transfer`, which everyone has by default. The new owner has to be online or have played on the server before, and the shop has to fit within their [limit](settings.md#max-per-player). For an offline player the Max Per Player setting counts, since their permissions cannot be read.

The shop keeps its item, prices, contents, name and history, and the sign shows the new owner. The new owner is taken off its staff, and sale notices still waiting for the old owner are dropped. A later [refund](settings.md#refund-on-remove) goes to the new owner. Both players are told if they are online.

With `phoenixshop.sign.admin`, an admin can transfer any shop they look at, whatever the new owner's limit, and `/chestshop transferall <from> <to>` moves every shop of one player to another. Admin shops cannot be transferred.

## Inactive Owners

With [Purge Inactive Days](settings.md#purge-inactive-days) above 0, the shops of owners who have not played for that many days are removed shortly after the server starts and once a day after that. Admin shops are never removed, and neither are the shops of online owners or of owners the server has no last-played time for. The sign is removed like any other removal, the container keeps everything inside it, and nothing is refunded. The console logs how many shops were removed.

`/chestshop purge [days]` shows how many shops would go, using the setting when no days are given. `/chestshop purge <days> confirm` removes them. It needs `phoenixshop.sign.admin`.

## Bulk Removal

Each of these commands first shows how many shops would go, and removes them when run again with `confirm`. They need `phoenixshop.sign.admin`.

| Command | Removes |
| --- | --- |
| `/chestshop clean [confirm]` | The shops in loaded chunks that sell to players and hold less than one trade. Admin shops and ender chest shops are skipped. |
| `/chestshop removeall <player> [confirm]` | Every shop that player owns. Admin shops are kept. |
| `/chestshop removeworld <world> [confirm]` | Every chest shop in that world, admin shops included. |

The sign is removed, the container keeps everything inside it, and nothing is refunded.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/player-shops