Shop System
Overview
A drop-in shop UI for any Roblox game. Server-authoritative purchases with full validation. Multi-currency from day 1 — in-game currencies (via CoreShun Currency System) plus Robux Developer Products and Roblox Gamepasses. Three layouts (Grid, List, Tabbed) and six themes toggleable from one config flag. DataStore-persistent ownership with session locks. Pure-scale UI — looks identical on phone, tablet, desktop, and console. Auto-detects CoreShun Currency, Toast, and Anti-Exploit at boot — no setup.
Drop in. One config file. Define items. Done.
Open source. Plain Luau. No obfuscation. Edit any file.
The Item Schema
Every item is a table in
Config.Items. Required fields: Id, Name, Price, Currency, Category. Everything else unlocks specific behaviors.- Featured — pin to top of the Featured section
- SalePrice + SaleEndsAt — discount price with strikethrough on the original. Sale auto-reverts after the timestamp.
- Stock — global stock counter shared across all servers via MessagingService. Decrements atomically.
- MaxPerPlayer — per-player purchase cap
- RequiresLevel / RequiresGamepass / RequiresItem / RequiresAchievement — purchase gates with custom locked-reason text
- Icon — emoji glyph OR
rbxassetid://for image icons (auto-detected) - AppliesAttribute — set a Player attribute true on grant. Pre-wires for a future Inventory product.
4 Payment Paths
Mix in-game currencies and Robux purchases freely on the same shop.
- In-game currency — Currency =
"Coins"/"Gems"/ any currency Id from your CoreShun Currency Config. Server routes through_G.CoreShunCurrency_Spend. - Robux Developer Products — Currency =
"Robux". Server uses ProcessReceipt for Roblox's exactly-once-eventually delivery guarantee. Receipts are stored idempotently. - Robux Gamepasses — Currency =
"RobuxGamepass". Auto-detects existing ownership on player join. New purchases route throughPromptGamePassPurchaseFinished. - Hybrid — any item can use any currency type. Build a single shop with mixed payment paths.
3 Layouts × 6 Themes
- Grid — side nav (left) + grid of cards (right). Best for visual items.
- List — top nav + horizontal rows with description. Best for dense catalogs and small screens.
- Tabbed — top tab bar (per category) + grid below. Best for shops with many categories.
Themes: Emerald (default) · Royal (purple) · Sunset (orange/gold) · Ocean (cyan) · Crimson (red) · Mono (minimalist). Define your own theme by adding to
Config.Themes.Switch by editing one line:
Config.UI.Layout = "Grid" and Config.UI.Theme = "Emerald".Fully Customizable
Every visible string, icon, size, and animation lives in one config file with heavily-commented inline docs. Four sub-tables under
Config.UI:- Text — 19 visible strings for full localization (title, button labels, badges, sort labels, empty state, fail reasons). Drop in Spanish, French, Japanese — anything.
- Icons — every icon supports emoji glyph OR Roblox image asset (auto-detected by
rbxassetprefix). Want your own image for the close button?Config.UI.Icons.CloseButton = "rbxassetid://...". Same for HUD button, featured star, default item icon, category icons, confirmation icon. - Sizes — grid card density, list row height, confirmation modal size, HUD aspect ratio + hover scale. Tune for tablet, console, or compact mobile.
- Animation — every duration is a knob (hover, flash, shake, toast, modal). Master
Enabled = falseswitch disables all animations for accessibility / low-end devices.
Plus configurable backdrop color + transparency, click-outside-to-close toggle, and 4 advanced DataStore tuning knobs (lock TTL, retry limit, backoff, shutdown budget).
5 Item Card States
Every card auto-renders the right state based on player ownership, stock, and requirements:
- Available — default. Click opens the confirmation modal.
- Owned — green border + "OWNED" badge. Auto-restored from DataStore on rejoin.
- On Sale — yellow border + strikethrough original price + "SALE" badge.
- Low Stock — red "N LEFT" badge when stock falls below the configurable threshold.
- Locked — greyed icon + reason text + lock overlay (e.g. "Need Iron Sword first").
Server-Authoritative Purchase Flow
The client UI is just a request layer. Every purchase is validated server-side against the Config. Prices, currencies, stock, ownership, and requirements are all checked on the server.
- Rate limit — sliding window of N purchases per W seconds. Over-limit policy: drop silently or kick.
- Per-transaction cap —
Config.AntiCheat.MaxSingleTransactioncatches accidental price misconfigurations. - Atomic stock decrement — happens BEFORE charging, via DataStore UpdateAsync. Race conditions across servers cannot double-sell.
- Auto-pairs with Anti-Exploit Suite — all 8 Shop remotes register with
_G.CoreShunAntiExploit_ReportRemoteat boot. - Roblox-native Robux validation — ProcessReceipt handles crashes, double-spend, and network failures.
DataStore Persistence
Per-player ownership persists under
"CoreShunShop_v1" with session locks. The same battle-tested DataStore pattern that ships in CoreShun Currency System v1.0:- Session locks — prevent cross-server overwrites
- Lock-steal protection — every save checks the lock is still ours
- Exponential backoff retries up to 5 attempts before session-only fallback
- Save coalescing — rapid purchases coalesce into one DataStore write after 2.5s
- Parallel BindToClose — on shutdown, all dirty saves fan out in parallel
- Global stock — limited-stock items share a counter across all servers
API + Hooks
One global namespace, ten functions. Call from anywhere.
_G.CoreShunShop_Open()/Close()/Toggle()— modal visibility_G.CoreShunShop_SetCategory("weapons")— open + jump to category_G.CoreShunShop_HasItem(player, "sword_iron")— ownership check_G.CoreShunShop_GiveItem(player, "vip_pass")— admin grant, bypass payment_G.CoreShunShop_RevokeItem(player, "vip_pass")— admin revoke_G.CoreShunShop_GetStock("pet_dragon")/SetStock(id, count)
Seven hooks for wiring your game logic to shop events:
- BeforePurchase — reject before charging (return false)
- OnPurchaseSuccess — apply consumable effects, log analytics, credit Robux purchases
- OnPurchaseFail — react to insufficient / locked / out-of-stock
- OnShopOpen / OnShopClose — analytics
- OnItemHover — throttled, useful for preview tracking
- OnItemGranted — fires on ALL grant paths (purchase, admin, rejoin). Wire to a custom inventory.
Pairs with the CoreShun Stack
Auto-detects sibling products at boot. No setup required.
- CoreShun Currency System — in-game purchase flow. Multi-currency from day 1.
- CoreShun Toast Notifications — branded purchase result toasts. Falls back to built-in.
- CoreShun Anti-Exploit Suite — all remotes registered at boot for rate-limit + intrusion rules.
- CoreShun Daily Rewards — daily login can grant shop items via
_G.CoreShunShop_GiveItem. - CoreShun Codes Redemption — promo codes grant shop items the same way.
What's in the box
- CoreShunShopSystem.rbxmx — drop-in model with installer
- ShopServer.lua (1100 lines) — purchase flow, DataStore w/ session locks, Robux ProcessReceipt, rate limit, hooks, _G API
- ShopClient.lua (1486 lines) — full UI: 3 layouts, 6 themes, animations, mobile bottom sheet, image-or-emoji icons throughout
- ShopConfig.lua (842 lines) — heavily commented schema with 12 sample items, 4 customization sub-tables (Text / Icons / Sizes / Animation)
- Installer.lua — auto-places everything to the right service
- Manual.pdf — long-form docs covering every feature
- Cheatsheet.pdf — one-pager reference
Drop in. Define items. Done.
