TargetFrame Architecture FAQ

TargetFrame establishes Unreal Engine 5.5 as the absolute floor. It avoids version-specific C++ APIs by encapsulating necessary version shims into TargetFrameEngineCompat.h (such as GetTotalDeviceWorkingMemory which was introduced in 5.6).

In addition, target files use BuildSettingsVersion.Latest (which resolves cleanly to V5 on 5.5/5.6, V6 on 5.7, and V7 on 5.8) because no single build settings literal compiles across all four versions.

In Unreal Engine, FPluginManager::IsPluginCompatible treats EngineVersion as an exact-match gate, not a minimum floor. If a descriptor declares "EngineVersion": "5.7.0", it is instantly rejected when opened in 5.5, 5.6, or 5.8.

By omitting EngineVersion in source, the plugin opens cleanly in any compatible engine. When built for Fab distribution via RunUAT BuildPlugin, Unreal's automation tool automatically stamps the exact per-engine version into the output descriptor.

Unreal Engine reads packages older than the running engine, but never packages newer than itself. Shipped plugin assets (such as WBP_TargetFrameExperience.uasset) are strictly authored and serialized on UE 5.5 (package version 1013).

If an asset were saved in UE 5.7 or 5.8, its version would increase to 1018, causing a hard crash/failure when loaded in UE 5.5 or 5.6. This requirement is enforced by Scripts/CheckContentEngineFloor.py.

In earlier builds, demo classes like AScalabilityGameMode, AScalabilityDebugHUD, and ATargetFrameShowcaseActor lived inside the runtime plugin. This polluted the consumer's UObject namespace and forced games to compile demo assets and hardcoded shape lookups.

• Plugins/TargetFrame: The pure runtime policy module, settings CDO, math library, and drop-in onboarding widget. Zero sample maps or demo classes.
• Plugins/TargetFrameSample: The optional showcase arena, camera tour, and developer debug HUD, equipped with CoreRedirects so existing assets seamlessly resolve.

1. Creation Gate: Under UE_SERVER, IsRunningDedicatedServer(), or !FApp::CanEverRender(), the subsystem refuses creation entirely. Zero memory allocated.
2. Session Gate: IsDisabledInCurrentSession checks world type, map filters, and per-instance PIE overrides.
3. Activation Gate: bPolicyControlActive must be explicitly activated by the game. Until then, TargetFrame only observes and benchmarks; it writes zero settings.
4. Governor Gate: Enforces warmup (default 10s), evaluation cadence (default 4s), and suppression when window is unfocused, paused, or during cinematics.
5. Lock Gate: The fire-and-forget stabilization lock, which silences all adjustments once frame rate is stable and only wakes on severe deficits.

When defending a deficit (StepQualityDown):

1. CPU Groups: (View Distance & Foliage) — only if the frame is classified as CPU-bound.
2. Upscaler Quality: Steps vendor upscaler mode (e.g. Quality → Balanced).
3. Triangle Culling Scale: Tightens cull distances on heavy static meshes.
4. Overall Scalability Level: Steps down base presets (Epic → High → Medium).
5. Nanite Pixels-per-Edge: Softens rasterization density.
6. Resolution Scale: Reduces 3D scene render percentage.

When recovering during a surplus (StepQualityUp), the order is reversed, with CPU groups restored last. This asymmetry prevents foliage and view distances from oscillating ahead of resolution and Nanite.

Isolated long frames (e.g., streaming hitches or garbage collection pauses exceeding HitchThresholdSeconds = 0.1s) are excluded from the smoothed frame rate.

However, if a slow frame run persists longer than SustainedSlowFrameWindowSeconds = 1.0s, TargetFrame recognizes that the machine is genuinely struggling and integrates the true frame rate, triggering controlled step-downs.

Unreal's UGameUserSettings::GetOverallScalabilityLevel() returns -1 whenever any single per-group value (like Foliage or Shadows) diverges from a standard preset. In earlier builds, as soon as the CPU governor stepped down foliage, the policy engine read back -1, assumed overall quality was permanently invalid, and froze the overall scalability lever for the rest of the session.

TargetFrame separates quality into two distinct properties:

• Status.OverallQualityLevel: Faithfully mirrors the engine's report (reporting -1 for custom mixes).
• Status.ManagedOverallQualityLevel: Tracks the actual tier TargetFrame is actively driving, seeded at activation.

When ApplyOverallQualityLevel writes a preset, it explicitly preserves ResolutionQuality (owned by the resolution lever) and, when bCPUQualityManaged is set, the foliage and view-distance groups. The two levers compose harmoniously without clobbering each other.

Unreal's synthetic benchmark returns a normalized performance index on a scale where 115 represents the boundary for Epic-quality settings (as defined by [ScalabilitySettings] PerfIndexThresholds_* across UE 5.5–5.8: GPU 18 42 115).

An earlier build of TargetFrame mistakenly demanded an index of 220 for its top tier. As a result, powerful cards (such as an RTX 5060 Ti) were erroneously demoted to Entry tier and capped at 45 FPS.

The Fix: TargetFrame now dynamically reads PerfIndexThresholds directly from GScalabilityIni at runtime:

• Entry: Index < 42 (Target: 45 FPS)
• Mainstream: Index 42 – 114 (Target: 60 FPS)
• Performance: Index ≥ 115 (Target: 90 FPS)

On devices like the Mali-G57 (tested on Android 14), Unreal's synthetic GPU benchmark can fail or return an invalid negative score (e.g. -25.1). TargetFrame's pure math core detects the non-monotonic or negative score, rejects it, falls back to the CPU benchmark score, and applies the low-memory constraint to select Entry tier safely.

Render resolution scale affects GPU pixel shading and rasterization cost. If the game is bottlenecked by the GameThread (e.g., hundreds of ticking actors, AI, or complex animation graphs), dropping the screen percentage from 100% to 50% yields 0 ms of CPU savings while making the game blurry. TargetFrame instead targets CPU-bound scalability levers (View Distance and Foliage) to reduce culling and transform overhead.

TargetFrame includes two complementary soak tests:

• TargetFrame.Soak.CPUBoundLadder: Injects deterministic thread timings (40ms GameThread vs 6ms GPU) to test the decision logic.
• TargetFrame.Soak.CPUBoundRealWorkload: Executes 30ms/frame of genuine mathematical work on the Unreal GameThread. Across all four engines (5.5–5.8), the engine measured 31.3–31.6ms of GGameThreadTime vs 6.0–6.3ms GPU time, proving that real workloads properly trigger the CPU ladder.

TargetFrame writes console variables at ECVF_SetByGameSetting. In Unreal Engine's priority hierarchy:

ECVF_SetByCode > ECVF_SetByGameSetting > ECVF_SetByScalability > ECVF_SetByProjectSetting

This means TargetFrame overrides standard engine scalability sweeps (sg.*), preventing Unreal from clobbering its VSM page limits or texture pool budgets.

If a variable is locked by C++ code using ECVF_SetByCode or by an active Device Profile, Unreal silently ignores writes with lower priority. TargetFrame instruments this, detects when a write is rejected, records the variable in Status.RejectedConsoleVariables, and notes it in the diagnostic summary.

In a bare editor session with no active world or GameInstance, client-dependent tests hit their "no live subsystem" guard. Previously, this guard logged a warning but returned true — resulting in 12 tests reporting a false "green" pass without ever executing.

Removing EditorContext ensures they only run when a live world exists (via -game or PIE), and the guard now explicitly calls AddError so silent skips are impossible.

Unreal's RunUAT BuildPlugin compiles a plugin inside an isolated throwaway host project containing only that plugin. Because TargetFrameSample explicitly depends on TargetFrame, BuildPlugin cannot resolve the dependency in an isolated container. To package the sample, package the parent host project or include both plugins in your game repository.