/roblox-simulator-economy

name: roblox-simulator-economy
description: >
  Design, balance, and implement the economy of a Roblox simulator, tycoon, clicker, or idle game
  in Luau: upgrade cost curves, buy max, income per second, rebirth/prestige requirements and
  multipliers, offline earnings, big-number display (1.5K, 3.4M, 2.0Qa), server-authoritative
  purchases, repairing tampered or old save data, and odds disclosure for paid random items such
  as eggs, crates, and spins. Includes a Lune pacing calculator. Use when choosing or checking
  baseCost/costGrowth/rebirth numbers, writing upgrade/currency/rebirth/offline code, or when
  progress stalls, a rebirth takes far longer than the last, numbers display as 1000K, offline
  earnings pay too much, or players gain currency they did not earn.

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. Code targets Luau on Roblox's rolling platform APIs; the bundled scripts are pure Luau and were run with **Lune 0.11.0**, outside Studio.

When to use

• Picking or reviewing `baseCost`, `costGrowth`, rebirth requirement and multiplier, or offline

cap and efficiency values for a simulator, tycoon, clicker, or idle game.

• Writing upgrade, buy-max, currency, rebirth, or offline-earnings code in Luau.
• Displaying large numbers, or values above about `1e15` that lose precision.
• Adding eggs, crates, or spins bought with Robux, or with currency that can be bought with Robux.

**When not to use:** DataStore reads, writes, session locking and retries → `roblox-datastores`. Remote protocol design and rate limiting in depth → `roblox-networking`. Shop and HUD layout → `roblox-ui` + `game-ui-ux`. A wave-defense economy → `tower-defense`. Engine-neutral save format questions → `save-systems`.

Workflow

1. **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. 2. **Write the numbers as one config table**: base income; each upgrade's `baseCost`, `costGrowth`, effect, and `maxLevel`; rebirth `baseRequirement`, `requirementGrowth`, `multiplierPerRebirth`; offline `maxHours`, `efficiency`. Server and client both read it. 3. **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, then `lune run scripts/balance.luau economy.json`. Read the `wait` and `vs prev` columns and tune until they match the targets below. `--help` lists every field and its allowed range; a missing file, invalid JSON, or out-of-range field prints an error and exits 1. 4. **Implement on the server** with the patterns below and [references/server-patterns.md](references/server-patterns.md). Copy `scripts/economy_math.luau` unchanged into a ModuleScript so the maths you tested is the maths that runs. 5. **Verify.** `lune run scripts/test_economy_math.luau` (exits 1 on failure) for the maths; a Studio playtest with Server & Clients for purchases, rebirth, leaving and rejoining, and invalid remote arguments.

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 |

Derivations, the rebirth wait-ratio formula, and a worked example: [references/formulas.md](references/formulas.md).

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 prev` column is that ratio. With an additive multiplier it approaches `requirementGrowth` over time, so `requirementGrowth = 3` gives x2.0 rising to x2.7 and rebirth 8 takes 137 days at the default income. `requirementGrowth = 1.8` gives 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)

• `trySpend` checks every currency in a multi-currency cost before subtracting