Item Upgrades

Item upgrades let an item climb from level to level by paying materials. Each level costs more than the last. A try can fail and still costs its price, but a failure never lowers the level, and each miss in a row raises the chance of the next try until it cannot miss. The shown price is the price charged.

Also called: Weapon upgrades, Enhancement, Gear levels, Item tuning.

A goat engineer in goggles holds a silver blade in a ring of light on a floating workshop, as the blade turns from grey to bright blue and three star gems circle it, two lit and one dark. — Cogwhistle Skies, an invented sky-workshop tinkering 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 "Item Upgrades" to my game.

What it should do: Upgrades give the player something to save for and a reason to love one item, while a rising price and a limited top level keep the climb meaningful.

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

```mermaid
stateDiagram-v2
  [*] --> base
  base: Base level
  upgraded: Upgraded
  maxed: Highest level
  base --> upgraded: first upgrade works
  base --> maxed: one-level item upgraded
  upgraded --> maxed: top level reached
  maxed --> [*]
```

Use these starting values:
- maxLevel: 5 levels
- baseCost: 40 materials
- costGrowth: 1.6 factor
- successChance: 0.75 share
- pityBonus: 0.1 share
- powerPerLevel: 4 units

Watch out for these common mistakes:
- Failing wipes out the effort: Tell your AI: a failure costs the price and nothing else, and the level stays. If you want a harsher game, add the penalty on purpose and warn the player before they try.
- Bad luck never ends: Tell your AI: raise the chance with each miss in a row until it reaches one, and reset it on a success.
- The price on the screen is not the price charged: Tell your AI: use one function for the price, and call it from both the screen and the upgrade itself.
- A top-level item still takes the price: Tell your AI: check for the highest level before any materials are taken.
- A refused try counts as a miss: Tell your AI: count a miss only when the price was paid and the try failed.
- A roll right at the edge: Tell your AI: the roll runs from 0 up to but not including 1, and the try succeeds only when the roll is below the chance.
- Reloading to retry: Tell your AI: save the random seed with the game, so a reload brings back the same result.
- A price that falls or overflows: Tell your AI: keep the factor at 1 or more, and check the top price against how much a player really earns.

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

Upgrades give the player something to save for and a reason to love one item, while a rising price and a limited top level keep the climb meaningful.

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

Base level → Upgraded: first upgrade works
Base level → Highest level: one-level item upgraded
Upgraded → Highest level: top level reached

Good starting values

Value	Start with	What it changes
maxLevel	5 levels	How high an item can go. A low top level keeps each step important, and a high one makes the climb a long goal.
baseCost	40 materials	What the first upgrade costs. It should be a bit more than a player collects in a short time, so the first step is soon but not instant.
costGrowth	1.6 factor	How much each level costs compared with the level before. It is never below 1, because a falling price would reward waiting, and 1.6 makes the last step several times dearer than the first.
successChance	0.75 share	The chance that a first try works. It is never zero, so an upgrade can always succeed. At 0.75, one try in four fails, which gives a small thrill without making the player feel robbed.
pityBonus	0.1 share	What each failure in a row adds to the next chance. At 0.1 and 0.75, three misses guarantee the next try, so bad luck always ends. Zero turns the help off.
powerPerLevel	4 units	How much power each level adds, so every level is felt.

What usually goes wrong

Failing wipes out the effort

A failed try costs the materials and also drops the level or destroys the item. The player feels punished for a dice roll and stops trying.

Fix: Tell your AI: a failure costs the price and nothing else, and the level stays. If you want a harsher game, add the penalty on purpose and warn the player before they try.

Bad luck never ends

Each try has the same chance, so some players fail ten times in a row and quit while others succeed at once. The game feels unfair.

Fix: Tell your AI: raise the chance with each miss in a row until it reaches one, and reset it on a success.

The price on the screen is not the price charged

The screen works out the price one way and the code another, perhaps with different rounding. The player sees 102 and pays 103.

Fix: Tell your AI: use one function for the price, and call it from both the screen and the upgrade itself.

A top-level item still takes the price

The code takes the materials first and then notices the item is at its highest level. The player pays for nothing.

Fix: Tell your AI: check for the highest level before any materials are taken.

A refused try counts as a miss

The player lacks materials, the try is refused, and the game still adds one to the run of misses. The chance creeps up with nothing tried.

Fix: Tell your AI: count a miss only when the price was paid and the try failed.

A roll right at the edge

Success is checked with "the roll is at most the chance". A chance of zero then still succeeds on a roll of exactly zero, and a chance of one needs care at the top end.

Fix: Tell your AI: the roll runs from 0 up to but not including 1, and the try succeeds only when the roll is below the chance.

Reloading to retry

The roll is made when the player presses the button. If the player saves before and reloads after a failure, they get a new roll and can retry for free.

Fix: Tell your AI: save the random seed with the game, so a reload brings back the same result.

A price that falls or overflows

A growth factor below 1 makes upper levels cheaper than lower ones, so players wait. A growth factor that is too high makes the last price larger than anything a player can ever collect.

Fix: Tell your AI: keep the factor at 1 or more, and check the top price against how much a player really earns.

How to check it works

A new item at level 0 and 100 materials. you upgrade it and the roll is a success: the item is level 1, you have 60 materials left, 40 were spent and the power is 4.
The starting values. you look at the price of each level from 0 to 4: the prices are 40, 64, 102, 164 and 262.
An item at any level and enough materials. you upgrade it: the materials taken equal the price the game shows for that level.
An item at level 2 and 500 materials. you upgrade it and the roll is a failure: the item stays at level 2, 102 materials are taken, and the game counts one miss in a row.
A first try with a chance of 0.75. the roll is exactly 0.75, and then 0.7499: the first fails and the second succeeds.
A chance of 0.75 and a help of 0.1 for each miss. you look at the chance after 0, 1, 2, 3 and 4 misses: it is 0.75, 0.85, 0.95, 1 and 1.
The worst possible roll on every try. you keep trying: three tries fail and the fourth succeeds, and the run of misses starts again at zero.
An item that costs 40 to upgrade, two misses in a row, and 39 materials. you try to upgrade it: it is refused, nothing is taken and the run of misses stays at two. With 40 it goes ahead.
An item at its highest level. you try to upgrade it: it is refused and no materials are taken.
An item and a run of one miss. the roll is below zero, 1 or more, or not a number: nothing happens, no materials are taken and the run of misses stays.
A player with no materials. you add 30, and then try to add 0, minus 5, two and a half, or a number that is not a number: the player has 30 and the other tries change nothing.
A first-try chance of 1. the roll is the highest value there is below 1: the try succeeds.

Works well with

Item Durability: A free full repair hidden in an upgrade makes players upgrade only to repair. Decide whether an upgrade restores durability, and tell the player before they pay.
Crafting System: Take the materials only in the same step that raises the level or fails the try. Collect the materials by crafting or loot first, then spend them in one upgrade step.
Currency Wallet: A price paid in two places can be taken twice or not at all. If the price is in coins, let the wallet check and take the coins, then run the upgrade.
Skill Tree: Two levelling systems at once make it hard to tell what made the player strong. Keep item levels and character skills apart, and show both strengths on the same screen.

Common questions

how should upgrade costs grow

Make each level cost around one and a half times the one before. A flat price makes upgrades feel pointless, and a steep one makes the top levels a wall. Check the top price against how much a player really collects.

what do i tell my ai to add item upgrades

Paste this: Add item upgrades. Each level costs 1.6 times the one before, starting at 40. A try works with a chance of 75 percent, and each miss in a row adds 10 percent. A failed try costs its price but never lowers the level. Use one function for the price and call it from the screen and the upgrade.

should a failed upgrade destroy the item

It is a harsh choice that many players resent. If you want the risk, tell the player before they try, and offer a way to protect the item. Keeping the level on a failure is the gentler start.

why add a bonus after failed upgrades

Pure chance gives some players long runs of bad luck, and they quit. A rising chance after each miss keeps the average the same and makes sure the bad luck always ends.

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

17 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