MaidEngine/docs/superpowers/specs/2026-04-04-combat-tactics-design.md

Combat Tactics System Design

Overview

Units gain a list of selectable combat tactics that modify how they participate in combat. Tactics encapsulate their own stat logic — each tactic knows how to produce offensive stats and determine the relevant defensive stat, rather than exposing configuration for the combat system to interpret. Both attacker and defender select a tactic during the combat proposal phase, with AI auto-selecting for non-player units.

Data Model

CombatTactic Base Class

A new base CombatTactic resource (resources/resource_definitions/combat_tactic.gd):

Properties:

• name: String — display name (e.g., "Attack", "Heavy Strike", "Fireball", "Defend")
• range: CombatTacticRange — exported resource determining range validity (see below)

Methods (virtual, overridden by subclasses):

• func get_offensive_stats(unit: Unit) -> Dictionary — returns {"atk": int, "hit": int} with the tactic's effective offensive values pulled from the unit's stats and modified as needed. Returns null if the tactic does not attack (e.g., Defend).
• func get_relevant_defense(unit: Unit) -> int — returns the defense value from the given unit that applies against this tactic's attack. E.g., a physical tactic returns unit.current_stats.phys_def, a magical one returns unit.current_stats.magic_def.
• func deals_damage() -> bool — returns whether this tactic produces an attack. Base implementation returns get_offensive_stats() != null. Subclasses like Defend override to return false.

The combat system never interprets damage types or applies modifiers — it just calls these methods.

CombatTactic Subclasses

AttackCombatTactic extends CombatTactic:

• get_offensive_stats(unit) returns {"atk": unit.current_stats.phys_atk, "hit": unit.current_stats.hit}
• get_relevant_defense(unit) returns unit.current_stats.phys_def

DefendCombatTactic extends CombatTactic:

• get_offensive_stats(unit) returns null
• deals_damage() returns false
• get_relevant_defense(unit) returns unit.current_stats.phys_def (default for display; unused in resolution)

Future subclasses (not built now, examples for illustration):

• MagicAttackCombatTactic — pulls magic_atk/magic_def, could apply modifiers
• HeavyAttackCombatTactic — pulls phys_atk + 5 and hit - 20

CombatTacticRange Hierarchy

Range checking is polymorphic via a resource subclass hierarchy:

CombatTacticRange (base Resource, resources/resource_definitions/combat_tactic_range.gd):

• func is_valid_range(distance: int, unit: Unit) -> bool — abstract, returns false by default

FixedCombatTacticRange extends CombatTacticRange:

• tactic_range: int — the fixed max range in tiles
• Returns distance <= tactic_range

AnyCombatTacticRange extends CombatTacticRange:

• Always returns true

UnitMatchingCombatTacticRange extends CombatTacticRange:

• Returns distance <= unit.current_stats.atk_range

Built-in Tactics

Two built-in tactic instances, always available to all units:

• Attack — AttackCombatTactic with range: UnitMatchingCombatTacticRange
• Defend — DefendCombatTactic with range: AnyCombatTacticRange

These are instantiated in code (not .tres files) since they use specific subclasses. Future tactics with more complex behavior would also be subclasses; a generic parameterized subclass can be added later when patterns emerge across many similar tactics.

Unit Changes

Tactic Assignment

Unit gains:

• @export var tactics: Array[CombatTactic] — additional tactics beyond the built-ins (e.g., Fireball, Heavy Strike)
• At _ready(), Attack and Defend are appended to the unit's tactic list automatically. Custom tactics from the export list are kept as-is. This guarantees every unit always has Attack and Defend.

CombatProposal Changes

CombatantStats Additions

CombatantStats gains:

• available_tactics: Array[CombatTactic] — tactics filtered to those valid for the combat distance
• selected_tactic: CombatTactic — the chosen tactic (defaults to Attack)

The stat snapshot (atk, def, hit, etc.) is produced by calling the selected tactic's methods:

• atk and hit come from selected_tactic.get_offensive_stats(unit) (null if the tactic doesn't attack)
• def comes from the opponent's selected_tactic.get_relevant_defense(this_unit) — the defense stat used is determined by what attack is incoming, not what this unit is doing
• When the opponent's tactic doesn't deal damage, def defaults to phys_def for display purposes

Stat Recalculation

When a tactic is changed on either side:

1. The combatant's offensive stats recalculate via new_tactic.get_offensive_stats(unit)
2. The opponent's defensive stat recalculates via new_tactic.get_relevant_defense(opponent)
3. Both sides' snapshots update accordingly

CombatSystem Changes

Proposal Creation

create_proposal(attacker, defender) expands to:

1. Calculate tile distance between attacker and defender
2. For each unit, filter their tactics list by tactic.range.is_valid_range(distance, unit)
3. Default-select Attack for both sides
4. Snapshot stats with Attack's modifiers applied (none for the base case)
5. For AI combatants, auto-select optimal tactic (see AI Selection below)

New Method: update_tactic

update_tactic(proposal, is_attacker: bool, tactic: CombatTactic):

• Sets the combatant's selected_tactic
• Recalculates that combatant's offensive stats via tactic.get_offensive_stats(unit)
• Recalculates the opponent's defensive stat via tactic.get_relevant_defense(opponent)
• Called by the UI when the player picks a different tactic

Combat Resolution

apply_proposal() changes:

• If a combatant's selected_tactic.deals_damage() returns false, skip their attack entirely (no hit roll, no damage)
• Otherwise, resolution works as before: roll against hit, apply atk - def damage
• The stats in the snapshot are already produced by the tactic's methods, so resolution logic stays simple

AI Tactic Selection

For non-player combatants, auto-select the tactic that maximizes predicted damage:

1. For each available tactic where tactic.deals_damage() is true:
   • Get offensive stats via tactic.get_offensive_stats(unit)
   • Get opponent's relevant defense via tactic.get_relevant_defense(opponent)
   • Calculate effective damage: offensive.atk - defense
2. Pick the tactic with the highest damage
3. If all tactics result in 0 or negative damage, select Defend
4. This logic should be isolated in its own method for easy future modification (e.g., factoring in hit chance later)

Combat UI Changes

Tactic Selector

Each combatant's side in the proposal panel gains a tactic dropdown/list:

• Shows available_tactics by name
• Defaults to Attack
• On selection change, calls CombatSystem.update_tactic() and refreshes the displayed stats
• For AI combatants, the selector is shown as read-only so the player can see what the AI chose

Existing UI

• Stat labels (ATK, DEF, HIT, SPD) continue working as-is — they read from the snapshot which now includes tactic modifiers
• Fight/cancel buttons and overall flow unchanged
• The selected tactic name should be visible for each combatant

File Changes Summary

New Files

• resources/resource_definitions/combat_tactic.gd — CombatTactic base class
• resources/resource_definitions/attack_combat_tactic.gd — AttackCombatTactic subclass
• resources/resource_definitions/defend_combat_tactic.gd — DefendCombatTactic subclass
• resources/resource_definitions/combat_tactic_range.gd — base range class
• resources/resource_definitions/fixed_combat_tactic_range.gd
• resources/resource_definitions/any_combat_tactic_range.gd
• resources/resource_definitions/unit_matching_combat_tactic_range.gd

Modified Files

• nodes/unit.gd — add tactics export, append built-in Attack/Defend at ready
• resources/resource_definitions/combat_proposal.gd — add available_tactics, selected_tactic to CombatantStats
• nodes/combat_system.gd — distance calculation, tactic filtering, update_tactic method, AI selection, tactic-driven stat resolution
• scripts/combat_ui.gd — tactic selector UI elements, refresh on tactic change
• prefabs/combat_ui.tscn — add tactic selector nodes to proposal panel

Out of Scope

• SP/resource costs for tactics
• Healing tactics (targeting allies) — future work, would be a new CombatTactic subclass
• Generic parameterized tactic subclass (for when many tactics share a pattern)
• Complex AI (hit chance weighting, situational awareness)