Skip to main content
skill CX Codex

roblox-simulator-economy — Claude Code skill: features and setup

roblox-simulator-economy — a skill for Claude Code designs upgrade cost curves, passive income rates, rebirth pacing, and offline gains for Roblox idle games in Luau. Runs during balance tuning for simulators and tycoons.

Apache-2.0 ★ 10,033 updated 2026-11-12

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gamedev-skills/awesome-gamedev-agent-skills
/plugin install gamedev@awesome-gamedev-agent-skills
Open on GitHub

What roblox-simulator-economy does

This skill builds progression mechanics and reward curves for Roblox simulators using a centralized configuration file. It stores base earnings, upgrade scaling factors, rebirth requirements, and idle income limits. Developers run scripts/balance.luau before wiring gameplay code to inspect wait times between purchases and verify how rebirth intervals scale across tiers.

Server logic keeps full authority over all player balances. Remote events send upgrade identifiers instead of prices or wallet subtractions; the server fetches costs, verifies funds via EconomyMath.trySpend, and applies level changes atomically. The package also handles large-number formatting up to Vg (1e63) and sanitizes data stores to drop NaN, infinite, or negative amounts on load.

Running the offline balance calculator and automated tests requires the standalone Lune runtime. This tool does not cover persistent DataStore management, remote rate limiting, or shop interface layouts.

What it helps with

  • Calculate upgrade price growth and progression curves for rebirth cycles
  • Protect game currency by processing all purchases strictly on the server
  • Format massive numerical values up to suffix Vg and scientific notation
  • Sanitize saved session records to strip invalid NaN or infinite values

Example prompts for the agent

  • Generate default economy parameters and run the balance check using Lune
  • Implement server purchase validation for upgrades with EconomyMath.trySpend
  • Tune rebirth scaling so subsequent milestones take roughly 1.5 times longer

How to install roblox-simulator-economy

1Plugin marketplace

/plugin marketplace add gamedev-skills/awesome-gamedev-agent-skills
/plugin install gamedev@awesome-gamedev-agent-skills

This installs the whole gamedev plugin with all its skills

2Skills CLI (Vercel)

npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill roblox-simulator-economy -a claude-code

3Manually: put the files in place

~/.claude/skills/roblox-simulator-economy/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/roblox-simulator-economy/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about roblox-simulator-economy

How to install roblox-simulator-economy in Claude Code?

Run /plugin marketplace add gamedev-skills/awesome-gamedev-agent-skills followed by /plugin install gamedev@awesome-gamedev-agent-skills in Claude Code.

What does roblox-simulator-economy do?

It calculates upgrade pacing, idle income formulas, and rebirth requirements for Luau simulators, providing secure server transaction handlers.

What is required to run roblox-simulator-economy?

Executing the pacing scripts and mathematical tests outside Roblox Studio requires the standalone Lune CLI utility.

Source text

SKILL.md · Apache-2.0
---
name: roblox-simulator-economy
description: >
  Roblox 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

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; read
   [references/server-patterns.md](references/server-patterns.md) for the full handlers. Copy
   `scripts/economy_math.luau` unchanged into a ModuleScript so the maths you tested is the maths
   that runs.
5. **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 from `execute_luau` on the `Server`
   datamodel with valid ids, unknown ids, `0/0`, `math.huge` and negative values, then read
   `get_console_output` and 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](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 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.

```lua
-- 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 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) and `sanitizeLevel` (also clamps to the current `maxLevel`).
  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 future `lastSeen` counts as
  now, which pays nothing.
- **Precision:** Luau numbers are doubles, exact for integers up to `2^53` (about `9e15`). If
  balances can pass about `1e15`, 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** → `requirementGrowth` far above the multiplier's growth; read the
  `vs prev` column and lower `requirementGrowth` or switch to a multiplicative multiplier.
- **Prices outrun income after ~20 levels** → `costGrowth` of 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; keep `requirementGrowth / q` near 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`, keep
  `baseCost >= 1` (`maxAffordable` errors 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) / 10` before choosing the suffix; use
  `formatNumber`.
- **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 (`--help` first) 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 and `formatNumber`.
- `scripts/test_economy_math.luau`: run it after any change to the maths module (exits 1 on
  failure).
- [references/formulas.md](references/formulas.md): read when you need a derivation or the
  rebirth wait-ratio formula.
- [references/server-patterns.md](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.md` was 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).

© gamedev-skills · Apache-2.0 · gamedev-skills/awesome-gamedev-agent-skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set91

The whole set →
ebitengine-game ebitengine-game — a skill for Claude Code that creates, debugs, and packages 2D games in Go using Ebitengine v2. CX Codex +1 6,000installs defold-core defold-core — a skill for Claude Code, Codex, and Cursor that builds and debugs Defold 1.14 Lua games. Runs when editing .collection or .script files. CX Codex +1 5,800installs game-docs game-docs — a skill for Claude Code and Cursor writes and maintains game design documentation synced with the codebase. CX Codex +1 2,000installs unity-build-size unity-build-size — a skill for Claude Code analyzes build reports, spots oversized textures, audio and glTFast models in Unity 6.3 LTS projects, and shrinks build size. CX Codex +1 1,800installs workflows workflows — a Claude Code plugin that brings game development process skills: game jam runs, rapid prototyping, Steam and itch.io publishing. It covers the shipping cycle from first prototype to store page. ★ 10,033repo stars genres A Claude Code plugin with compositional templates for nine game genres: platformer, roguelike, RPG, FPS, tower defense, card game, visual novel, survival, puzzle. Sets project structure and core mechanics for the chosen genre. ★ 10,033repo stars disciplines disciplines — a plugin that consolidates gamedev knowledge across engines: visual assets, AI, procedural generation, dialogue systems, saves, audio, shaders, physics, level design, and input handling. ★ 10,033repo stars other-engines The other-engines plugin for Claude Code adds game development skills for Bevy, pygame, LÖVE, Defold, and Roblox. It helps write gameplay logic for each engine. ★ 10,033repo stars

Project sponsors

Companies that keep this analytics open