Unreal Engine 3 Application Compatibility (AppCompat) System

Document Summary: Description of the application compatibility system in Unreal Engine 3.

Document Changelog: Created by Wes Hunt.

Overview

Application Compatibility (or, AppCompat for short) is used to supply a default set of performance options for a game based on the capabilities of the machine on which it is running. It is only meant to be used on platforms with varying performance characteristics. Therefore, only the PC uses AppCompat. All other platforms work the same way as before, initializing GSystemSettings from EngineIni[SystemSettings] directly.

This document does not attempt to explain what the various SystemSettings do. For that information, check out the TextureSupportAndSettings and SystemSettings pages.

AppCompat is solely intended to initialize values for GSystemSettings. The game never queries AppCompat for values, it only queries GSystemSettings for the current set of options to use. GSystemSettings is written to EngineIni[SystemSettings] at shutdown (and a few other places), so once initialized, AppCompat no longer needs to participate in the startup process. In that case, GSystemSettings is initialized from EngineIni[SystemSettings] directly.

AppCompat is never used during Editor runs because the editor should not be sensitive to machine capabilities, especially when targeting a fixed platform. Therefore, EngineIni[SystemSettingsEditor] is always used to init GSystemSettings for editor runs. These settings are loaded and saved separately so as not to overwrite settings used during normal runs of the game.

NOTE: The CPU detection portion of AppCompat is currently incompatible with Win64 and simply returns the highest compat level available for the CPU.

Operation

At its core, AppCompat is merely is set of templates for GSystemSettings. Thus, each CompatIni[AppCompatBucketX] entry contains the same elements as EngineIni[SystemSettings], with higher buckets representing settings for increasingly powerful machines. The first time an app is run, GSystemSettings is initialized with the corresponding CompatIni[AppCompatBucketX] entry based on measured machine performance. After the first run, AppCompat is no longer used at startup, and GSystemSettings is initialized from EngineIni[SystemSettings] directly.

AppCompat can also be used in conjunction with the "SystemSettingsFriendly" classes to expose simple sliders to the UI that effectively perform complex GSystemSettings transformations to scale performance for a group of related options. For example, the "Shadow Detail" option (FSystemSettingsFriendly::ShadowDetail) distills over a dozen distinct GSystemSettings into 5 discrete levels that can be chosen by the user simply by moving a slider. This allows a title to hide the complexity of configuring EngineIni[SystemSettings] by providing preset values. Those preset values are drawn from CompatIni[AppCompatBucketX].

DefaultCompat Structure

The DefaultCompat.ini file should look something like this:

[Configuration]
; INI inheritance system. Do not touch
BasedOn=..\Engine\Config\BaseCompat.ini

[AppCompatBucket1]
; settings go here. Any SystemSettings value is supported. For example:
StaticDecals=False
DynamicDecals=False
DynamicLights=False
TEXTUREGROUP_Character=(MinLODSize=256,MaxLODSize=512,LODBias=2,MinMagFilter=linear,MipFilter=point)

[AppCompatBucket2]
; Settings for increasingly powerful machines

[AppCompatBucket3]
; Settings for increasingly powerful machines

[AppCompatBucket4]
; Settings for increasingly powerful machines

[AppCompatBucket5]
; Settings for increasingly powerful machines

See the SystemSettings page for a complete list of the settings that are supported.

DefaultCompat may also contain configuration values used to determine AppCompat level thresholds for your game. See the next section for details on configuring those values.

Determining AppCompat Level

As mentioned before, AppCompat level is only computed the first time the app is run. This is detected by the presence of existing compat level scores stored in EngineIni[AppCompat]. If no entries are found, AppCompat is run and EngineIni[AppCompat] is updated with the results.

The core logic used to determine the compatibility level is currently part of the engine (see CompatibilityEvaluator.cpp), but the performance thresholds for each test are configurable per game (see the [AppCompat] section of BaseCompat.ini in Engine/Config). The resulting compat level is an aggregate of the score of each test. A detailed description of this logic is given below. All configurable values referred to below come from the [AppCompat] section of BaseCompat.ini. Override them by specifying new values in the DefaultCompat.ini file for your game.

CPU Level

1. An empirical CPU score is generated by running a CPU-intensive task on a single thread and measuring the performance. The score is the time in milliseconds it takes to compresses a random 256x256 texture using NVTT.
2. Then, information is gathered about the specific OS/CPU/GPU being used (and logged for debugging).
   • NOTE: CPU detection is currently incompatible with Win64. The highest CPU level is always returned in this case.
3. If the CPU is multicore, the CPU is given a configurable bonus taken from CPUMultiCoreMult.
4. If the CPU is not multicore, but supports hyperthreading, the CPU is given a configurable bonus taken from CPUHyperThreadMult.
5. If AppCompat.ini has config values for CPUScore[1-5], then:
   • Adjusted CPU Score = CPUScore / CPU bonus
   • This means that LOWER CPU scores are better!
   • That adjusted score is used to determine the bucket based on the CPUScore[1-5] config values.
6. If AppCompat.ini does not hae config values for CPUScore[1-5], then:
   • A method is used purely based on the speed of the CPU, which doesn't account for different CPU types.
   • Adjusted CPU Score = CPUSpeed * CPU bonus
   • This means that HIGHER CPU scores are better!
   • That asjusted score is converted to GHz and used to determine the bucket based on the CPUSpeed[1-5] config values.

CPU Memory Level

1. CPUMemory[1-5] config values are used to determine a CPU memory level based on the total physical memory in the machine.
2. Memory thresholds for each bucket are specified in gigabytes in the config.

GPU Memory Level

1. GPUMemory[1-5] config values are used to determine a GPU memory level based on the total physical memory in the primary video card.
2. Memory thresholds for each bucket are specified in megabytes in the config.

GPU Shader Level

1. GPUShaderlevel[1-5] config values are used to determine a GPU capability level based on the supported DX9 pixel shader level.
2. GPU Shader thresholds for each bucket are specified as integers. UnrealEngine3 requires shader model 2, so the only valid values are 2 or 3.

GPU Device Level

1. AppCompat.ini contains several sections [AppCompatGPU-0xXXXX] for each video card vendor.
2. Each section contains the following values:
   • VendorName=XXXX - indicates the name of the vendor
   • VendorMobileTag=XXXX - indicates a string that, if present in the card name, indicates a mobile card.
   • One more more entries of the form 0x014F=1,GeForce 6200
   • The first number is the hardwareID, the second is the compat bucket it goes into, and the string after the comma is the name of the card.
   • Based on the hardwareID of the card, this config setting is used to determine the GPU Device Level of the card, and if it is a mobile card.
   • If the particular card is not found in the config, the following formula is used to determine the level:
   • if VidMem > 512 and ShaderLevel > 2 and not mobile card=
     • Level = 4
   • else if VidMem >= 256
     • Level = 3
   • else if VidMem >= 128
     • Level = 2
   • else
     • Level = 1

Composite Level

The final numbers reported to the engine are:

• GPU Composite = min(GPU Mem Level, GPU Device Level)
• CPU Composite = min(CPU Level, CPU Mem Level)
• Overall Composite = min(GPU Composite, CPU Composite)

Mapping Composite Levels to SystemSettings.

The AppCompatBucketX section that corresponds to the Overall Composite Level is copied into EngineIni[SystemSettings] and used to initialize GSystemSettings. The texture detail settings portion of EngineIni[SystemSettings] is initialized from the AppCompatBucketX section that corresponds to the GPU Composite Level. CPU Composite Level is currently unused.

Disabling AppCompat for your game.

You can effectively disable AppCompat by supplying an empty DefaultCompat.ini for your game, which causes it to initialize all buckets from EngineIni[SystemSettings]. The compatibility evaluator will still be run the first time, but since all buckets are equivalent, it won't matter.

AppCompat Startup Logic (PC only)

• if editor:
  • Init GSystemSettings with EngineIni[SystemSettingsEditor].
• else if the app has been run before (query GEngineIni[AppCompat]):
  • Init GSystemSettings with EngineIni[SystemSettings]
• else:
  • Run a capability check and return a compatibility level.
  • Init GSystemSettings with CompatIni[AppCompatBucketX].
  • Save GSystemSettings to EngineIni[SystemSettings].