add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/13-polish/109_BPC_FPSCounter.md
+++ b/docs/blueprints/13-polish/109_BPC_FPSCounter.md
@@ -0,0 +1,186 @@
+# 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