Currency Wallet

A currency wallet holds the player's coins as whole numbers. Earning adds coins up to a limit, and the game is told what did not fit. Buying costs the full price or does not happen. Selling gives back only part of the price, so buying and selling in a loop never makes money.

Also called: Coin purse, Money system, Gold counter, Coin counter, Wallet.

A fox customer opens a coral-pink pouch so full of gold coins that some spill over the rim, while a badger merchant at a crate market stall holds out a glowing blue gem. — Pennywhistle Quay, an invented floating-island trading 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 "Currency Wallet" to my game.

What it should do: A wallet turns effort into choices. The player earns coins, weighs what to buy, and feels the cost of each choice, so shops, rewards and prices all have a number to work with.

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

```mermaid
stateDiagram-v2
  [*] --> empty
  empty: Empty
  some: Some coins
  full: At the limit
  empty --> some: earns some coins
  empty --> full: earns a fortune
  some --> full: reaches the limit
  some --> empty: spends everything
  full --> some: spends some coins
  full --> empty: spends everything
```

Use these starting values:
- capacity: 9999 coins
- sellRatio: 0.5 share of price
- incomeBonus: 1 multiplier

Watch out for these common mistakes:
- Decimal prices leave dust: Tell your AI: keep all coins as whole numbers. Round a price up and a reward down, so the player never pays less or gets more than the number.
- Coins vanish at the limit: Tell your AI: take only what fits, report how much was left over, and let the game keep the rest of the bag where it lies.
- Buying and selling in a loop makes money: Tell your AI: selling gives back at most the price paid, rounded down, so every loop loses coins or breaks even.
- A negative price pays the player: Tell your AI: only spend when the price is a number above zero, and ignore anything else.
- A half payment goes through: Tell your AI: check the full price first. If the wallet cannot pay it, change nothing and say the purchase was refused.

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

A wallet turns effort into choices. The player earns coins, weighs what to buy, and feels the cost of each choice, so shops, rewards and prices all have a number to work with.

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

Empty → Some coins: earns some coins
Empty → At the limit: earns a fortune
Some coins → At the limit: reaches the limit
Some coins → Empty: spends everything
At the limit → Some coins: spends some coins
At the limit → Empty: spends everything

Good starting values

Value	Start with	What it changes
capacity	9999 coins	The most coins the wallet holds. A four-digit limit fits a counter on the screen and is far above what most shops ask. A lower limit makes players spend instead of hoarding.
sellRatio	0.5 share of price	The share of an item's price that selling gives back. Half makes a purchase a real commitment. It is never above one, because a higher share would pay the player to buy and sell in a loop.
incomeBonus	1 multiplier	A multiplier on coins earned, for events or upgrades. One means no bonus. It is never below one, because a bonus below one would quietly take coins away.

What usually goes wrong

Decimal prices leave dust

Prices and rewards with decimals, such as 0.1 and 0.2, do not add up exactly in a computer. The balance ends up a hair off, shows 9.999999 coins, or a price check says 'not enough' when the numbers look equal.

Fix: Tell your AI: keep all coins as whole numbers. Round a price up and a reward down, so the player never pays less or gets more than the number.

Coins vanish at the limit

The wallet is nearly full, the player picks up a bag of coins, and the whole bag disappears while only part fits. The player feels robbed.

Fix: Tell your AI: take only what fits, report how much was left over, and let the game keep the rest of the bag where it lies.

Buying and selling in a loop makes money

An item sells for as much as it costs, or a rounding step adds one coin, and the player buys and sells over and over until the shop is useless.

Fix: Tell your AI: selling gives back at most the price paid, rounded down, so every loop loses coins or breaks even.

A negative price pays the player

A broken shop entry, or a discount that overshoots, gives a price below zero. Spending it adds coins to the wallet instead of taking them.

Fix: Tell your AI: only spend when the price is a number above zero, and ignore anything else.

A half payment goes through

The player has 30 coins and an item costs 40. The shop takes the 30 and hands over the item, or leaves the wallet at minus 10.

Fix: Tell your AI: check the full price first. If the wallet cannot pay it, change nothing and say the purchase was refused.

How to check it works

An empty wallet. the player earns 30 coins: the wallet holds 30 and the game is told the change was 30.
A wallet with 100 coins. the player buys something for 40: the wallet holds 60, the game is told the change was minus 40, and 40 count as spent.
A wallet with 30 coins. the player tries to buy something for 40: the purchase is refused and the wallet still holds 30.
A wallet with 40 coins. the player buys something for exactly 40: the purchase goes through and the wallet is empty.
A wallet with 9990 coins and a limit of 9999. the player earns 50: the wallet holds exactly 9999, only 9 count as earned, and the game is told that 41 did not fit.
A bonus of one and a half times. the player earns 5 coins, and then in a fresh wallet 1 coin: the first gives 7 coins, not 7.5, and the second gives 1.
A sell share of one half. the player sells an item that cost 25, and then one that cost 100: the first gives back 12 coins, rounded down, and the second gives back 50.
A wallet with 1000 coins and any sell share up to one. the player buys an item and sells it straight back: the wallet holds no more than 1000, for every price tried.
A wallet with 30 coins. an amount of zero, minus 5, not a number or endless is used to earn, spend or sell, or an amount below one whole coin is used to earn or sell: the wallet still holds 30 and the action is marked as ignored.
A wallet with 100 coins. the player buys something priced at 9.5: the wallet holds 90, because the price was rounded up to 10, and with only 10 coins a price of 10.2 is refused.

Works well with

Inventory System: A purchase should change both together or neither. If the bag is full, refuse before taking coins. Take the coins first, then hand over the item.
Loot Table: A drop of coins goes through the same earning rules, so a full wallet reports what did not fit and the rest stays on the ground. Roll the drop first, then add the coins.

Common questions

how do i make a currency system in a game

Keep the coins as whole numbers in one balance. Earning adds up to a limit, buying takes the full price or does nothing, and selling gives back part of the price.

should game currency be whole numbers

Yes. Decimals do not add up exactly in a computer, so the balance drifts by tiny amounts. Whole numbers, with prices rounded up and rewards rounded down, stay exact.

how much should items sell for in a game shop

Start at half the buying price, rounded down. It makes buying a real choice and makes a buy and sell loop lose coins.

what do i tell my ai to add a coin wallet

Paste this: Add a coin wallet with whole numbers and a limit of 9999. Spending costs the full price or is refused. Earning takes only what fits and reports the rest. Selling gives back half the price, rounded down. Ignore amounts that are zero, negative or not numbers.

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

19 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