Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 136 additions & 59 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

# Unreal Engine Gameplay Module Template


<!-- Header Start -->
<a href = "https://docs.unrealengine.com/5.3/en-US/"> <img height="40" img width="40" src="https://cdn.simpleicons.org/unrealengine/white"> </a>
<a href = "https://learn.microsoft.com/en-us/cpp/cpp-language"> <img height="40" img width="40" src="https://cdn.simpleicons.org/c++"> </a>
Expand All @@ -13,17 +14,17 @@
<img align="right" src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FJDSherbert%2FUnreal-Engine-Gameplay-Module-Template%2Fhit-counter%2FREADME&count_bg=%2379C83D&title_bg=%23555555&labelColor=0E1128&title=🔍&style=for-the-badge">
<!-- Header End -->

-----------------------------------------------------------------------
</br>

<a href="https://docs.unrealengine.com/5.3/en-US/">
<img align="left" alt="Unreal Engine Template" src="https://img.shields.io/badge/Unreal%20Engine%20Template-black?style=for-the-badge&logo=unrealengine&logoColor=white&color=black&labelColor=black"> </a>

<a href="https://choosealicense.com/licenses/unlicense/">
<img align="right" alt="License" src="https://img.shields.io/badge/License%20:%20Unlicense-black?style=for-the-badge&logo=unlicense&logoColor=white&color=black&labelColor=black"> </a>

<br></br>
</br>
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In Github Markdown, there isn't a need to provide additional <br> it can just be referenced as </br> Opens and closes, though with it it requires that there is 1 space above and below on where it has been added.



-----------------------------------------------------------------------
## Overview
A repository containing a dummy Unreal Engine 5 gameplay module. Contains a folder structure that has been premade to help kickstart the making of new Unreal gameplay modules. I'm always forgetting what specifically I need to do, so this is a nice point of reference. Using this will allow you to create unreal engine modules for your project much more easily.

Expand All @@ -43,32 +44,37 @@ If you'd like to get Unreal Engine and use this project template, please follow

Lemme know if you have any questions or feedback!

-----------------------------------------------------------------------
</br>

# Guide

-----------------------------------------------------------------------
Copy link
Author

@VerzatileDev VerzatileDev Jan 28, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the guide's <h1> already splits it clearly enough so additional areas would clutter the information around it, instead I have used </br> to separate them from the previous


<a href="https://docs.unrealengine.com/5.2/en-US/"><img align="top" alt="Unreal Engine Guide" src="https://img.shields.io/badge/Unreal%20Engine%20Guide-00549F?style=for-the-badge&logo=unrealengine&logoColor=white&color=black&labelColor=midnight"></a>


-----------------------------------------------------------------------
Unreal Engine Modules are a useful way to organize your code, improve your project's build times, and configure its loading and unloading processes for systems and code. This guide will cover the steps necessary to implement a new runtime module from scratch in C++. This module will be separate from the primary module for your project.

The module in this example is named ModuleTest.
The module in this example is named `ModuleTest`.

1. Required Setup
To follow this guide, start by creating a new project named MyProject, and make sure it is a C++ project. If you are following along with a Blueprint-only project, create a new piece of C++ code in Unreal Editor to convert it to a C++ project.
- *Required Setup:*

2. Setting Up Your Directories
First, you need to set up directories to contain the module and its code.
To follow this guide, start by creating a new project named `MyProject`, and make sure it is a C++ project. If you are following along with a Blueprint-only project, create a new piece of C++ code in Unreal Editor to convert it to a C++ project.

Navigate to your project's root directory, then open the Source folder.
- *Setting Up Your Directories:*

Inside your project's Source folder, make a new folder named ModuleTest. This will serve as your module's root directory.
`First, you need to set up directories to contain the module and its code.`

Inside your module's root directory, create two new folders called Private and Public.
- Navigate to your project's root directory, then open the Source folder.

- Inside your project's Source folder, make a new folder named ModuleTest. This will serve as your module's root directory.

- Inside your module's root directory, create two new folders called Private and Public.

</br>

Your directory structure should resemble this:

```
- MyProject
- Source
- MyProject.Target.cs
Expand All @@ -82,52 +88,84 @@ Your directory structure should resemble this:
- Private
- Public

3. Creating the Build.cs File
```
</br>

## 3. Build.cs Setup (Creating the `Build.cs` File)

When Unreal Build Tool (UBT) looks through your project's directories for dependencies, it ignores your IDE solution file and instead looks at the Build.cs**** files in your Source folder. Every module must have a `Build`.cs file, or else UBT will not discover it.

To set up your Build.cs file, follow these steps:
</br>

Setup:

Create a file called ModuleTest.Build.cs in your module's root directory. Open this file and add the following code:
1. Create a file called `ModuleTest.Build.cs` in your module's root directory.
2. Open this file and add the following code:

### ModuleTest.Build.cs
```

```cs
using UnrealBuildTool;

public class ModuleTest: ModuleRules
{
public ModuleTest(ReadOnlyTargetRules Target) : base(Target)
{

}
}
```

This will make your module visible to the Unreal build system.
Edit the constructor so that it reads as follows:
Note:

- The following makes your module visible to the Unreal build system.
- Edit the constructor so that it reads as follows:

</br>

### ModuleTest.Build.cs
```

```cs
public ModuleTest(ReadOnlyTargetRules Target) : base(Target)
{
PrivateDependencyModuleNames.AddRange(new string[] {"Core", "CoreUObject", "Engine"});
}
```
This will add the Core, CoreUObject, and Engine modules as private dependencies for your module. This will make several classes available to this module for later steps in this guide.

Note:

- This will add the Core, CoreUObject, and Engine modules as private dependencies for your module.
- This will make several classes available to this module for later steps in this guide.

Now when you add code to this module's folders, that code will be discovered both when UBT builds the project and whenever you generate your IDE project files.

4. Implementing Your Module in C++
While the Build.cs file makes your module discoverable to UBT, your module also needs to be implemented as a C++ class so that the engine can load and unload it.
</br>

## 4. Implementing Your Module in C++

Note:

- While the Build.cs file, it makes your module discoverable to `UBT`, your module also needs to be implemented as a `C++ class` so that the engine can load and unload it.

- Fortunately, Unreal Engine includes macros that can streamline this process for most common implementations. To make a quick implementation file, follow these steps:

</br>

Steps:

Fortunately, Unreal Engine includes macros that can streamline this process for most common implementations. To make a quick implementation file, follow these steps:
1. Navigate to your module's root directory and open the `Private` folder.
2. Create a new file called ModuleTestModule.cpp inside this folder.

Navigate to your module's root directory and open the Private folder. Create a new file called ModuleTestModule.cpp inside this folder. It is not necessary to make a .h file for this class.
- It is not necessary to make a .h file for this class.
4. [ModuleName]Module is the typical naming convention for module implementation files in Unreal Engine source code.

[ModuleName]Module is the typical naming convention for module implementation files in Unreal Engine source code. This is useful for keeping track of them in a large codebase.
- This is useful for keeping track of them in a large codebase.

Inside ModuleTestModule.cpp, add the following code:
Inside `ModuleTestModule.cpp`, add the following code:

### ModuleTestModule.cpp
```

```cpp
#include "Modules/ModuleManager.h"

IMPLEMENT_MODULE(FDefaultModuleImpl, ModuleTest);
Expand All @@ -137,27 +175,45 @@ This provides a default implementation for your module that makes it available t

You can create more detailed implementations by manually writing the class for your module, its constructor, and the Startup and Shutdown functions for it. However, for most gameplay modules, this default implementation will be sufficient to load and unload your module.

5. Compiling Your Module
After defining and implementing your module, the process to compile it is very simple.
</br>

## 5. Compiling Your Module

Note:

- After defining and implementing your module, the process to compile it is very simple.

Steps:

Right-click MyProject.uproject and click Generate Visual Studio Files to regenerate your IDE solution.
1. Right-click `MyProject.uproject` and click `Generate Visual Studio Files` to regenerate your IDE solution.

This will ensure that your new module becomes visible in your IDE and within Unreal Editor.
- This will ensure that your new module becomes visible in your IDE and within Unreal Editor.
- Any time you re-organize your module's code or change the contents of its `Build.cs` file, you should regenerate your IDE solution to make sure it stays up to date.

Any time you re-organize your module's code or change the contents of its Build.cs file, you should regenerate your IDE solution to make sure it stays up to date.
3. Compile your project in Visual Studio.

Compile your project in Visual Studio. Your new module will be compiled alongside it.
- Your new module will be compiled alongside it.

Any time you add a new module manually, change your module's directory structure, move or rename C++ files, or change your module's dependencies, you should regenerate your project files to update your Visual Studio solution, then compile your project again.

Although you can compile your project while Unreal Editor is running, sometimes you will need to close Unreal Editor, then restart it after compiling for major changes or new classes to take effect.

6. Including Your Module In Your Project
Your module should be able to compile, but to use any code from your module in your project, you need to register it with your .uproject file, then make a dependency for your game's primary module.
</br>

Open the MyProject root directory, then open MyProject.uproject in a text editor and edit your "Modules" list as follows:
## 6. Including Your Module In Your Project

Note:

- Your module should be able to compile, but to use any code from your module in your project, you need to register it with your `.uproject` file, then make a dependency for your game's primary module.

Steps:

1. Open the `MyProject` root directory
2. Now open `MyProject.uproject` in a text editor
3. Edit your "Modules" list as follows:

### MyProject.uproject

```
"Modules":
[
Expand All @@ -172,55 +228,76 @@ Open the MyProject root directory, then open MyProject.uproject in a text editor
}
]
```

You can use this list entry to configure which Loading Phase it will load up on and its Type. This example is a runtime module, so it can be used when the project is running as a standalone application or in the editor.

By comparison, Editor modules can only run in the editor. It also uses the Default loading phase, which initializes after game modules are loaded. Depending on the specifics of your module, you might need to use earlier loading phases to make sure other modules that depend on it don't throw errors looking for unloaded code.

Navigate to your MyProject/Source folder, then open the MyProject.Build.cs file. Add ModuleTest to your PublicDependencyModuleNames list. It should as follows:
4. Navigate to your MyProject/Source folder
5. Open `MyProject.Build.cs` file.
6. Add `ModuleTest` to your `PublicDependencyModuleNames` list.

It should be the following:

### MyProject.Build.cs
```

```cs
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "ModuleTest" });
```
Now it will be possible to include code from your module in your primary game module.

7. Adding Code to Your Module
You can add C++ files to the Public and Private directories in your module manually, or you can add them in Unreal Editor.
It is now possible to include code, from your module in your primary game module.

These steps will guide you through using the New Class Wizard to add code to a module:
</br>

## 7. Adding Code to Your Module

Open your project in Unreal Editor.
You can add `C++` files to the Public and Private directories in your module manually, or you can add them in Unreal Editor.

In the Content Browser, click Add, then click New C++ Class.

Choose Actor as the parent class, then click Next.
These steps will guide you through using the New Class Wizard to add code to a module:

Locate the dropdown next to the Name field. It should read MyProject (Runtime) by default. Click this dropdown, then change it to ModuleTest (Runtime).
1. Open your project in Unreal Editor.
2. In the Content Browser, click Add, then click New C++ Class.
3. Choose Actor as the parent class, then click Next.
4. Locate the dropdown next to the Name field. It should read MyProject (Runtime) by default. Click this dropdown, then change it to ModuleTest (Runtime).

If you do not see MyModule (Runtime) as an option, review the previous sections to ensure you followed the steps correctly.

Name the class ModuleActorBase, set the Class Type to Public, then click Create Class.
5. Name the class `ModuleActorBase`, set the Class Type to Public, then click Create Class.

Your class's .h and .cpp files will open automatically in your IDE. Your class's .cpp file will be added to your module's Private folder, while its .h file will be added to the Public folder.
- The class's .h and .cpp files will open automatically in your IDE.
- The class's .cpp file will be added to your module's Private folder, while its .h file will be added to the Public folder.

Open ModuleActorBase.cpp, then add the following line to the AModuleActorBase::BeginPlay function:
6. Open ModuleActorBase.cpp
7. Add the following line to the AModuleActorBase::BeginPlay function:

`GEngine->AddOnScreenDebugMessage(0, 5.0f, FColor::Blue, TEXT("Hello, world!"));`
```
GEngine->AddOnScreenDebugMessage(0, 5.0f, FColor::Blue, TEXT("Hello, world!"));
```

8. Save your code and compile your module.

Save your code and compile your module.
Additional notes:

This class defines a simple Actor that outputs an on-screen debug message when the game starts. You can test this by using the Place Actors tool in Unreal Editor.
- This class defines a simple Actor that outputs an on-screen debug message when the game starts.
- You can test this by using the Place Actors tool in Unreal Editor.

8. Extending Code From Your Module
Finally, follow the steps below to test your new Actor class and your primary game module's ability to see it.

Open your project in Unreal Editor. Create a New Blueprint Class, then expand the All Classes list.
## 8. Extending Code From Your Module

Choose ModuleActorBase as the parent class. Name your Blueprint class ModuleActorBP.

Drag a copy of ModuleActorBP from the Content Browser into your game's world. Click the Play button.
Follow the steps below to test your new Actor class and your primary game module's ability to see it.

1. Open your project in Unreal Editor.
2. Create a New Blueprint Class, then expand the All Classes list.
3. Choose ModuleActorBase as the parent class.
4. Name your Blueprint class ModuleActorBP.
5. Drag a copy of `ModuleActorBP` from the Content Browser into your game's world.
6. Click the Play button.

If you do not see ModuleActorBase in the list of classes, make sure its header is in the Public folder, that it has the BlueprintType UCLASS specifier, and that you have added the ModuleTest module to your project's dependencies.

</br>

## Final Result
When you click Play, your project will start playing in editor, and the on-screen debug message "Hello, world!" will display in blue text. This Blueprint-based Actor extends a class that is defined in a separate gameplay module. When you write modules in the future, you will now be prepared to create extensible classes as a foundation for gameplay-specific code.