Actions

create-playershop

Creates a shop on the container the executor is standing at, wrapping ShopService#create.

If town-economy is true, the action looks up the town at location and requires the executor to hold BANK_WITHDRAW there; if there is no town or the check fails, it sends NO_WITHDRAWAL_PERMISSION and stops — no shop is created, and ShopService#create is never called. If town-economy is false this check is skipped at the action level, but ShopService#create unconditionally requires the block to sit inside a town regardless of town-shared/town-economy (sends AstralTown's ERROR_OCCURRED otherwise) and separately re-validates the owner's shop limit, that no shop already exists at that location, and fires the cancellable PlayerShopCreateEvent — see Shops and Developer API. On success the action sends SHOP_CREATED with the item and %price% substituted; on an unexpected exception it logs the error and sends CREATION_FAILED. If ShopService#create itself rejects the shop (limit reached, duplicate location, cancelled event), it has already messaged the player and the action sends nothing further.

edit-playershop

Updates an existing shop's price, type, town-shared flag, and economy routing, wrapping ShopService#update.

Requires shop.hasPermission(executor) — true for the shop's owner, for a playershops.admin holder, or (since the check is the same one interaction/edit/manage all share) for any town member holding USE_PLAYER_SHOPS if the shop is already town-shared. Failing that sends NOT_OWNER. If town-economy is true, it separately requires the executor to hold the town's BANK_WITHDRAW at the shop's location (NO_WITHDRAWAL_PERMISSION otherwise) — same guard as create-playershop. Passing both checks, the action applies an optimistic update: it writes the new price/type/town-shared directly onto the in-memory PlayerShop, and either resolves the shop's town UUID as the new economyAccount (when town-economy is true) or clears economyAccount to null (routing sales to the owner's own balance) — all before the database write completes. If ShopService#update fails, all four fields are rolled back to their pre-edit values, the error is logged, and SHOP_UPDATE_FAILED is sent. On success, ShopService#refreshShop runs (updates the sign/hologram) and SHOP_UPDATE_SUCCESS is sent with the shop placeholder.

buy-playershop-item

Buys amount units from shop, on behalf of the executor.

Calls ShopService#buy(player, shop, shop.location().getBlock(), amount) directly — the same overload InteractionListener drives when a non-owner right-clicks a BUY-type shop, which opens the "playershops-buy" menu that this action is typically wired into. The action performs no clamping itself: a non-positive amount is a silent no-op, and ShopService#buy re-validates the chest still holds at least amount, transfers price * amount from the buyer to shop.economyAccount(), re-checks stock again on the main thread, removes the items (custom-item aware via ContainerUtils), delivers them to the player (falling back to the mailbox if their inventory is full), refreshes the sign, sends PURCHASE_SUCCESS, notifies the owner with BUY_NOTIFICATION if their recap preference is enabled, and records the sale — see Shops and Activity Recaps.

sell-playershop-item

Sells up to amount units of shop's item, out of the executor's inventory, into shop.

Unlike buy-playershop-item, this action clamps before calling the service: it first caps amount down to how many matching items the executor's inventory actually holds, then — back on the main thread — checks the chest has enough empty capacity for that (already inventory-clamped) amount; if it doesn't, it sends CHEST_FULL and aborts entirely rather than selling a partial quantity. Only then does it call ShopService#sell(player, shop, chestBlock, finalAmount) — the same overload the "playershops-sell" menu uses — which independently re-validates chest space and inventory count before transferring funds and items.

open-playershops-container

Opens the shop's backing container inventory for the executor.

Looks up the shop by UUID via ShopService#findByUniqueId, resolves the block at the shop's stored coordinates in the executor's current world, and opens its inventory if that block is a Container (chest, barrel, shulker box, etc.). If the shop id doesn't resolve, or the block is no longer a container, sends UNEXPECTED_ERROR. There is no ownership check in the action itself — gate access through the menu button's own requirements (this action is the natural fit for a management button inside the "playershops-main" menu, which is only opened for players shop.hasPermission already approved — see InteractionListener).

open-playershops-transactions

Opens the shop's transaction history menu for the executor.

Looks up the shop by UUID via ShopService#findByUniqueId and, if found, calls MenuService#openTransactionHistoryMenu, which loads the shop's transactions and opens the "playershops-history" menu with shop and transactions in its context. If the shop id doesn't resolve, sends UNEXPECTED_ERROR. As with open-playershops-container, there is no permission check in the action itself.

toggle-playershops-recap

Toggles the executor's away-recap notification preference. No arguments.

Registered globally (see above), so this is callable from any plugin's menu/dialog configuration, not just AstralPlayerShops's own. Looks up the executor's PSPlayerData via SyncAPI#findData; if present, flips recapEnabled and sends RECAP_ENABLED or RECAP_DISABLED to match the new state. If the player's synced data isn't loaded, sends UNEXPECTED_ERROR instead. The resulting state is exposed back for rendering a toggle button via %playershops_recapNotification% — see Placeholders and Activity Recaps.

Action Summary Table

See also

• AstralCore Actions — the [action-id] <argument> <param=value> syntax and global delay/async parameters shared by every action on the network.

• Shops — the creation, buy/sell, and editing mechanics these actions wrap.

• Activity Recaps — the recap preference toggle-playershops-recap flips.

• Placeholders — %shop%/%shop_*%, %playershops_recapNotification%, and the other context placeholders these actions consume.

• Developer API — PlayerShopCreateEvent and friends, fired underneath create-playershop.

• Commands — playershops.admin, which also bypasses the edit-playershop ownership check.