Shop — Server Owner Guide

A complete GUI shop system for Rust with categorized item stores, a player-to-player marketplace, live auctions, direct trading, dynamic pricing, NPC vendors, vending machine terminals, and deep analytics — all powered by EconomyCore. Plugin by TheOwlSky | gameservershub.com | Discord

Table of Contents

1. Quick Start

2. Permissions

3. Player Commands

4. Admin Commands

5. Console Commands

6. Configuration Reference

7. How the Shop Works

8. How the Marketplace Works

9. How Auctions Work

10. How Trading Works

11. How Dynamic Pricing Works

12. NPC Vendors & Vending Machines

13. Discord Webhooks

14. MySQL Setup

15. CUI / UI Overlay

16. API for Other Plugins

17. Language / Messages

18. Tips & Recommendations

19. Troubleshooting

20. Frequently Asked Questions

1. Quick Start

1. Install required dependency: EconomyCore plugin

2. Optional: Install ImageLibrary for item icon images

3. Drop Shop.cs into your carbon/plugins/ folder

4. Config auto-generates at carbon/configs/Shop.json

5. Grant permissions:

   oxide.grant group default shop.use
   oxide.grant group default shop.sell
   oxide.grant group default shop.marketplace
   oxide.grant group default shop.auction
   oxide.grant group default shop.trade
   oxide.grant group admin shop.admin

6. Players open the shop with /shop or /s in-game

7. On first load, Shop auto-fills items from all Rust items if no categories exist

That's it. MySQL, Discord webhooks, NPC vendors, and dynamic pricing are optional enhancements.

2. Permissions

Grant with: oxide.grant user <steamid> <permission> or oxide.grant group <group> <permission>

Player Permissions

Staff Permissions

Special Permissions

Discount & cooldown permissions are defined in config — Shop registers them automatically.

Typical setup:

oxide.grant group default shop.use
oxide.grant group default shop.shop
oxide.grant group default shop.sell
oxide.grant group default shop.marketplace
oxide.grant group default shop.marketplace.list
oxide.grant group default shop.auction
oxide.grant group default shop.auction.create
oxide.grant group default shop.trade
oxide.grant group admin shop.admin
oxide.grant group moderator shop.setnpc
oxide.grant group moderator shop.setvm

3. Player Commands

Shop

Marketplace

Auctions

Trading

4. Admin Commands

All admin console commands require shop.admin permission (or server console).

5. Console Commands

Import Formats

Stats Commands (MySQL Required)

6. Configuration Reference

Shop's config file lives at carbon/configs/Shop.json. Sections are grouped below.

General Settings

Sound effects are configurable for open, purchase, and error events using Rust prefab paths.

Shop Settings

Sell Terminal Settings

Restriction Settings

Marketplace Settings

Auction Settings

Trade Settings

Dynamic Pricing

Discount Permissions

Define custom discount tiers in config. Each entry has:

• Permission — registered automatically (e.g., shop.vip.10)

• Discount Percent — percentage off buy prices

• Priority — highest priority wins when a player has multiple

Cooldown Overrides

Define permission-based cooldown multipliers:

• Permission — registered automatically

• Global Cooldown Multiplier — multiplied against global cooldown

• Item Cooldown Multiplier — multiplied against per-item cooldowns

UI Theme

Shop's entire color scheme is configurable. All values use Rust's RGBA format ("R G B A" from 0-1). Key colors:

All theme colors — header, cards, text, notifications, scrollbar, border, and bottom bar — are customizable.

Image Settings

Logging Settings

7. How the Shop Works

Shop is a full-screen GUI with five tabs: Shop, Marketplace, Auctions, Sell, and Trade. Players open it with /shop and browse categorized items.

Browsing & Purchasing

1. Players select a category from the sidebar

2. Items display in grid or list view with prices, stock status, and sale badges

3. Clicking an item opens an item detail modal with full info

4. Players choose a quantity using quick-select presets or custom input

5. Click Buy for instant purchase or + Cart to add to cart

6. Checkout processes all cart items in one transaction

Item Types

Shop supports three item types:

• Item — a standard Rust item (with optional skin, attachments, ammo, plant genes, or container contents)

• Command — executes a server command on purchase (for kits, VIP, custom rewards)

• Kit — grants a predefined kit

Stock System

When Enable Stock System is true, each item can have limited stock:

• Stock depletes on purchase

• Auto-restocks at a configurable interval and amount

• Stock resets on wipe if Auto Wipe Reset Stock is enabled

Buy Limits

Each item can enforce limits per player:

• Daily Limit — resets every 24 hours

• Wipe Limit — resets on server wipe

• Lifetime Limit — permanent across all wipes

• Min/Max Per Transaction — quantity bounds per single purchase

Cooldowns

• Global Cooldown — minimum time between any two shop actions (default 0.5 seconds)

• Per-Item Cooldown — configurable per item in seconds

• Both can be reduced with cooldown override permissions

Discounts & Sales

• Permission-based discounts — VIP tiers with automatic percentage off

• Category discounts — percentage off all items in a category

• Timed sales — scheduled sales affecting specific items or categories, with recurring options (daily, weekly, monthly, every wipe)

• Bulk discounts — automatic discounts at quantity thresholds

• First-purchase discounts — one-time discount per item per player

Wipe Behavior

On server wipe, Shop can automatically reset:

• Stock levels, cooldowns, buy limits

• Marketplace listings and auctions

• Player favorites

• Dynamic price data

All wipe behaviors are individually configurable.

8. How the Marketplace Works

The marketplace lets players list their own items for sale to other players.

1. Seller opens the Marketplace tab and clicks Create Listing

2. Selects an item from inventory, sets a price and currency

3. The item is removed from inventory and listed publicly (or privately with a share code)

4. Buyer browses listings, searches by name or seller, and purchases

5. Seller receives payment minus the listing tax (default 5%)

6. Listing expires after the configured duration if unsold

Private listings are hidden from browse — only accessible via /market code <CODE>.

Blacklisted items cannot be listed. Max active listings are controlled by permission (shop.marketplace.limit.5 through .50).

9. How Auctions Work

Auctions let players sell items to the highest bidder.

1. Seller creates an auction with a starting bid, optional buyout price, and duration

2. Bidders place bids that must exceed the current bid by the minimum increment (default 5%)

3. Anti-snipe protection extends the auction by 2 minutes if a bid arrives near the end

4. When the auction ends, the highest bidder receives the item and the seller receives payment minus tax

5. If a buyout price is set, any bidder can instantly win the auction at that price

6. Auctions with no bids end as NoBids and the item returns to the seller

Bid history is tracked and viewable in the UI.

10. How Trading Works

Shop includes direct player-to-player trading with a split-screen trade window.

1. Player A types /trade PlayerB

2. Player B receives a trade request and types /trade accept

3. Both players see a trade window with two sides

4. Each side can add items (up to 8) and currency from any EconomyCore currency

5. Both players click Ready, then Confirm

6. Items and currency swap atomically — if either side fails, the trade rolls back

Restrictions:

• Players must be within Max Distance meters (default 50)

• Trade auto-cancels after Trade Timeout Seconds (default 120)

• If either player disconnects, the trade cancels and items return

11. How Dynamic Pricing Works

When enabled, item prices fluctuate based on supply and demand.

How it calculates:

• Final Price = (Base Price × Base Weight) + (Base Price × Demand Multiplier × Demand Weight)

• Demand is calculated from purchases and sales within the Demand Window (default 24 hours)

• Prices change by at most Price Change Rate per update cycle (default 5%)

• Prices never drop below Price Floor (50% of base) or rise above Price Ceiling (200% of base)

Price trends are tracked as up, stable, or down — visible in the UI and available via API.

Dynamic pricing must be enabled per-item in the item data (Dynamic Pricing Enabled: true on each price entry).

12. NPC Vendors & Vending Machines

NPC Vendors

Link HumanNPC NPCs as shop vendors:

1. Spawn an NPC using the HumanNPC plugin

2. Look at the NPC and run: shop.setnpc "Merchant" 1 2 3 (name + category IDs)

3. Players interact with the NPC to open the shop filtered to those categories

Each NPC vendor can have:

• Custom name and category filters

• Price/sell multipliers — adjust all prices up or down

• Allowed currencies — restrict which currencies are accepted

• Required permission — limit who can use this vendor

Vending Machines

Link in-world vending machines as shop terminals:

1. Look at a vending machine and run: shop.setvm "Shop Terminal" 1 2 3

2. Players interact with the vending machine to open the shop

3. Unlink with shop.unsetvm

Vending machine links support the same multipliers, currency restrictions, and permissions as NPC vendors.

13. Discord Webhooks

Enable Discord notifications for shop events.

{
  "Discord Webhook": {
    "Enabled": true,
    "Webhook URL": "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL",
    "Purchase Notifications": true,
    "Sale Notifications": true,
    "Admin Action Notifications": true,
    "Error Notifications": true,
    "Marketplace Notifications": true,
    "Auction Notifications": true,
    "Trade Notifications": false,
    "Embed Color (decimal)": 4437377,
    "Discord Timestamp Format": "F"
  }
}

14. MySQL Setup

Shop optionally stores analytics and transaction history in MySQL/MariaDB. All gameplay data works without MySQL — it only adds analytics and multi-server insights.

Configuration

{
  "MySQL Settings": {
    "Enabled": true,
    "Host": "localhost",
    "Port": 3306,
    "Database": "gshshop",
    "Username": "root",
    "Password": "",
    "Table Prefix": "gshshop_",
    "Server ID": "server1",
    "SQL Batch Size": 50,
    "SQL Flush Interval Seconds": 10,
    "Max Pending Operations": 500,
    "Analytics Enabled": true,
    "Behavior Tracking Enabled": true,
    "Behavior Tracking Detail Level": "Standard",
    "Analytics Retention Days": 90,
    "Behavior Retention Days": 30,
    "Price History Retention Days": 60,
    "Whale Spending Threshold": 10000.0
  }
}

Database Tables

Requirements: MariaDB 10.6 LTS recommended. Avoid 10.10+ due to a known InvalidCastException bug.

Multi-server: Set a unique Server ID per server. All tables are keyed by server ID, so multiple servers can share one database.

Behavior Tracking Detail Levels:

• Minimal — sessions and transactions only

• Standard — adds item popularity, category analytics, search tracking

• Detailed — adds individual session events and granular click tracking

Retention: Old data is automatically purged based on the configured retention days.

15. CUI / UI Overlay

Shop uses a full-screen CUI overlay with multiple layers:

┌──────────────────────────────────────────────────────────┐
│ [Logo]  SHOP | MARKETPLACE | AUCTIONS | SELL | TRADE  [X]│  ← Header + Tabs
│  Balance: 1,250 Cash                     [🔍 Search...] │  ← Balance + Search
├────────┬─────────────────────────────────────────────────┤
│        │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐     │
│ Weapons│  │ AK  │ │ M4  │ │ LR  │ │ SAR │ │ MP5 │     │
│ Tools  │  │$500 │ │$450 │ │$350 │ │$200 │ │$300 │     │
│ Attire │  │[Buy]│ │[Buy]│ │[Buy]│ │[Buy]│ │[Buy]│     │
│ Medic  │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘     │
│ Ammo   │                                                │
│ Food   │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐     │
│ Build  │  │ ...more items...                      │     │
│        │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘     │
├────────┴─────────────────────────────────────────────────┤
│ [◄ Prev]  Page 1 of 5  [Next ►]    [🛒 Cart (3)]       │  ← Pagination + Cart
├──────────────────────────────────────────────────────────┤
│ GAME SERVERS HUB                    gameservershub.com   │  ← Bottom Bar
└──────────────────────────────────────────────────────────┘

Key UI elements:

• Tab bar — Switch between Shop, Marketplace, Auctions, Sell, and Trade

• Sidebar — Category list with icons and item counts

• Content area — Grid or list view with item cards showing name, price, stock, sale badges

• Item detail modal — Full item info, quantity selector with presets, buy/cart buttons

• Cart panel — Slide-out cart with item list, totals, and checkout button

• Quantity selector — Quick presets (1, 5, 10, 25, 50, 100) + custom input + max affordable

• Confirmation dialogs — Purchase and sell confirmations with totals

• Toast notifications — Success, error, warning, and info popups

• Search bar — Context-aware search (items, listings, auctions, players)

• Sort controls — Name, price ascending/descending, newest, most popular

The UI auto-destroys when the player closes the shop, disconnects, or dies.

16. API for Other Plugins

Other plugins can interact with Shop using [PluginReference]:

[PluginReference] private Plugin Shop;

Shop Control

// Open the shop for a player
Shop?.Call<string>("API_OpenShop", player);

// Open a specific tab ("Shop", "Marketplace", "Auctions", "Sell", "Trade")
Shop?.Call<string>("API_OpenShopTab", player, "Marketplace");

// Close the shop
Shop?.Call("API_CloseShop", player);

// Check if a player has the shop open
bool isOpen = Shop?.Call<bool>("API_IsShopOpen", player.userID) ?? false;

Pricing

// Get buy/sell prices for an item
double buyPrice = Shop?.Call<double>("API_GetBuyPrice", "rifle.ak", "cash") ?? -1;
double sellPrice = Shop?.Call<double>("API_GetSellPrice", "rifle.ak", "cash") ?? -1;

// Get dynamic buy price (includes demand multiplier)
double dynPrice = Shop?.Call<double>("API_GetDynamicBuyPrice", "rifle.ak", "cash") ?? -1;

// Get price trend (-1 = falling, 0 = stable, 1 = rising)
int trend = Shop?.Call<int>("API_GetPriceTrend", "rifle.ak", "cash") ?? 0;

Stock & Inventory

// Check if an item is in stock
bool inStock = Shop?.Call<bool>("API_IsInStock", "rifle.ak") ?? false;

// Get current stock level (-1 if stock system disabled)
int stock = Shop?.Call<int>("API_GetStock", "rifle.ak") ?? -1;

Force Transactions

// Force a purchase (deducts currency, gives item)
var result = Shop?.Call<Dictionary<string, object>>("API_ForceBuy", player.userID, "rifle.ak", 1, "cash");
// result["Success"] = true/false, result["TotalCost"], result["Error"]

// Force a sale (takes item, deposits currency)
var result = Shop?.Call<Dictionary<string, object>>("API_ForceSell", player.userID, "rifle.ak", 5, "cash");
// result["Success"], result["TotalPayout"], result["AmountSold"], result["Error"]

Marketplace & Auctions

// Create a marketplace listing programmatically
string listingId = Shop?.Call<string>("API_CreateListing", sellerId, "rifle.ak", 1, 0UL, "cash", 500.0);

// Get active listing/auction counts
int listings = Shop?.Call<int>("API_GetActiveListingCount", player.userID) ?? 0;
int auctions = Shop?.Call<int>("API_GetActiveAuctionCount", player.userID) ?? 0;

Trading

// Check if a player is in a trade
bool inTrade = Shop?.Call<bool>("API_IsInTrade", player.userID) ?? false;

// Initiate a trade between two players
Shop?.Call("API_OpenTrade", initiator, target);

Other

// Get a player's preferred currency
string currency = Shop?.Call<string>("API_GetPlayerCurrency", player.userID);

// Get currently active sales
var sales = Shop?.Call<Dictionary<string, object>>("API_GetActiveSale");

// Get linked vending machine count
int vmCount = Shop?.Call<int>("API_GetLinkedVendingMachineCount") ?? 0;

17. Language / Messages

Lang file: carbon/lang/en/Shop.json

Shop includes approximately 290 lang keys across all 10 supported languages: English, Russian, Spanish, German, Portuguese (BR), French, Chinese (Simplified), Turkish, Polish, and Korean.

Message categories:

• ui.* — All UI labels, buttons, tabs, and tooltips

• msg.* — In-game chat messages and notifications

• err.* — Error messages (no permission, insufficient funds, out of stock)

• admin.* — Admin command responses and stats output

• market.* — Marketplace-specific messages

• auction.* — Auction-specific messages

• trade.* — Trade-specific messages

Key messages:

18. Tips & Recommendations

Getting Started

• Start with auto-fill: Let Shop populate items on first load, then customize categories and prices

• Import from other plugins: If migrating from Mevent Shop, ShoppyStock, ShopUI, or ServerRewards, use shop.import <format> to bring your items over

• Set up categories first: Organize items into logical groups — players browse by category

Tuning the Economy

• Sell ratio: Default Sell Price Ratio: 0.5 means players get 50% back when selling. Lower to 0.3 for a tighter economy, raise to 0.7 for casual servers

• Use shop.fill.prices 0.4 to bulk-set all sell prices at 40% of buy price

• Dynamic pricing: Enable for a living economy. Set Price Floor: 70 and Price Ceiling: 150 for moderate swings, or 50/200 for volatile markets

• Bulk discounts: Add tiers like {MinQuantity: 10, DiscountPercent: 5} and {MinQuantity: 50, DiscountPercent: 10} to encourage larger purchases

Marketplace & Auctions

• Tax rate: 5% is balanced. Lower to 2-3% for active markets, raise to 8-10% to act as a currency sink

• Anti-snipe: 2 minutes is standard. Raise to 5 for high-value auctions

• Zero-result searches: Use shop.stats zero to find items players are searching for but can't find — then add them

Performance

• Shop uses dynamic hook subscription — NPC and vending machine hooks are only active when vendors exist

• Auto-save runs every 5 minutes by default

• MySQL operations are batched and flushed every 10 seconds to minimize database calls

• All timers are properly destroyed on plugin unload

Multi-Server

• Set unique Server ID values per server in MySQL config

• All servers can share one MySQL database

• Player profiles and analytics are keyed by server ID

19. Troubleshooting

Shop not opening

• Verify the player has shop.use permission: oxide.show user <steamid> shop.use

• Check if restrictions are blocking: combat, raid, building blocked, mounted, swimming

• If EconomyCore is not loaded, the shop waits for it — check carbon/logs/ for errors

"Economy not ready" message

• Shop requires EconomyCore to be loaded and initialized first

• Verify EconomyCore is in carbon/plugins/ and has no errors

• Shop checks for economy readiness on server init and retries periodically

Items not showing

• Check that the item is Enabled: true in shop data

• Verify the item's category is enabled and the player has access

• If using NPC vendors, check that the vendor's category list includes the item's category

MySQL not connecting

• Verify host, port, username, and password in config

• Use MariaDB 10.6 LTS — avoid 10.10+ (known InvalidCastException bug)

• Check firewall rules allow the connection

• Look for connection errors in carbon/logs/

Marketplace listings disappearing

• Listings expire after Default Listing Duration Hours (default 48 hours)

• Listings are wiped on server wipe if Auto Wipe Reset Marketplace is true

• Check if the item is blacklisted in Blacklisted Items

Trade not working

• Both players need shop.trade permission

• Trade Settings > Enabled must be true

• Players must be within Max Distance meters of each other

• Trades timeout after Trade Timeout Seconds of inactivity

20. Frequently Asked Questions

What does Shop do?

Shop is a full-featured GUI store plugin for Rust servers running Carbon or Oxide. It provides a categorized item shop, player-to-player marketplace, live auction system, direct trading, dynamic pricing, NPC vendor support, and deep analytics with MySQL — all integrated with EconomyCore for multi-currency support.

How do I install Shop?

Drop Shop.cs into your carbon/plugins/ folder alongside EconomyCore. The config generates automatically at carbon/configs/Shop.json. Grant shop.use to all players and shop.admin to staff. On first load, Shop auto-fills items from all Rust items.

Does Shop work with both Carbon and Oxide?

Yes. Shop uses the standard RustPlugin base class and is fully compatible with both Carbon and Oxide/uMod servers. It uses Oxide-compatible APIs for maximum compatibility.

Can I import items from other shop plugins?

Yes. Shop supports importing from Mevent Shop, ShoppyStock, ShopUI, and ServerRewards using shop.import <format>. Items and categories are imported with their prices preserved.

Where can I get support for Shop?

Join the Game Servers Hub Discord at https://discord.gg/gsh or visit https://gameservershub.com for documentation, updates, and direct support from TheOwlSky.

Shop v1.5.0 — Developed by TheOwlSky | gameservershub.com | Discord