BundleName

BundleName

#Overview

name: BundleName

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

#Summary

#Usage in the C# source code and build system

The purpose of BundleName is to specify the display name for the app bundle when targeting iOS or tvOS platforms in Unreal Engine 5. This setting is particularly important for the packaging and deployment process of iOS and tvOS applications.

BundleName is primarily used by the iOS and tvOS build and deployment systems within Unreal Engine. Specifically, it’s referenced in the following subsystems:

  1. UEBuildIOS: The iOS-specific build configuration
  2. UEDeployIOS: The iOS deployment system
  3. UEDeployTVOS: The tvOS deployment system
  4. XcodeFrameworkWrapperProject: Used when generating Xcode project files

The value of this variable is typically set in the project’s configuration files. It can be found in the “/Script/UnrealEd.ProjectPackagingSettings” section of the game’s configuration hierarchy, or in the “/Script/IOSRuntimeSettings.IOSRuntimeSettings” section of the INI files.

BundleName interacts with other variables, particularly:

  1. BundleDisplayName: A longer display name that can be used if needed
  2. ProjectName: The BundleName can include a placeholder “[PROJECT_NAME]” which gets replaced with the actual project name

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

  1. The BundleName is used as the display name for the app on the device.
  2. It should be a valid and appropriate name for the App Store.
  3. Special characters and underscores in the BundleName are typically removed or replaced.

Best practices for using this variable include:

  1. Keep the name concise and descriptive.
  2. Avoid special characters that might cause issues in the App Store or on devices.
  3. Ensure the name is unique and doesn’t conflict with other apps.
  4. Consider localization requirements if targeting multiple regions.

Regarding the associated variable BundleDisplayName:

The purpose of BundleDisplayName is to provide a longer, more descriptive name for the app if needed. This can be useful when the BundleName needs to be short for technical reasons, but a longer name is desired for display purposes.

BundleDisplayName is used in similar contexts to BundleName, primarily in the iOS and tvOS build and deployment systems. It’s typically set in the same configuration sections as BundleName.

When using BundleDisplayName, developers should:

  1. Ensure it accurately represents the app.
  2. Consider how it will appear on different device sizes and in the App Store.
  3. Use it when a more descriptive name than BundleName is needed.

Best practices for BundleDisplayName include:

  1. Keep it consistent with your BundleName to avoid user confusion.
  2. Consider localization if targeting multiple regions.
  3. Ensure it fits well on device screens and in the App Store listing.

#Setting Variables

#References In INI files

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

#References in C++ code

The name of this variable is too overloaded. There are many C++ source code (271 callsites) referencing the name of this variable. We have to skip these details.

#References in C# build files

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

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEBuildIOS.cs:344

		/// override for the app's display name if different from the project name
		/// </summary>
		[ConfigFile(ConfigHierarchyType.Game, "/Script/UnrealEd.ProjectPackagingSettings", "BundleName")]
		public readonly string BundleName = "";

		/// <summary>
		/// longer display name than BundleName if needed
		/// </summary>
		[ConfigFile(ConfigHierarchyType.Game, "/Script/UnrealEd.ProjectPackagingSettings", "BundleDisplayName")]

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

			// bundle name
			string BundleName;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleName", out BundleName);

			// disable https requirement
			bool bDisableHTTPS;
			Ini.GetBool("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "bDisableHTTPS", out bDisableHTTPS);

			// short version string

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

			// bundle name
			string BundleName;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleName", out BundleName);

			// short version string
			string BundleShortVersion;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "VersionInfo", out BundleShortVersion);

			// required capabilities

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeFrameworkWrapperProject.cs:290

			ConfigHierarchy Ini = GetIni(ProjectDirectory);
			string BundleName;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleName", out BundleName);

			BundleName = BundleName.Replace("[PROJECT_NAME]", ((ProjectFile != null) ? ProjectFile.GetFileNameWithoutAnyExtensions() : "UnrealGame")).Replace("_", "");
			return BundleName;
		}

		public static bool GetBuildAsFramework(DirectoryReference ProjectDirectory)