In games, one system or object will often need to respond to an event that happens elsewhere in the code. One common scenario is showing or updating the HUD when part of the game simulation changes, e.g. the player’s actor spawning in the world. Delegates are Unreal Engine’s method of declaring, subscribing to, and executing events at runtime.

Example

Given the above example scenario, it would be best to structure the code in a deterministic way such that the HUD always subscribes to the actor’s Begin Play delegate before that event is triggered. This leads to simple and straightforward code. Here’s an example of a demo actor and view model.

Here is a video of this code in action

As expected, as soon as the button is pressed, the callback subscriptions are made, the actor begins play, and the event is triggered in one frame.

Problem

Given the number of different ways an actor may spawn, for example via the network, level loading, manual spawning, etc., having a deterministic order and a simple setup won’t always be possible. Take the following case where the subscription to and triggering of the event is purposefully out of order as a demonstration.

In this function, the following happens:

• The first callback subscribes to the event immediately

• The second callback subscribes to the event after two seconds

• The actor finishes spawning, triggering the event, after one second

Here is the video of this sequence

As expected, the second callback is never triggered since the subscription happens after the event fires.

Solution 1

One naive solution is to check if the event being subscribed to has already happened. In the event the actor has already begun play, instead of subscribing to the event, immediately run the callback code. Here’s the same function as above with those checks.

Although the checks aren’t necessary in this case since the order is known, this demonstrates what will be scattered throughout a codebase when it’s unclear what comes first: the subscription to or the triggering of an event.

Here is the video of this function running:

This fixes the out of order subscription issue and is logically correct. The problem is that every subscription to this event must manually check and handle the case where the event has already fired.

Solution 2

The CallOrRegister pattern can assist in writing simple, straightforward, and easy to understand event handling code while removing the unnecessary code duplication. The concept is simple: move the branching logic into a function that called instead of subscribing to the delegate directly. Unreal uses the pattern CallOrRegister_X where the X is the name of the event. Here is the updated version of the Demo Actor with the CallOrRegister pattern.

The header defines a new function.

The source file has two changes:

• The CallOrRegister_OnBeginPlay implementation

  • This function takes in a type of X::FDelegate&&, where X is the type of delegate

  • If the actor has already begun play, immediately trigger the callback that was passed in

  • If the actor hasn’t already begun play, add the callback to the OnBeginPlay delegate for later

• After the event is triggered in BeginPlay, clear out the list of callbacks

Here’s the View Model function that uses the new pattern

When comparing to the other out of order subscriptions, this has the simplicity of the first example, but also has the correct logic of the second example

Conclusion

Delegates in Unreal Engine are not conceptionally complex; they are essentially a list of callbacks that are triggered when the delegate is invoked. Those callbacks can be manually triggered or manually added to the delegate. Understanding this allows for the CallOrRegister pattern to be a simple and straightforward way to write event handling code when the order of the subscription to and triggering of an event is not deterministic.

Example code can be found here.

Example data can be found here.

In the course of a game, there are times that the input from a player will initiate a predetermined sequence of events. The individual steps of an event may have a complicated dependency structure where some parts are prerequisites of others while other parts may be able to run in parallel. Unreal Engine provides the Tasks System, a generic job system that can handle sequencing of events and does so asynchronously by default.

Demonstration

Below is a demonstration of how the Tasks System can be used inside of a ViewModel.

Tasks are run via the Launch function in the UE::Tasks namespace. The function takes the following parameters:

1. A debug string. The provided UE_SOURCE_LOCATION macro will set the debug string to the name and line number of the source file

2. The task to run. This is either a lambda or an rvalue reference to a functor — an object with an overloaded operator()

3. An optional list of prerequisite tasks.

In this demonstration, Tasks 2 and 3 have a prerequisite of Task 1. The final task has prerequisites of Tasks 2 and 3. As the name implies, all prerequisites must be complete before a given task will start; therefore Task 2 and 3 will start in parallel as soon as Task 1 is complete. Task 4 will only start after both Task 2 and 3 are complete.

Below is the definition of the functor used in this function.

Finally, below is the SetLoadingTaskColor function that the functor calls:

Since the Task System doesn’t run code on the GameThread, SetLoadingTaskColor must use the AsyncTask method to force the color changing code on the GameThread as Unreal requires all UI changes to happen there.

The video below shows the TaskDemonstration function in action:

Example

A common event sequence found in games is going from one world to another, for example a main menu screen to an in-game world. In Unreal Engine, this would commonly be the result of a ClientTravel call on the PlayerController. This process can be hidden behind a loading screen that persists until the target world is ready for the player.

The video below shows a travel sequence made up of several tasks. The loading screen remains visible until all tasks are complete, demonstrated by the three green squares at the completion of the sequence.

Task Events

Sometimes Tasks may take several frames to complete, e.g. traveling to another world. Since a Task is marked as complete after the code in operator() completes (or the lambda code completes if using one), there needs to be another mechanism to inform dependent Tasks when a given Task is “actually” complete.

This is where Task Events can be useful. Instead of using a Task as a prerequisite, a Task Event that must be manually triggered can be used as a substitute.

Below is an example of a Task that travels to another world and triggers a Task Event when that travel is complete:

Below is another example of a Task that defines a Task Event. The Task Event is passed along to another ViewModel for triggering completion after the simulated loading completes and the GameThread has updated the color accordingly.

Finally, here is the code that runs all the tasks when the Travel to Another World button is clicked:

The function breaks down as follows:

1. A loading screen widget is placed over the entire screen

2. A Task is started to travel to another world

3. 3 Simulate Loading Tasks are created, all with a prerequisite of the OnTravelComplete Task Event being triggered

4. Finally, using a lambda version of a Task, the loading screen widget is removed from the viewport after the 3 Task Events from the 3 Simulate Loading Tasks are triggered

Conclusion

Unreal Engine’s Task System is a great built-in tool for running parallel tasks and can handle complicated dependency structures.

Example code can be found here.

Example data can be found here.

When creating games in Unreal Engine, the engine code and most tutorials push developers towards an Object Oriented Design. Objects in the world derive from Actor, player characters often derive from Pawn, etc. While Object Oriented Programming is what most engineers are taught and allow for a quick creation of a set of classes that designers and other developers can manipulate, there are downsides to this approach. Monolithic classes that are difficult to change, huge class hierarchies via inheritance, and poor performance are some examples. Addressing the issues of deep inheritance hierarchies via composition using Actor Components still won’t address a lot of the performance problems of Object Oriented Programming.

Data Oriented Design isn’t a new concept; however it is infrequently seen in the games industry, especially when compared to Object Oriented Design. At a high level, Data Oriented Design is the idea that code should be structured and modeled around the data that will be transformed. This is in contrast to Object Oriented Design which structures code around an object hierarchy that is meant to model objects in the world.

Data Oriented Design is a large topic. This is an Unreal Engine specific and narrowly focused example demonstrating how a small change in mindset and code design can result in big performance gains.

Example

Here is a video of the example to be analyzed:

There are 10,000 actors in this scene, each with a static mesh component with a custom material. The material applies a world Z Offset and tints the mesh red based on parameters passed into the material instance. The Z offset is changed by using a cosine function and the red tint is changed by distance from the camera.

Actor Tick

Using a typical Object Oriented Design, here is a simple actor class that implements getting the Z Offset based on a cosine function and calculating the distance from the camera to get a red tint. The values are updated every tick. The camera location must be retrieved for all 10,000 actors even though it won’t change in the middle of a frame.

Using Unreal Insights, the time it takes to run this code per frame can be analyzed.

In a typical frame, the timer section is reporting about 8.2ms for ticking the 10,000 actors. Looking on the left side of the insights, the full cost is more clear — about 12.87ms. Dealing with a large number of actors that tick a relatively small amount of logic results in a large percentage of wasted time — about 36% in this example.

Actor Tick by Manager

While not actually an implementation of a Data Oriented Design, updating a large number of actors manually from an outside object can result in significant performance gains. As seen above, there is a lot of time spent in the management of the tick system. Here is how the same code could be executed from an outside object.

Here is the timing information for this code:

In a typical frame, the timer section is reporting 4.7ms to tick all of the actors. This is approaching half the time it takes to call the virtual Tick on the actors individually. Additionally, the total time is down from 12.87m — a savings of about 64%.

Tick Manager Data

Finally, if instead of having each individual actor be responsible for updating its data, the data is stored internally to the manager and updated, that code could look like this:

This is an example of what Data Oriented Design is as opposed to Object Oriented. It’s not perfect as the code still reaches into the actors to update their dynamic material, which in the process is going to jump all over RAM, causing continual cache misses. That being said even just being able to grab the camera location once as opposed to 10,000 times is a significant savings.

Here is the timing information for this code:

In a typical frame, the timer section is reporting 3.6ms to tick the internal stored data. This is about a 24% savings over the manager ticking the actors, and about a 72% savings from ticking all of the actors individually!

Conclusion

Data Oriented Design is a large topic. From creating code that is easily parallelized, easily vectorized to use SIMD operations and more cache efficient, the performance gains can be significant. Epic Games is working on their Data Oriented gameplay framework, Mass, which is currently experimental at the time of writing. Also, with Iris, Epic took more of a Data Oriented design. See SphereNetObjectPrioritizer as an example of how Iris determines net priority based on distance to the camera.

Example code can be found here.

Example data can be found here.

Recommended Links

GDC 2014: Mike Acton “Data-Oriented Design and C++”

Casey Muratori’s Simple Code High Performance

Casey Muratori’s Becoming an N+2 Programmer

As the data for a game grows in size and complexity, it is important to load only what is needed given the player’s context. For the assets that won’t be managed automatically, Unreal Engine provides an Asset Manager that facilitates loading and unloading of assets manually. Combining the concepts of Primary Assets and Asset Bundles, subsets of these assets can also be loaded depending on the context.

Example

Consider a game that has dozens of characters from which a player can choose. Characters could be described by a data asset. This data asset could have a texture of the character’s portrait to display in a lobby screen, a localized name, a blueprint to use as a pawn in game, and dozens of additional pieces of data and assets. The following code is an example of how that might be set up:

Asset Bundles

Whenever a data asset of this type is loaded, it is also going to load every asset it references, even in a context where those assets might not be used. For example, the game may be designed such that the pawn blueprint isn’t used in the lobby. To address this wasteful loading time and memory usage, assets can be associated with Asset Bundles within Primary Assets. Here is the same object definition using Asset Bundles that adds context to the different assets to be loaded

The three different ways the data will be loaded are:

• CharacterLobbyPortrait is only loaded if the Data Asset is loaded with the Lobby Asset Bundle

• CharacterGamePawnClass is only loaded if the Data Asset is loaded with the Game Asset Bundle

• CharacterName is not an asset and will always be loaded

Notice the property types of the objects that are associated with Asset Bundles. Instead of being TObjectPtr and TSubclassOf, they are now TSoftObjectPtr and TSoftClassPtr respectively. Internally, these contain paths to the asset and a pointer to that asset in memory if valid. TObjectPtr and TSubclassOf are ‘Hard’ references, and will always be loaded when their owning assets are loaded.

In order for the Asset Manager to load the Asset Bundles requested, the owning object must be a Primary Asset.

Primary Assets

In order for AssetBundlesCharacterData to be considered a Primary Asset and discovered by the Asset Manager, the following must be done:

• Overload the GetPrimaryAssetId function from UObject and return a unique Id based on the type and asset

  • This is handled automatically when deriving from UPrimaryDataAsset instead of UDataAsset

  • Note: Deriving from UPrimaryDataAsset also adds support for Asset Bundles

• Add the new Asset Type in Project Settings → Game → Asset Manager

Interacting with the Asset Manager

Here is an example of a ViewModel that loads all of the AssetBundlesCharacterData Data Assets with different Asset Bundles.

Note: The ClearCharacterData function forces garbage collection for demonstration purposes so that all assets that are no longer referenced are immediately deleted.

Asset Bundles in Action

Here is an example instance of an AssetBundlesCharacterData instance and the results of running a UI with the ViewModel above.

Conclusion

Loading data when it’s not needed will increase loading times, memory footprint, and negatively affect players. It is important to understand what is loaded and when. Using the Asset Manager correctly is specific to each game and a necessary tool for the engineers to learn.

Example code can be found here.

Example assets can be found here.

The Model View View Model (MVVM) architecture is a software design pattern to separate the user interface from the business logic of an application. In game terms, business logic would be the state of the simulation. View Models often use a service, or multiple, to interact with an API to the backend of an application in what James Montemagno refers to as MVVMS in his video here.

In games it is common to have screens that have a one-to-one or one-to-many relationship with services. Examples are a player profile, loadouts or a store. Integrating the use of a Type Container with Unreal Engine’s View Models allows for the user interface to interact with these services in a decoupled and testable manner.

Example

Below is a simplified example of a common pattern for a ProfileService. The service acts as the API and the implementation requires a ProfileRepo which does the actual retrieving of the profile.

Note the Expose_TNameOf lines after the declaration of the Interfaces. This is necessary. If forgotten, the GetInstance calls in the Type Container will not work and crash the program.

The Type Container

Given the above service and repo, the concrete versions can be associated with, stored, and retrieved by their interface in a Type Container.

The Type Container provides four ways to register a concrete class with its interface, two of which are demonstrated here:

• RegisterClass takes the interface type and the concrete type as template parameters. It also takes a variable number of template parameters if the concrete implementation takes constructor arguments (not shown here).

• RegisterInstance takes the interface type as a template parameter and then a concrete instance of that interface as an argument.

• RegisterFactory and RegisterDelegate are the additional two ways to register types. See TypeContainerTests.cpp for examples.

Given a Type Container, call GetInstance with a template parameter of the interface type to retrieve a concrete implementation. Depending on the register method used, the object returned will differ in the following ways:

• RegisterClass will return a new insanitation on each call to GetInstance.

• RegisterInstance will return the one instance that is passed in at registration time.

• RegisterFactory and RegisterDelegate must return an instance of the interface type; however what they return is implementation specific.

Where to Instantiate a Type Container

There are many options as to where the Type Container can be instantiated. Some common options are:

• A Subsystem (Engine, GameInstance, LocalPlayer, etc.)

• On a custom Engine class

• In a Module

In this example, the Module class for a new ServicesModule has been chosen as the object to create and populate the Type Container as shown below:

The pros of putting the Type Container in the Module are:

• During a normal run of the editor or game, StartupModule and ShutdownModule will be called exactly once

• There is no need for a World Context Object, unlike a GameInstanceSubsystem

The Type Container in Action

The following is an example of a View Model using the Type Container to get access to, storing, and using the Profile Service.

The asynchronous call to GetProfileAsync and usage of Promises and Futures is explained more here.

The View Model stores the Profile Service in a TSharedRef which is non nullable version of a TSharedPtr. This has the benefit of preventing null pointer exceptions and the need to check for validity throughout its use. Since it can’t be null, it must be initialized in the Constructor member initializer list, including the version that takes the FVTableHelper which will be auto-generated and cause compiler errors if not explicitly written.

Unfortunately, Unreal Engine does not have a way to call a custom constructor with parameters on any class that derives from UObject; therefore real dependency injection can not be achieved. The alternatives are:

• What is shown here - in the constructors, get the object desired from a global Type Container. The tradeoffs of this option are:

  • Pro - Guaranteed a valid object throughout the lifetime of the owning View Model.

  • Con - This code will crash if using a Type Container declared in the same Module where the View Model lives. This is because the Class Default Object (CDO) will be created before the StartupModule function is called, and the Type Container will not yet be populated with the desired type.

• Don’t store the service as a member variable in the class, but instead get it every time it is needed. The tradeoffs of this option are:

  • Pro - This removes the need to declare the constructors and destructor in the example above.

  • Pro - The Type Container always returns a TSharedRef, so a valid object is still guaranteed at access time.

  • Con - Paying for access each time the type is needed

  • Con - More difficult to inspect the dependencies of the View Model while debugging.

Below is a video of this code in action:

Conclusion

If a project has a use for the MVVMS architecture, it may not be as nice as other frameworks, but it is doable using Unreal Engine’s View Model plugin coupled with a Type Container to store and retrieve services.

Example code can be found here.

Example assets can be found here.

Unreal Engine provides a few mechanisms to run asynchronous code. AsyncTask wraps functionality of the TaskGraph in a simple and convenient function that runs code in the form of a function or lambda on a specified thread. Promises and Futures, while not inherently multi-threaded, provide capabilities to trigger a continuation function once they are marked as completed in a thread safe manner. Combining AsyncTasks with Promises and Futures can keep the UI responsive even when doing expensive operations.

Example

Below is a simplified example of a ViewModel that simulates an expensive task, perhaps reading a file or requesting data from a backend service, by sleeping the thread for 3 seconds before increasing the RunCount by 1.

This ViewModel is hooked up to the following widget using the View Bindings window. The bindings are:

• Clicking on the Run Button calls the function

• The Common Text Box holds the FText representation of RunCount.

There’s also an animated spinner to demonstrate when the game thread is blocked.

The following video demonstrates this ViewModel in action

Making it Asynchronous

This is the asynchronous version of the same ViewModel from above

Understanding TFuture and TPromise

At a high level, Futures provide the capability to call a function via the Next method after it has become fulfilled. This is convenient, because the function passed to Next will be called even in the case where the Future was fulfilled before Next was invoked.

Promises wrap a Future and provide the SetValue method to fulfill its internal Future.

Understanding the Threaded ViewModel

When DoALongRunningAsyncTask is called, the following happens:

• The Task is marked as running immediately so the UI can respond accordingly

• DoALongRunningAsyncTaskInternal is called

  • A SharedRef (non nullable version of a SharedPtr) of a Promise is created

  • This Promise is passed to an AsyncTask call via a lambda which will now hold a reference which will prevent it from falling out of scope and being deleted

  • The AsyncTask will start a thread sometime in the future that will:

    • Sleep for 3 seconds

    • Fulfill the Future of the Promise that was passed in by incrementing the RunCount by 1

  • The Promise’s Future is returned immediately

• Next is called on the returned Future and a continuation function is passed in for whenever the Future is fulfilled. This continuation function passes a lambda to be called back on the Game Thread that will:

  • Mark the Task as completed by setting bIsTaskRunning to false

  • Increment the RunCount by the Result from the Future

The threaded ViewModel is hooked up to the following UI. This widgets adds bindings for an animated throbber that is visible when the task is running and disabling the Run button when the task is running.

The following video demonstrates the threaded ViewModel in action

Conclusion

AsyncTask, Promises, and Futures are a subset of tools that Unreal Engine provides to run asynchronous code. Interacting with the TaskGraph directly and the Task System are others. Expensive calls, such as interacting with a backend service or doing File I/O can be done on a thread other than the Game Thread to keep the UI and simulation smooth

Example code can be found here.

Example assets can be found here.

Data Validation is a plugin to inform developers when assets are in an invalid state at edit and build time. This means that errors can be caught when developers are making changes and during a project’s build pipeline. This allows programmers to write simpler code and, more importantly, prevent bugs and crashes from showing up in front of players.

Example

The following is a simplified example of an actor that contains a pointer to a data asset that the actor will use and be referenced at runtime.

Since the DataAsset pointer isn’t guaranteed to be valid, it is essential to check it before it is accessed both in the IncreaseSpeed and BeginPlay functions.

Consider how this code could be simplified if the pointer to the data asset was guaranteed to always be valid. Here is how the same class looks with Data Validation.

By guaranteeing that the pointer to the internal Data Asset is valid at build time, the code is now future proofed against null pointer exceptions and has been simplified in the following ways:

• The Data Asset can be returned by reference, signaling to other developers that they are guaranteed a valid, non-null object

• Accessing the Data Asset doesn’t require validity checking and assertions

• There is only the code path where the Data Asset is valid and there is no need for error logging or error handling

One thing to note is that care must be taken not to lose an invalid data validation result from a parent class. Don’t ever return EDataValidationResult::Valid from the subclass implementation of IsDataValid, but instead capture the result from the parent class and change it to EDataValidationResult::Invalid when needed. This will ensure that all invalid cases from parent classes are caught reported appropriately.

Data Validation in Action

Now that there is an asset type that can be created that implements data validation, an instance can be created in the editor to demonstrate what happens when an asset is in an invalid state.

Data Validation Errors in Editor

The most common place Data Validation errors are going to show up is in editor when developers are creating new or editing existing assets.

Given an invalid Blueprint instance of ADataValidationAsset, data validation errors will present in the following three ways:

Data Validation Errors via Commandlet

Unreal Engine provides a commandlet to do a Data Validation pass on all of the assets in a project. This is especially helpful when:

• Adding new validation paths which may introduce validation errors to existing assets

• Running in an automation pipeline to verify the integrity of a build during a Continuous Integration (CI) process.

Assuming an installed version of Unreal Engine the Data Validation Commandlet can be run via a command line prompt, e.g. Powershell, the following way:

Conclusion

It is an engineering responsibility to guarantee the code is performant, free of bugs or crashes, and easy to understand. Data Validation is one tool that can help in those efforts.

This is a brief introduction to Data Validation. Check out the documentation here to see the other ways that it can be implemented, e.g. creating a validator that derives from UEditorValidatorBase.

Example code can be found here