bEnableSimulatorSupport

bEnableSimulatorSupport

#Overview

name: bEnableSimulatorSupport

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 7 C++ source files. Also referenced in 1 C# build file meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of bEnableSimulatorSupport is to enable or disable iOS Simulator support for the project. This setting is primarily used for development and testing purposes, allowing developers to run and debug their iOS applications on a simulated iOS environment without the need for physical iOS devices.

This setting variable is mainly utilized by the iOS Target Platform module of Unreal Engine 5. Specifically, it’s used in the IOSTargetPlatform and IOSDeviceHelper components.

The value of this variable is set in the IOSRuntimeSettings class, which is part of the IOSRuntimeSettings module. It’s defined as a UPROPERTY with GlobalConfig and EditAnywhere attributes, meaning it can be modified through the project settings in the Unreal Engine editor.

bEnableSimulatorSupport interacts with several other aspects of the iOS build and deployment process:

1. It affects the available shader formats, potentially adding the SF_METAL_SIM format when enabled.
2. It influences the texture formats used, especially for Volume textures in simulator builds.
3. It impacts the device querying process, determining whether simulator devices should be included.

Developers should be aware of the following when using this variable:

1. It’s marked as experimental, indicating that it may not be fully stable or supported.
2. Enabling this option requires a project restart to take effect.
3. It can significantly impact the build process and the resulting application package.

Best practices when using this variable include:

1. Only enable it when actively developing for or testing on the iOS Simulator.
2. Be prepared for potential differences in behavior between simulator and real device builds.
3. Remember to disable it before creating release builds to ensure optimal performance on real devices.
4. Use it in conjunction with other iOS-specific settings to create a comprehensive development environment.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3008, section: [/Script/IOSRuntimeSettings.IOSRuntimeSettings]

• INI Section: /Script/IOSRuntimeSettings.IOSRuntimeSettings
• Raw value: False
• Is Array: False

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSTargetPlatform/Private/IOSDeviceHelper.cpp:447

Scope (from outer to inner):

file
class        class FDeviceQueryTask : public FRunnable
function     void QueryDevices

Source code excerpt:

		bool HasDevices = true;

		bool bEnableSimulatorSupport = false;
		GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bEnableSimulatorSupport"), bEnableSimulatorSupport, GEngineIni);
		if (bEnableSimulatorSupport)
		{
			SimulatorDevices = GetSimulatorDevices();
			HasSimDevices = SimulatorDevices.Num() > 0;
		}

		FString LibimobileDeviceId = GetLibImobileDeviceExe("idevice_id");

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSTargetPlatform/Private/IOSTargetPlatform.cpp:545

Scope (from outer to inner):

file
function     void FIOSTargetPlatform::GetAllPossibleShaderFormats

Source code excerpt:

			OutFormats.AddUnique(NAME_SF_METAL);

			bool bEnableSimulatorSupport = false;
			GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bEnableSimulatorSupport"), bEnableSimulatorSupport, GEngineIni);
			if (bEnableSimulatorSupport)
			{
				OutFormats.AddUnique(NAME_SF_METAL_SIM);
			}
		}

		if (SupportsMetalMRT())

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSTargetPlatform/Private/IOSTargetPlatform.cpp:674

Scope (from outer to inner):

file
function     void FIOSTargetPlatform::GetTextureFormats

Source code excerpt:

	}

	bool bEnableSimulatorSupport = false;
	GConfig->GetBool(TEXT("/Script/IOSRuntimeSettings.IOSRuntimeSettings"), TEXT("bEnableSimulatorSupport"), bEnableSimulatorSupport, GEngineIni);

	for (FName& TextureFormatName : OutFormats.Last())
	{
		if (Texture->GetTextureClass() == ETextureClass::Cube) 
		{
			FTextureFormatSettings FormatSettings;

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSTargetPlatform/Private/IOSTargetPlatform.cpp:691

Scope (from outer to inner):

file
function     void FIOSTargetPlatform::GetTextureFormats

Source code excerpt:

		// Currently (Xcode14), the iOS Simulator does not support compressed Volume textures.
		if (bEnableSimulatorSupport && Texture->GetTextureClass() == ETextureClass::Volume)
		{
			FTextureFormatSettings FormatSettings;
			Texture->GetDefaultFormatSettings(FormatSettings);
			TextureFormatName = FName(TEXT("RGB8"));
		}
	}

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:272

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

    // Whether or not iOS Simulator support should be enabled for this project (Experimental)
    UPROPERTY(GlobalConfig, EditAnywhere, Category = Build, meta = (DisplayName = "Enable iOS Simulator Support (Experimental)", ConfigRestartRequired = true))
    bool bEnableSimulatorSupport;
    
    /** Set the maximum frame rate to save on power consumption */
    UPROPERTY(GlobalConfig, EditAnywhere, Category = PowerUsage, meta = (ConfigHierarchyEditable))
    EPowerUsageFrameRateLock FrameRateLock;

    //Whether or not to allow taking the MaxRefreshRate from the device instead of a constant (60fps) in IOSPlatformFramePacer

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Private/IOSRuntimeSettings.cpp:40

Scope (from outer to inner):

file
function     UIOSRuntimeSettings::UIOSRuntimeSettings

Source code excerpt:

	bSupportsIPhone = true;
	bEnableSplitView = false;
	bEnableSimulatorSupport = false;
	MinimumiOSVersion = EIOSVersion::IOS_Minimum;
    bBuildAsFramework = true;
	bGeneratedSYMFile = false;
	bGeneratedSYMBundle = false;
	bGenerateXCArchive = false;
	bSupportSecondaryMac = false;

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Private/IOSRuntimeSettings.cpp:102

Scope (from outer to inner):

file
function     void UIOSRuntimeSettings::PostEditChangeProperty

Source code excerpt:

		{
			// User canceled, so reset the value
			bEnableSimulatorSupport = !bEnableSimulatorSupport;
			UpdateSinglePropertyInConfigFile(GetClass()->FindPropertyByName(GET_MEMBER_NAME_CHECKED(UIOSRuntimeSettings, bEnableSimulatorSupport)), GetDefaultConfigFilename());
			return;
		}

		FScopedSlowTask SlowTask(0, LOCTEXT("UpdatingCodeProject", "Updating code project..."));
		SlowTask.MakeDialog();

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeProject.cs:1805

				{
					bool bEnableSimulatorSupport = false;
					PlatformIni.GetBool("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "bEnableSimulatorSupport", out bEnableSimulatorSupport);

					SDKRoot = "iphoneos";
					SupportedPlatforms = "iphoneos";
					if (bEnableSimulatorSupport)
					{
						SupportedPlatforms += " iphonesimulator";