Combat System

Expert guidance for building flexible, component-based combat systems.

NEVER Do

NEVER use direct damage references (

target.health -= 10

)

— Bypasses armor, resistance, events. Use DamageData + HealthComponent pattern.

NEVER forget invincibility frames

— Without i-frames, multi-hit attacks deal damage every frame. Add 0.5-1s invincibility after hit.

NEVER keep hitboxes active permanently

— Enable/disable hitboxes with animation tracks. Permanent hitboxes cause unintended damage.

NEVER use groups for hitbox filtering

— Use collision layers. Groups don't respect physics layers and cause friendly fire.

NEVER emit damage_received without DamageData

— Raw int/float damage loses context (source, type, knockback). Always use DamageData class.

Available Scripts

MANDATORY

Read the appropriate script before implementing the corresponding pattern. hitbox_hurtbox.gd Component-based hitbox with hit-stop and knockback. Uses Engine.time_scale with ignore_time_scale timer for proper hit-stop freeze frame. Damage System

damage_data.gd

class_name DamageData extends RefCounted var amount : float var source : Node var damage_type : String = "physical" var knockback : Vector2 = Vector2 . ZERO var is_critical : bool = false func _init ( dmg : float , src : Node = null ) -> void : amount = dmg source = src Hurtbox/Hitbox Pattern

hurtbox.gd

extends Area2D class_name Hurtbox signal damage_received ( data : DamageData ) @ export var health_component : Node func _ready ( ) -> void : area_entered . connect ( _on_area_entered ) func _on_area_entered ( area : Area2D ) -> void : if area is Hitbox : var damage := area . get_damage ( ) damage_received . emit ( damage ) if health_component : health_component . take_damage ( damage )

hitbox.gd

extends Area2D class_name Hitbox @ export var damage : float = 10.0 @ export var damage_type : String = "physical" @ export var knockback_force : float = 100.0 @ export var owner_node : Node func get_damage ( ) -> DamageData : var data := DamageData . new ( damage , owner_node ) data . damage_type = damage_type

Calculate knockback direction

if owner_node : var direction := ( global_position - owner_node . global_position ) . normalized ( ) data . knockback = direction * knockback_force return data Health Component

health_component.gd

extends Node class_name HealthComponent signal health_changed ( old_health : float , new_health : float ) signal died signal healed ( amount : float ) @ export var max_health : float = 100.0 @ export var current_health : float = 100.0 @ export var invincible : bool = false func take_damage ( data : DamageData ) -> void : if invincible : return var old_health := current_health current_health -= data . amount current_health = clampf ( current_health , 0 , max_health ) health_changed . emit ( old_health , current_health ) if current_health <= 0 : died . emit ( ) func heal ( amount : float ) -> void : var old_health := current_health current_health += amount current_health = minf ( current_health , max_health ) healed . emit ( amount ) health_changed . emit ( old_health , current_health ) func is_dead ( ) -> bool : return current_health <= 0 Combat State Machine

combat_state.gd

extends Node class_name CombatState enum State { IDLE , ATTACKING , BLOCKING , DODGING , STUNNED } var current_state : State = State . IDLE var can_act : bool = true func enter_attack_state ( ) -> bool : if not can_act : return false current_state = State . ATTACKING can_act = false return true func enter_block_state ( ) -> void : current_state = State . BLOCKING func enter_dodge_state ( ) -> bool : if not can_act : return false current_state = State . DODGING can_act = false return true func exit_state ( ) -> void : current_state = State . IDLE can_act = true Combo System

combo_system.gd

extends Node class_name ComboSystem signal combo_executed ( combo_name : String ) @ export var combo_window : float = 0.5 var combo_buffer : Array [ String ] = [ ] var last_input_time : float = 0.0 func register_input ( action : String ) -> void : var current_time := Time . get_ticks_msec ( ) / 1000.0 if current_time - last_input_time

combo_window : combo_buffer . clear ( ) combo_buffer . append ( action ) last_input_time = current_time check_combos ( ) func check_combos ( ) -> void :

Light → Light → Heavy = Special Attack

if combo_buffer . size ( )

= 3 : var last_three := combo_buffer . slice ( - 3 ) if last_three == [ "light" , "light" , "heavy" ] : execute_combo ( "special_attack" ) combo_buffer . clear ( ) func execute_combo ( combo_name : String ) -> void : combo_executed . emit ( combo_name ) Ability System

ability.gd

class_name Ability extends Resource @ export var ability_name : String @ export var cooldown : float = 1.0 @ export var damage : float = 25.0 @ export var range : float = 100.0 @ export var animation : String var is_on_cooldown : bool = false func can_use ( ) -> bool : return not is_on_cooldown func use ( caster : Node ) -> void : if not can_use ( ) : return is_on_cooldown = true

Execute ability logic

_execute ( caster )

Start cooldown

await caster . get_tree ( ) . create_timer ( cooldown ) . timeout is_on_cooldown = false func _execute ( caster : Node ) -> void :

Override in derived abilities

pass Damage Popups

damage_popup.gd

extends Label func show_damage ( amount : float , is_crit : bool = false ) -> void : text = str ( int ( amount ) ) if is_crit : modulate = Color . RED scale = Vector2 ( 1.5 , 1.5 ) var tween := create_tween ( ) tween . set_parallel ( true ) tween . tween_property ( self , "position:y" , position . y - 50 , 1.0 ) tween . tween_property ( self , "modulate:a" , 0.0 , 1.0 ) tween . finished . connect ( queue_free ) Critical Hits func calculate_damage ( base_damage : float , crit_chance : float = 0.1 ) -> DamageData : var data := DamageData . new ( base_damage ) if randf ( ) < crit_chance : data . is_critical = true data . amount *= 2.0 return data Best Practices Separate Concerns - Health ≠ Combat ≠ Movement Use Signals - Decouple systems Area2D for Hitboxes - Built-in collision detection Invincibility Frames - Prevent spam damage Reference Related: godot-2d-physics , godot-animation-player , godot-characterbody-2d Related Master Skill: godot-master