AdditionalPlistData

AdditionalPlistData

#Overview

name: AdditionalPlistData

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 2 C++ source files. Also referenced in 3 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C# source code and build system

The purpose of AdditionalPlistData is to allow developers to add custom data to the Info.plist file for iOS and tvOS applications built with Unreal Engine 5. This variable is specifically used in the deployment process for iOS and tvOS platforms.

The Unreal Engine subsystems that rely on this setting variable are the iOS and tvOS deployment systems. This is evident from the file locations where the variable is referenced: UEDeployIOS.cs and UEDeployTVOS.cs.

The value of this variable is set in the IOSRuntimeSettings section of the project’s configuration files. It’s retrieved using the Ini.GetString method, which suggests that it’s stored in an INI file, likely the project’s configuration files.

This variable interacts with other iOS and tvOS specific settings, such as ‘bCustomLaunchscreenStoryboard’, which is read immediately after AdditionalPlistData in the same context.

Developers must be aware that this variable allows for direct insertion of custom XML data into the Info.plist file. This is powerful but can also be dangerous if not used correctly. Incorrect plist data can cause issues with app submission to the App Store or even prevent the app from running correctly on devices.

Best practices when using this variable include:

  1. Only add well-formed XML data.
  2. Test thoroughly after adding custom plist data to ensure the app still functions correctly.
  3. Be aware of Apple’s guidelines and requirements for plist entries to avoid issues during app submission.
  4. Use this for adding necessary custom capabilities or configurations that aren’t covered by Unreal Engine’s standard iOS/tvOS settings.

Regarding the associated variable bCustomLaunchscreenStoryboard:

The purpose of bCustomLaunchscreenStoryboard is to indicate whether the project is using a custom launch screen storyboard for iOS applications.

This variable is used in conjunction with the iOS deployment system, as seen in the UEDeployIOS.cs file.

The value of this variable is also set in the IOSRuntimeSettings section of the project’s configuration files and is retrieved using the Ini.GetBool method.

This variable likely interacts with other iOS-specific settings related to the app’s launch screen and initial presentation.

Developers should be aware that using a custom launch screen storyboard requires creating and configuring the storyboard file separately from the standard Unreal Engine process.

Best practices for using this variable include:

  1. Only set it to true if you have actually created a custom launch screen storyboard.
  2. Ensure your custom storyboard follows Apple’s guidelines for launch screens.
  3. Test the custom launch screen on various iOS devices to ensure it scales and displays correctly.
  4. Keep the launch screen simple and fast-loading to provide a good user experience.

#Setting Variables

#References In INI files

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

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

    // Any additional plist key/value data utilizing \n for a new line
    UPROPERTY(GlobalConfig, EditAnywhere, Category = Build)
    FString AdditionalPlistData;
    
    // Whether or not to add support for iPad devices
    UPROPERTY(GlobalConfig, EditAnywhere, Category = Build, meta = (DisplayName = "Supports iPad"))
    bool bSupportsIPad;

    // Whether or not to add support for iPhone devices

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

Scope (from outer to inner):

file
function     UIOSRuntimeSettings::UIOSRuntimeSettings

Source code excerpt:

	bUseRSync = true;
	bCustomLaunchscreenStoryboard = false;
	AdditionalPlistData = TEXT("");
	AdditionalLinkerFlags = TEXT("");
	AdditionalShippingLinkerFlags = TEXT("");
    bGameSupportsMultipleActiveControllers = false;
	bAllowRemoteRotation = true;
	bDisableMotionData = false;
    bEnableRemoteNotificationsSupport = false;

#References in C# build files

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

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs:669

			// extra plist data
			string ExtraData = "";
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "AdditionalPlistData", out ExtraData);

			Ini.GetBool("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "bCustomLaunchscreenStoryboard", out VersionUtilities.bCustomLaunchscreenStoryboard);

			// generate the plist file
			StringBuilder Text = new StringBuilder();
			Text.AppendLine("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs:313

			// extra plist data
			string ExtraData = "";
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "AdditionalPlistData", out ExtraData);

			Ini.GetBool("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "bCustomLaunchscreenStoryboard", out VersionUtilities.bCustomLaunchscreenStoryboard);

			// generate the plist file
			StringBuilder Text = new StringBuilder();
			Text.AppendLine("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/TVOS/UEDeployTVOS.cs:75

			// extra plist data
			string ExtraData = "";
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "AdditionalPlistData", out ExtraData);

			// create the final display name, including converting all entities for XML use
			string FinalDisplayName = BundleDisplayName.Replace("[PROJECT_NAME]", ProjectName).Replace("_", "");
			FinalDisplayName = FinalDisplayName.Replace("&", "&amp;");
			FinalDisplayName = FinalDisplayName.Replace("\"", "&quot;");
			FinalDisplayName = FinalDisplayName.Replace("\'", "&apos;");