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 has_method(&"take_damage") / is checks.
• NEVER hardcode hitstun with OS.delay_msec() — Blocks the OS thread. Use tweens / Engine.time_scale + ignore_time_scale timers.
• NEVER apply RigidBody impulses in _process() — Use _physics_process / _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. damage_data.gd — typed DamageData Resource with enum / flags for damage types (no String elements).
2. health_component.gd — take_damage + i-frame gate + health_changed / died signals.
3. hitbox_hurtbox.gd / hitbox_component.gd — Area hit delivery into hurtboxes.
4. combat_system_patterns.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

• damage_data.gd — MANDATORY DamageData Resource + type flags.
• health_component.gd — MANDATORY Health + i-frames golden path.
• hitbox_hurtbox.gd — MANDATORY before Area combat wiring.
• hitbox_component.gd — 3D Area hitbox companion (flags-aligned).
• combat_system_patterns.gd — MANDATORY for AoE / hit-stop / duck-typing.
• combo_system.gd — windowed combo buffer (Do NOT Load if no combos).
• combat_state.gd — lightweight combat FSM gate.
• damage_popup.gd — floating damage label tween (pool in production).
• combat_logger.gd — batched combat telemetry JSON.
• networked_damage_manager.gd — server-validate damage RPC shell.
• hitbox_visualizer.gd — toggle collision debug colors.

Elite Deltas (keep short)

• Combat telemetry: batch JSON flushes via combat_logger.gd.
• Authoritative damage: networked_damage_manager.gd — clients request; server validates.
• Hitbox debug: hitbox_visualizer.gd + SceneTree.debug_collisions_hint.
• Combos / popups / FSM: combo_system.gd, damage_popup.gd, combat_state.gd.

MANDATORY for telemetry, networked hits, combos, and moved inline tutorials: 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.