Ability Cooldowns

An ability cooldown makes a power wait before it can be used again. Each use spends a charge, and each charge returns after one cooldown, one at a time. The wait is kept as progress, so a change of speed in the middle scales the rest of it and nothing restarts.

Also called: Cooldown, Ability charges, Recharge time, Skill cooldown.

A small tin automaton on a workbench throws a burst of sparks beside two glass vials, one full of amber light and one half filled and slowly refilling from a golden thread. — Tinwhistle Works, an invented clockwork 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 "Ability Cooldowns" to my game.

What it should do: A cooldown keeps a strong move from being used all the time without making it cost a resource. The player waits, plans and uses it at the right moment.

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

```mermaid
stateDiagram-v2
  [*] --> ready
  ready: All ready
  recharging: Recharging
  empty: No charge
  ready --> ready: nothing used
  ready --> recharging: uses a charge
  ready --> empty: uses the only charge
  recharging --> recharging: recharge goes on
  recharging --> ready: all charges back
  recharging --> empty: uses the last charge
  empty --> empty: waits
  empty --> recharging: a charge is back
  empty --> ready: the charge is back
```

Use these starting values:
- cooldown: 4 s
- maxCharges: 2

Watch out for these common mistakes:
- Using an ability restarts the wait: Tell your AI: keep the progress toward the next charge separate, and never touch it when a charge is used.
- A change of speed restarts the wait: Tell your AI: store the wait as progress from 0 to 1 and add dt times the speed divided by the cooldown each tick.
- A long frame loses the extra time: Tell your AI: keep the leftover, and give back as many charges as the time covers.
- A cooldown of zero: Tell your AI: keep the cooldown above zero, and if an ability should have no wait, give it a very short one.
- The charge comes back in the same moment as the press: Tell your AI: let time pass first, then check the press. A charge that arrives this moment can be used this moment.
- Strange speeds: Tell your AI: never let the speed go below zero. Zero freezes the wait. Treat anything that is not a number as normal speed.

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 cooldown keeps a strong move from being used all the time without making it cost a resource. The player waits, plans and uses it at the right moment.

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

All ready → All ready: nothing used
All ready → Recharging: uses a charge
All ready → No charge: uses the only charge
Recharging → Recharging: recharge goes on
Recharging → All ready: all charges back
Recharging → No charge: uses the last charge
No charge → No charge: waits
No charge → Recharging: a charge is back
No charge → All ready: the charge is back

Good starting values

Value	Start with	What it changes
cooldown	4 s	How long one charge takes to come back at normal speed. Four seconds is long enough to be felt and short enough to be used several times in a fight. It is never zero, because the game divides by it.
maxCharges	2	How many uses the ability can store. Two allows a quick double use and then a wait. At 1 it is a plain cooldown.

What usually goes wrong

Using an ability restarts the wait

With one charge already on its way back, the player uses the other. A single timer for the whole ability starts over, and the half-finished charge is lost.

Fix: Tell your AI: keep the progress toward the next charge separate, and never touch it when a charge is used.

A change of speed restarts the wait

A speed-up arrives halfway through a cooldown of 4 seconds that stores seconds left. Either the wait jumps back to 4 or keeps its old end, and the bonus does nothing for the charge already running.

Fix: Tell your AI: store the wait as progress from 0 to 1 and add dt times the speed divided by the cooldown each tick.

A long frame loses the extra time

The game stalls for 6 seconds. A cooldown of 4 gives back one charge and throws away the other 2 seconds, so the second charge comes late.

Fix: Tell your AI: keep the leftover, and give back as many charges as the time covers.

A cooldown of zero

The wait is divided by the cooldown. At zero the progress becomes endless or not-a-number, and the ability breaks for good.

Fix: Tell your AI: keep the cooldown above zero, and if an ability should have no wait, give it a very short one.

The charge comes back in the same moment as the press

The last charge returns in the very moment the player presses. If the press is checked first, it is thrown away and the player has to press again, which feels like a lost input.

Fix: Tell your AI: let time pass first, then check the press. A charge that arrives this moment can be used this moment.

Strange speeds

A slow effect is stacked until the speed turns negative, and the progress runs backwards. Or a broken value arrives that is not a number, and the progress is ruined for the rest of the game.

Fix: Tell your AI: never let the speed go below zero. Zero freezes the wait. Treat anything that is not a number as normal speed.

How to check it works

Your ability is ready with 2 charges. you press the button: it goes off and 1 charge is left.
Your ability has no charge left. you press the button: nothing happens.
You used one of two charges. you wait 3.5 seconds, and then another 0.7: the charge is not back after the first wait and is back after the second.
One charge is three quarters of the way back. you use the other charge: the charge on its way still arrives one second later.
Your ability has no charge. you wait a little more than one cooldown, and then another full one: you have 1 charge after the first wait and 2 after the second.
A charge is exactly halfway back. the speed doubles and you wait one more second: the charge is back, because the rest of the wait ran twice as fast.
A charge is partway back. the speed is zero for ten seconds: the charge has not moved and the time left is endless.
Three charges are missing and a cooldown is 4 seconds. a single stretch of 10 seconds goes by at once: 2 charges are back and half of the next is done.
Your ability has no charge but one is a hair from returning. you press the button in the moment it arrives: the ability goes off.

Works well with

Mana Pool: If the mana is short, the cooldown must not start, or a refused spell would still cost the player a wait. Check both before either is spent: the cooldown first, then the mana, then take both.
Combo System: A finisher with a cooldown keeps a combo from being looped forever. Let the combo decide what the player is trying, and the cooldown decide whether it is allowed.
Jump Buffering: Remembering a press a split second early removes the lost input at the end of a cooldown. Buffer the press for a moment, then try the use when the charge returns.

Common questions

how do cooldowns work in games

After an ability is used, it cannot be used again until a wait is over. With charges, each use costs one charge and charges come back one at a time, so a quick double use is possible.

how long should an ability cooldown be

Start with about 4 seconds for a normal ability, and tune from there. Under 2 seconds it feels like spam, and over 20 seconds the player forgets they have it.

how do cooldown reduction bonuses work

They make the wait run faster. Store the wait as progress, not seconds left, so a bonus that arrives halfway speeds up only the rest.

what do i tell my ai to add cooldowns

Paste this: Add a cooldown of 4 seconds with 2 charges. Each use costs one charge, charges come back one at a time, and using one never restarts the wait for the next. Keep the wait as progress so speed bonuses work.

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