Defend your target frame rate with an observable runtime policy.
Welcome to TargetFrame! It bridges the gap between raw Unreal Engine rendering knobs and shipped PC games. It benchmarks hardware, detects project capabilities, respects player ceilings, and executes an asymmetric cost ladder to preserve smooth frame pacing without thrashing.
Subsystem Telemetry Ingest & Double-Apply State Restores
Engine Matrix: Unreal Engine 5.5 – 5.8
One single source tree builds cleanly across four major engine versions. Unreal Engine 5.5 is the absolute floor, guaranteeing that all shipping assets, code shims, and target settings are backwards- and forwards-compatible.
| Engine Version | Build Settings Literal | Package Ceiling | Automation Tests | Release Status |
|---|---|---|---|---|
| Unreal Engine 5.5.4 (Floor) | BuildSettingsVersion.Latest → V5 |
Version 1013 (Authored Floor) | 27 / 27 Pass | • Verified Clean (0 warn) |
| Unreal Engine 5.6.1 | BuildSettingsVersion.Latest → V5 |
Version 1017 | 27 / 27 Pass | • Verified Clean (0 warn) |
| Unreal Engine 5.7.4 | BuildSettingsVersion.Latest → V6 |
Version 1018 | 27 / 27 Pass | • Verified Clean (0 warn) |
| Unreal Engine 5.8.2 | BuildSettingsVersion.Latest → V7 |
Version 1018 | 27 / 27 Pass | • Verified Clean (0 warn) |
Why Neither Plugin Declares EngineVersion
In Unreal Engine, EngineVersion inside a .uplugin descriptor is an exact-match gate, not a minimum floor. Pinning a version would exclude three of the four supported engines. When packaging via RunUAT BuildPlugin or Fab's build farm, the packaging tool stamps the exact target version dynamically into the packaged distribution.
The Package Version 1013 Rule
Unreal Engine can open assets authored in older versions, but never assets saved in a newer engine. All plugin content (such as WBP_TargetFrameExperience) is strictly authored and serialized on UE 5.5 (ver 1013) and guarded by Scripts/CheckContentEngineFloor.py.
Quick Start Guide
The shortest path from enabling the plugin to running the project-aware Beginner Wizard, applying calibrated defaults, and inspecting live readiness.
Open Your Primary Map
Open your heaviest gameplay map if integrating into a production title, or open /TargetFrameSample/ to test extreme multi-bottleneck stress.
Open Beginner Wizard
In the Unreal Editor, open Window > TargetFrame Beginner Setup Wizard for the one-click launcher, or trigger the in-game setup flow during play.
Run One-Click Flow
Click Run Beginner Flow. TargetFrame reads the GPU, VRAM, and synthetic benchmark index from GScalabilityIni and assigns a calibrated profile.
Confirm Calibration
Review the recommendation pause card. Keep the posture, open settings, or start over before moving on to live gameplay testing.
Toggle Debug Overlay
Press F10 to inspect the in-game control panel, or toggle the real-time Canvas diagnostics overlay with tf.DebugHUD 1 and tf.DebugHUD 0.
Run Automation Tests
Verify plugin integrity across any engine with Automation RunTests TargetFrame. All 27 tests should pass cleanly.
Installation & Wiring
TargetFrame can be adopted as a silent runtime subsystem, a static Blueprint façade, a drop-in UMG experience widget, or all three.
Project Settings Surface
Open Project Settings > Plugins > TargetFrame. Simple Mode provides curated setup controls: target FPS mode, quality bias, explicit activation, low-memory ceilings, and telemetry. Switch to Advanced Mode for low-level policy tuning.
Blueprint Facade
The static library exposes StartTargetFrameFireAndForget, RunTargetFrameSetupWizard, SetTargetFrameTargetFPS, GetTargetFrameStatus, and ApplyTargetFramePolicy.
Drop-In Runtime Widget
WBP_TargetFrameExperience (in Plugins/TargetFrame/Content/UI/) provides player-facing onboarding, quick intent presets, and telemetry notes out of the box.
#include "TargetFrameSubsystem.h"
void UMyGameInstance::Init()
{
Super::Init();
// Acquire the TargetFrame game instance subsystem
if (UTargetFrameSubsystem* TF = GetSubsystem<UTargetFrameSubsystem>())
{
// 1. One-call automatic calibration & capability probe
TF->StartAutomaticSetup();
// 2. Or configure an explicit intent & apply
TF->SetTargetFPS(60);
TF->ApplyCurrentPolicy();
}
}Two-Plugin Clean Architecture
To eliminate shipping namespace pollution, TargetFrame separates production runtime code from showcase and demo assets into two distinct plugins.
Pristine Shipping Namespace
In earlier builds, demo classes like AScalabilityGameMode and AScalabilityDebugHUD lived inside the runtime plugin. They have been completely extracted into TargetFrameSample with CoreRedirects, leaving TargetFrame 100% clean for commercial submissions.
TargetDenyList: [Server]
Dedicated servers do not render frames. Both plugins declare TargetDenyList: [Server] in their descriptors, ensuring they are stripped automatically from dedicated server builds.
The 5-Gate State Machine
TargetFrame does not write to engine state without passing through five hierarchical safety gates. Observation is active by default; execution requires explicit permission.
Extracted Pure Core: TargetFramePolicyMath
All core algorithmic decisions have been factored into pure, static C++ mathematical functions with zero engine state, enabling deterministic verification.
ResolveFrameBudget
Resolves requested vs effective target against player frame limit, t.MaxFPS, fixed frame rate, and engine smoothing ceiling. Clamps recovery threshold below any detected limiter so recovery is reachable.
AccumulateFrameSample
Folds one frame into the smoothed rate via an exponential wall-clock filter. Discards isolated long frames ($> 100\text{ms}$) as transient hitches; accepts a run once sustained past 1.0s.
IsLikelyCPUBound
GameThread time is the primary indicator. Render/RHI timers corroborate only with a wider margin because they absorb GPU fence and present waits.
ParsePerfIndexThresholds
Parses an engine PerfIndexThresholds_* entry such as "GPU 18 42 115" directly from GScalabilityIni, rejecting malformed and non-monotonic inputs.
ResolveTierFromPerfIndex
Maps normalized synth-benchmark indices onto Entry, Mainstream, and Performance tiers using the engine's own boundaries.
ApplyMemoryConstraintToTier
Steps a tier down by at most one place for constrained graphics memory ($\le 6\text{ GB}$), avoiding demoting capable GPUs straight to Entry.
The Asymmetric Cost Ladder
TargetFrame reduces rendering cost when frame time drifts into deficit, but restores features in an intentionally asymmetric order to prevent visual oscillation.
Why CPU Levers Are Restored Last
In earlier builds, the CPU governor restored view distance and foliage ahead of resolution and Nanite. In dynamic gameplay, this caused foliage and actor distances to oscillate visibly before the scene settled. Making CPU recovery the final step completely stabilized visual pacing.
Oscillation Protection
TargetFrame counts direction reversals during runtime evaluation. If a scene causes repeated flips within a short window ($> 4$ reversals), the governor throttles further adjustments and triggers the stabilization lock.
Dual Quality Accounting
Eliminates the critical defect where custom graphics mixes or CPU-bound foliage steps permanently broke overall scalability management.
Status.OverallQualityLevel (Engine Mirror)
Mirrors Unreal's UGameUserSettings::GetOverallScalabilityLevel(). It returns -1 whenever any single sub-group (like Shadows or View Distance) diverges from a standard preset—including after TargetFrame's own CPU adjustments.
Status.ManagedOverallQualityLevel (TargetFrame Track)
Tracks the actual quality level TargetFrame is actively driving. Seeded at activation and maintained independently. When ApplyOverallQualityLevel executes, it writes the preset while preserving ResolutionQuality and CPU groups (View Distance / Foliage) if bCPUQualityManaged is set.
Why This Matters to Developers
In standard UE5 implementations, adjusting a single sub-group like foliage drops GetOverallScalabilityLevel() to -1. If a policy loop reads back that -1, it loses its place in the quality ladder and either freezes or clobbers the player's custom settings. Dual accounting ensures the CPU governor and overall quality compose harmoniously without conflict.
Engine-Calibrated Hardware Tiers
Tiers derive dynamically at runtime from Unreal's own engine configuration rather than invented hardcoded constants.
| Calibration Parameter | Legacy Build (Defective) | TargetFrame 0.4.0 (Calibrated) |
|---|---|---|
| Performance Tier Boundary | Hardcoded 220 Score | Dynamically parsed from GScalabilityIni (Index 115) |
| RTX 5060 Ti Desktop Result | Classified as • Entry (45 FPS) | Classified as • Performance (90 FPS) |
| Low-VRAM Action (≤ 6 GB) | Forced directly to Entry | Steps down by at most 1 tier (Mainstream) |
| Mobile Negative Benchmark Index | Unhandled / invalid calibration | Gracefully falls back to CPU Index (45 FPS Entry) |
Measured Hardware Captures
NVIDIA RTX 5060 Ti / Ryzen 7600 (Win64): GPU Index 231.0, CPU 204.1 → Performance Tier, 90 FPS (Byte-identical across UE 5.5, 5.6, 5.7, and 5.8).
Mali-G57 / Unisoc T606 (Android 14): GPU Index -25.1 (synth-benchmark failure), CPU 82.8 → Gracefully rejects negative GPU index, uses CPU score → Entry Tier, 45 FPS.
Dynamic GScalabilityIni Engine Binding
By reading PerfIndexThresholds_* directly from GScalabilityIni at runtime, TargetFrame stays synchronized with Epic's official engine boundaries (GPU 18 42 115) across all four supported engines without manual tuning.
Rendering Systems Managed by TargetFrame
Coordinated management of all major UE5 cost centers under one cohesive policy.
CPU Tick & Animation Governor
Detects when GameThreadTime exceeds GPUFrameTime. Steps down sg.ViewDistanceQuality and sg.FoliageQuality while locking screen percentage at 100% to preserve visual clarity.
Virtual Shadow Map (VSM) Guardrails
Clamps r.Shadow.Virtual.MaxPhysicalPages (4096 → 1024 / 512) and enforces r.Streaming.LimitPoolSizeToVRAM = 1 during low-memory states, freeing 500 MB – 1.2 GB VRAM and preventing OOM driver crashes.
Nanite Runtime Policy
Manages r.Nanite.MaxPixelsPerEdge and enforces r.Nanite.PrimaryRaster.TimeBudgetMs to regulate geometry rasterization before broader visual degradation is applied.
Direct Upscaler Integration
Detects vendor plugins (DLSS r.NGX.DLSS.*, FSR r.FidelityFX.FSR.*, XeSS r.XeSS.*). Falls back gracefully to Epic's Temporal Super Resolution (TSR) when vendor plugins are not installed.
Upscaler-Safe UI
Uses r.SecondaryScreenPercentage.GameViewport to allow dynamic resolution scaling in the 3D scene while keeping UMG menus, crosshairs, and text pin-sharp at native 100% resolution.
Hardware Ray Tracing (HWRT) Clamp
Guards r.Lumen.HardwareRayTracing on entry-level or Intel GPUs to ensure Lumen remains stable and performant.
Console Variable Ownership Semantics
Unreal Engine enforces strict CVar ownership priorities. TargetFrame respects these rules and instrumentally logs when a write is rejected by higher-priority code.
ECVF_SetByCode (Highest - Manual C++ overrides)
|
ECVF_SetByGameSetting <-- TargetFrame writes here!
|
ECVF_SetByScalability <-- Engine Scalability presets (sg.*)
|
ECVF_SetByProjectSetting (Default engine project defaults)Winning Writes
Because TargetFrame writes at ECVF_SetByGameSetting, it wins against default SetByScalability writes. This prevents engine scalability sweeps from quietly overriding texture pool or VSM page clamps.
Instrumented Rejection Tracking
If a developer CVar or device profile holds SetByCode priority, TargetFrame logs the discarded write and records it into Status.RejectedConsoleVariables so developers always know what took precedence.
Telemetry & Policy Audit History
Every policy change is logged with structured rationale, timings, and decision records for QA validation.
26 CSV Telemetry Channels
Emits detailed metrics under CSV_CUSTOM_STAT(TargetFrame, ...) including requested/effective targets, smoothed FPS, 4 thread timings, active upscaler, VSM page count, and stabilization lock states.
Structured Policy History
Stores the last 12 policy modifications inside FTargetFramePolicyHistoryEntry with exact GameThread/GPU timings, CPU-bound verdicts, and before/after quality snapshots.
| Telemetry Channel | Signal Tracked |
|---|---|
SmoothedFPS |
Wall-clock exponential filtered rate |
GameThreadTimeMs |
Unreal engine game thread CPU time |
GPUFrameTimeMs |
RHI GPU execution time |
ManagedOverallQuality |
Active TargetFrame driven quality index |
VSMPhysicalPages |
Virtual Shadow Map page allocation cap |
27 Automation Tests Across 3 Suites
Validated on UE 5.5, 5.6, 5.7, and 5.8 in both standalone game sessions (-game) and Packaged Win64 Development builds.
TargetFrame.PolicyMath
12 Tests • Pure math and state verification. Runs instantly in any context. Validates frame budgets, hitch filtering, wall-clock smoothing consistency at 33Hz and 333Hz, tier decision surfaces, and CPU classification.
TargetFrame.Runtime
11 Tests • Requires a live world (Client context). Validates baseline snapshots, custom mix protection, effective fractional t.MaxFPS clamping, upscaler-safe UI separation, and delegate broadcasts.
TargetFrame.Soak
4 Tests • Continuous endurance testing. Includes GovernorLadder, ShippingCadenceWithTravel, CPUBoundLadder (injected), and CPUBoundRealWorkload (30ms/frame real work).
UnrealEditor-Cmd.exe Scalability.uproject -game -ExecCmds="Automation RunTests TargetFrame; Quit" -unattended -nopause -nosplashProduction Tuning Guide
Guidelines for configuring TargetFrame to match your studio's art direction and performance targets.
1. Calibrate on Real Content
Never tune purely on flat sample levels. Test on your heaviest gameplay sequences with live AI, particles, and physics active.
2. Establish Player Ceilings
TargetFrame treats the user's selected preset in GameUserSettings as an absolute ceiling. It steps down to defend frame rate, but never exceeds player-configured quality.
3. Engage Stabilization Lock
Enable bLockPolicyAfterStabilization=True in shipping builds. Once the game settles after level load, visual quality locks in place to prevent distraction.
Troubleshooting & Quick Diagnostics
Immediate solutions for common runtime and integration questions.
| Symptom | Root Cause | Resolution |
|---|---|---|
| Policy does not adjust quality in editor | bDisableInEditor is set to True by default to prevent altering editor viewport settings. |
Run in Standalone Game, packaged build, or set bDisableInEditor = False in Project Settings. |
| Resolution scale drops during CPU bottleneck | CPU Governor is disabled or IsLikelyCPUBound lacks GPU timing data. |
Ensure bEnableCPUGovernor = True. Verify GPU cycles are supported by the active RHI. |
| Custom graphics settings get flattened | Project re-derived managed level from engine report. | TargetFrame 0.4.0's Dual Quality Accounting automatically preserves custom sub-group mixes. |
| Tests fail with "No live subsystem" in bare editor | Runtime and Soak tests require a live game world. | Run automation tests with the -game switch. |
Resources & Support
Official channels, downloads, and technical consultation.
GregOrigin LLC →
Official creator portal, developer blog, and roadmap updates.
Fab Marketplace Listing →
Get TargetFrame Pro on Epic Games Fab for Unreal Engine 5.5 – 5.8.
Direct Technical Support • Discord
Have a custom engine integration, questions about vendor upscalers, or need help tuning VSM page pools? Join the official Discord: https://discord.gg/nqYQ5mtmHb.