Action Points

Action points are a small budget of whole points that a character spends on its turn. Every action has a price. A few unspent points carry over to the next turn, within a floor and a ceiling. A heavy action can take a whole untouched turn, and taking an action back returns only what was spent.

Also called: AP, Turn points, Movement points, Turn budget, Action budget.

A hooded heron on a tiled tactics board points toward a hedgehog guard in a stone tower, with three tokens above its head, two used up and one still glowing. — Marrowfeather Gambit, an invented tabletop tactics 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 "Action Points" to my game.

What it should do: Action points make a turn a puzzle of choices. The player has a few points and many things to do, so every move, attack or item use has to earn its place.

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

```mermaid
stateDiagram-v2
  [*] --> fresh
  fresh: Fresh turn
  mid: Mid turn
  out: Out of points
  fresh --> mid: spends some points
  fresh --> out: spends it all
  mid --> out: spends the rest
  mid --> fresh: new turn or full undo
  out --> mid: takes points back
  out --> fresh: new turn begins
```

Use these starting values:
- pointsPerTurn: 3 points
- carryLimit: 1 points
- minPoints: 1 points
- maxPoints: 8 points

Watch out for these common mistakes:
- Points pile up: Tell your AI: carry over only a small limit of unspent points, and cap the total a turn can start with.
- A big action can never be afforded: Tell your AI: let an action that costs more than a whole turn be taken on an untouched turn, and use the whole turn up. Anything else is refused.
- Undo hands out free points: Tell your AI: taking back an action returns at most what was spent so far this turn.
- A slowing effect freezes the character: Tell your AI: hold the points a turn starts with to a floor of at least one, whatever the effects say.
- A negative cost pays points: Tell your AI: only charge a cost that is a number of zero or more, and ignore anything else.

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

Action points make a turn a puzzle of choices. The player has a few points and many things to do, so every move, attack or item use has to earn its place.

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

Fresh turn → Mid turn: spends some points
Fresh turn → Out of points: spends it all
Mid turn → Out of points: spends the rest
Mid turn → Fresh turn: new turn or full undo
Out of points → Mid turn: takes points back
Out of points → Fresh turn: new turn begins

Good starting values

Value	Start with	What it changes
pointsPerTurn	3 points	How many points a turn starts with. Three lets a character do about three small things or one big thing, which makes every turn a real choice without making the player count for long.
carryLimit	1 points	The most unspent points that carry into the next turn. A small carry rewards saving up for a big move, while a large one lets the player hoard points for a huge turn.
minPoints	1 points	The fewest points a turn can start with, even under a slowing effect. At least one keeps a slowed character from being frozen out of the game. At zero, a slowing effect can skip a whole turn.
maxPoints	8 points	The most points a turn can start with, even with carry and speed-ups added. It keeps a stack of bonuses from letting one character act all alone for a turn.

What usually goes wrong

Points pile up

Every unspent point carries over for ever. A player saves for ten turns, then does everything in one huge turn, and the game stops being a turn-by-turn puzzle.

Fix: Tell your AI: carry over only a small limit of unspent points, and cap the total a turn can start with.

A big action can never be afforded

A move costs 6 points and a turn gives 4. The player can never use it, and nothing says why.

Fix: Tell your AI: let an action that costs more than a whole turn be taken on an untouched turn, and use the whole turn up. Anything else is refused.

Undo hands out free points

The player takes back the same action again and again. Each time it returns a full price, and the points climb past what the turn gave.

Fix: Tell your AI: taking back an action returns at most what was spent so far this turn.

A slowing effect freezes the character

Two slowing effects stack, the next turn starts with zero points, and the character never acts again while the others take turns.

Fix: Tell your AI: hold the points a turn starts with to a floor of at least one, whatever the effects say.

A negative cost pays points

A broken item or a discount that overshoots gives an action a cost below zero. Using it adds points to the turn instead of taking them.

Fix: Tell your AI: only charge a cost that is a number of zero or more, and ignore anything else.

How to check it works

A new game with 3 points per turn. the first turn starts: the character has 3 points and it is turn 1.
A fresh turn with 3 points. the character does something that costs 2: 1 point is left, 2 count as spent, and the game is told the change was minus 2.
A turn in which 2 were spent and 1 point is left. the character tries something that costs 2: the action is refused and nothing changes.
A turn with no points left. the character does something that costs nothing: it goes through and the points stay at zero.
A turn with 2 points left, a usual turn of 3 and a carry limit of 1. the turn ends: the next turn starts with 4 points, because 1 of the 2 carried over, and nothing is spent yet.
A carry limit of 1. a turn ends with 3 points left, and another with 7: both next turns start with 4 points.
A fresh turn of 3 points. the character does something that costs 6: it goes through, all 3 points are used, and none are left.
A turn in which 1 point has already been spent. the character tries something that costs 6: it is refused and the 2 points left stay.
A turn in which 1 point was spent. the player takes back an action that cost 5: only that 1 point returns, so the turn is back at 3, and on an untouched turn an undo does nothing.
A floor of one point. a turn ends with a slowing effect of minus 5: the next turn still starts with 1 point, and with a floor of zero it starts with none.
A ceiling of 8 points. a turn ends with a speed-up of plus 20, or a smaller one of plus 2: the next turn starts with 8 points in the first case and 6 in the second.
A turn with 2 points left and 1 spent. a cost below zero, not a number, or endless is tried, either to act or to take back: the points stay at 2, the spent stays at 1, and the action is marked as ignored.

Works well with

Turn-Based Combat: Turn order decides who acts next, and the points decide how much each one does. Ending the turn should hand the points over in the same step. Start the turn, give the points, then let the player act.
Stamina System: Two budgets on one action can be a lot to track. Use stamina for the long fight and points for the single turn, not both for the same thing. Spend points for the action, then stamina for its effort.

Common questions

how do action points work in games

Each turn the character gets a few points. Every action costs some, and the turn ends when the points are gone or the player ends it. A small number of unspent points may carry over.

how many action points should a character get per turn

Start with three. It is enough for a few small actions or one big one, and few enough that every point is a decision.

should unspent action points carry over

A little, yes. One carried point rewards saving up without letting a player hoard points for a huge turn.

what do i tell my ai to add action points

Paste this: Add action points. Each turn starts with 3 points, and 1 unspent point carries over. Every action has a whole-number cost, and an action that is too expensive is refused. A turn never starts with fewer than 1 or more than 8 points. Taking back an action returns only what was spent.

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

22 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