EconomySystem

Getting it

local EconomySystem = Engine:GetSystem("EconomySystem")

Overview

EconomySystem is a complete in-game economy on top of DataService:

• Currencies with limits, decimals, formatting, and optional leaderstats and leaderboards.
• Transactions (deposit, withdraw, set) that never take a balance below its minimum or above its maximum, are reported to StatisticsService, and replicate to the player.
• Shops with fixed or dynamic prices, purchase limits, requirements and grant callbacks.
• Timed rewards such as daily rewards, with streaks.
• Trades between two players in the same server.
• Robux products that grant currency through safe receipts.
• Offline and cross-server deposits, withdrawals and transfers that are applied exactly once.

Balances live in player profiles. By default the system creates and runs its own profile store (Engine.Economy) and starts a session for every player. If your game already has a player profile store, call :BindProfileStore(store) before players join, and balances are stored in your profiles under ProfilePath (default "Economy"). The system adds the tables it needs there itself. When your data already holds a value that is not a table at ProfilePath, it errors instead of overwriting that value.

local EconomySystem = Engine:GetSystem("EconomySystem")

EconomySystem:CreateCurrency("Coins", { Symbol = "C", Leaderstat = true })
EconomySystem:CreateCurrency("Gems", { Symbol = "G", Max = 100000 })

EconomySystem:CreateShop("Weapons", {
	Currency = "Coins",
	Items = {
		{ Id = "Sword", Price = 250, Limit = 1, Grant = function(player) giveTool(player, "Sword") end },
		{ Id = "Potion", Price = 40 },
	},
})

EconomySystem:CreateReward("Daily", {
	Currency = "Coins",
	Amount = function(player, streak)
		return 100 + streak * 25
	end,
	Cooldown = 24 * 3600,
	MaxStreak = 7,
})

-- Somewhere in your game
EconomySystem:Deposit(player, "Coins", 50, { Transaction = "Gameplay", Sku = "EnemyKill" })

local EconomySystem = Engine:GetSystem("EconomySystem")

EconomySystem:OnBalanceChanged("Coins", function(balance)
	coinsLabel.Text = EconomySystem:FormatBalance("Coins", balance)
end)

buySwordButton.Activated:Connect(function()
	EconomySystem:GetShop("Weapons"):PurchaseAsync("Sword"):catch(function(reason)
		showError(reason)
	end)
end)

Currencies

CreateCurrency

EconomySystem:CreateCurrency(name: string, options: CurrencyOptions?): Currency

A Currency has :Round(amount), :Clamp(amount), :Format(amount), :Describe(), :Destroy() and read-only fields for every option. :GetCurrency(name), :FindCurrency(name) and :GetCurrencies() look them up.

Balances and transactions

A Result is { Ok, Balance, Delta, Reason? }. Deposits are clamped to the currency's maximum, so Delta tells you how much actually changed. Reasons: "Insufficient", "NoProfile", "Invalid".

Transaction options: { Transaction?, Sku?, Fields? }. Transaction is the Roblox Analytics transaction type (default DefaultTransactionType); Sku names what the money was for.

Offline and cross-server

They resolve with { Ok, Status?, Balance?, Delta?, Reason? }, where Status is the edit result ("applied", "queued", "rejected", "missing"). Options are the transaction options plus WaitForApply. Use them for gifts, admin tools and rewards from other places.

Shops

CreateShop

EconomySystem:CreateShop(name: string, options: { Currency, Items, OnPurchase?, MaxQuantity?, Replicate? }): Shop

OnPurchase is called for every purchase in the shop. MaxQuantity caps units per purchase.

A PurchaseResult is { Item, Quantity, Total, Balance, Count }. If a grant function errors, the payment is refunded.

Timed rewards

CreateReward

EconomySystem:CreateReward(name: string, options: { Currency, Amount, Cooldown, StreakWindow?, MaxStreak?, Replicate? }): Reward

A reward the player can claim once per Cooldown seconds. Claiming again within StreakWindow after it became available raises the streak (up to MaxStreak); waiting longer resets it. Amount is a number or function(player, streak) -> amount.

Trades

CreateTrade

EconomySystem:CreateTrade(a: Player, b: Player, options: { Timeout? }?): Trade

A trade window between two players in this server. Each side offers amounts of currencies; any change resets both acceptances, and when both players accept the exchange happens in one step, so nobody can be scammed by a last-second change.

Open trades cancel themselves after TradeTimeoutSeconds, and when a participant leaves. :GetTrade(id), :FindTrade(id) and :FindTradeFor(player) look trades up; TradeCreated fires for each new trade.

Robux products

DefineProduct

EconomySystem:DefineProduct(productId: number, { Currency, Amount, Name? }): Product

A developer product that grants currency. :CreateReceiptProcessor(handlers?, options?) returns a ProcessReceipt callback that grants these products exactly once (built on DataService receipts); pass extra handlers for other products. ProductGranted: Signal<(player, product, receipt)> fires after each grant.

If you use MonetizationService, let it own the receipt callback and deposit currency from its product handlers instead.

Profiles

Client

Purchases and claims requested by the client are validated and executed on the server; the client cannot change balances. Requests are rate-limited (ClientRequestRatePerSec).

Configuration

Types

export type Currency
export type CurrencyOptions
export type TransactionOptions = { Transaction: string?, Sku: string?, Fields: { [string]: any }? }
export type TransactionInfo
export type Result = { Ok: boolean, Balance: number, Delta: number, Reason: string? }
export type Flow = "Source" | "Sink"
export type Shop
export type ShopOptions
export type ShopItem
export type ShopItemOptions
export type PurchaseResult
export type Trade
export type TradeStatus = "Open" | "Completed" | "Cancelled"
export type Reward
export type RewardOptions
export type RewardStatus
export type ClaimResult
export type Product
export type RemoteResult