Grims Player Shops

This guide covers Grims Player Shops 0.4.2 (GrimsPlayerShop-0.4.2.jar) for Paper 26.3. It provides physical player shops, server-owned admin shops, real-world rental spaces, drop chests with virtual stock, and its own shop protection. Menus for phones and tablets are routed through Grims Client Checker.

Requirements

Required:

• Paper 26.3 build 194 on Java 25
• Grims Client Checker 0.3.1
• Floodgate
• Vault
• A Vault economy, such as EssentialsX Economy

Optional:

• LuckPerms for limits and admin-shop groups
• GriefPrevention can run alongside the plugin, but rental spaces always use Grims Player Shops' own protection

Plugin data is stored in:

plugins/GrimsPlayerShop/shops.db

Administrative activity is recorded in:

plugins/GrimsPlayerShop/audit.log

Back up both files before major updates or database maintenance.

Upgrading to 0.4.0

1. Stop the server and back up shops.db and audit.log.
2. Install Grims Client Checker 0.3.1. The shop plugin won't start without it.
3. Replace the old GrimsPlayerShop JAR with GrimsPlayerShop-0.4.0.jar.
4. Start the server. The database adds its new tables and columns on its own.

What changes for existing servers:

• config.yml gains limits.default-drop-chests-per-shop and the virtual-stock section with their defaults.
• Existing rental stalls and leases start as unfurnished, so renters keep the access they already paid for.
• The /gs ui command is gone. Players' old choices move to /gcc menu playershop on the first start, unless they already chose there.
• crossplay.bedrock-native-forms is no longer read. You can delete it.

Main permissions

playershop.admin.bypass is deliberately separate from playershop.admin because it lets staff change protected property.

Individual administrative permissions, all included in playershop.admin:

playershop.admin.inspect
playershop.admin.delete
playershop.admin.bank
playershop.admin.evict

Player limits

Default limits are set in config.yml:

limits:
  default-shops: 3
  default-items-per-shop: 12
  default-stock-chests-per-shop: 3
  default-helpers-per-shop: 2
  default-drop-chests-per-shop: 1

Use numbered permissions to grant higher limits:

playershop.limit.shops.5
playershop.limit.items.20
playershop.limit.stockchests.5
playershop.limit.helpers.4
playershop.limit.dropchests.2

Every category also accepts .unlimited, for example playershop.limit.dropchests.unlimited.

The highest granted number wins. Stock chest, drop chest, and helper limits apply to each shop, not across the player's account. Drop chests don't count toward the stock chest limit. A shop's drop chest limit follows its owner's permissions and refreshes when the owner joins.

Each potion, book, or gear variant is its own listing, so it counts toward items. Raise that limit if your shops sell many potion types.

Drop chests and virtual stock

A drop chest lets a shop hold many copies of a non-stackable item in one chest slot. Players attach a [Drop] wall sign to a chest or barrel within the link distance, then link it from Extra Stock Storage → Add Extra Storage. The full player steps are in the Player Wiki.

virtual-stock:
  items-per-slot: 64

items-per-slot is how many identical items one real chest slot can stand for: one real item plus up to 63 virtual copies at the default. Values from 1 to 1,000,000 are accepted, and 1 turns virtual counting off.

Sorting rules

• Sorting runs when the last viewer closes the drop chest.
• Only items with a maximum stack size of 1 are sorted. Stackable items stay in the drop chest.
• Items group only on an exact match: effects, enchantments, attribute modifiers, custom name, and durability.
• The first copy of an item takes a free slot in the shop or stock chests. More copies are added to that slot's virtual count until it reaches the limit. After that, the next copy takes another free slot.
• Items that can't be placed stay in the drop chest, and the player is told how many.
• A restock-locked shop doesn't sort. The player sees the lock reason.

Virtual copies are sold and withdrawn before the real item that anchors their slot. Purchases, withdrawals, and Stop Selling & Take Stock all include virtual stock.

Where virtual stock lives

Virtual counts are rows in shops.db (tables drop_chests and virtual_stock), not items in the world. Back up shops.db the same way you back up the world. Unlinking a drop chest leaves both its contents and the shop's virtual stock in place.

Audit entries: DROP_CHEST_LINKED, DROP_CHEST_UNLINKED, and DROP_CHEST_SORTED, which records how many items became virtual, went into chest slots, or stayed behind.

Administrative commands

Server status

/gs status
/gs reload

/gs status shows loaded shops, open shops, rental shops, and the active economy. /gs reload reloads supported configuration settings.

Economy

/gs economy
/gs economy auto
/gs economy <provider>

The first command lists the selected Vault economy and the available providers. auto picks the highest-priority provider.

Linked Floodgate players keep their stable Floodgate identity for ownership and records, while purchases are charged to the account Vault uses for their current session.

Shop inspection

/gs inspect

Waits 30 seconds for you to interact with a shop, then shows its owner, state, products, linked storage, drop chests and virtual stock total, helpers, limits, and location.

/gs inspect <player>

Shows that player's shops, helper roles, leases, identities, and client details from Grims Client Checker: device, OS, input, which shop menus they get, and their saved preference.

Rental inspection

/gs inspect rental
/gs inspect rental <online-player>

Your next block placement or break is cancelled and inspected instead. The plugin scans a 3×3×3 area around the target block:

• One matching stall shows that stall's details.
• No matching stall falls back to the rental shop's reservation.
• Several nearby stalls cancel the inspection and list each one.

Stall details include bounds, furnishing, paid-through date, renter identity, and a verdict for each action: place, break, and use. When the lease and the next term differ, both are shown, for example furnished (current lease unfurnished).

Adding an online player evaluates access as that player. Use it when a renter reports they can't build or open something.

Shop aliases

Player shops use readable references:

PlayerName#1
PlayerName#2

Admin shops use:

admin#1
admin#2

Staff never need to type database UUIDs.

Shop numbers aren't reused after deletion. Rental stall numbers may reuse the lowest vacant number without changing existing stalls.

Deleting a shop

Start an assisted deletion:

/gs admin delete

Or delete by alias:

/gs admin delete <player#shop> confirm

Example:

/gs admin delete Grim#2 confirm

Deletion removes the shop registration and its generated signs. Containers and merchandise stay in the world. Linked [Drop] signs go back to Not linked.

Virtual stock is turned back into real items in the shop and stock chests before deletion. If they don't fit, deletion is refused with the number of items waiting. Make room first. The plugin won't delete stock that has nowhere to go.

All administrative deletions are audited. A successful deletion records virtualStockReturned when virtual stock was converted.

Admin shops

Create an admin shop by attaching a sign to a chest and writing:

[AdminShop]
Optional Name

Eligible staff are set by LuckPerms groups:

admin-shops:
  enabled: true
  admin-groups:
    - owner
    - admin
  infinite-stock: true

Direct and inherited groups both count.

Admin shops:

• Are owned by the server
• Don't count toward player limits
• Have unlimited listed stock, so they don't link storage or drop chests
• Remove customer payments from circulation
• Keep a sales total that can't be withdrawn
• Can be managed or deleted by eligible administrators

View or reset the recorded bank:

/gs admin bank <admin#number>
/gs admin bank <admin#number> reset

Shop protection

Grims Player Shops protects:

• Main shop containers and shop signs
• Linked stock containers and their [Stock] signs
• Linked drop chests and their [Drop] signs
• Rental storefront signs
• Rental reservations and stalls

Protection covers opening without access, breaking, explosions, and pistons. Only the owner, helpers with stock access, and staff with playershop.admin.bypass can open a shop's containers, drop chests included. Linked stock and drop chests can't be broken until they're unlinked from the shop menu.

Hoppers are ignored on purpose. Handle unsupported hopper setups through normal moderation.

playershop.admin.bypass allows direct access and changes. Use it carefully, because some owner actions inside an occupied rental are audit logged.

Shop spacing

Regular shops must normally be at least 10 blocks apart.

Closer placement is allowed when the creator owns or helps run the existing shop. If that helper role is removed later:

• The affected shop isn't deleted.
• Buying and withdrawing still work.
• New stock deposits are locked, and its drop chests stop sorting.
• The owner is told to restore access or resolve the spacing conflict.

Rental shops reserve a configurable area, 25×25 by default, and can't be created near another shop.

Rental administration

Rental shops are created with [RentShop] or [Rental] on the first line of the sign.

Rental durations use real-world time.

Important default settings:

rentals:
  reserved-size: 25
  maximum-width: 25
  maximum-height: 16
  maximum-depth: 25
  maximum-volume: 5000
  grace-hours: 24
  safety-grace-hours: 1
  auto-renew-days-before: 3
  minimum-auto-renew-days: 7

The safety grace adds one hour after the configured grace period. It keeps an expiration check from interrupting a renter who is still collecting their belongings.

Furnished and unfurnished stalls

Owners set each stall's furnishing with the Furnished / Unfurnished toggle in Add Stall Space or when editing its terms. On touch forms it's a button in the same setup screen.

Furnishing is part of the lease terms, like price and duration. Each lease stores the furnishing it was paid under. Changing it on a leased stall only takes effect when the renter accepts the new terms at their next renewal. Auto-renew never accepts a change on its own. The change is audited as STALL_TERMS_CHANGED, and the renter is notified.

Owners can't delete an occupied stall or one in grace. Taking a stall off the market declines the next renewal but doesn't cancel time that's already paid.

Evicting a renter

/gs admin evict <player#shop> <stall#> confirm

Eviction:

• Ends the lease immediately
• Doesn't refund the renter
• Removes the stall from the storefront
• Gives the property owner control of everything left inside
• Notifies the renter
• Creates an audit entry

Use eviction only for moderation and recovery.

Menu routing and crossplay

Grims Player Shops doesn't detect clients itself. Grims Client Checker decides whether each player gets touch forms or inventory menus. The layouts themselves haven't changed.

Players choose for this plugin with /gcc menu playershop <auto|classic|mobile>, or for every Grims plugin with /gcc menu <mode>. Choices are saved by Grims Client Checker across logins, devices, and restarts.

Use /gs inspect <player> or /gcc check <player> to see the detected device, OS, input, and the menus that player gets.

Floodgate reports Android phones as keyboard and mouse, and iOS as unknown. Client Checker 0.3.1 routes phones and tablets by device type for that reason. On 0.3.0, phone players had to choose mobile by hand.

Pricing and sales

Price buttons are configurable:

shops:
  price-buttons: [50, 100, 500, 1000, 2500, 5000, 10000]
  sale-percent-buttons: [1, 5, 10, 25]
  purchase-quantities: [1, 2, 4, 8, 16, 32]
  even-price-button-alignment: left

You can add more price values. Up to nine are shown. With an even number of price buttons, change left to right to set their menu alignment.

Sales are percentage discounts. A 25% sale makes a $100 product cost $75. A positive price never drops below one currency unit.

Prefix and console banner

The chat prefix supports MiniMessage, gradients, and hex colors:

messages:
  prefix: '<gradient:#C37AFF:#8C00FF:#FF00FF>[GrimsPlayerShop]</gradient> '

A simpler prefix may suit Bedrock-heavy servers.

console-banner: auto

Available modes: auto, retro, basic, plain, and off.

Troubleshooting checklist

When a shop fails:

1. Run /gs status.
2. Confirm Vault has an active economy provider.
3. Run /gs inspect and select the shop.
4. For rental access, run /gs inspect rental <player> and read the place, break, and use verdicts. Check whether the stall is furnished.
5. Check whether the shop is closed or restock-locked.
6. Confirm linked storage is loaded and still exists.
7. Check the player's limits and helper permissions.
8. Review audit.log for recent changes.
9. Check the server console for database or economy errors.
10. Back up shops.db before any manual database repair.

Common questions