Hitbox and Hurtbox

A hitbox is the invisible shape of an attack, and a hurtbox is the invisible shape of a body that can be hurt. An attack lands when the two overlap while the attack is active. Each swing hits each target once, and a wind-up and a recovery keep fights fair and readable.

Also called: Hit detection, Collision boxes, Attack box, Damage zone.

A badger knight swings an iron mallet at a stone-skinned toad, and glowing outlines of the swing and the toad's body overlap in a bright patch at the moment of impact, while a second toad stands outside it. — Gravelmoor Bridge, an invented brush-painted brawler. 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 "Hitbox and Hurtbox" to my game.

What it should do: Fights feel fair when what hurts matches what the player sees. Keeping the shape of an attack apart from the shape of a body lets you tune each without changing how the characters look.

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

```mermaid
stateDiagram-v2
  [*] --> idle
  idle: Ready
  startup: Wind-up
  active: Active
  recovery: Recovery
  idle --> startup: presses attack
  startup --> active: wind-up is over
  active --> recovery: active time is over
  recovery --> idle: recovery is over
```

Use these starting values:
- startupTime: 0.12 s
- activeTime: 0.1 s
- recoveryTime: 0.3 s
- reach: 1.4 units
- hitHeight: 1 units
- offset: 0.2 units

Watch out for these common mistakes:
- The hit that lands every frame: Tell your AI: write down which targets a swing has hit, and skip those until the swing ends.
- A long frame skips the hit: Tell your AI: check for hits on every frame whose time span touches the active window, not only on frames that end inside it.
- The box turns around late: Tell your AI: read the facing once when the swing starts, mirror the box from it, and keep it until the swing ends.
- Touching counts as a hit: Tell your AI: use a strict overlap, with less-than and not less-or-equal, and ignore boxes with no size.
- The attacker hits themselves: Tell your AI: never put the attacker in the list of targets, and start the attack box a little in front of the body.
- A button press in the middle of a swing: Tell your AI: ignore the button until the swing is over, or remember the press for the moment it ends.

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

Fights feel fair when what hurts matches what the player sees. Keeping the shape of an attack apart from the shape of a body lets you tune each without changing how the characters look.

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

Ready → Wind-up: presses attack
Wind-up → Active: wind-up is over
Active → Recovery: active time is over
Recovery → Ready: recovery is over

Good starting values

Value	Start with	What it changes
startupTime	0.12 s	The wind-up before the attack can hurt anyone. It gives the other side time to see the blow coming. Under 0.1 seconds it can no longer be reacted to.
activeTime	0.1 s	How long the attack can hurt. Short makes it precise and hard, long makes it forgiving. It must last at least a couple of frames, or a hit can slip through between two frames.
recoveryTime	0.3 s	The time after the blow in which the attacker is stuck. It is the price of missing, and the chance for the other side to strike back.
reach	1.4 units	How far the attack box reaches. It should be a bit more than the weapon looks, so near misses feel like hits rather than cheats.
hitHeight	1 units	How tall the attack box is. A box as tall as the body hits anything standing in front, and a low one lets a jump pass over.
offset	0.2 units	The gap between the middle of the attacker and the start of the attack box. It stops the attack from hitting things standing behind or inside the attacker.

What usually goes wrong

The hit that lands every frame

The boxes overlap for six frames in a row. The code deals damage on each of them, so one swing does six times the damage.

Fix: Tell your AI: write down which targets a swing has hit, and skip those until the swing ends.

A long frame skips the hit

On a slow device one frame lasts longer than the active window. The code checks only at the end of the frame, the window is already over, and the blow goes through the enemy.

Fix: Tell your AI: check for hits on every frame whose time span touches the active window, not only on frames that end inside it.

The box turns around late

The attack box always sits in front of the character, so turning mid-swing flips the whole attack to the other side, or the box stays right while the picture faces left.

Fix: Tell your AI: read the facing once when the swing starts, mirror the box from it, and keep it until the swing ends.

Touching counts as a hit

Two boxes that exactly touch are counted as overlapping. A player standing at the very tip of the reach gets hit by something that looks a pixel short.

Fix: Tell your AI: use a strict overlap, with less-than and not less-or-equal, and ignore boxes with no size.

The attacker hits themselves

The attack box starts inside the attacker's own body box, so every swing hurts the one who swings.

Fix: Tell your AI: never put the attacker in the list of targets, and start the attack box a little in front of the body.

A button press in the middle of a swing

The player taps attack again during the swing. The code starts a new swing at once, which clears the list of hits, so the same enemy is hit twice within one blow.

Fix: Tell your AI: ignore the button until the swing is over, or remember the press for the moment it ends.

How to check it works

A target stands in front of the attacker, inside the reach. the attacker swings: the target is hit on the 8th frame, once the wind-up is over, and not before.
One target that stands in the reach only during the wind-up, and another that steps in only after the active time is over. the attacker swings: neither is hit.
A target that stays inside the reach for the whole swing. the swing runs to its end: the target is hit exactly once.
Two targets stand in the reach. the attacker swings once: both are hit, once each, on the same frame.
A target stands on each side of the attacker. the attacker swings to the right, and then to the left: only the target on the swing's side is hit each time.
A target on the right and one on the left. the attacker swings right, and the stick flips to the left in the middle of the swing: only the right target is hit.
A target whose edge exactly touches the end of the attack box, or the top of it. the attacker swings: the target is not hit.
A target in the reach. the attacker swings and one frame lasts a whole second: the target is still hit, and the swing is over.
A target that was hit by a swing that has ended. the attacker swings again: the target is hit again, once.
A swing in progress with the target already hit. the player presses attack again: the swing does not restart and the target is not hit again.
A target whose box has no width, or no height, or a negative one. the attacker swings at it: it is never hit.

Works well with

Health and Damage: The boxes only say who was hit. How much it hurts, and whether the target dies, belongs to health. Deal the damage from the list of targets hit, after the whole tick is checked.
Knockback: Use the side the swing went to, not where the target stands, so a hit from the left always pushes right. Push the targets after they are hit, away from the attacker.
Dodge Roll: Invulnerability is simply a body that has no box for a short time. The attack goes on and finds nothing. Take the hurtbox out of the list while the roll protects.
Combo System: Every step has its own times and its own box, and its own list of hits, so the same target can be hit once by each step. Let each step of the combo start its own swing.
Parry: A parry changes what a hit does, not whether the boxes overlap. Find the hit first, then ask the defender what happens. Check the parry window before the hit is dealt.

Common questions

what is the difference between a hitbox and a hurtbox

A hitbox belongs to an attack and says where it can hurt. A hurtbox belongs to a body and says where it can be hurt. A hit happens when one overlaps the other.

why does my attack hit an enemy several times

The boxes overlap for many frames and every frame counts as a hit. Write down who a swing has already hit and skip them until the swing ends.

how big should a hitbox be compared to the sprite

Make the attack box slightly bigger than the weapon looks and the body box slightly smaller than the character. Both mistakes favour the player, so close calls feel fair.

what do i tell my ai to add hit detection

Paste this: Add attack boxes and body boxes. A swing has a wind-up of 0.12 seconds, 0.1 seconds in which it can hurt, and 0.3 seconds of recovery. It hits each target once per swing, mirrors the box by the side it started on, and checks every frame that touches the active time.

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

19 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