Guide

Game hitbox and hurtbox systems explained

Harbor Ruins' first melee build used a single sphere at the sword tip, toggled on for three active frames per swing. Attacks connected through dungeon walls, missed enemies standing beside the blade, and headshots dealt the same damage as body hits because every defender wore one torso capsule. Playtest “whiff” reports spiked 41% above the studio average. The combat refactor replaced tip spheres with bone-swept capsules, split defenders into head/torso/limb hurtboxes, and routed queries through explicit collision layers so geometry never stole hits meant for enemies. Close-quarters fights became legible: players could see why a slash landed, when a parry window opened, and how reach differed between daggers and halberds. A hitbox/hurtbox system is the spatial contract under melee combat and projectile combat: attack volumes that ask “did I touch a valid target?” and defender volumes that answer “where was I hittable?” This guide covers volume types, sweep vs static overlap, layer masks, weak-point multipliers, i-frame suppression, multiplayer authority, the Harbor Ruins refactor, a technique decision table, pitfalls, and a production checklist.

Hitboxes vs hurtboxes: two sides of one query

Confusion between hitboxes and hurtboxes causes more combat bugs than almost any other subsystem. The distinction is simple:

Hitbox (attack volume): ephemeral shape owned by an attack, projectile, or hazard. Lives only during active frames or flight time. Carries damage, knockback, elemental tags, and team filters.
Hurtbox (defender volume): persistent shape on a character, destructible, or interactive prop. Defines where damage can apply. May be disabled during invincibility, cutscenes, or ghost states.

A collision query is asymmetric: the attack’s hitbox tests against the defender’s hurtbox (and sometimes a separate blockbox or parrybox for defensive moves). Visual meshes are cosmetic; never use render triangles for combat resolution unless you enjoy non-deterministic performance and artist-dependent fairness.

Common volume primitives

Shape	Typical use	Trade-off
Sphere	Explosions, AoE pulses, simple pickups	Fast; poor fit for elongated weapons
Capsule	Character hurtboxes, sword sweeps	Smooth normals; good for limbs and blades
Axis-aligned box (AABB)	Fighting-game limb boxes, block volumes	Cheap tests; rotates awkwardly unless re-oriented per frame
Oriented box (OBB)	Shield blocks, vehicle sides	Better rotation fidelity; slightly costlier
Convex mesh / compound	Boss weak points, complex props	Authorial precision; harder to tune and debug

Scale hurtboxes slightly larger than visible models on heroes so near-misses still connect — players forgive generous hurtboxes more than invisible whiffs. Enemy hurtboxes can be tighter to reward precision without changing animation.

Detection strategies: static, sweep, and animated

How you move hitboxes through space determines whether fast swings feel fair:

Static overlap: spawn a volume at the weapon pose for one or more ticks. Cheap but misses motion between frames unless you sample densely.
Sweep (cast between poses): cast a capsule or box from last frame’s bone transform to this frame’s transform. Catches curved arcs and high-speed swings; standard in action games.
Animated hitbox data: keyframed boxes parented to bones, toggled per frame in spreadsheets. Maximum control; fighting games and precision souls-likes live here.
Physics-driven: enable weapon colliders during active frames. Flexible for ragdoll-heavy titles but noisy for rollback netcode unless carefully constrained.

Pair detection with hit-once-per-target flags so a single swing cannot apply damage every frame it overlaps. Multi-hit moves explicitly reset the flag per active window or use discrete hit indices in data.

Active frames and animation sync

Hitboxes must align with frame phases: startup (no hitbox), active (hitbox live), recovery (hitbox off). Author animation events or notifiers that enable/disable volumes at exact ticks. When animators retime a clip, events travel with the animation instead of breaking hard-coded constants in code.

For projectiles, the hitbox rides the bullet’s kinematic path each tick; use continuous collision detection (swept sphere along velocity) to prevent tunneling through thin defenders at high speed.

Collision layers, masks, and team filters

Without explicit layers, environment meshes absorb attacks, friendly fire becomes random, and triggers fire combat code. A typical scheme:

Layer: what an object is (player hurtbox, enemy hurtbox, world static, projectile, trigger).
Mask: what an object tests against (player attack hits enemy hurtbox + destructible, not other player attacks).
Team / allegiance ID: secondary filter for co-op, factions, and PvP arenas where layers alone are insufficient.

Document the matrix in a single table designers can read. Debug builds should render hitboxes and hurtboxes in distinct colors (attack red, hurt green, block blue) with a toggle hotkey. QA cannot file actionable whiff bugs from gameplay video alone without this view.

Weak points and limb multipliers

Split defender hurtboxes by region: head (1.5–2.0× damage), torso (1.0×), limbs (0.8× or armor-gated), backstab cone (bonus if attacker behind). Return the highest-priority overlapping region or the closest-to-attack-origin box to avoid multi-counting one swing. Expose multipliers in data so balance passes do not require re-exporting animations.

Invincibility, ghosting, and defensive volumes

Hurtboxes are not always active. Common suppression rules:

I-frames on dodge: disable all hurtboxes or only torso while leaving a smaller hurtbox on feet for area attacks (design choice).
Spawn protection and cutscenes: global hurtbox off; still run AI so enemies do not stack idle.
Phase transitions: boss invulnerable volumes replaced with interact-only hurtboxes for cinematic QTEs.

Defensive moves may spawn separate parryboxes or blockboxes — thin volumes in front of the defender that intercept attacks before hurtboxes are tested. A successful parry skips damage entirely and may trigger attacker stagger. See parry and block systems for timing; this guide focuses on the volumes those systems query.

Harbor Ruins refactor: from tip spheres to swept limbs

The Ruins dungeon melee pass addressed four concrete failures:

Wall penetration: tip spheres ignored line-of-sight. Fix: ray or sweep occlusion test against world static layer before accepting a hit; alternatively, shrink attack mask so world blocks queries.
Side whiffs: a sphere at the tip missed wide arcs. Fix: capsule sweep along the weapon bone from guard to follow-through, sampled every simulation tick.
Flat damage: one torso hurtbox. Fix: head/torso/arm capsules with multipliers; halberd sweet-spot at mid-blade dealt bonus poise.
Double hits: spin attacks applied damage each overlap frame. Fix: per-swing hit index and per-target hit-once set cleared on move end.

After the pass, mean time-to-first-hit in tutorial combat dropped 0.4 s (players connected sooner because volumes matched animation), and support tickets tagged “attack didn't register” fell 41% over two playtest cohorts. The team exported hitbox gizmos to a shared debug overlay used by animators, designers, and netcode engineers — one source of truth.

Multiplayer authority and rollback

Hit detection in networked games must be deterministic given the same inputs and tick. Common models:

Server authoritative: clients send inputs; server runs hit queries and replicates hits. Fair but latency-sensitive; use lag compensation rewind for shooters.
Rollback (GGPO-style): predict locally, rewind and reconcile when snapshots arrive. Requires identical hitbox simulation on all peers.
Cosmetic client hits: client shows blood and numbers immediately; server confirms or denies. Never grant invulnerability based on client-only hits.

Keep hitbox logic in fixed-point or stable float paths; avoid physics engine nondeterminism in rollback titles. Log hit events with tick, attack ID, defender ID, and hurtbox region for dispute replay.

Technique decision table

Approach	Best for	Avoid when
Static per-frame overlap	Slow attacks, turn-based, mobile budgets	Fast weapon swings at 30 Hz
Bone sweep capsules	Action RPGs, brawlers, souls-likes	You need pixel-perfect fighting-game fidelity
Keyframed box data	Fighting games, competitive platformers	Small team without animation tooling
Physics colliders on weapons	Ragdoll brawlers, physics puzzles	Rollback PvP without heavy constraints
Hitscan ray	Instant guns, lasers	Melee weapons with visible arc

Common pitfalls

Using render meshes as hitboxes — triangle counts vary by LOD; combat becomes art-dependent and non-deterministic.
One hurtbox for the entire body — removes headshots, backstabs, and limb armor gameplay.
Forgetting hit-once semantics — multi-frame overlap melts bosses and breaks combo scaling.
Environment on the attack mask — walls eat hits or, worse, become damageable by mistake.
Desynced animation events — hitbox enables on frame 4 while VFX shows frame 8; players distrust the game.
Scaling hurtboxes with world scale — imported assets at 0.01 scale silently shrink combat volumes.
I-frames that disable hurtbox but not collision — player still blocks allies or gets pushed by kinematic movers.
No debug visualization — whiff bugs become un-reproducible folklore instead of ticket with screenshots.

Production checklist

Define hitbox vs hurtbox vs blockbox/parrybox roles in a one-page combat glossary.
Publish layer and mask matrix; enforce via code review on new entity types.
Choose detection strategy per weapon class (static, sweep, keyframed); document in data schema.
Sync hitbox enable/disable to animation events or authored frame tables.
Implement per-attack hit-once-per-target with explicit multi-hit exceptions.
Split defender hurtboxes by region; wire damage and poise multipliers in spreadsheets.
Add world occlusion or layer blocking so attacks cannot pierce geometry.
Ship debug overlay with color-coded volumes and frame-phase labels.
Log hit events with tick, attack ID, defender ID, and hurtbox region for QA replay.
Validate multiplayer determinism on recorded input fixtures before cert.

Key takeaways

Hitboxes are attack volumes; hurtboxes are where defenders can be damaged — never conflate them with visual meshes.
Sweep tests along weapon bones fix most melee whiffs; static tip spheres fail on arcs and walls.
Layers, masks, and team filters prevent environment steals and friendly-fire accidents.
Regional hurtboxes enable headshots, limb armor, and backstab bonuses without new animations.
Debug visualization and deterministic netcode hooks are as important as the collision math itself.