186 lines
6.8 KiB
Markdown
186 lines
6.8 KiB
Markdown
# 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 |