Game modules
Create your project's C++ game module, understand its Build.cs and Target.cs rules, add classes, and hot-reload the module into a running editor.
Your gameplay code lives in a game module: a shared library in your project's Source/ folder that depends on the engine, declares reflected classes, and is loaded at run time. Nothing links against it. Its classes register themselves when the library loads, which is what lets the editor rebuild it and swap it in while running.
Creating a class
You do not write the module boilerplate by hand.
- In the editor: Tools > New C++ Class… opens a wizard. Pick a base class, name the class, and the editor writes the header and source, scaffolding the module on first use, then builds and loads it. See Editor.
- From a terminal:
mbt newclassdoes the same.
./mbt.cmd newclass ADoorActor --project MyGame
./mbt.cmd newclass UHealthComponent --project MyGame --parent component
./mbt.cmd newclass FDamageEvent --project MyGame --parent none
./mbt.cmd newclass AMyCharacter --project MyGame --parent-class ACharacter --parent-include Game/ACharacter.h--parent is actor (the default), component or none; --parent-class with --parent-include subclasses any reflected class. --module names the module; it defaults to the project's name. All options are in the mbt CLI reference.
newclass ADoorActor writes Public/MyGame/ADoorActor.h:
#pragma once
#include "Game/AActor.h"
#include "Game/MSceneComponent.h"
#include "ADoorActor.generated.h"
namespace Mowo {
MCLASS()
class ADoorActor : public AActor {
public:
MGENERATED_BODY()
ADoorActor() {
MSceneComponent* root = CreateDefaultSubobject<MSceneComponent>("Root");
SetRootComponent(root);
}
void Tick(float deltaSeconds) override;
};
} // namespace Mowoand Private/ADoorActor.cpp, which includes stdafx.h and the header and calls AActor::Tick. The component variant derives from MActorComponent and overrides TickComponent; the none variant writes a plain class without reflection. To fill the class in (components, the actor lifecycle, input), continue in Gameplay.
The module's files
A project made from a template nests the module in Source/<Module>/; a project made with mbt init keeps it directly in Source/. Either way the layout is:
Source/
MyGame.Target.cs the game: the player host named after the project
MyGameEditor.Target.cs the editor with this module beside it (templates)
MyGame/
MyGame.Build.cs the module's rules
Public/MyGame/ reflected headers
Private/ sources, including MyGameModule.cppBuild.cs
public class MyGame : ModuleRules
{
public MyGame(ReadOnlyTargetRules Target) : base(Target)
{
PublicDependencyModuleNames.Add("EngineLoop");
PrivateIncludePaths.Add(EngineLoopIncludeDirectory);
CompilerFlags.Add("/FIstdafx.h");
bUseHeaderTool = true;
HeaderToolDirectories.Add("Public/MyGame");
}
}- It depends on
EngineLoop, the engine umbrella library, and so sees the whole engine. The module exports nothing. /FIstdafx.hand the EngineLoop private path give every source and every generated.refl.cppthe engine'sstdafx.h.bUseHeaderToolturns on reflection for the headers underPublic/MyGame. Without it yourMCLASStypes have no class descriptor.
The full rules API is in Build tool.
Target.cs
The game target is the engine's player host built under your project's name, with your module beside it:
public class MyGameTarget : TargetRules
{
public MyGameTarget(TargetInfo Target) : base(Target)
{
Type = TargetType.Game;
LaunchModuleName = "MowoGame";
OutputName = "MyGame";
ExtraModuleNames.Add("MyGame");
}
}A package of the project is therefore named MyGame-<Platform>-<Config>. Templates add an editor target (Type = TargetType.Editor, LaunchModuleName = "MowoEditor") so the module builds beside the editor.
The module entry points
MyGameModule.cpp exports the module's ABI version and two optional hooks:
#include "stdafx.h"
#include "Core/FModuleManager.h"
MOWO_IMPLEMENT_MODULE_API_VERSION()
extern "C" __declspec(dllexport) void InitializeModule() {
}
extern "C" __declspec(dllexport) void ShutdownModule() {
}Keep the MOWO_IMPLEMENT_MODULE_API_VERSION() line. The module loader refuses a binary that does not export the engine's module ABI version, so a game module without it never loads. See the module ABI check.
InitializeModule runs after the library loads; register anything that is not a reflected type (scene systems, serializers, console commands) there. ShutdownModule runs before it unloads.
Building and hot reload
From a terminal:
./mbt.cmd build -t MyGame --extra-source MyGame/Source--extra-source points the build tool at the project's Source/ tree. To rebuild while the editor is running, the editor's Build > Compile Game Module command runs:
./mbt.cmd build -t MyGame --hot-reload --frozen-engine --extra-source MyGame/Source--hot-reloadlinks the module to a versioned file (<name>.v<N>.dll), so the new build can load while the old one is still mapped.--frozen-enginetreats the engine binaries as up to date and builds only your module, so the build does not try to relink DLLs the running editor holds open.
When the build finishes, the editor swaps the module (FHotReload::ReloadModule):
- SnapshotEvery actor whose class lives in the module is saved and destroyed.
- CollectA garbage collection runs so nothing holds code from the old module.
- UnloadThe module's classes are unregistered and the library is freed.
- LoadThe newest versioned binary loads and its classes register again.
- RestoreThe actors are recreated against the new class tables with their saved state.
FHotReload::ReloadModule Hot reload replaces the whole module, so it handles header and layout changes. To patch only changed function bodies without reloading, use live coding.
Engine sources
This page describes behavior implemented in these files of the engine repository, checked against commit 3f3a08d31.
- Templates/TP_FirstPerson/Source/TP_FirstPerson/TP_FirstPerson.Build.cs
- Templates/TP_FirstPerson/Source/TP_FirstPerson.Target.cs
- Templates/TP_FirstPerson/Source/TP_FirstPersonEditor.Target.cs
- Templates/TP_FirstPerson/Source/TP_FirstPerson/Private/TP_FirstPersonModule.cpp
- Engine/Source/Runtime/Core/Public/Core/FModuleManager.h
- Engine/Source/Runtime/Game/Public/Game/HotReload.h