KyuubiSoft Player Shops v1.2.0

▸ What is Player Shops?

A complete player marketplace for your Hytale server. Players spawn their own NPC shopkeepers, stock them via real drag-and-drop, set buy/sell prices, and earn while offline. A public directory lets buyers find shops by name, category or item search. Hand-curated rental stations turn map hotspots into a competitive marketplace - fixed-price slots or full timed auctions with anti-sniping.

Works standalone - no other plugins required. Just needs a VaultUnlocked-compatible economy provider (e.g. Ecotale).



▸ Features

Standalone NPC Shops

• /ksshop create <name> spawns an interactive NPC at the player's position
• Each shop has its own NPC with the owner's skin (auto-fetched via PlayerDB)
• Customizable nameplate, look-at-player rotation, configurable interaction range
• F-key to open the shop - same UX as any vanilla NPC

Drag-and-Drop Editor

• Native ItemGrid editor with three connected grids: shop, inventory, hotbar
• Per-slot pricing: separate buy + sell, daily quota, stock cap, mode (Buy / Sell / Both)
• Item layouts are preserved - place a sword in slot 10 and buyers see it in slot 10
• 24-tile shop icon picker for the directory card
• NPC skin field with live Apply Skin button
• Sub-tabs: Settings, Pricing, Revenue, History

Public Directory

• /ksshop browse opens a card grid with all listed shops
• Filters: All / Player / Admin / Featured tabs, category dropdown, rating, sort
• Each card shows shop avatar, owner, rating, item count, distance, listing time
• /ksshop search <query> - find items across every shop at once
• /ksshop visit <name> opens any shop directly without walking to it

Rental Stations - Fixed Mode

• Admin places persistent leasable shop slots at fixed map positions
• Players F-key the slot, pick days via slider, pay price * days
• Slot is theirs for the rented window - they fill it like any other shop
• On expiry, items + balance auto-mailed back via the mailbox system
• Self-service /ksshop myrentals page with EXTEND + RELEASE EARLY actions

Rental Stations - Auction Mode

• Timed bidding rounds for hotspot slots - spawn plaza, dungeon lobby, etc
• Live countdown, current high bid, bid history, slider with min/max clamping
• Anti-sniping - bids in the last 30 seconds extend the auction by 30 seconds
• One-shot ending-soon broadcast warns the world before close
• Outbid notifications via chat to displaced bidders
• Auto-restart between rounds - the hotspot stays competitive forever
• Bids are NOT charged at bid time - only the final winner pays

Paid Directory Listings

• Player shops require a paid listing to appear in the public directory
• Configurable price * day - economy sink that scales with player base
• One-time free trial on first shop creation (persistent flag, can't be gamed)
• Buy or extend directly from the shop editor - slider + live cost + button
• Permission shortcuts for ranks: ks.shop.list.permanent, ks.shop.list.free

Mailbox Integration

• Items + balance from expired rentals are mailed back to the renter
• Offline sales accumulate in the owner's mailbox until they collect
• BSON metadata preserved - enchanted items survive the round-trip
• Force-deleted shops mail their contents back to the owner automatically

Tax + Featured + Admin Tools

• Optional buy-tax + sell-tax with configurable recipient (server / named player)
• Featured Shops - admin promotion or auto-feature for top-rated high-volume sellers
• Item blacklist (live-editable) - block certain items from any shop
• Full admin panel UI - tabs for Shops, Players, Transactions, Rentals
• Force-close / force-delete / settax / reload commands
• /kssa respawnnpcs recovers stuck NPCs without server restart

Shop Transfer (Player-to-Player)

• /ksshop transfer <shop> <player> sends a transfer request
• Target accepts via /ksshop accepttransfer or rejects via declinetransfer
• Both sides notified, 60-second expiry, no silent ownership transfers

Persistence + Performance

• SQLite by default - or MySQL if you prefer (configurable)
• Auto-save every 60 seconds with dirty-flag tracking (only modified shops written)
• Periodic NPC orphan-sweep prevents chunk-restored ghost duplicates
• NPC spawn delay on first-player-join (3s default) so client cosmetics init before skins push
• Skin retry on transient PlayerDB failures - rare hiccups don't leave NPCs naked
• Per-world skin refresh on re-entry - chunk-restored NPCs get their skins back automatically

Permissions System

• Granular LuckPerms permissions for create / edit / browse / rate / collect
• Per-rank limits: ks.shop.limit.shops.N, ks.shop.limit.items.N, ks.rental.limit.N
• Wildcard sentinel - OPs don't silently inherit permanent listings or unlimited shops
• Listing perks: ks.shop.list.permanent (forever), ks.shop.list.free (no charge)

Localization

• 9 languages shipped out of the box
• English, German, French, Spanish, Portuguese, Russian, Polish, Turkish, Italian
• Auto-versioned migration system - your custom strings survive plugin updates

▸ Player Commands

• /ksshop create <name> - spawn a shop NPC at your position
• /ksshop edit - drag-and-drop editor for the nearest owned shop
• /ksshop browse - open the public directory
• /ksshop search <query> - search items across all shops
• /ksshop visit <name> - open any shop directly
• /ksshop list <days> - buy or extend a directory listing
• /ksshop myshops - your owned shops
• /ksshop myrentals - active rentals with extend / release-early
• /ksshop rentalstations - browse rental slots in current world
• /ksshop transfer <shop> <player> - transfer ownership (with target consent)
• /ksshop rate <shop> <stars> - rate a shop 1-5 stars
• /ksshop stats / history / collect / deposit

▸ Admin Commands

• /kssa admin - open the full admin panel UI
• /kssa createadmin / editadmin / deleteadmin - admin shop management
• /kssa createrental <name> [price] [days] - fixed-price slot
• /kssa createrentalauction <name> [minBid] [step] [minutes] [days] - auction slot
• /kssa forceexpirerental <slotId> - end any rental immediately (refunds via mail)
• /kssa deleterental / listrentals
• /kssa feature <shop> <days> - promote a shop
• /kssa settax <percent> - live tax adjustment
• /kssa blacklist <add|remove|list>
• /kssa respawnnpcs / deletenearest / reload

▸ Configuration

Everything tunable in config.json:

• Max shops per player + max items per shop (configurable per-rank)
• Creation cost, listing prices, free-trial days
• Tax percentages + recipient
• NPC spawn delay, skin retry behavior, look-at-player toggle
• Rental defaults (price, days, min bid, auction duration, anti-sniping window)
• Featured shop costs + auto-feature thresholds
• Database (SQLite or MySQL)
• Item blacklist (live-editable via /kssa blacklist)
• Shop categories with custom icons

▸ Requirements

• Hytale Server (Update 3+)
• Java 25
• VaultUnlocked + an economy provider (Ecotale recommended)
• Optional: KyuubiSoft Core (additional features)
• Optional: LuckPerms (recommended for the permission system)

▸ Documentation

Full wiki with command reference, configuration guide, rental flow deep-dive, FAQ:
wiki.kyuubisoft.com/hytale/player-shops



▸ Support

Questions or issues? Join our Discord: dc.gg/kyuubisoft