Health Regeneration

Health regeneration lets a character heal by itself once it has been left alone for a few seconds. Every hit restarts the wait, and the healing eases in instead of snapping on. It stops at a ceiling that can sit below full, and it never brings back a character who is down.

Also called: Regenerating health, Auto-heal, Self-healing, Recharging health, Health recovery.

A small knight made of tin cans crouches behind a broken pillar while green sparkles close the cracks in its armour, and a stone gargoyle across the courtyard turns away. — Tinplate Vigil, an invented pixel-art action 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 "Health Regeneration" to my game.

What it should do: Self-healing lets the player take a risk, retreat and recover, instead of hunting for medical kits. It rewards stepping out of the fight, and the wait stops it from making every hit free.

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

```mermaid
stateDiagram-v2
  [*] --> full
  full: Healthy
  wait: Waiting
  heal: Healing
  down: Down
  full --> wait: takes a hit
  full --> heal: hit, with no wait
  full --> down: knocked out
  wait --> heal: wait is over
  wait --> full: item restores health
  wait --> down: knocked out
  heal --> wait: takes a hit
  heal --> full: health restored
  heal --> down: knocked out
  down --> [*]
```

Use these starting values:
- maxHealth: 100 units
- regenRate: 12 units/s
- regenDelay: 4 s
- rampTime: 1.5 s
- regenCeiling: 1 share of full

Watch out for these common mistakes:
- Healing brings back the dead: Tell your AI: when health is zero, healing by itself does nothing. Only an item or a respawn can bring a character back.
- Healing in the moment of a hit: Tell your AI: when a hit lands, restart the wait and the easing, and do not heal in that same moment.
- Fast computers heal faster: Tell your AI: heal by speed times the seconds that passed, and when a frame is long, count only the seconds after the wait.
- A heal item is lost at the ceiling: Tell your AI: the ceiling only stops regeneration. Never lower health that is already above it.
- A hit of zero holds healing back: Tell your AI: only a hit above zero restarts the wait. Zero, below zero or something that is not a number does nothing.

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

Self-healing lets the player take a risk, retreat and recover, instead of hunting for medical kits. It rewards stepping out of the fight, and the wait stops it from making every hit free.

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

Healthy → Waiting: takes a hit
Healthy → Healing: hit, with no wait
Healthy → Down: knocked out
Waiting → Healing: wait is over
Waiting → Healthy: item restores health
Waiting → Down: knocked out
Healing → Waiting: takes a hit
Healing → Healthy: health restored
Healing → Down: knocked out

Good starting values

Value	Start with	What it changes
maxHealth	100 units	How big the full health is. Hits and healing are best read as shares of this number.
regenRate	12 units/s	How fast health comes back at full speed. At the starting values a character at one tenth of health is back to full in about ten seconds after the wait. It is never zero, because the character could not recover.
regenDelay	4 s	How long the character must go without a hit before healing starts. Four seconds is long enough that standing in the open costs something, and short enough that taking cover works.
rampTime	1.5 s	How long healing takes to reach full speed. A slow start makes the first moments after cover feel safer without a jump in health. At zero it starts at full speed.
regenCeiling	1 share of full	The share of full health that regeneration reaches. Below one, some damage stays until the player finds an item, which makes long fights wear the player down.

What usually goes wrong

Healing brings back the dead

A character at zero health is also healed by the timer, comes back, and walks on after a death screen was already shown.

Fix: Tell your AI: when health is zero, healing by itself does nothing. Only an item or a respawn can bring a character back.

Healing in the moment of a hit

The healing and the hit land in the same moment, so the player takes less than the hit says, or the wait never starts.

Fix: Tell your AI: when a hit lands, restart the wait and the easing, and do not heal in that same moment.

Fast computers heal faster

Healing adds a fixed amount per frame, so a computer running at 144 frames a second heals more than twice as fast as one running at 60.

Fix: Tell your AI: heal by speed times the seconds that passed, and when a frame is long, count only the seconds after the wait.

A heal item is lost at the ceiling

The ceiling is set below full, a medical kit lifts health above it, and the next moment health is cut back to the ceiling. The player wasted the item.

Fix: Tell your AI: the ceiling only stops regeneration. Never lower health that is already above it.

A hit of zero holds healing back

A poison or a fire that deals zero damage in some moments still restarts the wait. The player never heals, and cannot tell why.

Fix: Tell your AI: only a hit above zero restarts the wait. Zero, below zero or something that is not a number does nothing.

How to check it works

A full character that takes a hit of 40, with a wait of 4 seconds. 4 seconds go by with no further hit: health stays at 60 for all of them and starts to rise only after that.
A character at 10 whose wait is over, with healing that eases in over 1.5 seconds and then heals 12 per second. 1.5 seconds pass, and then 1.5 seconds more: health is 19 after the first 1.5 seconds, because the speed climbed from zero, and 31 after the next 1.5, because it now runs at full speed.
A character that has been healing for a while. it takes another hit of 5: health drops by 5, the wait of 4 seconds starts again, the easing starts again, and nothing heals during those 4 seconds.
A ceiling at half of full health and a character at 40. the character heals for as long as it likes: health stops at exactly 50.
A ceiling at half of full health and a character at 80. the character rests for a long time: health stays at 80, and nothing is taken away.
A character at 95 and a ceiling at full. it rests long enough: health stops at exactly 100.
A character at zero health. a long time passes, with or without a heal item offered: health stays at zero and the character stays down.
A character at 20. it takes a hit of 500: health is zero, and the game is told that only 20 were taken off.
A character with one second of wait left. hits of zero, of minus 5, and of something that is not a number come in: the wait keeps counting down and health does not change.
A character at 40 who still has to wait. a heal item of 30 is used: health is 70 at once, the wait carries on, and nothing counts as regeneration.
A character at 10 whose wait is over. 8 seconds are played at 240, 60, 15 or 4 frames a second: health ends at 97 in every case, give or take a fraction.

Works well with

Health and Damage: The hit rules decide how much damage lands and when the character is protected. Regeneration only restarts its wait when a hit really lands. Apply the hit first, then let healing run.

Common questions

how does health regeneration work in games

After a few seconds without a hit, health starts to come back by itself. Every new hit restarts the wait. Most games ease the healing in and stop it at full or at a ceiling.

how long should the wait before regeneration be

Start with about four seconds. Shorter makes hits almost free, longer makes the player hide for a long time.

should health regeneration go all the way to full

It can, and it keeps the game moving. Stopping at a lower ceiling, such as half, makes a long fight wear the player down until they find an item.

what do i tell my ai to add health regeneration

Paste this: Add health regeneration. After 4 seconds without a hit, health comes back at 12 per second, easing in over 1.5 seconds. Every hit restarts the wait. It never heals a character at zero and never lowers health above its ceiling.

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

20 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