Game Features and Modular Gameplay

Build standalone features that you can quickly activate or deactivate.

Windows
MacOS
Linux

Choose your implementation method:

Blueprints

C++

The Game Features and Modular Gameplay plugins help developers create standalone features for their projects.

Building features with these plugins offers several benefits, including keeping the project's codebase clean and readable, and avoiding accidental interactions or dependencies between unrelated features. This is particularly important when developing live products that change their feature sets over time.

Initial Setup

The following steps will put your project into a state where you can add one or more standalone, plugin-based features:

  1. If this is the first feature you are adding to this project, you will need to begin by activating the Game Features and Modular Gameplay plugins. To do this, go to the Edit dropdown menu in the main Unreal Engine 5 (UE5) editor window, and select Plugins. Once the Plugins window opens, find and enable the Game Features and Modular Gameplay plugins. You can find both plugins in the left-side panel's Gameplay category.

  2. After enabling these plugins, the editor will inform you that it needs to restart. Before doing that, click New Plugin to create the plugin that will contain the feature you are building. The plugin does not have to be of any specific type; for this example, we have chosen Content Only as our type, and named the plugin MyStandaloneFeature. Make sure that your plugin is saved under the /Plugins/GameFeatures/ directory within your project.

  3. Restart the editor by clicking the Restart Now button in the Plugins window, or by closing the editor and then reopening it.

  4. Upon restarting, you may see the following text in the Message Log, within the Load Errors category:

    "Asset Manager settings do not include an entry for assets of type GameFeatureData, which is required for game feature plugins to function. Add entry to PrimaryAssetTypesToScan?"

    If you see this text, click "Add entry to PrimaryAssetTypesToScan?" to fix the issue. The editor will make the appropriate changes to DefaultEngine.ini and the message will not reappear in the future. Alternately, you can set up the Primary Asset Type manually, by using the dropdown Edit menu and selecting Project Settings, then navigating to the Asset Manager category under the Game section. Under Primary Asset Types to Scan, add one called GameFeatureData that uses the GameFeatureData base class, and add the directory /Game/Unused to the Directories array. Finally, expand Rules and set Cook Rule to Always Cook.

  5. Use the Content Browser to navigate to your plugin's top-level content folder. In this case, its name is MyStandaloneFeature Content. Create a new Data Asset by right-clicking in the Asset Panel, expanding Miscellaneous within the context menu, and selecting Data Asset. From the list of classes, choose GameFeatureData and name the new Asset whatever you named your plugin; in this case, the Asset's name must be MyStandaloneFeature.

Once you have completed these steps, your standalone feature will be set up to load when the engine (or editor) starts.

You can now begin developing the feature itself, and adding the Actions that will implement it. There are four types of Actions available:

  • Add Cheats Actions extend the Cheat Manager, creating new "cheat codes" or extending existing ones. Cheat codes are helpful for debugging, and are automatically removed from shipping builds. The ~ (tilde) key opens the console where you can enter these codes while running your project.

  • Add Components Actions take a list of Actor subclasses and add a set of Components to them on an opt-in basis. This is the most common way to use the Game Features and Modular Gameplay plugins, since Components are well-suited to encapsulating a wide range of behaviors.

  • Add Data Registry Actions add one or more Data Registries to the project. Data Registries are efficient places to store and retrieve globally-registered data.

  • Add Data Registry Source Actions add one or more Data Tables to existing Data Registries.

To add an Action, open the Data Asset you just created. Expand the ACTIONS category to reveal an array called Actions. Add an element to that array and set it to the appropriate Action type. You can find further guidance for each Action type in the sections below.

AddActions.png

One of each type of Action. You can have as many Actions as you need for any given plugin.

If, after adding Actions, your Game Feature does not function as expected, you may need to restart the editor once. GameFeatureData Assets load during editor startup, meaning that failure to restart after creating a new GameFeatureData Asset will result in that Asset not functioning. You will only need to do this after initially creating the Asset; updating it during later sessions will not require a restart.

Adding Cheats

An Add Cheats Action registers a Cheat Manager Extension with the game. Using this, developers can create their own debug commands (or "cheat codes") as part of a standalone feature, and make these commands available whenever the feature is in effect. Because Cheat Managers and Cheat Manager Extensions are debugging tools, they do not instantiate in Shipping builds.

Adding Components

An Add Components Action goes through the list of paired Actor and Component classes you provide and attempts to add an instance of each Component to each matching Actor.

You can specify whether the Components should be added on clients, servers, or both; by default, Components will be added in both cases.

To keep your feature fully encapsulated within the plugin, the Component or Components that you add will come from the plugin itself, while the Actor class will be a built-in Engine class, like Pawn, or a project-specific child of an Engine class, like a typical MyPawn. Ideally, the Component or Components should handle all program logic and data storage related to your feature.

By keeping the required interaction with the project's Actor subclass to the minimum possible, you make it easier to implement your feature in another project.

Do not use the base Actor class for an Add Components Action; this is unsupported, and the system will ignore that part of the Action. Instead, you should identify the most narrow subset of Actor subclasses that require your Component and specify that class. If there are multiple classes that should receive the Component and they do not have a common parent below Actor, you can set up multiple Add Components Actions to cover all appropriate base classes.

To receive Components from Add Components Actions, your Actor must register itself with the Game Framework Component Manager, generally in its Begin Play event. You can do this by getting the global Game Framework Component Manager and calling its Add Receiver function, passing the Actor in as the Receiver parameter. Actors only need one Add Receiver call, regardless of the number of active Game Features. To remove all Components associated with Game Features from the Actor, use the Game Framework Component Manager's Remove Receiver function.

AddReceiver.png

Registering to receive Components in an Actor's Begin Play event.

To receive Components from Add Components Actions, your Actor must register itself with the UGameFrameworkComponentManager singleton instance, and pass itself into the AddReceiver function. This is generally done in BeginPlay. The code should look like this:

if (UGameFrameworkComponentManager* ComponentManager = GetGameInstance()->GetSubsystem<UGameFrameworkComponentManager>())
{
    ComponentManager->AddReceiver(this);
}

Adding Data Registries

The Add Data Registry Action can add an entire Data Registry to your project. Configure the Action with the path to the Data Registry Asset you want to add. For more information about Data Registries, see the Data Registries page.

Adding Data Registry Sources

To add a data source that streams into a Data Registry, use an Add Data Registry Source Action. You must configure the paths to each data source, the name of the Data Registry that will load them, and the relevant priority and usage flags.

If the Game Feature is loaded at startup, the appropriate identifiers will populate dropdown lists. For more information, see the Data Registry Sources section of the Data Registries page.