132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# 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:
|
|
```cpp
|
|
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:
|
|
```cpp
|
|
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:
|
|
```yaml
|
|
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)
|
|
```yaml
|
|
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)
|
|
```yaml
|
|
recharge_time: 300 # Quicker cooldown for high-damage units
|
|
attack_flash_duration: 350
|
|
```
|
|
|
|
### Slower Recharge (Heavy Infantry/Armor)
|
|
```yaml
|
|
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* |