introduction
Thank you for your interest in learning GameFeatures! In this article, we will start to explain the basic usage of GameFeatures, including simple usages such as how to create a GameFeature, how to configure a GameFeature, and how to activate and release a GameFeature. We will also explain some basic concepts. However, some of its advanced usage, such as Action expansion and GameFeature strategy customization, will be described later.
Demo
First, let’s take a look at a very simple Demo that I have implemented. I deliberately made it very simple to prevent irrelevant logic code from interfering with the core code context.
00:00 / 00:56
double speed
HD
00:56
As demonstrated in the Demo, you can dynamically switch game functions on and off through the simple function of buttons during runtime, thereby changing the performance of Echo in the scene and adding new animations, special effects and logic to it.
Basic usage
It is worth noting that the engine version used in the demonstration is the UE5 EA version. Although in theory it is a relatively independent plug-in framework from GameFeatures, you can also manually transplant it to UE4 and use it in your existing projects. But I think it's generally not necessary unless your project really needs various switch gameplay functions.
1. Open the plug-in
The first step is to go to the plug-in interface and enable these two plug-ins: GameFeatures and ModularGameplay.
The GameFeatures plug-in implements Actions execution and GameFeature loading, while ModularGameplay provides implementation support for AddComponent.
2. Create GameFeature
In the plug-in interface, after selecting NewPlugin, there will be an additional GameFeature option. Click Create to create a GameFeature. Just be careful here not to change the default directory, it must be placed in the GameFeatures directory . Therefore, it is hard-coded in the source code to only detect the plug-ins in this directory as GameFeature.
Creating a GameFeature through the editor will automatically configure the AssetManager and create the GameFeatureData asset in the GameFeatures directory for you, so this method is also the first and recommended way. Of course, sometimes you may also want to copy an existing GameFeature from elsewhere to your project. If you manually copy and create it, you have to pay extra attention to the correct directory, AssetManager configuration, and GameFeatureData name and configuration.
Note: Do not change the default directory, GameFeatures must be placed in the GameFeatures directory!
3. View GameFeature
The created GF can be seen by selecting the display plug-in content on the content browser. We have noticed here that an asset (MyFeature) with the same name as the plug-in has been automatically generated in the root directory. This is GameFeatureData, which defines a list of actions to be performed by the entire GameFeature. The mechanism of GameFeature is to directly read the GameFeatureData asset with the same name as the plug-in, so we should edit it but not change its name.
Note: Do not change the name of GameFeatureData, keep it with the same name as the GameFeature plug-in!
4. Configure AssetManager
Of course, at this time we can check whether the AssetManager in the project settings has automatically added the main asset type of GameFeatureData. If it doesn't exist, for example, if we copied the GameFeature plug-in directly from somewhere else, it won't automatically exist. We can just fill it in as shown in the picture. Only if this item is defined can the loading of GameFeatureData work properly. The implementation of GameFeature strongly relies on AssetManager's resource detection and discovery to load and release the corresponding assets, so this must be configured. Fortunately, this configuration is mechanical and brainless. Just follow it and you don't need to delve too deeply into the principles.
If there is no configuration, a warning will be reported when the editor starts:
Note: Be sure to configure AssetManager accordingly to scan GameFeatureData, otherwise it will not work properly!
5. Configure Actions
We double-click GameFeatureData to configure the functions of this GameFeature plug-in. From top to bottom are the initial state and current state of the plug-in. We will describe the state of GameFeature in detail later. The most important thing here is to configure Actions. Here we can configure an Action array to specify a series of operations to be performed after the plug-in is activated. The implementation of the entire GameFeature plug-in is actually to define some components or assets within the plug-in, and then configure the association through Action here. After the configuration is completed, it is best to restart the editor so that the editor can reload GameFeatureData, or set the current status to Installed and then Active to reload it. The list of available Actions in the screenshot is more than your default list because I copied some code from the "Ancient Valley" project. We will also talk about how to extend custom Actions later. The data of this GameFeatureData can actually be expanded to add more items to provide more configuration items for project needs. For example, there are many more items used in Fortnite than in the engine.
Note: Plugin information cannot be edited in the Active state. After editing GameFeatureData, it is best to trigger a reload to take effect.
6. GameFeatureAction_AddComponent example
The most important thing in Action is AddComponent. Take the dark world battle in "Ancient Valley" as an example. After Echo comes into contact with the portal, it will trigger the opening of the Ancient Battle Game Feature plug-in. After that, AddComponent will start to be used and will add a Animation replacement component, replaces Echo's skeletal animation with another animation blueprint, and adds spellcasting actions. Markers are also added to objects in the scene that can be targeted.
The logic in our own projects is the same. The Active of GameFeature is triggered through some scene interaction or opportunity, and then a series of Actions of this GameFeature start to take effect. When it fails, just do some cleaning and finishing work in reverse.
7. Register Actor as receiver
The prerequisite for AddComponent to work is that the receptor Actor must register itself as a receiver. Just remember to call AddReceiver and RemoveReceiver in Actor's BeginPlay and EndPlay respectively. Call AddReceiver for the Actor you want to dynamically add GameFeatureAction_AddComponent (most common), remember to call RemoveReceiver in EndPlay. Then you can add the AddComponent Action to it. Other types of Action do not require this manual operation. When debugging GameFeature, you may often find that Action is configured, but the Actor does not respond or work. In this case, it is likely that you forgot to register the Actor as a receiver in advance. One more thing, the implementation of AddComponent is quite sophisticated. Even if the Actor is registered as a Receiver after the GameFeature takes effect, the AddComponent can be successfully added.
Of course, it is quite troublesome to do this step every time for every Actor you want to implement. For lazy people, the ModularGameplayActors defined in the ModularGameplay plug-in have already implemented this operation for you. We only need to inherit from the base class. OK, this part will be described in detail later.
Note: You must remember to register the Actor as a Receiver so that AddComponent can work!
7. Activate GameFeature
There are several ways to load and activate plug-ins, and they can be switched directly through buttons in the editor. At runtime, you can also use the C++ API provided by GameFeaturesSubsystem. It can also be executed through command line instructions. The underlying core is the various methods inside the UGameFeaturesSubsystem that are called. You can call these APIs at appropriate locations in your game logic.
Note: Remember to activate GameFeature before it can work!
Summarize
So far, the basic usage has been explained. It can be seen that it is relatively simple and the required operations are not complicated. But how to really use it in a production environment requires a further understanding of the internal mechanism of GameFeature in order to achieve best practices. In the next article, we will formally describe the framework mechanism.