gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/roblox-simulator-economy
roblox-simulator-economy
VerifiedRoblox simulator, tycoon and idle-game economies in Luau: upgrade cost curves, income per second, rebirth pacing, big-number formatting and paid-egg odds, with a Lune calculator. Use for baseCost or rebirth numbers or unearned currency. Not for DataStores (`roblox-datastores`), remote limits (`roblox-networking`), shop layout (`roblox-ui`) or wave economies (`tower-defense`).
Roblox simulator economy
Choose the economy's numbers with a pacing table before writing gameplay code, then implement them
so the server owns every amount. The bundled scripts are pure Luau and run outside Studio with
Lune (install it from https://github.com/lune-org/lune/releases; lune --version to check).
Workflow
- Inspect. Find where currency, upgrade, and rebirth values live now and which scripts change them. List every RemoteEvent that touches currency and what each one sends.
- Write the numbers as one config table: base income; each upgrade's
baseCost,costGrowth, effect, andmaxLevel; rebirthbaseRequirement,requirementGrowth,multiplierPerRebirth; offlinemaxHours,efficiency. Server and client both read it. - Run the pacing calculator from the skill directory (paths are relative to it):
lune run scripts/balance.luau --print-defaults > economy.json, edit the file, thenlune run scripts/balance.luau economy.json. Read thewaitandvs prevcolumns and tune until they match the targets below.--helplists every field and its allowed range; a missing file, invalid JSON, or out-of-range field prints an error and exits 1. - Implement on the server with the patterns below; read
references/server-patterns.md for the full handlers. Copy
scripts/economy_math.luauunchanged into a ModuleScript so the maths you tested is the maths that runs. - Verify. Run
lune run scripts/test_economy_math.luau(exits 1 on failure) after any change to the maths module, and re-run the calculator on the final config. In Studio, with the MCP server connected, start play and fire the purchase handlers fromexecute_luauon theServerdatamodel with valid ids, unknown ids,0/0,math.hugeand negative values, then readget_console_outputand the wallet. Purchases from two players, rebirth, and leave-and-rejoin need Server & Clients: ask the user to run them and report balances before and after.
Formulas
| Quantity | Formula | Notes |
|---|---|---|
| Price of the next level | floor(baseCost * costGrowth ^ owned) | 1.07-1.15 for upgrades bought many times; 1.5-3 for rare large ones |
| Cost from level a to b | baseCost * g^a * (g^(b-a) - 1) / (g - 1) | Players pay the floored per-level sum, slightly less |
| Buy max | walk real prices until the next exceeds the balance or maxLevel | Safer than the log formula with floored prices |
| Rebirth requirement k | baseRequirement * requirementGrowth ^ k | |
| Rebirth multiplier | 1 + k * multiplierPerRebirth | Additive grows slowly; multiplicative (q ^ k) grows exponentially |
| Offline income | floor(min(away, maxHours * 3600) * rate * efficiency) | Away time of 0 or less (clock went back) pays 0 |
Read references/formulas.md when you need a derivation, want to solve for a parameter instead of trying values, or must explain the calculator's output.
Pacing targets (starting points, not rules)
- Early upgrades take seconds. In the default config the first 10 levels take 3-10 s each.
- Each rebirth should take only a little longer than the last, for example x1.2-x1.5. The
calculator's
vs prevcolumn is that ratio. With an additive multiplier it approachesrequirementGrowthover time, sorequirementGrowth = 3gives x2.0 rising to x2.7 and rebirth 8 takes 137 days at the default income.requirementGrowth = 1.8gives x1.2 rising to x1.6. - Offline earns less than online. An efficiency of 0.25-0.5 and an 8-12 hour cap keep playing worth more than idling without zeroing out players who log off.
Server-owned purchases
A RemoteEvent carries what the player wants ("buy upgrade Income"), never an amount or a price.
The server looks up the price, checks the balance, spends, and grants without yielding in between.
-- ServerScriptService/Economy.server.luau (excerpt; full version in references/server-patterns.md)
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local EconomyMath = require(ReplicatedStorage.Shared.EconomyMath)
local Config = require(ReplicatedStorage.Shared.EconomyConfig)
ReplicatedStorage.Remotes.BuyUpgrade.OnServerEvent:Connect(function(player: Player, upgradeId: unknown)
local session = sessions[player]
if not session or type(upgradeId) ~= "string" then return end
local upgrade = Config.upgrades[upgradeId]
if not upgrade then return end -- unknown id
local owned = session.levels[upgradeId] or 0
if owned >= upgrade.maxLevel then return end
local price = EconomyMath.levelCost(upgrade.baseCost, upgrade.costGrowth, owned)
if EconomyMath.trySpend(session.wallet, { [upgrade.currency] = price }) then
session.levels[upgradeId] = owned + 1
end
end)
trySpendchecks every currency in a multi-currency cost before subtracting any, and rejects negative or non-finite costs.- Rebirth on the server: compare the server's balance with the requirement, then reset wallet and levels and increment the count. Never accept "I rebirthed" or a balance from the client.
- Rate-limit each remote per player with a token bucket (
roblox-networking).
Save data and offline time
- Repair on load; never error. Use
sanitizeAmount(non-numbers, NaN, infinity and negatives become 0; fractions are floored) andsanitizeLevel(also clamps to the currentmaxLevel). Drop unknown upgrade ids and return a list of what was repaired, so old versions and edited data load cleanly. - Never save NaN or infinity. A division by zero that reaches the wallet should be caught by the same sanitizers before saving.
- Offline time comes from the server clock only: save
os.time()on the server when the player leaves; on join,away = os.time() - lastSeen. A missing or futurelastSeencounts as now, which pays nothing. - Precision: Luau numbers are doubles, exact for integers up to
2^53(about9e15). If balances can pass about1e15, store a mantissa/exponent pair or a base-10 logarithm instead.
Big-number display
EconomyMath.formatNumber(value, decimals?) uses the suffixes K, M, B, T, Qa, Qi, Sx, Sp, Oc, No,
Dc, Ud, Dd, Td, Qad, Qid, Sxd, Spd, Ocd, Nod, Vg (1e63), then scientific notation.
- The rollover bug:
999950 / 1000 = 999.95, which rounds to"1000.0K". Round first; if the rounded value reaches 1000, move to the next suffix ("1.0M"). The tests cover this case. - Format on the client for display only; never parse a formatted string back into a number.
Paid random items (eggs, crates, spins)
Roblox's paid random items policy applies when a random item is bought with Robux, directly or through in-game currency bought with Robux. The current rules are summarized under Version notes; re-read the policy page before shipping. The implementation rule does not change: build the odds panel and the roll from one list.
Build the odds panel with EconomyMath.oddsPercent(outcomes) and roll on the server with
EconomyMath.pickWeighted(outcomes, rng:NextNumber()) from the same list (after applying any
boost), so shown and actual odds cannot drift. Check PolicyService:GetPolicyInfoForPlayerAsync() before
the spend and apply a restricted-player treatment when ArePaidRandomItemsRestricted is true.
For live tuning of prices and rewards without a server restart, and for funnel and currency
analytics, Studio's built-in rbx-configs-experimentation and rbx-instrument-analytics skills
(through the Studio MCP skill tool) cover ConfigService and AnalyticsService; this skill supplies
the numbers.
Gotchas
- Rebirth 6 takes weeks →
requirementGrowthfar above the multiplier's growth; read thevs prevcolumn and lowerrequirementGrowthor switch to a multiplicative multiplier. - Prices outrun income after ~20 levels →
costGrowthof 1.5+ on an upgrade meant to be bought 50 times (level 50 costs about 637 million times level 0); use 1.07-1.15. - Late game breaks after a few rebirths → multiplicative multiplier (
1.5 ^ k) without a matching requirement curve; keeprequirementGrowth / qnear the ratio you want. - Players gain currency they did not earn → a remote accepts an amount or price, or the check happens only on the client; send ids, price on the server.
- Two purchases pass one balance check → the handler yields between check and spend; spend
before any
task.wait, DataStore call, or other yield. - Buy max freezes the server → uncapped loop or a price of 0; pass
maxLevel, keepbaseCost >= 1(maxAffordableerrors instead of looping forever). - Offline pays days of income → client timestamp, no cap, or a corrupted
lastSeen; use the server clock, cap, and treat future times as now. - HUD shows "1000.0K" →
math.floor(x * 10) / 10before choosing the suffix; useformatNumber. - A save fails or loads as garbage → NaN or infinity reached the wallet; sanitize before save and on load.
- Odds panel wrong after a one-per-player pet is owned → outcomes a player can no longer get must leave the shown and rolled list; rebuild both from the same filtered list.
Resources
Script paths are relative to the skill directory.
scripts/balance.luau: run it (--helpfirst) whenever you choose or change economy numbers. Prints per-level price, total, income and wait; per-rebirth requirement, multiplier, wait and ratio; offline maximum.scripts/economy_math.luau: copy it unchanged into a ModuleScript; read it only to look up a function's arguments. Formulas,trySpend, sanitizers, odds andformatNumber.scripts/test_economy_math.luau: run it after any change to the maths module (exits 1 on failure).- references/formulas.md: read when you need a derivation or the rebirth wait-ratio formula.
- references/server-patterns.md: read when you implement the handlers: config layout, income tick, buy max, rebirth, load repair with offline income, and paid random item rolls.
Related skills
roblox-luau— services, ModuleScripts, and the client/server split.roblox-networking— remote validation and token-bucket rate limits.roblox-datastores— loading and saving the session this skill repairs.roblox-ui— shop, upgrade, and odds panels.roblox-studio-workflow— Server & Clients playtests.
Version notes
Last verified: 2026-11-11.
- Scripts and tests pass under Lune 0.11.1 (13 tests); the worked example in
references/formulas.mdwas produced with 0.11.0 and matches 0.11.1 output. - Paid random items policy, as summarized from the Creator Hub page:
- Show every outcome and its actual odds as percentages summing to exactly 100% before purchase. Long decimals may be rounded with a note that the shown total may not equal 100%.
- If the list does not fit, open it from a control labelled "Info" or "Details" that is visible before purchase; an "(i)" icon alone is not enough.
- Luck boosts, pity systems and other probability modifiers count: explain their effect numerically before purchase and show the boosted odds while active.
- When a player can get an outcome only once, update the remaining odds for that player.
ArePaidRandomItemsRestricted: give those players a listed treatment (free earnable path, fixed disclosed order, direct purchase at expected value, hide, block with a message, or move them away).IsPaidItemTradingAllowed: when false, those players must not trade paid outcomes.
Sources: https://create.roblox.com/docs/production/monetization/paid-random-items,
https://create.roblox.com/docs/reference/engine/classes/PolicyService,
https://create.roblox.com/docs/reference/engine/datatypes/Random,
https://create.roblox.com/docs/assistant/skills,
https://github.com/lune-org/lune/releases (0.11.1, 2026-10-21).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |