Experience and Levels

Experience and levels turn everything a player does into steady growth. Actions earn points, and the total decides the level. Each level costs more than the one before, leftover points carry over, and one big reward can lift the player several levels. At the top level the bar simply stays full.

Also called: XP system, Leveling, Experience points, Level-up system.

A young hedgehog apprentice with raised fists is lifted by three golden rings of light in a tall spiral, while a glass gauge beside her overflows into the next tube. — Brambleclimb Academy, an invented comic-style fantasy adventure. 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 "Experience and Levels" to my game.

What it should do: Levels give the player a clear sense of getting stronger and a next goal that is always close. Rising costs keep the early levels quick and the later ones a real achievement.

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

```mermaid
stateDiagram-v2
  [*] --> fresh
  fresh: No points yet
  climbing: Earning points
  levelup: Just levelled up
  maxed: Top level
  fresh --> fresh: nothing earned
  fresh --> climbing: earns points
  fresh --> levelup: earns enough
  fresh --> maxed: earns a huge gain
  climbing --> climbing: earns points
  climbing --> levelup: crosses a level line
  climbing --> maxed: reaches the top
  levelup --> climbing: earns a bit more
  levelup --> levelup: levels up again
  levelup --> maxed: reaches the top
  maxed --> maxed: points are dropped
  maxed --> [*]
```

Use these starting values:
- baseXp: 100 points
- growth: 1.4
- maxLevel: 30

Watch out for these common mistakes:
- A big reward gives only one level: Tell your AI: after a gain, keep levelling up until the points no longer reach the next level.
- Leftover points vanish on a level-up: Tell your AI: store the total, and work out the progress inside a level by subtracting the level line.
- The level and the points disagree: Tell your AI: save only the total points, and work out the level from it every time.
- Past the top level: Tell your AI: stop the total at the points the top level needs, and show a full bar there.
- A penalty or a bad number ruins the total: Tell your AI: count a gain below zero or not a number as zero. If a penalty should exist, take points off the bar inside the current level and never below its line.
- A level that costs nothing: Tell your AI: round each cost to a whole number and make it at least 1.

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

Levels give the player a clear sense of getting stronger and a next goal that is always close. Rising costs keep the early levels quick and the later ones a real achievement.

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

No points yet → No points yet: nothing earned
No points yet → Earning points: earns points
No points yet → Just levelled up: earns enough
No points yet → Top level: earns a huge gain
Earning points → Earning points: earns points
Earning points → Just levelled up: crosses a level line
Earning points → Top level: reaches the top
Just levelled up → Earning points: earns a bit more
Just levelled up → Just levelled up: levels up again
Just levelled up → Top level: reaches the top
Top level → Top level: points are dropped

Good starting values

Value	Start with	What it changes
baseXp	100 points	What the first level costs, and the scale for all the others. At 100, a player who earns 10 points per fight reaches level 2 after ten fights.
growth	1.4	How fast the cost of a level grows. At 1.4, going from level 10 to 11 costs about 25 times the first level. At 1 the cost grows in even steps, and at 3 the late levels become huge.
maxLevel	30	The top level. At the starting values it takes 140372 points to reach level 30. Points beyond that are dropped, because a bar that never fills would suggest more to come.

What usually goes wrong

A big reward gives only one level

The code checks for a level-up once per gain. A boss that gives 835 points leaves the player at level 2, and each following fight gives one more level until it catches up.

Fix: Tell your AI: after a gain, keep levelling up until the points no longer reach the next level.

Leftover points vanish on a level-up

The bar is emptied to zero on every level-up. A player who gets 130 points when 100 were needed loses the extra 30, and feels the game is stealing from them.

Fix: Tell your AI: store the total, and work out the progress inside a level by subtracting the level line.

The level and the points disagree

The level and the points are saved as two separate numbers. A bug, an edit or an old save leaves them out of step, and a player with 5000 points is shown as level 1.

Fix: Tell your AI: save only the total points, and work out the level from it every time.

Past the top level

Nothing stops the points at the top. The player becomes level 31 in a game that has 30, the table of level lines is read past its end, and the game crashes or shows nonsense.

Fix: Tell your AI: stop the total at the points the top level needs, and show a full bar there.

A penalty or a bad number ruins the total

A death penalty adds minus 50, or a bonus formula returns a value that is not a number. The level drops, or the total turns into a value that is not a number and the player is stuck for good.

Fix: Tell your AI: count a gain below zero or not a number as zero. If a penalty should exist, take points off the bar inside the current level and never below its line.

A level that costs nothing

A tiny base cost rounds to zero for a level. Two levels sit on the same line, and one gain skips straight past a level without its reward.

Fix: Tell your AI: round each cost to a whole number and make it at least 1.

How to check it works

A new player at level 1. they earn 99 points: they stay at level 1 with 99 points inside it and 1 point to go.
A new player at level 1. they earn exactly 100 points: they reach level 2 with 0 points inside it and 264 to go.
A new player at level 1. they earn 130 points: they reach level 2 with the extra 30 points already inside it.
A new player at level 1. they earn 835 points in one go: they reach level 4 with 5 points inside it, and the game reports 3 levels gained.
The starting values. you look at the cost of levels 1, 2, 3 and 4: they are 100, 264, 466 and 696 points.
A new player. they earn a huge number of points, then 500 more, or an endless amount: they stand at level 30 with 140372 points and 0 to go, and extra points change nothing.
A player with 250 points. they get minus 50, minus infinity, not a number or 0: their points and level stay exactly the same.
Two new players. one earns 40, 60, 130 and 5 points in turn, and the other earns 235 at once: both have the same points, level and progress inside it.
A new player. they earn 0.4 points, or 99.6 points: 0.4 counts as 0, and 99.6 counts as 100 and reaches level 2.

Works well with

Skill Tree: When one gain crosses several levels, give the skill points of every level crossed, not only of the last one. A level-up gives skill points, and the skill tree decides how they are spent.
Health and Damage: Decide whether a level-up also refills health. Raising the maximum without refilling can feel like a punishment. Work out the new level first, then recalculate the maximum health from it.
Loot Table: If drops depend on level, use the level after the gain, and say so in the game's rules. Kills give points and drops. Add the points first, then roll the table, so a level-up can change what drops.

Common questions

how do experience and levels work in games

Actions earn points and the points add up to a total. The total decides the level, using a table of lines. Each level needs more points than the last, and extra points carry over into the next level.

how much xp should each level need

Start with the first level costing about 10 actions' worth of points, and let each level cost somewhat more. A growth of 1.4 makes level 10 cost about 25 times the first. Test by playing: no level should take much longer than the one before feels fair.

should dying cost experience

Be careful. Losing levels hurts a lot and can make players quit. A softer choice is to lose points inside the current level only, never below its line, so the level is always kept.

what do i tell my ai to add experience and levels

Paste this: Add experience points. Save only the total. Going from level n to n+1 costs 100 times n to the power 1.4, rounded. Work out the level from the total each time, carry leftover points over, allow several level-ups at once, and stop at level 30.

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

14 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