Combat base added

docs/superpowers/specs/2026-04-02-combat-system-design.md

@@ -0,0 +1,87 @@
+# Combat System
+
+## Overview
+
+A stateless CombatSystem node that creates pre-combat proposals and applies combat resolution between two units. The system encapsulates all combat stat calculation so other systems don't need to know proposal logic.
+
+## CombatProposal Resource
+
+`resources/resource_definitions/combat_proposal.gd`
+
+A Resource containing two sides — attacker and defender. Each side holds:
+
+- A reference to the `Unit` node
+- Pre-combat snapshot stats via an inner class `CombatantStats`:
+  - `hp: int` — from `current_stats.current_hp`
+  - `sp: int` — from `current_stats.current_sp`
+  - `hit: int` — calculated as `own hit - opponent's eva`
+  - `atk: int` — from `current_stats.phys_atk`
+  - `def: int` — from `current_stats.phys_def`
+  - `spd: int` — from `current_stats.spd`
+
+### Stat Calculation
+
+For the **attacker** side:
+- `atk` = attacker's `phys_atk`
+- `def` = attacker's `phys_def`
+- `hit` = attacker's `hit` - defender's `eva`
+- `hp`, `sp`, `spd` copied directly from attacker's `current_stats`
+
+For the **defender** side:
+- `atk` = defender's `phys_atk`
+- `def` = defender's `phys_def`
+- `hit` = defender's `hit` - attacker's `eva`
+- `hp`, `sp`, `spd` copied directly from defender's `current_stats`
+
+In the future, different attacks may swap between physical and magic stats, but for now only physical stats are used.
+
+## CombatSystem Node
+
+`nodes/combat_system.gd`
+
+A `Node` added to the strategy phase scene tree. Stateless — operates purely on units passed in.
+
+### `create_proposal(attacker: Unit, defender: Unit) -> CombatProposal`
+
+- Reads both units' `current_stats`
+- Builds a `CombatProposal` with snapshot stats for each side
+- Applies cross-calculations (hit - eva)
+- Returns the proposal without modifying any unit state
+
+### `apply_proposal(proposal: CombatProposal) -> void`
+
+1. **Attacker strikes:** Roll random int 1–100. If roll <= attacker's calculated `hit`, apply `max(attacker.atk - defender.def, 0)` damage to the defender Unit's `current_stats.current_hp` (modifies the actual unit, not the snapshot).
+2. **Counterattack:** If the defender Unit's `current_stats.current_hp > 0` after the attack, roll 1–100 for defender. If roll <= defender's calculated `hit`, apply `max(defender.atk - attacker.def, 0)` damage to the attacker Unit's `current_stats.current_hp`.
+
+- Damage has a floor of 0 (no negative damage / healing).
+- Range is ignored for now. In the future, counterattack will depend on whether the defender has skills at appropriate range (defaulting to a "defend" action if not).
+
+## Scene Integration
+
+The CombatSystem node is added to `scenes/strategy_phase.tscn` as a sibling of PlayerController, CombatMap, etc. No exports needed.
+
+```
+CombatTest (Node2D)
+  ├─ CombatUI
+  ├─ CombatMap
+  ├─ PlayerController
+  ├─ CombatSystem       <-- new
+  ├─ Camera2D
+  └─ AudioStreamPlayer
+```
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `resources/resource_definitions/combat_proposal.gd` | New — CombatProposal resource with CombatantStats inner class |
+| `nodes/combat_system.gd` | New — CombatSystem node with `create_proposal` and `apply_proposal` |
+| `scenes/strategy_phase.tscn` | Add CombatSystem node to scene tree |
+
+## Out of Scope
+
+- Magic attack/defense selection (future: different attack types swap stats)
+- Range-based counterattack eligibility (future: defend action when no skills in range)
+- Critical hits
+- UI for displaying the combat proposal
+- Animations or visual feedback for combat resolution