Ascent-of-Man/docs/recharge_system.md

Military Unit Recharge System Implementation

Overview

This implementation adds a recharge/cooldown system to military units in the RTS game engine, providing visual feedback when units cannot attack due to recent attacks or damage taken. The recharge bar is displayed below the unit's health bar.

Features Implemented

1. Recharge Timer System

• Military units now have a configurable recharge time between attacks
• Recharge timer decrements over time, preventing immediate re-attack after each hit
• Units are automatically reset to idle state when recharge completes

2. Visual Feedback - Recharge Bar

• A green bar is displayed below military unit cylinders during recharge cooldown
• Bar fill percentage indicates remaining recharge time (0% = ready to attack, 100% = just attacked)
• Only military units that can attack (config.canAttack()) are shown with recharge bars
• Non-military units (settlement, builders) have the fields but won't display bars

3. Attack Flash Enhancement

• Attack flash timer now uses configurable duration from config
• Flash effect provides immediate visual confirmation of successful attacks
• Color transitions smoothly from red/white back to unit base color

Technical Implementation

Modified Files

unit.h / unit.cpp

Added new member variables:

float attackFlashTimer;   // Flash effect timer (seconds)
float rechargeTimer;      // Recharge/cooldown timer (seconds)
bool isRecharging();      // Checks if unit is currently on cooldown

Modified methods:

• canAttack(): Now checks recharge timer before allowing attack
• performAttack(): Sets rechargeTimer when attack is performed
• takeDamage(): Resets rechargeTimer when unit takes damage
• update(): Decrements both flash and recharge timers each frame

unitconfig.h / unit.cpp

Added configuration fields:

int rechargeTime;              // Time in milliseconds between attacks
float rechargeDuration;        // Visual cooldown bar duration  
int attackFlashDuration;       // How long the flash effect lasts (ms)

Default values:

• recharge_time: 500ms (0.5 seconds)
• recharge_duration: 300ms
• attack_flash_duration: 400ms

unitrenderer.h / unitrenderer.cpp

Added recharge bar rendering:

• New mesh buffers for flat quad-based recharge bars
• Trapezoidal bar geometry showing remaining recharge percentage
• Positioned below unit cylinder with small gap for visual separation
• Only rendered for military units currently recharging

All Unit YAML Configs (config/units/*.yaml)

Added recharge configuration to all 12 unit types:

recharge_time: 500
recharge_duration: 300
attack_flash_duration: 400

Game Mechanics

Attack Cooldown Flow

1. Unit performs attack → attackFlashTimer = 0.4s, rechargeTimer = 0.5s
2. Visual flash effect plays (red/white transition)
3. Recharge bar appears below unit showing remaining cooldown
4. Both timers decrement each frame
5. When rechargeTimer reaches 0, unit can attack again

Damage Taken Flow

1. Unit receives damage → Health decreased
2. attackFlashTimer set to 0.4s (damage flash effect)
3. rechargeTimer reset to full recharge time
4. Unit must wait through recharge before attacking

Visual Hierarchy (from bottom to top)

1. Ground level
2. Recharge bar (below unit, if applicable)
3. Unit cylinder mesh
4. Health bar (if implemented later)
5. Selection ring (when selected)

Configuration Examples

Default Recharge Settings (All Units)

recharge_time: 500      # 0.5 seconds between attacks
recharge_duration: 300   # Visual feedback duration
attack_flash_duration: 400  # Flash effect time

Faster Recharge (Rapid Attack Units)

recharge_time: 300      # Quicker cooldown for high-damage units
attack_flash_duration: 350

Slower Recharge (Heavy Infantry/Armor)

recharge_time: 700      # Longer cooldown for powerful units
attack_flash_duration: 500

Design Rationale

1. Modular Configuration: All recharge parameters are YAML-configurable per the AGENTS.md guidelines
2. Visual Feedback: Recharge bar provides clear indication of when units can attack again
3. Performance: Single mesh buffer reused for all recharge bars (efficient batch rendering)
4. Backwards Compatible: Non-military units have fields but no functional impact
5. Consistent API: isRecharging() method used by both renderer and game logic

Future Enhancement Possibilities

• Add configurable recharge times per tech tree node
• Implement different recharge rates for melee vs ranged attacks
• Add area-of-effect cooldown reduction mechanics
• Implement weapon-specific reload animations
• Display numerical cooldown timer on hover tooltip

---

Implementation Date: 2026-11-10 See AGENTS.md Section 4.2 for Unit Architecture Reference