godot-combat-system

NEVER Do

• NEVER use direct damage references (target.health -= 10) — Bypass armor, resistances, and i-frames. Always DamageData + HealthComponent.take_damage.
• NEVER forget invincibility frames (i-frames) — Multi-hit shapes otherwise tick every physics frame. Apply a short invuln window after a successful hit.
• NEVER keep hitboxes active permanently — Enable/disable with AnimationPlayer tracks or timed code; permanent monitoring causes ghost hits.
• NEVER use groups for physics-based hit filtering — Prefer collision layers/masks (C++ filter). Groups are secondary logic, not the physics gate.
• NEVER emit damage signals without a DamageData object — Raw numbers lose type, source, knockback, and crit context.
• NEVER use raw strings for elemental damage types — Use enum / @export_flags bitfields. String "physical" violates this skill’s own contract.
• NEVER use try/catch to validate targets — GDScript has no exceptions. Use hasmethod(&"takedamage") / is checks.
• NEVER hardcode hitstun with OS.delaymsec() — Blocks the OS thread. Use tweens / Engine.timescale + ignoretimescale timers.
• NEVER apply RigidBody impulses in process() — Use physicsprocess / integrate_forces.
• NEVER couple UI lifebars inside the Player script — Emit health_changed; HUD listens.
• NEVER leave CollisionShapes active on dead entities — set_deferred("disabled", true) on death.
• NEVER scale CollisionShapes non-uniformly — Scale the shape resource (radius, size), not the node transform unevenly.
• NEVER use instanced Nodes for base combat stats — Prefer Resource / RefCounted containers; duplicate() per instance.
• NEVER use standard strings for high-frequency state names — Prefer StringName (&"attacking").
• NEVER forget duplicate() on shared Resource stats — Shared templates = shared health pools.

Golden Path (MANDATORY)

1. [damagedata.gd](scripts/damagedata.gd) — typed DamageData Resource with enum / flags for damage types (no String elements).
2. [healthcomponent.gd](scripts/healthcomponent.gd) — takedamage + i-frame gate + healthchanged / died signals.
3. [hitboxhurtbox.gd](scripts/hitboxhurtbox.gd) / [hitboxcomponent.gd](scripts/hitboxcomponent.gd) — Area hit delivery into hurtboxes.
4. [combatsystempatterns.gd](scripts/combatsystempatterns.gd) — duck-typing, hit-stop, nodeless AoE, frame sync.

Do NOT re-inline Hitbox/Health/Combo/Ability tutorials in scenes. Route abilities to godot-ability-system; compose components per godot-composition; FSMs via godot-state-machine-advanced.

Decision Tree

Damage Type Contract (aligned with NEVER)

# From damage_data.gd — prefer this shape everywhere
enum DamageType { PHYSICAL = 1, FIRE = 2, ICE = 4, LIGHTNING = 8, POISON = 16 }

@export_flags("Physical", "Fire", "Ice", "Lightning", "Poison")
var damage_types: int = DamageType.PHYSICAL

Hitboxes must pass DamageData (or equivalent AttackData built from the same flags), never "Physical" strings.

Available Scripts

• [damagedata.gd](scripts/damagedata.gd) — MANDATORY DamageData Resource + type flags.
• [healthcomponent.gd](scripts/healthcomponent.gd) — MANDATORY Health + i-frames golden path.
• [hitboxhurtbox.gd](scripts/hitboxhurtbox.gd) — MANDATORY before Area combat wiring.
• [hitboxcomponent.gd](scripts/hitboxcomponent.gd) — 3D Area hitbox companion (flags-aligned).
• [combatsystempatterns.gd](scripts/combatsystempatterns.gd) — MANDATORY for AoE / hit-stop / duck-typing.
• [combosystem.gd](scripts/combosystem.gd) — windowed combo buffer (Do NOT Load if no combos).
• [combatstate.gd](scripts/combatstate.gd) — lightweight combat FSM gate.
• [damagepopup.gd](scripts/damagepopup.gd) — floating damage label tween (pool in production).
• [combatlogger.gd](scripts/combatlogger.gd) — batched combat telemetry JSON.
• [networkeddamagemanager.gd](scripts/networkeddamagemanager.gd) — server-validate damage RPC shell.
• [hitboxvisualizer.gd](scripts/hitboxvisualizer.gd) — toggle collision debug colors.

Elite Deltas (keep short)

• Combat telemetry: batch JSON flushes via [combatlogger.gd](scripts/combatlogger.gd).
• Authoritative damage: [networkeddamagemanager.gd](scripts/networkeddamagemanager.gd) — clients request; server validates.
• Hitbox debug: [hitboxvisualizer.gd](scripts/hitboxvisualizer.gd) + SceneTree.debugcollisionshint.
• Combos / popups / FSM: [combosystem.gd](scripts/combosystem.gd), [damagepopup.gd](scripts/damagepopup.gd), [combatstate.gd](scripts/combatstate.gd).

MANDATORY for telemetry, networked hits, combos, and moved inline tutorials: [elite-combat-patterns.md](references/elite-combat-patterns.md). Do NOT Load for first DamageData + HealthComponent pass.

Reference

Progressive disclosure: Skim Official Documentation only for the APIs you are implementing (Areas, layers/masks, Resources, signals, timers, animation hit windows). Open Related Skills when wiring adjacent systems—do not preload the whole lattice.

Official Documentation

• Using Area2D — Hitbox/hurtbox combat is Area overlap detection (area_entered / monitoring), not CharacterBody movement queries.
• Physics introduction — Prefer collision layers/masks for hit filtering; groups are slower and do not replace physics masks for high-frequency combat.
• Area2D — 2D hit volumes: monitoring/monitorable, areaentered, and layer/mask bits for team/faction filtering.
• Area3D — 3D HitboxComponent / hurtbox volumes use the same Area overlap model with 3D layers and shapes.
• CollisionShape2D — Enable/disable attack shapes with setdeferred("disabled", …) so the physics server is not mutated mid-step; never non-uniform-scale the node.
• PhysicsShapeQueryParameters3D — Nodeless AoE/explosions via intersectshape on PhysicsDirectSpaceState3D without spawning temporary Area nodes.
• AnimationPlayer — Drive hitbox active windows from animation tracks (or method calls) so attacks are not permanently monitoring.
• Resources — Keep DamageData / combat stats as data (Resource / RefCounted), and duplicate() shared templates per instance so enemies do not share one health pool.
• Using signals — Emit healthchanged / died / damage events so HUD and VFX subscribe without coupling lifebars into the player script.
• SceneTreeTimer — Hit-stop after Engine.timescale = 0 must use createtimer(..., ignoretime_scale=true) or the thaw timer freezes with the world.
• Tween — Interruptible hitstun/flash VFX: kill and recreate tweens on consecutive hits instead of stacking parallel flash animations.
• High-level multiplayer — Authoritative damage: clients request hits; the server validates and confirms via @rpc before applying take_damage.

Related Skills

Prerequisites

• godot-2d-physics — Area layers/masks, CollisionShape2D deferred disable, and space queries are the physics substrate under hitbox/hurtbox filtering.
• godot-signal-architecture — Damage, health, and death signals need clear ownership so combat components stay decoupled from UI and AI listeners.
• godot-composition — Prefer HealthComponent / HitboxComponent children over baking combat into a monolithic Character script.
• godot-resource-data-patterns — DamageData, elemental flags, and combat stats belong in Resource/RefCounted data with safe duplicate() on spawn.

Complements

• godot-ability-system — Abilities resolve into this skill’s damage/targeting pipeline; keep ability metadata separate from DamageData.
• godot-rpg-stats — Armor, resistances, crit chance, and modifier stacks feed take_damage before health is written.
• godot-animation-player — Attack animations own hitbox enable windows, cancel frames, and recovery locks for combos.
• godot-state-machine-advanced — IDLE/ATTACKING/BLOCKING/STUNNED combat states belong in a character FSM that gates can_act, not ad-hoc bool soup.
• godot-input-handling — Combo buffers and attack actions should call into combat/combo systems from the action map rather than embedding hit logic in input callbacks.

Downstream / consumers

• godot-monte-carlo-balancer — After DamageData, i-frames, cooldowns, and crit curves are tunable, Monte Carlo sims prove DPS/TTK bands before shipping difficulty.
• godot-multiplayer-networking — Predicted hits, lag compensation, and authority checks build on the DamageData + server-validate RPC split.
• godot-genre-action-rpg — Action-RPG combat loops assemble hitboxes, abilities, stats, and progression genre glue on top of this skill.

Master

• godot-master — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.