Preview

Complete material

Click for full resolution.

Usage

Put your widget in a Retainer Box and set the Effect Material.

Then on each tick, update the Value parameter to a number between 0–1.

In my game, I evaluate a curve and then plug the value into this parameter.

How it works

Let’s begin with a simple radial gradient which can be accomplished with the Distance node. We want to use the normalized UV of GetUserInterfaceUV because it’ll span the entire widget even when the brush is being drawn as a box or border. This is mapped to texture coordinate index 4.

For this material, we want to control the fade transition with a scalar parameter named Value. Our goal is to make it so that a value of 0 makes the widget completely invisible, and a value of 1 makes it completely visible.

By subtracting the distance from the parameter, we move one step closer to achieving this.

The result of the Subtract node will always be negative when Value is set to 0, rendering the widget completely invisible. As Value approaches 1, UVs closer to the center point will begin to output a positive number causing the widget to begin revealing itself outwards from the center point.

There are still two issues here:

1. Value is clamped to 1 so subtraction will never output 1 beyond the center which always produces a visible gradient.
2. Distances greater than 1, which happens when the center point is shifted to a corner, always output negative values and this portion of the texture will never be visible.

To solve this, let’s multiply the distance with Value and then add it to the output of the subtraction.

When Value is 1, both outputs negate each other and provides us with a uniform value of 1.0 for all UVs — no matter where the center point is.

StateTree is a hierarchical state machine introduced in Unreal Engine 5.

The base StateTree plugin provides a general-purpose hierarchical state machine, but it does not provide any schema or even a processor to actually execute a StateTree.

Unreal Engine comes with a handful of plugins with their own schemas and processors.

Unreal Engine uses StateTree exclusively for AI, and even placed the asset type under the Artificial Intelligence category.

I’m here to let you know that it’s not just for AI!

Once again, StateTree is a general purpose state machine built into Unreal Engine with its own editor. You don’t need a third-party plugin or develop your own state machine. In fact, Unreal Engine 5.4 has made it even more useful with linked assets and themes.

Why do I need a state machine?

First, let’s take a look at my game’s frontend.

The player goes through this sequence when launching my game — and no, I don’t expect you to read it all.

I want to bring my players into the game as soon as possible. Launching the game for the first time opens accessibility settings. On this screen, players may switch to graphics and audio settings if they wish.

Then it proceeds to the character creation screen. Next, the game creates a new save and enters the co-op lobby with the save slot name as a URL parameter.

If it’s not the first time, then it will prompt the player if they want to load their most recent save. Declining will bring the player to the main menu. This means for most players, they will never see the main menu at all!

But widgets have to have references to other widgets. The main menu widget has to be responsible for showing the settings and save selection menus. Some widgets have to check whether a save slot exists and then create a different widget based on this information. I could go on and on…

Without a state machine, this produces Blueprint spaghetti that is fragile, hard to maintain, and prone to bugs!

Using StateTree for the frontend

Here’s what my frontend looks as a StateTree. Each step in the flowchart above is implemented as a self-contained discrete state with tasks, conditions, and transitions.

The StateTree Component schema provides an actor as context data. Since my use case involves input and widgets, I set the actor type to PlayerController. The startup level in my game uses a special PlayerController actor that has a StateTree Component. This makes the StateTree immediately begin executing when the game loads.

The funny thing is I actually spent weeks building a UMG StateTree with its own custom schema and a set of tasks. Unfortunately, what I ended up with is more or less the same thing as the built-in GameplayStateTree plugin. The only real difference between my plugin and GameplayStateTree is that the processor is implemented as a subsystem rather than as an actor component.

I even wrote a whole article about this, but it doesn’t feel right to publish it when I realized the better solution is to just use GameplayStateTree.

Most tasks complete in a success or failed state. For example, a player wanting to back out of character creation causes the state to fail. This will trigger a transition to bring the player back to the main menu.

As for the main menu, there’s no success or failure condition. Instead, clicking on a menu button raises a StateTree event. A transition is set up for each event to enter another state that actually does something. The main menu widget only reports player intent, and leaves it to the StateTree to decide what to do next.

Widgets are clearly not tasks, so how did I raise a StateTree event? My solution is to create a base widget class with an event dispatcher that top-level widgets must subclass from.

Tasks bind to this event dispatcher after creating the widget. To simplify this even further, I created a base task class called CreateWidgetAsync that takes in a soft class reference as a parameter. By subclassing from this task, I don’t need to reimplement the same logic over and over.

Notably, it does not call Finish Task unless there was an error. This is how a widget remains visible indefinitely.

By the way, always use soft references in task parameters! Avoid hard references to any blueprint widget (other than the base class). If you’re not careful, the StateTree’s memory footprint will skyrocket.

StateTree tips & tricks

Here are some things about StateTree I wish I knew about earlier.

Rename tasks

Did you know you could rename tasks? I didn’t for an embarassingly long time. This really helps with identifying which widget to target in a property binding.

Just click on the task name to edit it.

This also works for conditions and evaluators.

Organize blueprint nodes

In each one of your blueprint nodes (tasks, conditions, or evaluators), be sure to go to Class Settings and override the display name and category. This will make it easier to find your nodes in the picker.

Parameter types

The Category sets the type of a parameter.

There are 3 special types of parameters:

Parameters in all other categories appear normal.

Condition operators and indentation

Adding more than one condition will reveal operators. Click on it to switch between AND/OR.

There is also an invisible button right before the operator button. Click on it to change the indentation of a condition. Operators apply to conditions within the same indentation.

Subtree transitions

The Tree Succeeded and Tree Failed transitions inside a subtree will surface to the linked state and no further. However, if a subtree was entered by a transition instead of a linked state, then these transitions will affect the whole StateTree.

Blueprint Latent Node Caveat

Be mindful when using certain latent nodes (e.g. Async Save Game). Calling Finish Task from these latent nodes will not trigger transitions. Consider raising a StateTree event instead.

Ending thoughts

I’m not claiming this is the best approach, but it does work pretty well. The biggest benefit of using StateTree is that I can see the entire flow within a single asset. So, yeah, I’m happy with what I have right now. :)

Did you know that one in five casual gamers have a disability—myself included? I’m creating a cozy life simulation game, so players with disabilities make up a significant portion of my target audience. It’s clear that my game must be accessible.

There are many ways to make a game accessible, and I strive to implement as much as I reasonably can.

— But that’s not the focus of this article.

Retrofitting a game with accessible features is hard, and this is why many games end up with just a band-aid solution. I want to share how I’m setting up my game to be accessible in a modular way—as Game Feature plugins.

Accessibility as a Game Feature plugin?

Yes. And it works really well!

Toggle animated preview

Just to be clear, I don’t mean game features as a concept. I am referring to the Game Features system, which is a relatively new Unreal Engine feature that makes it possible to create standalone content for a game.

In my game, each accessibility setting is implemented as a Game Feature plugin for these reasons:

• It enables previewing UMG widgets with accessible settings at design time.
• Some settings require assets that I don’t want loaded when they’re not in use, such as alternative fonts, additional icons, and replacement textures.
• Compartmentalization makes it easy to add (and maintain) accessibility settings.
• The Game Features system has a built-in activation/deactivation mechanism that also works in the editor.
• The only responsibility of a save game system is to activate the correct plugin based on user preferences.

To make all of this work, the game not only needs to know about these settings, but also needs to do so in a modular manner.

To solve this problem, I created the Global Parameters plugin that integrates with the Game Features system. A custom Game Feature action overrides global parameters when activated.

Global Parameters

A variable that’s used as input for some function or calculation is a parameter.

Global variables are generally a sign of poor design, but global parameters are appropriate for some purposes such as:

• feature flags
• accessibility overrides
• UI theme system (dark mode, maybe? 🌚)

Querying

Gameplay tags are used for parameter names.

Any UObject may query a global parameter. All accessors have a default fallback value for when the parameter is not set.

Parameter collections

Parameters are defined in a custom data asset, USunParameterCollection. This is similar to UMaterialParameterCollection, but it supports more than just scalar and vector values.

Each value is an instanced struct (from the StructUtils plugin), which means it can be any struct type.

UCLASS(MinimalAPI, BlueprintType, DisplayName="Parameter Collection")
class USunParameterCollection : public UDataAsset
{
    GENERATED_BODY()

public:
    /** Indicates the priority of this collection compared to other collections. */
    UPROPERTY(EditAnywhere, Category="Parameter Collection", meta=(InlineCategoryProperty))
    ESunParameterCollectionPriority Priority;

    /** The parameters in this collection. */
    UPROPERTY(EditAnywhere, Category="Parameter Collection", meta=(ForceInlineRow, BaseStruct="/Script/GlobalParameters.SunParameterBase", ExcludeBaseStruct, ShowOnlyInnerProperties))
    TMap<FGameplayTag, FInstancedStruct> Parameters;

    // - IsDataValid (to check for duplicate parameter names)
    // - Getter and setter functions for each parameter type using a template
}

Using the BaseStruct metadata for the Parameters property, I limit the parameter value to one of the following:

// GENERATED_BODY and UPROPERTY macros omitted for brevity.
// Each Value UPROPERTY needs the `EditAnywhere` modifier.

USTRUCT() struct FSunParameterBase;
USTRUCT(DisplayName="Feature Flag") struct FSunFlagParameter : public FSunParameterBase { bool Value; };
USTRUCT(DisplayName="Scalar") struct FSunScalarParameter : public FSunParameterBase { float Value; };
USTRUCT(DisplayName="Color") struct FSunLinearColorParameter : public FSunParameterBase { FLinearColor Value; };
USTRUCT(DisplayName="Brush") struct FSunSlateBrushParameter : public FSunParameterBase { FSlateBrush Value; };
USTRUCT(DisplayName="Font") struct FSunSlateFontParameter : public FSunParameterBase { FSlateFontInfo Value; };

Unreal Editor has built-in detail customization for FInstancedStruct. When adding a parameter to a Parameter Collection, I’m able to pick any one of above structs as the value type.

Each collection has a Priority property that provides control over how multiple collections are simultaneously loaded at runtime.

UENUM()
enum class ESunParameterCollectionPriority
{
    /* The collection represents default values. */
    Default = 0,

    /** The collection represents user preferences (including accessibility). */
    UserPreferences = 1,

    /** The collection represents a patch. */
    Patch = 2
};

Right now, I’m unsure about this order. I may rearrange and/or add new priority levels later.

Runtime state

Accessible UI requires fluid layouts and that’s hard to get right. There will be many, many iterations to make a widget look good in both normal and accessible modes. To make this easier, I need to preview what a UMG widget looks like with one or more accessiblity setting turned on in the widget designer. This rules out any gameplay framework objects including UGameInstance.

I ended up with a custom UEngineSubsystem. My subsystem maps each World Context’s handle to a runtime collection. This means the editor and each PIE session have their own separate runtime state.

A runtime collection maintains a list of pointers to collection assets, sorted by priority, for each parameter.

When a parameter is queried, the collection asset with the highest priority is returned. A templated function in the Blueprint function library reads the value directly from the collection.

UCLASS(MinimalAPI)
class USunGlobalParameterStatics final : public UBlueprintFunctionLibrary
{
  GENERATED_BODY()

public:
    /** Retrieves a global font parameter value or the default value if the parameter was not set. */
    UFUNCTION(BlueprintPure, Category="Global Parameters", meta=(WorldContext="WorldContextObject"))
    static GLOBALPARAMETERS_API FSlateFontInfo GetGlobalFontParameter(UObject* WorldContextObject, FGameplayTag ParameterName, FSlateFontInfo DefaultValue = FSlateFontInfo())
    {
        return GetParameter<FSunSlateFontParameter, FSlateFontInfo>(WorldContextObject, ParameterName, DefaultValue);
    }

    // GetGlobalScalarParameter, GetGlobalColorParameter, etc...

private:
    static FSunRuntimeParameterCollection* GetRuntimeCollectionFromWorldContextObject(UObject* WorldContextObject);
    static FWorldContext* GetWorldContextFromObject(UObject* WorldContextObject);

    template<typename TParameter, typename TParameterType>
    static TParameterType GetParameter(UObject* WorldContextObject, FGameplayTag ParameterName, TParameterType DefaultValue)
    {
        if (const FSunRuntimeParameterCollection* Collection = GetRuntimeCollectionFromWorldContextObject(WorldContextObject))
        {
            // GetParameterValue calls GetPtr<TParameter>() on the FInstancedStruct.
            if (const TParameter* ParameterValue = Collection->GetParameterValue<TParameter>(ParameterName))
            {
                return ParameterValue->Value;
            }
        }

        return DefaultValue;
    }
}

This approach makes changes to a parameter collection apply in realtime during a PIE session.

Observing changes

Rather than querying in each tick, an UObject may subscribe to one or more parameters.

HidePin and DefaultToSelf metadata modifiers are used to implicitly select the calling object as the observer.

UFUNCTION(BlueprintCallable, Category="Global Parameters", meta=(HidePin="Observer", DefaultToSelf="Observer"))
static GLOBALPARAMETERS_API void AddGlobalParameterObserver(FGameplayTagContainer Parameters, UObject* Observer);

UFUNCTION(BlueprintCallable, Category="Global Parameters", meta=(HidePin="Observer", DefaultToSelf="Observer"))
static GLOBALPARAMETERS_API void RemoveGlobalParameterObserver(FGameplayTagContainer Parameters, UObject* Observer);

Following a similar approach as UGameFeaturesSubsystem, the observing UObject must implement an interface to be notified. I find this easier to work with in a Blueprint graph compared to binding and unbinding delegates.

class ISunGlobalParameterObserverInterface
{
    GENERATED_BODY()

public:
    /** Raised when an observed global parameter value changes. */
    UFUNCTION(BlueprintImplementableEvent, Category="Global Parameters")
    void OnGlobalParameterChanged(FGameplayTag ParameterName);
};

Loading collections

There are two ways I can load and unload Parameter Collections.

When loading a save game, I use the AddGlobalParameterCollection and RemoveGlobalParameterCollection Blueprint functions.

Otherwise, I use the Add Global Parameter Collection Game Feature action.

Using the Game Feature action is the preferred approach. When the Game Feature is activated (or deactivated), the collection is added (or removed) for each world context.

void UGameFeatureAction_AddGlobalParameterCollection::OnGameFeatureActivating(FGameFeatureActivatingContext& Context)
{
    auto& GlobalParameterSubsystem = USunGlobalParameterSubsystem::Get();
    for (FWorldContext WorldContext : GEngine->GetWorldContexts())
    {
        if (Context.ShouldApplyToWorldContext(WorldContext))
        {
           GlobalParameterSubsystem.AddParameterCollection(WorldContext, GlobalParameterCollection);
        }
    }
}

void UGameFeatureAction_AddGlobalParameterCollection::OnGameFeatureDeactivating(FGameFeatureDeactivatingContext& Context)
{
    auto& GlobalParameterSubsystem = USunGlobalParameterSubsystem::Get();
    for (FWorldContext WorldContext : GEngine->GetWorldContexts())
    {
        if (Context.ShouldApplyToWorldContext(WorldContext))
        {
            GlobalParameterSubsystem.RemoveParameterCollection(WorldContext, GlobalParameterCollection);
        }
    }
}

What’s next?

The next step is to build a library of reusable widgets that have most of this wired up. Having semantic widgets like ContentTextBlock and TitleTextBlock that observe accessibility modifiers will help me make my game accessible with lesser effort.

I hope this article has helped you in one way or another. 😊

Over the past few months, I built several plugins and components I think is cool and really want to share with you all. The next dev log will be about how I used a StateTree as a UI system.

I am a huge fan of cozy games because they are relaxing and stress-relieving, which is what I want after a long day at work. Unfortunately, I haven’t found a game that feels sufficiently satisfying yet, inspiring me to make my own cozy life simulation game centered around two things I enjoy: trains and traveling!

In these dev logs, I share my thought process and decision-making in hopes that others find it interesting. The logs will cover both technical and game design topics.

Let’s begin with the ten essential steps I always take when creating a new Unreal Engine project:

1. Think about the game’s architecture

The architecture of a game makes a lasting impact in every way, yet is very difficult to change later on. A well-designed architecture is the glue that holds any software—especially games—together.

Poorly designed architecture not only makes it harder to implement features but also manifests in visible ways, such as longer loading times and a less polished player experience. This goes the other way; an architecture that is too rigid will have the same negative impact on a game.

Now, how do I know if my architecture is just right? The best one can do is learn from prior experience. In my role as a software engineer, I’ve been fortunate to have the opportunity to dive deep into well-designed software systems. Although I did not work on games, general software engineering principles and best practices absolutely do apply to video games.

I will make mistakes as I develop my game. My architecture may not represent the “best” way of doing things. All I can do is learn from my mistakes as well as learn from others. A game developer must make a lifetime commitment to learning.

Let’s start with three overarching goals I hope to achieve with my architecture:

1. Modular—Organize content into self-contained plugins.
2. Designer-focused—Develop building blocks in C++ and implement features in Blueprints.
3. Data-driven—Create content with data assets, data tables, and registries.

Organize content into self-contained plugins

With the Game Features plugin, content is organized into self-contained plugins. Deactivating any Game Feature plugin must not hinder the game from running.

Now, let’s define what I mean by “content”. In my view, content is anything that adds to the core sandbox experience. Here, the sandbox is the minimum viable player experience, and content is an extension built upon this sandbox. Individual pieces of content are bundled together as a Game Feature plugin, serving as a content pack.

Why does the definition matter? With a clear definition, I can easily determine whether an asset or class belongs in the sandbox or should be added as a Game Feature plugin.

These are content:

• Characters (except archetypes)
• Items (e.g., clothes, furniture, consumables)
• Maps
• Quests
• Gameplay abilities
• Title Menu & Lobby*

*The title menu and lobby are not necessary for the sandbox itself to function, and therefore can be isolated as a Game Feature plugin. For example, a demo build of the game may launch directly into the sandbox.

And these are not content:

• I/O systems (e.g., input, game saves, UI, haptics)
• AGameState and APlayerState
• Character archetypes
• Inventory system*

*The inventory system is a core game mechanic within the sandbox, and most content will have a dependency on the inventory system. For this reason, it is not content.

Develop building blocks in C++ and implement features in Blueprints

Systems, APIs, and tools are coded in C++ and then called from Blueprint graphs. These serve as building blocks that designers use to implement features. When a Blueprint graph becomes overly complex, then parts of it will be broken down and refactored into C++.

My understanding is that this is the intended way of using Unreal Engine. Developing the entire game solely in either C++ or Blueprints would be needlessly challenging, so I am using both.

Create content with data assets, data tables, and registries

For actors, this means creating an archetype actor with a property that points to a data asset which defines the appearance and behavior of the actor.

This completely decouples content from the sandbox, allowing me to make significant changes to actor archetypes and other parts of the sandbox without potentially invalidating hundreds of downstream assets. Actor components attached to the archetype bring it to life using data from the data asset.

Data tables and data registries are also useful for the same reason.

2. Create the initial project

My project is created with the following hierarchy and a few assets:

🕹️Sunshine
 ├── 📂Config
 │   ├── ...
 │   └── DefaultSunshine.ini
 ├── 📂Content
 │   ├── 📂Developers
 │   │   └── 📂Matt
 │   ├── 📂Maps
 │   │   └── L_Default.umap
 │   ├── 📂Movies
 │   │   └── UnrealEngine.mp4
 │   ├── 📂Splash
 │   │   └── Splash.bmp
 │   ├── 📂Sunshine
 │   └── 📂Legal
 │       └── ThirdPartyNotices.txt
 ├── 📂Plugins
 │   ├── 📂GameFeatures
 │   ├── 📂System
 │   └── 📂UI
 ├── 📂Source
 ├── .editorconfig
 ├── .gitattributes
 ├── .gitignore
 └── Sunshine.uproject

Sunshine is the working title of my project. It’s not the final name of my game. I need to pick (and stick to) a working title so that I can add a prefix to all of my C++ types, e.g., USunAssetManager. This prevents conflicting with engine types.

By the way, I use JetBrians Rider as my IDE, and it directly works with .uproject. That’s why I don’t have a Visual Studio .sln solution file.

3. Add initial assets

Maps

This folder contains internal system maps such as an empty L_Default map that is used as the fallback map. Maps for the game are content and belong in Game Feature plugins.

Movies

While entirely optional, I prefer starting with at least one startup movie to observe the transition from startup into the first map, i.e., the title screen. The animated Unreal Engine logo is used as a placeholder.

Splash

Optional as well, a temporary splash image can serve as inspiration. I’ve created a simple placeholder splash with my project’s name on it.

Legal

Software licenses must be taken seriously, even as an indie developer.

All applicable third-party licenses are tracked in ThirdPartyNotices.txt. When using an open-source plugin or asset, I add their license to this file.

I configured Additional Non-Asset Directories To Copy in Packaging Settings to automatically include this folder for distribution.

4. Enable the Developers folder

To support experimentation and development, I enabled the Developers folder.

Having my own sandbox folder allows me to freely create Blueprints and assets without worrying about cleanup afterwards. Additionally, I’ve excluded this folder from cooked builds in Packaging Settings to avoid accidentally including test assets in the distributed game.

5. Make an EditorConfig

Both Visual Studio and JetBrains Rider support EditorConfig. By placing an .editorconfig file in the project’s root folder, I enforce a consistent code style throughout the entire project.

I recommend having these global rules to ensure all files are encoded and formatted the same way:

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

Feel free to grab a copy of my .editorconfig file. Just bear in mind that most of these rules were added by Rider, so it’s unclear to me whether Visual Studio understands them.

6. Create game and editor modules in C++

I created two game modules specifically for the sandbox: SunshineGame and SunshineEditor. SunshineGame contains all the code needed to implement the sandbox, and SunshineEditor contains editor-only tooling.

7. Setup source control

Although Perforce is the industry standard, I’m very conscious of my budget as a solo developer and don’t want to pay for cloud hosting if I can avoid it. This is why I am pleased to learn that Azure DevOps offers free unlimited Git Large File Storage (LFS) hosting! For this reason, I use Git and Git LFS as my game’s version control system.

To enable Git LFS, I created a .gitattributes file targeting .uasset, .umap, and other binary files. These assets will use binary-compatible Git LFS instead of text-based Git for diffs. This is absolutely essential for game development.

# Unreal Assets
*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap filter=lfs diff=lfs merge=lfs -text lockable

# Non-UFS Assets
*.mp4 filter=lfs diff=lfs merge=lfs -text lockable
*.bmp filter=lfs diff=lfs merge=lfs -text lockable

It’s good practice to run git lfs status before each commit to ensure all binary files are properly handled by Git LFS.

It’s not feasible to merge two binary files so file locking is the standard operating procedure when working with assets. Each rule in my .gitattributes includes the lockable flag which makes binary files readonly by default. To make changes to a binary file, I must try to lock it first. Unreal Editor has built-in support for file locking. I get prompted to lock a file when I attempt to save changes to an asset.

Now, we don’t want to check nonessential files into version control. I created a .gitignore file to exclude auto-generated files. It’s a habit of mine to craft my own exclusion list from scratch. In this case, there is no need to add Visual Studio files to the list because I use JetBrains Rider, so files like .sln do not appear in my workspace at all.

# Miscellaneous JetBrains Rider files.
.idea/
*.DotSettings.user

# Ignore RiderLink Plugin since it's automatically reinstalled by JetBrains Rider.
Plugins/Developer/RiderLink/

# Exclude compiled files.
Binaries/
Intermediate/

# Exclude generated config files and autosaves.
Saved/

# Exclude other generated Unreal Engine directories.
DerivedDataCache/
Build/

8. Create a project config

DefaultSunshine.ini stores the project-level config for all of my building blocks and game features. By adding Config=Sunshine to the UCLASS macro, config properties will be written to this file.

Having a separate config file helps clearly delineate game-related config for designers to modify. DefaultGame.ini is still used for configuring most Unreal Engine features.

By default, Unreal will not cook any custom configuration file. DefaultSunshine.ini must be allowlisted in DefaultGame.ini.

[Staging]
+AllowedConfigFiles=Sunshine/Config/DefaultSunshine.ini

9. Prepare for a multilingual audience

Sharing my game with the whole world would be fantastic, but for this to happen, the game must first be translated into different languages.

It would be a mistake to think about localization as an afterthought. In my project, localization was set up right from the beginning, even before writing the first line of text.

To set my project up for localization, I followed these steps:

1. Open the Localization Dashboard.
2. Select the Game target.
3. Check Gather from Packages
4. Add Sunshine/Content/* to Include Path Wildcards.
5. Verify .uasset and .umap are in File Extensions.

As time goes on, I’ll consistently press the Gather Text button to scan for all localizable text in my game. To be honest, I haven’t really looked into how translations will work here. Nonetheless, I see buttons for exporting and importing translations, so I believe this is the right step.

The Localization Dashboard generates several files for each culture. I added .locmeta and .locres file extensions to my .gitignore because these are compiled from localization source files, so I believe they don’t need to be tracked by git.

# Exclude compiled localization files.
*.locmeta
*.locres

Some of the generated text files are encoded as UTF-16 with a byte order mark (BOM). Git mistakenly treats these files as binary for diffs. To fix this, I added the following to my .gitattributes:

# Correctly handle generated localization file encoding.
*.archive diff working-tree-encoding=UTF-16LE-BOM eol=CRLF
*.manifest diff working-tree-encoding=UTF-16LE-BOM eol=CRLF

10. Package a shipping build

Before each commit to my git repo, I package a shipping build to catch packaging errors early on. I do not want to find out something’s seriously wrong with my project when it’s deep into the development cycle.

Some day, I would like to set up continuous integration and delivery (CI/CD) using the Unreal Automation Tool to automate this process.

What’s next?

Stay tuned for more dev logs as I make progress on my game in the coming months.

Please don’t hesitate to drop your feedback in the comments below (requires a GitHub account).

About the Unreal Header Tool

The Unreal Header Tool (UHT) parses and generates code for UObject types. Many of the C++ macros in the Unreal Engine source code are actually implemented by the UHT.

For example, given a simple UObject:

// File: Example.h

#pragma once

#include "Example.generated.h"

/** This is an example UObject. */
UCLASS()
class UExample : public UObject
{
    GENERATED_BODY()
};

The UHT generates two files named Example.generated.h and Example.gen.cpp with code generated for the UCLASS() and GENERATED_BODY() macros.

This is how Unreal implements reflection and garbage collection in a language that does not support these. Serialization, network replication, and editor integration are also implemented as generated code.

Exporters

C++ code generation is implemented as an exporter in the UHT.

An exporter processes the parsed code and then optionally exports files to the Intermediate directory. An exporter may serve as an analyzer and not export any files—as demonstrated in the Stats exporter sample.

UHT implements these exporters under /Engine/Source/Programs/Shared/EpicGames.UHT/Exporters/.

Exporters that are not enabled by default are triggered by adding -<EXPORTER_NAME> to the commandline arguments for the UHT.

The following command will execute both the Stats and Json exporters. Replace MyGameEditor, Win64, and Development with the desired target, platform, and build configuration.

C:\UE_5.3\Engine\Build\BatchFiles>RunUBT.bat -Mode=UnrealHeaderTool -Stats -Json "-Target=MyGameEditor Win64 Development -Project=\"C:/Path/To/MyGame.uproject\""

Extend the UHT with plugins

The Unreal Build Tool (UBT) scans for extension plugins in both engine and your game’s source, and automatically activates them.

At this time, only exporters are supported in UBT plugins.

I created a UBT plugin called Specifier Reference Viewer that scans for all specifier keywords used in the source code for the engine, game, and all plugins. I recommend looking at my plugin’s source code to learn more about creating UBT plugins.

Let’s walk through the steps needed to create an exporter plugin.

1. Create a plugin

Create a .uplugin with at least one module. A module is required even if you’re not outputting any file, and it must have the Runtime type.

{
    "Modules": [
        {
            "Name": "MyCustomExporter",
            "Type": "Runtime",
            "LoadingPhase": "PreDefault"
        }
    ]
}

2. Add code to the module

A module must have at least one UObject in it to be added to the .uhtmanifest file. An empty module will not be added to the .uhtmanifest file which means the custom exporter will not execute.

3. Create the C# project

Create a C# project file with the .ubtplugin.csproj extension. It must have this extension to be detected by UHT.

This file should be configured to:

• import /Engine/Source/Programs/Shared/UnrealEngine.csproj.props,
• reference the EpicGames.Build, EpicGames.Core, EpicGames.UHT, and UnrealBuildTool assemblies, and
• output the compiled binaries to <PROJECT_NAME>/Binaries/DotNET/UnrealBuildTool/Plugins/<PLUGIN_NAME>.

Instead of creating the project file from scratch, it may be easier to copy it from my plugin and then edit the EngineDir, GeneratorName, and RootNamespace properties.

The Visual Studio solution file (.sln) is not necessary. The C# project will be rebuilt each time the game is built.

4. Create the exporter

Next, create a class and static method to serve as the main entry point for the exporter.

The class must have the [UnrealHeaderTool] attribute, and the exporter’s method must have the [UhtExporter] attribute. The Name and ModuleName properties are required.

using EpicGames.UHT.Tables;
using EpicGames.UHT.Utils;

[UnrealHeaderTool]
public static class Exporter
{
    [UhtExporter(Name = "MyCustomExporter", ModuleName = "MyCustomExporter", Options = UhtExporterOptions.Default)]
    public static void Generate(IUhtExportFactory factory)
    {
        // Process parsed code via factory.Session here.
        factory.Session.LogInfo("MyCustomExporter executed!");
    }
}

UhtExporterOptions.Default indicates that this exporter will be automatically executed each time UBT executes. Remove it or use UhtExporterOptions.None to make it opt-in just like the sample exporters.

5. Build

Build the game. Logs emitted by your exporter will appear in the build output.

0>  Running Internal UnrealHeaderTool C:\Path\To\MyGame.uproject C:\Path\To\MyGame\Intermediate\Build\Win64\MyGameEditor\Development\MyGameEditor.uhtmanifest -WarningsAsErrors -installed
0>Total of 0 written
0>C:\UE_5.3\Engine\Source\UnknownSource(1): Info: MyCustomExporter executed!

Up to four different engine preloading screens may be shown when an Unreal Engine game launches—one for each engine startup phase. While these screens are being displayed, the engine is initializing and the game has not even started loading yet.

Most developers find the default startup movie player perfectly acceptable, but a custom engine preloading screen makes sense if you’re looking for more control over the startup experience. For example, you may want to display a loading throbber or a series of images instead of movies at startup.

Read on to learn more about each engine startup phase and how to customize all four engine preloading screens.

Preload Screens Sequence

Platform splash screen

The game displays a small splash screen on desktop platforms (Windows, MacOS and Linux).

This is displayed under the following conditions:

• A splash image is selected for the platform in Project Settings (e.g., Platforms > Windows > Splash).
• It’s running on a desktop OS.
• It’s not running as a dedicated server or commandlet.
• The game was not launched with the -nosplash commandline argument.

At this point, the engine has not even started loading yet. This means the splash image must exist outside the Unreal File System (UFS) as a standalone file in the packaged build, i.e., <Game>/Content/Splash/Splash.bmp.

The platform splash screen does not use Slate. It runs on its own thread with its own window created via platform-specific hooks. It’s as low-level as it gets. The game window has not been created yet.

Using a BMP image

The Unreal Automation Tool (UAT) specifically looks for a bitmap file named Splash.bmp to copy when packaging. This means bitmap is the recommended image format to use for the splash screen. When you use a bitmap, the splash screen “just works” in a packaged build.

Using a PNG or JPEG image

To use PNG or JPEG, you must manually stage the image in Project Settings or DefaultGame.ini.

The “Additional Non-Asset Directories To Copy” setting is found under Project > Packaging. Make sure Splash is included in this setting.

Alternatively, add the following to DefaultGame.ini:

[/Script/GameFeatures.GameFeaturesSubsystemSettings]
+DirectoriesToAlwaysStageAsNonUFS=(Path="Splash")

A word of caution: all files under the /Content/Splash/ directory will be copied for distribution. As far as I know, you cannot stage individual files via config unless you extend the UAT. Really, just use a bitmap to make things easier on yourself.

Engine preloading screens

After the platform splash screen, the game window is created. All screens from here on are platform-independent and have access to the game’s Slate application.

As the engine goes through each initialization stage, more Unreal Engine features become available to use in your custom preload screens.

Creating a preload screen

FPreLoadScreenBase is used for all Slate-based engine preloading screens.

Preload screens of all types should override Init, GetPreLoadScreenType, and GetWidget.

// .h

#pragma once

#include "PreLoadScreenBase.h"

class FMyCustomPreloadScreen : public FPreLoadScreenBase
{
public:
    virtual void Init() override;
    virtual void RenderTick(float DeltaTime) override;

    virtual EPreLoadScreenTypes GetPreLoadScreenType() const override
    {
        // Change this to indicate which phase you want this screen to be created in.
        return EPreLoadScreenTypes::EarlyStartupScreen;
    }

    virtual TSharedPtr<SWidget> GetWidget() override
    {
        return Widget;
    }

protected:
    TSharedPtr<SWidget> Widget;
};

// .cpp

#include "CustomPreLoadScreen.h"

void FMyCustomPreloadScreen::Init()
{
    // Read from config here if needed.
    // EarlyStartupScreen - use GConfig to read raw values.
    // EngineLoadingScreen - UObjects like UDeveloperSettings may be used.

    // Create your Slate widget here.
    Widget = SNew(SOverlay);
}

void FMyCustomPreloadScreen::RenderTick(float DeltaTime)
{
    // This is executed on the render thread. Use it to animate the widget if desired.
}

For CustomSplashScreen and EarlyStartupScreen types, the preload screen is visible for as long GetWidget() returns a valid Slate widget. For EngineLoadingScreen, it is visible until bIsEngineLoadingFinished is true. Override IsDone() to customize this behavior to support skipping or some other custom logic.

The custom preload screen must be registered in the module.

// Module.cpp

#include "MyCustomPreloadScreen.h"
#include "PreLoadScreenManager.h"

class FMyCustomPreloadScreenModule : public IModuleInterface
{
public:
    virtual void StartupModule() override;

private:
    TSharedPtr<FMyCustomPreloadScreen> MyCustomPreloadScreen;

    void OnPreLoadScreenManagerCleanUp();
};

void FMyCustomPreloadScreenModule::StartupModule()
{
    // Preload screens will never be displayed on a dedicated server or commandlet.
    if (IsRunningDedicatedServer() || IsRunningCommandlet())
    {
        return;
    }

    // There's also no point in doing anything while in the editor or in headless mode.
    if (GIsEditor || !FApp::CanEverRender() || !FPreLoadScreenManager::Get())
    {
        return;
    }

    if (FPreLoadScreenManager* PreLoadScreenManager = FPreLoadScreenManager::Get())
    {
        MyCustomPreloadScreen = MakeShared<FMyCustomPreloadScreen>();
        MyCustomPreloadScreen->Init();

        PreLoadScreenManager->RegisterPreLoadScreen(MyCustomPreloadScreen);

        PreLoadScreenManager->OnPreLoadScreenManagerCleanUp.AddRaw(
            this, &FMyCustomPreloadScreenModule::OnPreLoadScreenManagerCleanUp);
    }
}

void FMyCustomPreloadScreenModule::OnPreLoadScreenManagerCleanUp()
{
    MyCustomPreloadScreen.Reset();
}

IMPLEMENT_MODULE(FMyCustomPreloadScreenModule, MyCustomPreloadScreen)

Finally, in .uplugin or .uproject, make sure the module uses the correct loading phase. Refer to the table above to determine which loading phase to use.

{
    "Modules": [
        {
            "Name": "MyCustomPreloadScreen",
            "Type": "ClientOnlyNoCommandlet",
            "LoadingPhase": "PreEarlyLoadingScreen"
        }
    ]
}

Custom splash screen

This is the second screen that may be displayed under the following conditions:

• It’s not running as a dedicated server or commandlet.
• The game was not launched with the -noloadingscreen commandline argument.
• A module with the PostSplashScreen load phase contains a FPreLoadScreenBase subclass with the type set to CustomSplashScreen and registered with FPreLoadScreenManager.

Unlike the platform splash screen, this screen will appear on all platforms and runs on the Slate render thread. In practice, there’s not really a good reason to have a custom splash screen. It will block the engine from loading any further while it’s visible (unless you create a new thread but that’s beyond the scope of this article). Not to mention the time between the custom splash screen and the early startup screen is insignificant.

Early startup screen

This is the third screen that’s displayed under the following conditions:

• There are no startup movies to play OR the platform does not support early playback.
• It’s not running as a dedicated server or commandlet.
• The game was not launched with the -noloadingscreen commandline argument.
• A module with the PreEarlyLoadingScreen load phase contains a FPreLoadScreenBase subclass with the type set to EarlyStartupScreen and registered with FPreLoadScreenManager.

A custom early startup screen is displayed if, and only if, there are no startup movies or the platform doesn’t support early playback of startup movies. As far as I can tell, early playback is supported on Android, iOS, and Windows.

Since UObject is not available in this phase, you must use GConfig to read and parse config values manually.

Engine loading screen

This is the final engine preloading screen that’s displayed under the following conditions:

• There are no startup movies to play.
• It’s not running as a dedicated server or commandlet.
• The game was not launched with the -noloadingscreen commandline argument.
• A module with the PreLoadingScreen load phase contains a FPreLoadScreenBase subclass with the type set to EngineLoadingScreen and registered with FPreLoadScreenManager.

This is the easiest preload screen to implement because you have access to most engine features at this point, especially UObject. Keep in mind that UGameInstance, UWorld, and other game-related singletons do not exist until after the engine loading screen.

If you plan on creating a custom engine loading screen that uses a background color other than black, then you probably would want to also create an early startup screen to set the background color of the window onwards from the first frame. This produces a seamless transition to the engine loading screen. If you don’t do this, then the game window will be black for a brief moment at launch, which may or may not be acceptable to you.

This is the third chapter in the Lyra Deep Dive series.

In the previous chapter, we’ve learned about how experiences are defined. In this chapter, we’ll take a deep dive into the lifecycle of an experience.

Lyra Deep Dive Series

• Chapter 1: Introduction
• Chapter 2: Experiences
• Chapter 3: Experience Lifecycle

Experience Lifecycle

ALyraGameState automatically adds ULyraExperienceManagerComponent to itself in its constructor. This component handles the entire lifecycle of an experience.

The lifecycle of an experience begins with ALyraGameMode on the server calling SetCurrentExperience and replicating CurrentExperience to all clients.

The loading process starts immediately on the server. For clients, the loading process starts after CurrentExperience is replicated.

The LoadState property reflects the current state of the experience. The following diagram shows the transition between states:

Let’s take a closer look at each stage of the lifecycle.

Replication

ULyraExperienceManagerComponent has a function SetCurrentExperience.

// File: LyraExperienceManagerComponent.h

void SetCurrentExperience(FPrimaryAssetId ExperienceId);

// File: LyraExperienceManagerComponent.cpp

void ULyraExperienceManagerComponent::SetCurrentExperience(FPrimaryAssetId ExperienceId)
{
    ULyraAssetManager& AssetManager = ULyraAssetManager::Get();
    FSoftObjectPath AssetPath = AssetManager.GetPrimaryAssetPath(ExperienceId);
    TSubclassOf<ULyraExperienceDefinition> AssetClass = Cast<UClass>(AssetPath.TryLoad());
    check(AssetClass);
    const ULyraExperienceDefinition* Experience = GetDefault<ULyraExperienceDefinition>(AssetClass);

    check(Experience != nullptr);
    check(CurrentExperience == nullptr);
    CurrentExperience = Experience;
    StartExperienceLoad();
}

In SetCurrentExperience, the server does the following:

1. Synchronously load the experience definition.
2. Verify the experience definition was loaded successfully.
3. Set CurrentExperience which will trigger replication to all clients.
4. Call StartExperienceLoad to start the experience lifecycle on the server.

// File: LyraExperienceManagerComponent.h

UPROPERTY(ReplicatedUsing=OnRep_CurrentExperience)
TObjectPtr<const ULyraExperienceDefinition> CurrentExperience;

UFUNCTION()
void OnRep_CurrentExperience();

// File: LyraExperienceManagerComponent.cpp

void ULyraExperienceManagerComponent::OnRep_CurrentExperience()
{
    StartExperienceLoad();
}

OnRep_CurrentExperience is executed on all clients when CurrentExperience is replicated from the server. This function then calls StartExperienceLoad to start the experience lifecycle on the client.

Stage 1: Load Experience Definition

The experience definition and all associated assets* are asynchronously loaded in this stage.

*Only assets that are directly referenced by the experience definition are loaded here like, for example, HUD widgets in the Add Widgets action. All other assets in game feature plugins are loaded in the next stage.

StartExperienceLoad begins by populating BundleAssetList with a set of primary asset IDs including the experience definition itself and any linked action sets.

// Function: StartExperienceLoad()

TSet<FPrimaryAssetId> BundleAssetList;

BundleAssetList.Add(CurrentExperience->GetPrimaryAssetId());
for (const TObjectPtr<ULyraExperienceActionSet>& ActionSet : CurrentExperience->ActionSets)
{
    if (ActionSet != nullptr)
    {
        BundleAssetList.Add(ActionSet->GetPrimaryAssetId());
    }
}

Next, it determines the asset bundles to load.

// Function: StartExperienceLoad()

TArray<FName> BundlesToLoad;
BundlesToLoad.Add(FLyraBundles::Equipped);

const ENetMode OwnerNetMode = GetOwner()->GetNetMode();
const bool bLoadClient = GIsEditor || (OwnerNetMode != NM_DedicatedServer);
const bool bLoadServer = GIsEditor || (OwnerNetMode != NM_Client);
if (bLoadClient)
{
    BundlesToLoad.Add(UGameFeaturesSubsystemSettings::LoadStateClient);
}
if (bLoadServer)
{
    BundlesToLoad.Add(UGameFeaturesSubsystemSettings::LoadStateServer);
}

The assets and asset bundles are loaded with a call to ChangeBundleStateForPrimaryAssets. You may notice that the async handle for this operation, BundleLoadHandle, is then combined with RawLoadHandle. LoadAssetList loads all secondary assets added to RawAssetList. However, this is unused right now and you won’t need it.

// Function: StartExperienceLoad()

const TSharedPtr<FStreamableHandle> BundleLoadHandle = AssetManager.ChangeBundleStateForPrimaryAssets(BundleAssetList.Array(), BundlesToLoad, {}, false, FStreamableDelegate(), FStreamableManager::AsyncLoadHighPriority);
const TSharedPtr<FStreamableHandle> RawLoadHandle = AssetManager.LoadAssetList(RawAssetList.Array(), FStreamableDelegate(), FStreamableManager::AsyncLoadHighPriority, TEXT("StartExperienceLoad()"));

// If both async loads are running, combine them
TSharedPtr<FStreamableHandle> Handle = nullptr;
if (BundleLoadHandle.IsValid() && RawLoadHandle.IsValid())
{
    Handle = AssetManager.GetStreamableManager().CreateCombinedHandle({ BundleLoadHandle, RawLoadHandle });
}
else
{
    Handle = BundleLoadHandle.IsValid() ? BundleLoadHandle : RawLoadHandle;
}

FStreamableDelegate OnAssetsLoadedDelegate = FStreamableDelegate::CreateUObject(this, &ThisClass::OnExperienceLoadComplete);
if (!Handle.IsValid() || Handle->HasLoadCompleted())
{
    // Assets were already loaded, call the delegate now
    FStreamableHandle::ExecuteDelegate(OnAssetsLoadedDelegate);
}
else
{
    Handle->BindCompleteDelegate(OnAssetsLoadedDelegate);

    Handle->BindCancelDelegate(FStreamableDelegate::CreateLambda([OnAssetsLoadedDelegate]()
    {
        OnAssetsLoadedDelegate.ExecuteIfBound();
    }));
}

When the async load operation is complete, it calls OnExperienceLoadComplete which brings us to the next stage.

At the end of StartExperienceLoad, certain assets may be preloaded without blocking the game. This is also unused at this time.

Stage 2: Load Game Features

Game features are loaded and activated in this stage.

OnExperienceLoadComplete begins by collecting all game feature plugins from the experience definition and all linked action sets, filtering out duplicates and invalid names.

// Function: OnExperienceLoadComplete()

GameFeaturePluginURLs.Reset();

auto CollectGameFeaturePluginURLs = [This=this](const UPrimaryDataAsset* Context, const TArray<FString>& FeaturePluginList)
{
    for (const FString& PluginName : FeaturePluginList)
    {
        FString PluginURL;
        if (UGameFeaturesSubsystem::Get().GetPluginURLByName(PluginName, /*out*/ PluginURL))
        {
            This->GameFeaturePluginURLs.AddUnique(PluginURL);
        }
        else
        {
            ensureMsgf(false, TEXT("OnExperienceLoadComplete failed to find plugin URL from PluginName %s for experience %s - fix data, ignoring for this run"), *PluginName, *Context->GetPrimaryAssetId().ToString());
        }
    }
};

CollectGameFeaturePluginURLs(CurrentExperience, CurrentExperience->GameFeaturesToEnable);
for (const TObjectPtr<ULyraExperienceActionSet>& ActionSet : CurrentExperience->ActionSets)
{
    if (ActionSet != nullptr)
    {
        CollectGameFeaturePluginURLs(ActionSet, ActionSet->GameFeaturesToEnable);
    }
}

When there is at least one valid game feature, it asynchronously loads and activates each one of them using a counter NumGameFeaturePluginsLoading to keep track of the number of plugins left to load.

// Function: OnExperienceLoadComplete()

NumGameFeaturePluginsLoading = GameFeaturePluginURLs.Num();
if (NumGameFeaturePluginsLoading > 0)
{
    LoadState = ELyraExperienceLoadState::LoadingGameFeatures;
    for (const FString& PluginURL : GameFeaturePluginURLs)
    {
        ULyraExperienceManager::NotifyOfPluginActivation(PluginURL);
        UGameFeaturesSubsystem::Get().LoadAndActivateGameFeaturePlugin(PluginURL, FGameFeaturePluginLoadComplete::CreateUObject(this, &ThisClass::OnGameFeaturePluginLoadComplete));
    }
}
else
{
    OnExperienceFullLoadCompleted();
}

When a game feature is activated, it invokes OnGameFeaturePluginLoadComplete which decreases the counter.

void ULyraExperienceManagerComponent::OnGameFeaturePluginLoadComplete(const UE::GameFeatures::FResult& Result)
{
    // decrement the number of plugins that are loading
    NumGameFeaturePluginsLoading--;

    if (NumGameFeaturePluginsLoading == 0)
    {
        OnExperienceFullLoadCompleted();
    }
}

OnExperienceFullLoadCompleted is called when there are no more game features left to load which brings us to the next stage.

Stage 3. Chaos Testing

This stage is optional and disabled by default. When enabled, a random delay is added to the load time here. This can help you test your game by having staggered client readiness.

To configure chaos testing, use these console variables:

Stage 4. Execute Game Feature Actions

Game feature actions are executed in the order as they appear in the experience definition and then each action set.

FGameFeatureActivatingContext Context;

// Only apply to our specific world context if set
const FWorldContext* ExistingWorldContext = GEngine->GetWorldContextFromWorld(GetWorld());
if (ExistingWorldContext)
{
    Context.SetRequiredWorldContextHandle(ExistingWorldContext->ContextHandle);
}

auto ActivateListOfActions = [&Context](const TArray<UGameFeatureAction*>& ActionList)
{
    for (UGameFeatureAction* Action : ActionList)
    {
        if (Action != nullptr)
        {
            Action->OnGameFeatureRegistering();
            Action->OnGameFeatureLoading();
            Action->OnGameFeatureActivating(Context);
        }
    }
};

ActivateListOfActions(CurrentExperience->Actions);
for (const TObjectPtr<ULyraExperienceActionSet>& ActionSet : CurrentExperience->ActionSets)
{
    if (ActionSet != nullptr)
    {
        ActivateListOfActions(ActionSet->Actions);
    }
}

Finally, the experience is fully loaded at this point.

The game is notified that the experience has finished loading via the OnExperienceLoaded delegates.

OnExperienceLoaded_HighPriority.Broadcast(CurrentExperience);
OnExperienceLoaded_HighPriority.Clear();

OnExperienceLoaded.Broadcast(CurrentExperience);
OnExperienceLoaded.Clear();

OnExperienceLoaded_LowPriority.Broadcast(CurrentExperience);
OnExperienceLoaded_LowPriority.Clear();

You may notice that it clears all delegates after broadcasting. This is because the CallOrRegister_OnExperienceLoaded functions for all priorities check whether the experience has been loaded and executes the callback immediately if so. Otherwise, it adds to the delegate to be called later.

Stage 5. Deactivate Experience

When EndPlay on the component is triggered, all loaded game feature plugins are asynchronously deactivated.

At this time, Lyra does not unload game features after they’ve been deactivated. Ideally, it should’ve called UGameFeaturesSubsystem::UnloadGameFeaturePlugin at some point in the deactivation logic. Maybe we’ll see that in a future version.

This is the second chapter in the Lyra Deep Dive series.

Lyra introduces the concept of “experiences” which essentially are modular game modes. In this chapter, we’ll walk through various data assets which define a Lyra Experience.

Lyra Deep Dive Series

• Chapter 1: Introduction
• Chapter 2: Experiences
• Chapter 3: Experience Lifecycle

What is an Experience?

In Lyra, an experience is an extensible and modular combination of a Game Mode and Game State that can be asynchronously loaded and switched at runtime.

For example, in a typical shooter game, game types will be implemented as different experiences. Lyra follows this pattern by having the ShooterCore game implement the Elimination and Control game types as standalone experiences.

Since experiences are completely modular, they don’t even need to be in the same genre! Lyra demonstrates this by having one of the experiences completely transform the game into a top-down party game called Exploder.

Most of the code related to Lyra Experiences are found in the /LyraGame/GameModes/ directory.

Plugins

The Lyra Experiences system is driven by the combination of the Game Features and Modular Gameplay plugins.

With the Game Features plugin, experiences are contained as standalone game feature plugins and loaded on demand. The Modular Gameplay plugin allows experiences to add components to actors, modify game state, add data sources, and much more.

Both plugins are commonly used together to make actors extensible via plugins and avoid coupling actors with features.

Game Features

With the Game Features plugin, the game can dynamically load and unload plugins at runtime. Game feature plugins can even be placed in separate standalone chunks to be distributed as downloadable content (DLC).

When you enable the Game Features plugin for your project and restart the editor, you’ll see a couple of new plugin templates.

These templates include the required UGameFeatureData data asset for your standalone game feature. This data asset describes what actions to perform when the feature is loaded and how to find additional primary data assets within the plugin. Keep in mind that all game feature plugins must go in the /Plugins/GameFeatures/ directory to be detected.

The default set of available actions are: Add Components, Add Cheats, Add Data Registry, and Add Data Registry Source. This can be extended with custom actions. In fact, Lyra has custom actions such as Add Widget, Add Input Binding, and more in the /LyraGame/GameFeatures/ directory. We’ll take a deeper look at these in a future chapter.

You can control the initial state of a game feature by editing the plugin in the Plugins window. In Lyra, all game features have the initial state of Registered. This is because with the Lyra Experiences system, the feature will be loaded only when the server selects the experience.

Modular Gameplay

The Modular Gameplay plugin enables actors to register themselves as receivers for components and senders of custom extension events.

Actors you want to make modular will need to register themselves with the UGameFrameworkComponentManager. With the AddGameFrameworkComponentReceiver function, the actor notifies the Modular Gameplay subsystem that it is accepting new actor components. This is typically done in the PreInitializeComponents function of the actor.

void AMyModularActor::PreInitializeComponents()
{
    Super::PreInitializeComponents();
    UGameFrameworkComponentManager::AddGameFrameworkComponentReceiver(this);
}

Actors also need to unregister themselves when they’re no longer accepting components. This is typically done in the EndPlay function of the actor.

void AMyModularActor::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    UGameFrameworkComponentManager::RemoveGameFrameworkComponentReceiver(this);
    Super::EndPlay(EndPlayReason);
}

Modular actors create custom extension points by broadcasting custom events to any object subscribed to the actor class via UGameFrameworkComponentManager.

Most modular actors will want to send the GameActorReady event in BeginPlay so that extensions can execute code only when the actor is active.

void AMyModularActor::BeginPlay()
{
    UGameFrameworkComponentManager::SendGameFrameworkComponentExtensionEvent(this, UGameFrameworkComponentManager::NAME_GameActorReady);
    Super::BeginPlay();
}

To create an extension, call AddExtensionHandler in the UGameFrameworkComponentManager subsystem. This will subscribe to all actors of the desired class for extension events. It must be an actor subclass and not the root AActor class, which means you cannot subscribe to every single actor. This is intentionally checked by the Modular Gameplay plugin to prevent significant performance impact to the game.

// This snippet is placed where you want to start handling actor extensions.
if (UGameFrameworkComponentManager* ComponentManager = UGameInstance::GetSubsystem<UGameFrameworkComponentManager>(GameInstance))
{			
    TSharedPtr<FComponentRequestHandle> ExtensionRequestHandle = ComponentManager->AddExtensionHandler(
        AMyModularActor::StaticClass(),
        UGameFrameworkComponentManager::FExtensionHandlerDelegate::CreateUObject(this, &ThisClass::HandleActorExtension));
}

Store ExtensionRequestHandle somewhere. Call Unregister on it to stop listening for extension events.

In the handler delegate, you typically would check the event name and execute code on the actor if it’s an event you wish to handle.

void UMyActorExtension::HandleActorExtension(AActor* Actor, FName EventName)
{
    if (EventName == UGameFrameworkComponentManager::NAME_GameActorReady)
    {
        // Do something when the actor is ready.
    }
    
    // Handle other extension events here.
}

Modular Gameplay Actors

The ModularGameplayActors plugin contains subclasses of the standard gameplay framework actors that are registered for extension via the Modular Gameplay plugin. While you can always register directly with UGameFrameworkComponentManager in your actors, this plugin makes it so that you don’t need to do it manually.

These actors are provided by this plugin:

• AModularAIController
• AModularCharacter
• AModularGameModeBase
• AModularGameMode
• AModularGameStateBase
• AModularGameState
• AModularPawn
• AModularPlayerController
• AModularPlayerState

This plugin does not come with Unreal Engine out of the box. You will need to extract it from the Lyra source code.

Experience Definition

An Experience Definition describes what game features need to be enabled and what actions to perform in order to implement the experience.

To create an experience, create a blueprint based on ULyraExperienceDefinition in a directory that’s scanned by the Asset Manager.

Keep in mind that you cannot subclass from another experience blueprint if you want to create a similar experience. Let’s say you have a blueprint ShooterGame that’s subclassed from ULyraExperienceDefinition. You cannot have other blueprints, for example, let’s call them EliminationGame and CaptureTheFlagGame, to have ShooterGame as the parent class.

Instead, you should use composition via Action Sets. Both EliminationGame and CaptureTheFlagGame in the example above should be standalone experiences and reference an action set that implements the standard experience.

The experience definition has the following properties:

Action Sets

Common game feature actions and plugins can be specified in an Action Set (ULyraExperienceActionSet).

It would be cumbersome to keep all experiences in sync during development, so a standard set of game feature actions are defined in an action set to be reused by multiple experiences.

In Lyra, both the Elimination and Control experiences are based on the same input, actor components, and HUD widgets. For this reason, they are specified in the LAS_ShooterGameSharedInput, LAS_ShooterGame_StandardComponents, and LAS_ShooterGame_StandardHUD action sets and referenced in the ActionSets list in both experience blueprints. You can see this for yourself in /Plugins/GameFeatures/ShooterCore/Content/Experiences/.

Since action sets are meant to be “merged” into experiences, they have some of the same properties found in experience definitions:

Asset Manager

The Asset Manager is used to discover and stream assets. Primary assets can be detected and loaded by the asset manager while secondary assets are referenced by (and loaded along with) primary assets.

By default, the asset manager scans for levels only. Enabling the Game Features plugin will prompt you to add the GameFeatureData to the list of asset types to scan.

In Lyra, the asset manager is configured to also scan for experience definitions and action sets as shown below:

As you can see in the next screenshot, only experiences in the /Game/System/Experiences/ directory will be found. You can either include individual assets with the Specific Assets property or add more directories to search.

Game features extend this via the GameFeatureData asset. You can add more asset types to scan and indicate which directories to look inside to find them. For example, the ShooterCore game feature data indicates that experience definitions can also be found under /Experiences/ and /System/Experiences/ directories within the plugin.

Lyra uses ULyraAssetManager (in /LyraGame/System/) which is subclassed from the base UAssetManager class. The Lyra Asset Manager implements thread-safe asset loading functions and handles initial game load.

Next Steps

In the next chapter, we will explore the lifecycle of experiences including how they are applied to all players, loaded, and executed.

Read Chapter 3: Experience Lifecycle ❭

Lyra Deep Dive Series

• Chapter 1: Introduction
• Chapter 2: Experiences
• Chapter 3: Experience Lifecycle

Introduction

Lyra is a sample game created by Epic Games to demonstrate Unreal Engine frameworks.

This is the first chapter in my Lyra deep dive. I am walking through the essence of Lyra step-by-step focusing on one feature at a time. I have no intention of covering everything Lyra has to offer, but I will keep going until when I’ve felt like I’ve gone far enough, which will be an arbitrary decision. 😊

Since this is a technical deep dive, I will assume you can read C++ and have more than just a surface level understanding of Unreal Engine.

Articles like this one are essentially my personal notes I’ve written while exploring Unreal Engine and cleaned up to share with the public. Unreal Engine is massive and Lyra introduces numerous new features on top of an already massive codebase. It helps me to better understand (and remember) how to do things and how they work if I flesh out my notes to make them useful for not just myself but everyone else too.

As Lyra is still under development, it’s probable for some details in this series to become out of date.

All code provided in this series are excerpts of Lyra source code that are copyrighted by Epic Games and subject to the Unreal Engine End User License Agreement.

Lyra Project

The Lyra project has four targets:

All targets call ApplySharedLyraTargetSettings in LyraGameTarget. This method configures common settings based on the target type.

Logging

Custom log channels make it easier to identify which feature generated a log message, warning, or error, and provides finer control over log verbosity. Lyra implements multiple log channels for various features.

In LyraGame, the log channels are defined in LyraLogChannels.h and implemented in LyraLogChannels.cpp.

There’s also a global helper function GetClientServerContextString implemented here. This function is used by actors and actor components to log their network context, i.e., running on either the client or server, or none if not networked.

// LyraLogChannels.h
LYRAGAME_API DECLARE_LOG_CATEGORY_EXTERN(LogLyra, Log, All);
LYRAGAME_API FString GetClientServerContextString(UObject* ContextObject = nullptr);

// LyraLogChannels.cpp
DEFINE_LOG_CATEGORY(LogLyra);
FString GetClientServerContextString(UObject* ContextObject) { /* Implementation */ }

Next Steps

Learn more about the Lyra Experiences system in the next chapter ❭

Introduction

Working with actor components that don’t have a physical representation may be challenging. Recently, I learned about Component Visualizers which makes it possible to draw anything in the Unreal Editor for each component when selected.

In my sandbox construction game, each building piece has a set of polar connection points that may be either positive or negative. Two points with the same polarity cannot be attached to each other. That is, a positive point may only be attached to a negative point and vice-versa. Each connection point is represented by a custom Scene Component that has a polarity property. There are three relevant properties here: Location, Rotation, and Polarity. It would be helpful if I can visualize all three properties as a colored arrow, but only in the Unreal Editor when I’m designing a building piece.

Fortunately, Unreal Engine makes it easy to do this with FComponentVisualizer. Component visualizers are drawn when a component is selected.

Getting Started

Component visualizers must be in an editor-only module that’s loaded after the engine has been initialized. Create one if you do not have one yet.

// File: MyGame.uproject

"Modules": [
  {
    "Name": "MyGame",
    "Type": "Runtime",
    "LoadingPhase": "Default"
  },
  {
    "Name": "MyGameEditor",
    "Type": "Editor",
    "LoadingPhase": "PostEngineInit"
  }
]

Add UnrealEd and ComponentVisualizers to the editor module’s dependencies.

// File: MyGameEditor.Build.cs

PublicDependencyModuleNames.AddRange(
    new string[]
    {
        "Core",
        "MyGame"
    }
);

PrivateDependencyModuleNames.AddRange(
    new string[]
    {
        "CoreUObject",
        "Engine",
        "UnrealEd",
        "ComponentVisualizers"
    }
);

Create the Component Visualizer

In the editor module, create a class derived from FComponentVisualizer. Override either DrawVisualization or DrawVisualizationHUD depending on whether the visualization renders inside the scene or on the editor’s viewport.

// File: MyComponentVisualizer.h

#pragma once

#include "ComponentVisualizer.h"

class FMyComponentVisualizer : public FComponentVisualizer
{
public:
    // Override this to draw in the scene
    virtual void DrawVisualization(const UActorComponent* Component, const FSceneView* View,
        FPrimitiveDrawInterface* PDI) override;
	
    // Override this to draw on the editor's viewport
    virtual void DrawVisualizationHUD(const UActorComponent* Component, const FViewport* Viewport,
        const FSceneView* View, FCanvas* Canvas) override;
};

// File: MyComponentVisualizer.cpp

#include "MyComponentVisualizer.h"
#include "MyComponent.h"

void FMyComponentVisualizer::DrawVisualization(const UActorComponent* Component, const FSceneView* View,
    FPrimitiveDrawInterface* PDI)
{
    // Draw a visualization here using PDI (or Canvas if using DrawVisualizationHUD)
}

FPrimitiveDrawInterface provides basic drawing functions such as DrawLine and DrawMesh. Utility functions for drawing boxes, sphere, torus, and other advanced shapes are also available. Check out Primitive Drawing Functions for a comprehensive list and examples.

⚠️ The component’s absolute location and rotation should be used in the drawing functions. If the relative location is used, then the visualization will be rendered incorrectly when the component’s owning actor is selected in the level editor.

Register the Component Visualizer

The component visualizer is registered in StartupModule and unregistered in ShutdownModule. Call RegisterComponentVisualizer with the name of the component that should be visualized.

// File: MyGameEditor.cpp

#include "MyGameEditor.h"

#include "MyComponent.h"
#include "MyComponentVisualizer.h"
#include "UnrealEdGlobals.h"
#include "Editor/UnrealEdEngine.h"

#define LOCTEXT_NAMESPACE "FMyGameEditorModule"

void FMyGameEditorModule::StartupModule()
{
    if (GUnrealEd)
    {
        TSharedPtr<FMyComponentVisualizer> Visualizer = MakeShareable(new FMyComponentVisualizer());
        GUnrealEd->RegisterComponentVisualizer(UMyComponent::StaticClass()->GetFName(), Visualizer);
        Visualizer->OnRegister();
    }
}

void FMyGameEditorModule::ShutdownModule()
{
    if (GUnrealEd)
    {
        GUnrealEd->UnregisterComponentVisualizer(UMyComponent::StaticClass()->GetFName());
    }
}

#undef LOCTEXT_NAMESPACE
    
IMPLEMENT_MODULE(FMyGameEditorModule, MyGameEditor)

That’s it! :)

Primitive Drawing Functions

Examples

DrawPoint

void FMyComponentVisualizer::DrawVisualization(const UActorComponent* Component, const FSceneView* View,
    FPrimitiveDrawInterface* PDI)
{
    const UMyComponent* MyComponent = Cast<UMyComponent>(Component);
    if (!MyComponent)
    {
        return;
    }

    double Thickness = 15;
    PDI->DrawPoint(MyComponent->GetComponentLocation(), FLinearColor::Yellow, Thickness, SDPG_World);
}

DrawLine

void FMyComponentVisualizer::DrawVisualization(const UActorComponent* Component, const FSceneView* View,
    FPrimitiveDrawInterface* PDI)
{
    const UMyComponent* MyComponent = Cast<UMyComponent>(Component);
    if (!MyComponent)
    {
        return;
    }

    double Length = 100;
    double Thickness = 1;
	
    FVector Start = MyComponent->GetComponentLocation();
    FVector End = Start + FRotationMatrix(MyComponent->GetComponentRotation()).GetScaledAxis(EAxis::X) * Length;

    PDI->DrawLine(Start, End, FLinearColor::Yellow, SDPG_World, Thickness);
}

DrawTranslucentLine

void FMyComponentVisualizer::DrawVisualization(const UActorComponent* Component, const FSceneView* View,
    FPrimitiveDrawInterface* PDI)
{
    const UMyComponent* MyComponent = Cast<UMyComponent>(Component);
    if (!MyComponent)
    {
        return;
    }

    double Length = 100;
    double Thickness = 1;
	
    FVector Start = MyComponent->GetComponentLocation();
    FVector End = Start + FRotationMatrix(MyComponent->GetComponentRotation()).GetScaledAxis(EAxis::X) * Length;

    FLinearColor Color(1.0, 1.0, 0.0, 0.5); // RGBA in floating-point format (between 0 and 1)
    PDI->DrawTranslucentLine(Start, End, Color, SDPG_World, Thickness);
}

DrawFlatArrow

void FMyComponentVisualizer::DrawVisualization(const UActorComponent* Component, const FSceneView* View,
    FPrimitiveDrawInterface* PDI)
{
    const UMyComponent* MyComponent = Cast<UMyComponent>(Component);
    if (!MyComponent)
    {
        return;
    }

    FVector ComponentLocation = MyComponent->GetComponentLocation();
    FRotationMatrix ComponentRotation = FRotationMatrix(MyComponent->GetComponentRotation());
    FColor Color = FColor::Yellow;
    float Length = 100.f;
    float Width = 20.f;
    float Thickness = 1.f;

    DrawFlatArrow(PDI, ComponentLocation,
        ComponentRotation.GetScaledAxis(EAxis::X),
        ComponentRotation.GetScaledAxis(EAxis::Y),
        Color,
        Length,
        Width,
        GEngine->GeomMaterial->GetRenderProxy(),
        SDPG_World,
        Thickness);
}

DrawDirectionalArrow

void FMyComponentVisualizer::DrawVisualization(const UActorComponent* Component, const FSceneView* View,
    FPrimitiveDrawInterface* PDI)
{
    const UMyComponent* MyComponent = Cast<UMyComponent>(Component);
    if (!MyComponent)
    {
        return;
    }

    FLinearColor Color = FLinearColor::Yellow;
    float Length = 100.f;
    float Width = 20.f;
    float Thickness = 1.f;

    FMatrix Matrix = FScaleRotationTranslationMatrix(
        MyComponent->GetComponentScale(),
        MyComponent->GetComponentRotation(),
        MyComponent->GetComponentLocation());
	
    DrawDirectionalArrow(PDI, Matrix, Color, Length, Width, SDPG_World, Thickness);
}

Drawing Functions Reference List

Primitive Drawing Interface

• DrawPoint
• DrawLine
• DrawTranslucentLine
• DrawSprite
• DrawMesh

Primitive Utility Functions

To set the color for most of the geometry functions in this list, you’ll need to use FDynamicColoredMaterialRenderProxy. This will require adding RenderCore to your module’s dependencies.

auto* Proxy = new FDynamicColoredMaterialRenderProxy(GEngine->GeomMaterial->GetRenderProxy(), FLinearColor::Yellow);
PDI->RegisterDynamicResource(Proxy);

DrawPlane10x10(PDI, Plane, Radii, UVMin, UVMax, Proxy, SDPG_World);

• DrawPlane10x10
• DrawTriangle
• DrawBox
• DrawSphere
• DrawCone
• DrawCylinder
• DrawTorus
• DrawDisc
• DrawRectangleMesh
• DrawFlatArrow
• DrawWireBox
• DrawCircle
• DrawArc
• DrawRectangle
• DrawWireSphere
• DrawWireSphereAutoSides
• DrawWireCylinder
• DrawWireCapsule
• DrawWireChoppedCone
• DrawWireCone
• DrawWireSphereCappedCone
• DrawOrientedWireBox
• DrawDirectionalArrow
• DrawConnectedArrow
• DrawWireStar
• DrawDashedLine
• DrawWireDiamond
• DrawCoordinateSystem
• DrawFrustumWireframe