PlatformTraits

PlatformTraits

#Overview

name: PlatformTraits

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of PlatformTraits is to define a set of platform-specific traits or characteristics that can be used to customize behavior and functionality across different platforms in Unreal Engine 5. These traits are represented as gameplay tags, which allow for flexible and extensible categorization of platform features.

PlatformTraits is primarily used by the CommonUI module, which is part of the Runtime plugin system in Unreal Engine 5. It is also utilized by the CommonGame plugin and the LyraGame project, indicating its importance in cross-platform game development.

The value of this variable is set in the configuration files and can be edited through the Unreal Engine editor. It is defined as a TArray in the UCommonUISettings class, which allows for easy manipulation and storage of multiple platform traits.

PlatformTraits interacts with PlatformTraitContainer, which is a merged version of PlatformTraits stored as an FGameplayTagContainer. This container is rebuilt using the RebuildTraitContainer() function whenever the PlatformTraits array is modified.

Developers must be aware that PlatformTraits can significantly influence various aspects of the game, including input modes, user privileges, and feature availability across different platforms. It’s crucial to carefully consider which traits are assigned to each platform to ensure consistent and appropriate behavior.

Best practices when using this variable include:

  1. Clearly defining and documenting the meaning and impact of each platform trait.
  2. Regularly reviewing and updating the traits as platform capabilities evolve.
  3. Using the traits consistently throughout the project to maintain a cohesive cross-platform experience.
  4. Leveraging the trait system to create flexible, platform-specific behaviors without hardcoding platform checks.
  5. Ensuring that the PlatformTraits are correctly set for each target platform in the project’s configuration files.

By properly utilizing PlatformTraits, developers can create more adaptable and maintainable cross-platform games with Unreal Engine 5.

#Setting Variables

#References In INI files

<Workspace>/Projects/Lyra/Config/Android/AndroidGame.ini:16, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Android/AndroidGame.ini:17, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/IOS/IOSGame.ini:16, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/IOS/IOSGame.ini:17, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:13, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:14, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:15, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:16, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:17, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:18, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:19, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:20, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Linux/LinuxGame.ini:21, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:13, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:14, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:15, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:16, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:17, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:18, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:19, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Mac/MacGame.ini:20, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:13, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:14, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:15, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:16, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:17, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:18, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:19, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:20, section: [/Script/CommonUI.CommonUISettings]
<Workspace>/Projects/Lyra/Config/Windows/WindowsGame.ini:21, section: [/Script/CommonUI.CommonUISettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/CommonUI/Source/CommonUI/Private/CommonUISettings.cpp:92

Scope (from outer to inner):

file
function     void UCommonUISettings::RebuildTraitContainer

Source code excerpt:

{
	PlatformTraitContainer.Reset();
	for (FGameplayTag Trait : PlatformTraits)
	{
		PlatformTraitContainer.AddTag(Trait);
	}

#if WITH_EDITOR
	if (GIsEditor)

#Loc: <Workspace>/Engine/Plugins/Runtime/CommonUI/Source/CommonUI/Private/CommonUISettings.cpp:151

Scope (from outer to inner):

file
function     const FGameplayTagContainer& UCommonUISettings::GetPlatformTraits

Source code excerpt:

			{
				TArray<FString> Entries;
				PlatformIni->GetArray(*GetClass()->GetPathName(), GET_MEMBER_NAME_STRING_CHECKED(UCommonUISettings, PlatformTraits), Entries, TEXT("Game"));

				UScriptStruct* GameplayTagStruct = StaticStruct<FGameplayTag>();
				TArray<FGameplayTag> OtherPlatformTraits;
				for(FString Entry : Entries)
				{
					FGameplayTag Element;

#Loc: <Workspace>/Engine/Plugins/Runtime/CommonUI/Source/CommonUI/Public/CommonUISettings.h:77

Scope (from outer to inner):

file
class        class UCommonUISettings : public UObject

Source code excerpt:

	/** The set of traits defined per-platform (e.g., the default input mode, whether or not you can exit the application, etc...) */
	UPROPERTY(config, EditAnywhere, Category = "Visibility", meta=(Categories="Platform.Trait", ConfigHierarchyEditable))
	TArray<FGameplayTag> PlatformTraits;

private:
	void LoadEditorData();
	void RebuildTraitContainer();

	bool bDefaultDataLoaded;

	// Merged version of PlatformTraits
	// This is not the config property because there is no direct ini inheritance for structs
	// (even ones like tag containers that represent a set), unlike arrays
	FGameplayTagContainer PlatformTraitContainer;

	UPROPERTY(Transient)
	TObjectPtr<UObject> DefaultImageResourceObjectInstance;

#Loc: <Workspace>/Projects/Lyra/Plugins/CommonGame/Source/Private/CommonGameInstance.cpp:84

Scope (from outer to inner):

file
function     void UCommonGameInstance::Init

Source code excerpt:


	// After subsystems are initialized, hook them together
	FGameplayTagContainer PlatformTraits = ICommonUIModule::GetSettings().GetPlatformTraits();

	UCommonUserSubsystem* UserSubsystem = GetSubsystem<UCommonUserSubsystem>();
	if (ensure(UserSubsystem))
	{
		UserSubsystem->SetTraitTags(PlatformTraits);
		UserSubsystem->OnHandleSystemMessage.AddDynamic(this, &UCommonGameInstance::HandleSystemMessage);
		UserSubsystem->OnUserPrivilegeChanged.AddDynamic(this, &UCommonGameInstance::HandlePrivilegeChanged);
		UserSubsystem->OnUserInitializeComplete.AddDynamic(this, &UCommonGameInstance::HandlerUserInitialized);
	}

	UCommonSessionSubsystem* SessionSubsystem = GetSubsystem<UCommonSessionSubsystem>();

#Loc: <Workspace>/Projects/Lyra/Source/LyraGame/Input/LyraMappableConfigPair.cpp:14

Scope (from outer to inner):

file
function     bool FMappableConfigPair::CanBeActivated

Source code excerpt:

bool FMappableConfigPair::CanBeActivated() const
{
	const FGameplayTagContainer& PlatformTraits = ICommonUIModule::GetSettings().GetPlatformTraits();

	// If the current platform does NOT have all the dependent traits, then don't activate it
	if (!DependentPlatformTraits.IsEmpty() && !PlatformTraits.HasAll(DependentPlatformTraits))
	{
		return false;
	}

	// If the platform has any of the excluded traits, then we shouldn't activate this config.
	if (!ExcludedPlatformTraits.IsEmpty() && PlatformTraits.HasAny(ExcludedPlatformTraits))
	{
		return false;
	}

	return true;
}