# 79 — BPC_FPSCounter

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- [`WBP_FPSCounterWidget`](../06-ui/47_WBP_FPSCounterWidget.md) — UI display (Phase 5)
- [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) — Quality auto-adjustment
- [`SS_SettingsManager`](../11-polish/71_SS_SettingsManager.md) — Show FPS toggle
- [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) — Debug overlay toggle

### Purpose
Performance monitoring component that calculates and displays real-time FPS (frames per second), frame time, and other performance metrics. Supports configurable update intervals, color-coded thresholds (green/yellow/red), on-screen display toggle, and optional system statistics (CPU/GPU time, memory usage). Provides performance data to auto-scaling systems and developer debugging tools.

### Enums

**EFPSDisplayMode**

| Value | Description |
|-------|-------------|
| Off | Hidden |
| Simple | FPS only |
| Detailed | FPS + frame time |
| Full | FPS + frame time + CPU/GPU |
| Profiling | Full + memory + draw calls |

**EFPSStatusColor**

| Value | Description |
|-------|-------------|
| Good | FPS >= 60 |
| Warning | FPS 30–59 |
| Critical | FPS < 30 |

### Structs

**FPerformanceMetrics**

| Field | Type | Description |
|-------|------|-------------|
| CurrentFPS | Float | Frames per second |
| AverageFPS | Float | Smoothed average |
| MinFPS | Float | Lowest this session |
| MaxFPS | Float | Highest this session |
| FrameTime | Float | Delta time in ms |
| CPUTime | Float | CPU frame time ms |
| GPUTime | Float | GPU frame time ms |
| UsedMemoryMB | Float | Memory usage |
| DrawCalls | Int32 | Current draw calls |
| TriangleCount | Int32 | Rendered triangles |

### Variables

| Name | Type | Description |
|------|------|-------------|
| `DisplayMode` | EFPSDisplayMode | Current display level |
| `UpdateInterval` | Float | Seconds between updates (default 0.25) |
| `AccumulatedTime` | Float | Timer accumulator |
| `FrameCount` | Int32 | Frames counted |
| `CurrentMetrics` | FPerformanceMetrics | Latest snapshot |
| `StatusColor` | EFPSStatusColor | Color threshold |
| `bIsVisible` | Bool | HUD element shown |
| `FPSCounterWidget` | WBP_FPSCounterWidget | UI reference |
| `SmoothFPS` | Float | Exponentially smoothed |
| `Alpha` | Float | Smoothing factor (0.05) |
| `PerformanceHistory` | TArray\<Float\> | Last 60 FPS values |
| `GoodThreshold` | Int32 | FPS for green (60) |
| `WarningThreshold` | Int32 | FPS for yellow (30) |

### Functions

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Initialize` | — | — | Setup timers, bind settings |
| `ToggleDisplay` | — | — | Show/hide FPS |
| `SetDisplayMode` | Mode: EFPSDisplayMode | — | Change detail level |
| `SetUpdateInterval` | Interval: Float | — | Change update rate |
| `CalculateFPS` | DeltaTime: Float | — | Compute metrics |
| `GetCurrentFPS` | — | Float | Latest FPS |
| `GetAverageFPS` | — | Float | Session average |
| `GetStatusColor` | FPS: Float | EFPSStatusColor | Threshold check |
| `UpdateDisplay` | — | — | Refresh widget |
| `GetPerformanceSnapshot` | — | FPerformanceMetrics | Full metrics |
| `GetMinFPS` | — | Float | Session minimum |
| `GetMaxFPS` | — | Float | Session maximum |
| `ResetMetrics` | — | — | Clear session stats |
| `LogPerformanceWarning` | FPS: Float | — | Log low FPS event |

### Blueprint Flow

```
[Initialize]
  └─► If Not HasAuthority: return (client only)
  └─► DisplayMode = Simple (default)
  └─► SmoothFPS = 0
  └─► GoodThreshold = 60, WarningThreshold = 30
  └─► Create WBP_FPSCounterWidget
  └─► Add to viewport (small, top-right corner, auto-z-order)
  └─► bIsVisible = false
  └─► Bind to SS_SettingsManager:
         OnSettingChanged("ShowFPS") -> ToggleDisplay()

[Tick / CalculateFPS]
  └─► If Not bIsVisible: return
  └─► AccumulatedTime += DeltaTime
  └─► FrameCount++
  └─► If AccumulatedTime >= UpdateInterval:
         CurrentMetrics.CurrentFPS = FrameCount / AccumulatedTime
         SmoothFPS = (Alpha * CurrentFPS) + (1 - Alpha) * SmoothFPS
         CurrentMetrics.AverageFPS = SmoothFPS
         CurrentMetrics.FrameTime = (AccumulatedTime / FrameCount) * 1000
         // Track min/max
         If CurrentFPS < MinFPS: MinFPS = CurrentFPS
         If CurrentFPS > MaxFPS: MaxFPS = CurrentFPS
         // Status color
         StatusColor = GetStatusColor(SmoothFPS)
         // Update history
         PerformanceHistory.Add(SmoothFPS)
         If PerformanceHistory.Length > 60: Remove oldest
         // Log warning if critical
         If SmoothFPS < WarningThreshold:
              LogPerformanceWarning(SmoothFPS)
         // Update widget
         UpdateDisplay()
         // Reset counters
         AccumulatedTime = 0
         FrameCount = 0

[UpdateDisplay]
  └─► If Not bIsVisible OR Not FPSCounterWidget: return
  └─► Switch DisplayMode:
         Simple: Set text "FPS: {SmoothFPS}" (integer)
         Detailed: "FPS: {SmoothFPS} | {FrameTime}ms"
         Full: "FPS | FrameTime | CPU | GPU"
         Profiling: Full stats + memory + draw calls
  └─► Set text color based on StatusColor:
         Good -> Green
         Warning -> Yellow
         Critical -> Red
  └─► Widget update complete

[ToggleDisplay]
  └─► bIsVisible = !bIsVisible
  └─► If bIsVisible:
         FPSCounterWidget.SetVisibility(Visible)
  └─► Else:
         FPSCounterWidget.SetVisibility(Collapsed)
         AccumulatedTime = 0
         FrameCount = 0

[ResetMetrics]
  └─► CurrentMetrics.MinFPS = max float
  └─► CurrentMetrics.MaxFPS = 0
  └─► PerformanceHistory.Empty()
  └─► AccumulatedTime = 0
  └─► FrameCount = 0
```

### Event Dispatchers

| Name | Payload | Description |
|------|---------|-------------|
| `OnPerformanceWarning` | FPS: Float, StatusColor: EFPSStatusColor | Low FPS detected |

### Communications With

| Target | Method | Why |
|--------|--------|-----|
| [`WBP_FPSCounterWidget`](../06-ui/47_WBP_FPSCounterWidget.md) | Widget reference | UI display |
| [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) | Event | Auto-adjust quality |
| [`SS_SettingsManager`](../11-polish/71_SS_SettingsManager.md) | Event | Toggle from settings |
| [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) | Direct call | Debug overlay |

### Reuse Notes
- Uses exponential smoothing for stable readout
- Color-coded thresholds for quick visual assessment
- Configurable update interval reduces overhead
- Multiple display modes for different needs
- Performance history tracks last 60 samples
- Min/Max tracking for session analysis
- Toggle via settings menu or developer console
- Lightweight; only updates on tick at configured interval