Idle Income

Idle income keeps paying while the player is away. The game does not run in the background. When the player returns, it works out the time away, pays at a reduced rate up to a set limit, and shows what was earned. Upgrades raise the rate and cost more each time.

Also called: Offline earnings, Idle progress, Passive income, Away rewards.

A tiny frog in a pointed hat climbs down a ladder at dawn and finds the water mill still turning, a basket beneath it overflowing with shining pearls after a night alone. — Mossbridge Mill, an invented cosy pond-keeping game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Idle Income" to my game.

What it should do: Money that grows while the player sleeps gives them something to come back to, and each return feels like opening a small gift.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> present
  present: Playing
  away: Away
  full: Cap reached
  present --> away: player leaves
  away --> present: player returns
  away --> full: cap time is reached
  full --> present: returns, paid to the cap
```

Use these starting values:
- incomePerLevel: 2 coins/s
- offlineCapHours: 8 h
- offlineEfficiency: 0.5 x
- liveGap: 5 s
- baseUpgradeCost: 50 coins
- costGrowth: 1.25 x

Watch out for these common mistakes:
- Counting ticks instead of time: Tell your AI: pay by the time that passed between two moments, never by the number of frames or timer calls.
- A month away pays a month: Tell your AI: cap the time away that pays, and say the cap out loud on the return screen.
- The device clock: Tell your AI: a time before the last one pays nothing and takes nothing. For a game with real money or a ranking, take the time from your server.
- The sleeping app: Tell your AI: when the gap between two updates is longer than a few seconds, pay it as time away.
- The upgrade is paid backwards: Tell your AI: pay the time up to now first, and only then change the level.
- Small income rounds away: Tell your AI: keep the fractions in the stored number, and round only what the player sees.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Money that grows while the player sleeps gives them something to come back to, and each return feels like opening a small gift.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Playing → Away: player leaves
Away → Playing: player returns
Away → Cap reached: cap time is reached
Cap reached → Playing: returns, paid to the cap

Good starting values

Value	Start with	What it changes
incomePerLevel	2 coins/s	What one upgrade level earns each second while playing. It sets the speed of the whole game, so change it first when the pace feels wrong.
offlineCapHours	8 h	The most time away that pays. Eight hours covers a night's sleep or a work day, and the player has a reason to return daily. Without a limit, one long break would pay out a whole game.
offlineEfficiency	0.5 x	How much of the playing rate is paid while away. Under one, being there still pays better than leaving the game alone. At one, there is no reason to play.
liveGap	5 s	The longest gap between two updates that still counts as playing. A longer gap means the app was asleep, and it is paid like time away.
baseUpgradeCost	50 coins	What the first upgrade costs. Cheap enough to buy within a minute, so the player learns the loop at once.
costGrowth	1.25 x	How many times more each further upgrade costs than the one before. It must stay above one, or upgrades would never get dearer and the game would run away. 1.25 makes the player wait a little longer each time.

What usually goes wrong

Counting ticks instead of time

The code adds income on every frame. When the app is closed, no frames run, so nothing is earned, or the phone slows the game down and income drops.

Fix: Tell your AI: pay by the time that passed between two moments, never by the number of frames or timer calls.

A month away pays a month

A player returns after 30 days and gets 30 days of income. The upgrades they wanted to save up for are all bought at once and the game is over.

Fix: Tell your AI: cap the time away that pays, and say the cap out loud on the return screen.

The device clock

A player moves the clock forward to get the cap in a minute, or back, and the code works out a negative time away and takes coins.

Fix: Tell your AI: a time before the last one pays nothing and takes nothing. For a game with real money or a ranking, take the time from your server.

The sleeping app

A phone freezes the app for an hour in the background, and no one told the game that the player left. When it wakes, it pays the whole hour at the full playing rate.

Fix: Tell your AI: when the gap between two updates is longer than a few seconds, pay it as time away.

The upgrade is paid backwards

The player buys an upgrade after a long wait, and the code uses the new level for the time that already passed, so the upgrade pays for itself at once.

Fix: Tell your AI: pay the time up to now first, and only then change the level.

Small income rounds away

Income of a hundredth of a coin per frame is rounded to zero on every frame, so a slow game earns nothing at all.

Fix: Tell your AI: keep the fractions in the stored number, and round only what the player sees.

How to check it works

A player at level 1, earning 2 coins a second. the game updates after 4 seconds of play: 8 coins are added.
A player at level 1. 600 updates of one sixtieth of a second go by: the player has 20 coins, with nothing lost to rounding.
A player leaves and returns one hour later. the game works out the time away: it pays 3,600 coins, which is half of the 7,200 playing would have paid.
A player leaves and returns 20 hours later. the game works out the time away: it pays for 8 hours only, 28,800 coins, and exactly 8 hours pays the same.
A player is playing and the app gets no update for 10 minutes. the next update arrives: the 600 seconds pay the away rate, 600 coins, and not the playing rate.
A player at time 100. the clock reads 40, or the player leaves and returns at an earlier time: nothing is paid and no coins are taken.
A player with 50 coins, 4 seconds after the last update. they buy the first upgrade: the 4 seconds pay 8 coins at the old rate, then 50 are spent, leaving 8 coins at level 2.
A player with 49 coins. they try the first upgrade, which costs 50: nothing is spent and the level stays.
The first upgrade costs 50 and each further one costs 1.25 times as much. the costs of the next two are worked out: they are 63 and 79, rounded up.
A player who has left. an upgrade is asked for before they return: nothing happens.

Works well with

Currency Wallet: The wallet owns the balance and its limits. Show the away pay on the return screen before adding it, so the player sees where it came from. Pay into the wallet after the away pay is worked out.
Shop (Buy and Sell): Every purchase that changes the income rate follows the same rule as the upgrade here: pay the past at the old rate first. Work out the income to now before any purchase.
Daily Rewards: Both greet a returning player. Put them on one return screen so the player is not met by two pop-ups in a row. Show the away pay first, then the daily reward.

Common questions

how do idle games earn while the app is closed

They do not run. When the player comes back, the game compares the time now with the time they left, and pays the income for that time in one go.

how long should offline earnings last

Start with a cap of eight hours at half the playing rate. That pays for a night away and still makes playing worth more than waiting.

how do i stop players cheating idle income with the clock

Ignore a time before the last one seen and cap the time away. If it matters for money or a ranking, ask your server for the time and do not trust the device.

what do i tell my ai to add idle income

Paste this: Add idle income. Save the time the player left. On return, pay half the playing rate for the time away, capped at 8 hours, and show the amount. Treat a long gap between two updates as time away, never pay a negative time, and pay the time up to now before any upgrade changes the rate.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

18 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it