Currency System v1.1

Overview

---

A drop-in multi-currency system for any Roblox game. Server-authoritative balances with DataStore persistence, session locks, and graceful fallback. Animated HUD widget with counter rollups, pulse on earn, flash on spend, and shake + toast on insufficient. Text or image icons — set Icon = "$" for a glyph or Icon = "rbxassetid://12345" for a custom asset. 4 number formats — Raw, Comma, Short, ShortDecimal — with a custom suffix table for idle games. Anti-cheat baked in: per-transaction caps, sliding-window rate limits, and auto-pairing with CoreShun Anti-Exploit. 6 buyer hooks for wiring your game logic to currency events. Scale-only UI — looks identical on phone, tablet, desktop, console, and 4K.

Drop in. One config file. Define currencies. Done.

Open source. Plain Luau. No obfuscation. Edit any file.

The API

---

One global namespace, six core functions. Call from anywhere in your server scripts.

• _G.CoreShunCurrency_Get(player, "Coins") — read a balance
• _G.CoreShunCurrency_GetAll(player) — read all enabled balances
• _G.CoreShunCurrency_Add(player, "Coins", 50, "quest") — earn
• _G.CoreShunCurrency_Spend(player, "Coins", 100, "shop") — spend with validation
• _G.CoreShunCurrency_CanAfford(player, "Gems", 50) — pre-check before showing a Buy button
• _G.CoreShunCurrency_SetWidgetVisible(player, false) — hide HUD during a cutscene

Spend returns false + "Insufficient" when balance is too low. Add and Spend return false if the amount is invalid (negative, NaN, over the per-transaction cap).

Currencies

---

Define unlimited currencies in one config table. Every field is optional with sensible defaults.

• Enabled — flip to false to pause a currency. Saved data stays on disk. Flip back to true → players get their balances back. Perfect for seasonal events.
• DisplayName — player-facing label used in popups and toasts
• Icon — text glyph OR rbxassetid:// URL (auto-detected). Examples: "$" · "♦" · "rbxassetid://12345678"
• IconColor — text color OR image tint
• StartingAmount / MaxBalance / MinBalance — starting value + bounds. Min can be negative for overdraft.
• Persist — true = save via DataStore. false = session-only.
• ShowInWidget / WidgetOrder — visibility + ordering in the HUD
• FormatStyle — override the default for this currency only

Two currencies ship by default

• Coins — gold "$" glyph, starting 100, max 1 trillion, persistent
• Gems — ice-blue "♦" glyph, starting 0, max 1 billion, persistent

Both are fully editable. Delete them, add your own — anything goes.

Animated HUD Widget

---

A polished, scale-only widget appears top-right by default. Every visual is configurable.

• Counter rollup — numbers tween 0.7-1.2s with Quart easing on every change
• Pulse on earn — row scales 1.08× + green tint
• Flash on spend — row tints red briefly
• Shake on insufficient — row wobbles via Rotation (UIListLayout-safe — won't fight the layout)
• Floating "+50 $" popups — rise and fade next to the row
• Insufficient toast — bottom-center "Not enough Coins!" with configurable text + colors
• Mobile-aware positioning — relocates on touch devices to avoid Roblox's chat icon
• Scale-only sizing — UDim2.fromScale everywhere, zero pixel offsets, looks identical on every device
• Per-player visibility toggle — hide for cutscenes via SetWidgetVisible
• Disable entirely — Config.UI.ShowWidget = false if you have your own HUD

Server-Authoritative Persistence

---

Clients NEVER touch balances directly. Every transaction is validated, applied, and replicated by the server.

• Per-player DataStore record — all currencies in one save key
• Session locks — prevents multi-server data races; if another server owns the lock, the new server plays in session-only mode without overwriting
• Auto-save on change — debounced 2.5s, coalesces rapid earnings into one write
• Periodic auto-save — every 60s as a backstop
• Save on leave + Save on shutdown (BindToClose) — never lose progress
• Exponential backoff retries — 3 attempts on throttle (1s, 2s, 4s)
• Graceful fallback — if DataStore API access is off (Studio Edit, or Game Settings → Security), the system runs in session-only mode without errors
• ForceInteger guard — round all balances to integers on every operation (clean coin economies, no floating-point drift)

Anti-Cheat (Two Layers)

---

On top of server authority:

• Transaction-size cap — single Add/Spend can't exceed MaxSingleTransaction (default 1e9). Catches logic bugs and abuse. Configurable: clamp, reject, or warn.
• Per-player rate limit — sliding window of N calls per M seconds on currency remotes. Configurable action: drop or kick.
• Min/Max balance clamping — every transaction respects bounds
• Insufficient policy — reject the spend OR clamp to MinBalance (your choice)

CoreShun Anti-Exploit Pairing

---

If you also own CoreShun Anti-Exploit, the systems auto-pair:

• Currency Server probes _G.CoreShunAntiExploit_ReportRemote on every incoming remote
• Every call is reported to Anti-Exploit's RemoteSpam detector — strengthens spam defenses with zero wiring
• Zero conflicts — distinct ReplicatedStorage folders, DataStore keys, and _G namespaces
• Works perfectly without Anti-Exploit — the probe silently no-ops if it's not installed
• One-line opt-out — Config.AntiCheat.ReportToAntiExploit = false

Number Formats

---

• Raw — 1234567
• Comma — 1,234,567 (custom separator)
• Short — 1M, 1.2K (integer K boundary)
• ShortDecimal — 1.23M, 12.4K (configurable decimal places)

Custom suffix table for idle games: K, M, B, T, Qa, Qi, Sx, Sp, Oc, No, Dc (extensible). Per-currency override or global default.

Buyer Hooks

---

Define handlers in Config.Hooks. All hooks are server-side, fired automatically, and pcall'd — a buggy hook can't crash the system.

• OnPlayerLoaded(player, balances) — fires once when DataStore data arrives. Use for first-time gifts, daily-login bonuses.
• OnEarn(player, currency, amount, newBal, reason) — fires after a successful Add()
• OnSpend(player, currency, amount, newBal, reason) — fires after a successful Spend()
• OnInsufficient(player, currency, attempted, current, reason) — Spend was rejected for not enough balance. Hook a "Buy More Gems" popup.
• OnBalanceChanged(player, currency, oldBal, newBal) — fires after ANY balance change. Use this if you don't care WHY it changed.
• OnPlayerSaved(player, success, balances) — fires on the final save attempt when the player leaves. success=false if DataStore failed.

Leaderstats Integration (Optional)

---

Set Config.Leaderstats.Enabled = true to auto-sync currencies to Roblox's built-in player-list leaderboard. Per-currency control via Show table — include only the currencies you want visible there.

Configurability

---

13 commented config sections in one ModuleScript:

1. General (kill switch, debug, log prefix)
2. Currencies (define each one)
3. DataStore (name, save cadence, retries, locks)
4. AntiCheat (caps, rate limits, AE pairing)
5. Leaderstats (native player-list sync)
6. UI (desktop + mobile positions, sizes, padding)
7. Theme (colors, fonts, shadow)
8. Animation (pulse, flash, shake, rollup easing)
9. Popups (floating text + insufficient toast)
10. SFX (earn/spend/insufficient sounds)
11. Format (Raw / Comma / Short / ShortDecimal)
12. Behaviors (save triggers, integer mode, clamp policies)
13. Hooks (6 callback slots)

Pairs Well With

---

• CoreShun Daily Rewards — strongest pair. Award currency from daily rewards via one hook call. Currency System provides the bookkeeping; Daily Rewards provides the loop.
• CoreShun Codes Redemption — award currency on code redemption. Same one-hook pattern.
• CoreShun Settings Menu — add a "Show Currency HUD" toggle that calls SetWidgetVisible. Players who don't want HUD clutter can hide it.
• CoreShun Toast — replace the built-in insufficient toast with branded Toast UI for unified game UX.
• CoreShun Anti-Exploit — auto-pairs at boot. Every currency remote routes through Anti-Exploit's RemoteSpam detector.
• CoreShun Quest System — reward quests in any currency you define. Currency System provides the balance layer underneath any reward system.

What's Included

---

• CoreShunCurrencySystem.rbxmx — drop into Workspace + run installer
• CurrencyConfig.lua — single config ModuleScript (the only file you edit)
• CurrencyServer.lua — authoritative core (API, DataStore, hooks, rate limits)
• CurrencyClient.lua — HUD widget + animations + popups + sounds
• TestCurrency.lua — 10-scenario auto-test (Studio-only via IsStudio() safety guard)
• Installer.lua — one-click command bar installer
• Manual.pdf — comprehensive feature guide with examples
• Cheatsheet.pdf — visual quick-reference
• README.txt — setup + reference
• PAIRING.txt — cross-product compatibility guide
• Rojo project files — for active development

Easy Installation

---

1. Drag CoreShunCurrencySystem.rbxmx into your place
2. Open the Studio Command Bar
3. Run require(workspace.CoreShunCurrencySystem.Installer)
4. Open CurrencyConfig in ReplicatedStorage and customize (or skip — defaults work)
5. Press F5 — HUD widget appears top-right with starting balances
6. Before shipping your game — delete TestCurrency from ServerScriptService (it auto-disables in production via IsStudio() guard, but removing is best practice)

Frequently Asked

---

How many currencies can I have?
Unlimited. Each one is ~10 lines of config. The widget grows vertically; the API is the same regardless of count.

Can I use image assets for icons?
Yes. Set Icon = "rbxassetid://12345" and the system swaps to an ImageLabel automatically. Set IconColor = Color3.new(1,1,1) for natural colors, or any Color3 to tint.

Does this need Anti-Exploit to work?
No. Currency System is fully standalone. If you also own Anti-Exploit, the pairing is automatic at boot (configurable via one flag).

How do I handle Robux purchases (developer products)?
In your ProcessReceipt handler, call _G.CoreShunCurrency_Add(player, "Gems", amount, "robux_purchase"). Done.

Can players hop between servers without losing progress?
Yes. Session locks prevent data races. If a player joins server B while server A still owns the lock, server B plays in session-only mode until A releases. No data is overwritten.

What about idle games with quadrillion-coin balances?
Roblox DataStore JSON safe limit is around 2^53 (9 quadrillion). Default MaxBalance is 1e12. Bump it to 1e15 for safer headroom. Past that, you'd want a custom big-number library.

Will players lose data if I rename a currency?
Renaming = deleting old + adding new. The old saved data becomes orphaned (lost). If you want to migrate, write a one-time migration in OnPlayerLoaded that reads the old key, adds to the new currency, and clears the old.

Can I disable a currency without losing player data?
Yes. Set Enabled = false. The API silently no-ops on it, the widget hides the row, but saved data stays on disk. Flip back to true and existing balances return.

Does it work in solo mode (one player)?
Yes — but DataStore needs the game to be published with API access enabled. Studio Edit alone won't persist data; the system falls back to session-only and warns in Output.

Open source?
Fully. Plain Luau, no obfuscation. Edit any file. No external dependencies.

More Tools by coreshun

---

• In-Game Systems — Weather System, Day & Night Cycle, Quest System, Settings Menu, Music Player, Simple Music Player, Daily Rewards, Loading Screen, Advanced Chat System, Toast, Anti-Exploit, AutoRejoin, Codes Redemption, Crash & Error Reporter
• Studio Plugins — Color Picker, UI Wireframe, Gamepass Manager, TODO Tracker (free)
• Bundles — up to 45% off

Browse all: builtbybit.com/creators/coreshun

Support

---

Discord: discord.com/invite/hdB5tadkk8