Programmer Guide
We generally use Epic's with a few exceptions [LINK REDACTED].
Part of our code style is enforced by our clang format file, so make sure your IDE has support for that.
This project features a full documentation system, complete with diagrams and full class/function documentation. Documentation of your own code is heavily encouraged. You can use Javadoc syntax to comment header file functions, fields and classes/structs. Additionally, you can document overall systems by creating/editing markdown files in the Documentation/md folder. Both of these are used by Doxygen in our build pipeline to generate documentation which you can view by running OpenDocs.bat.
As a programming team, we've seen that developers often excel with different contribution workflows. To give our team the flexibility and choice they need to do well, we offer two forms of development: trunk-based development and feature branches.
This workflow scheme is used when you want to drop in some quick code or a contribution which should be largely working (compiles, and doesn't cause major issues). It gives you the convenience of being able to contribute without the overhead or maintenance cost of your own branch, which is extremely useful if your availability is more sporadic. You can read more about the trunk based development concept here: https://trunkbaseddevelopment.com/
- Switch to the trunk branch:
git switch trunk. - Code!
- Add your files using
git add, or add all files withgit add -A .. - Commit with
git commit -m "<commit message>". You can leave off the end quote and press enter for multi-line. Add the end quote at the end of line and enter to finish the commit message. - Push your changes with
git push. - When you work on your branch again, make sure to
UpdateProject.batto get the latest changes.
This workflow scheme is used for when you have a longer feature which can't be ready for the faster release pace of trunk, or when you can drive feature development and branch upkeep on your own. You can read more about the feature branching concept here: https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow
- Branch
mainwith a branch name of the formatcode/feature-or-bug-fix-name:git switch -c <branch-name> - Push your new branch, linking it to the remote:
git push -u origin <branch-name>. - Create a WIP pull request for your new branch. More info about pull requests below.
- Code!
- Add your files using
git add, or add all files withgit add -A .. - Commit with
git commit -m "<commit message>". You can leave off the end quote and press enter for multi-line. Add the end quote at the end of line and enter to finish the commit message. - Push your changes with
git push. - When you work on your branch again, make sure to
git pupto update your branch to the latest changes. After that, runUpdateProject.batto do misc project updates.
If you are still working on your branch, please prefix your pull request with WIP: . When it is done, remove the WIP status.
Sometimes when you rebase, there will be conflicts. You can resolve text file conflicts easily, but you'll have to manually checkout LFS files with conflicts and compare them: https://github.blog/2018-11-02-git-lfs-v260/#new-git-lfs-checkout-options
Note that in a rebase, "ours" is the branch you are rebasing onto, and "theirs" is the branch you are replaying. So commonly, "ours" will be origin/main and "theirs" will be your branch.
We have a number of Git aliases to do common tasks:
-
git fm: fetches latest origin main branch -
git ro: rebases onto origin main branch -
git pf: push --force-with lease. This command does a force push, but with a lease which checks for commit integrity. -
git up: fm and ro -
git pup: up and pf -
git send: updates tracking for Source folder (adds, deletes, renames), refreshes already tracked files in all folders and pushes. -
git s: short form of status -
git state: shows Git LFS file status in addition togit s -
git lard: shows the 40 biggest files in the repo -
git last: shows the last commit -
git uncommit: undos your last commit, but keeps your changes. You can't use this command on a protected branch if you have already pushed the commit to it. -
git tree: shows the history in tree form -
git force-verify: verifies the state of the repository
<type>(<scope>): <subject>
[body]
[footer]
A commit type is a required prefix on the subject with the following options::
- feat: a new feature
- fix: a bug fix
- opt: optimization
- docs: a change to docs or comments
- style: style changes to the code that do not actually change the result
- refactor: organizational/structural adjustments to code, like renaming a variable
- test: anything to do with tests
- chore: any repo maintenance, build config changes
Commit scope is also a required classifier which describes the system that you changed. It could be, but not limited to, the following:
- weapons
- render
- config
- ai
- infrastructure
- core etc.
The commit message subject is an imperative, present-tense statement that describes the change in 50 characters or less.
The optional commit message body, like the subject, is imperative and present-tense that is more detailed explanatory text. You should try to wrap your messages to 72 characters per line, because of how git formats things. You may also use a bulleted list as a summary of changes if you don't want to write it in paragraphs.
Finally, the commit footer. This is optional and should be reserved for linking commits to issue tracker issues (ex. Fixes #AT-23), and documenting breaking changes or additional required steps for developers. These warnings should be labeled with "BREAKING CHANGE:"
We recommend Visual Studio 2022 with at least the following installer settings:
- Game Development with C++ workload
- Unreal Engine Installer
- Nuget Package Manager
- MSBuild
- Windows 10 SDK (latest version)
You may also want the following optional components:
- C++ profiling tools
- IntelliTrace
- IntelliCode
- AddressSanitizer
Alternatively, you can import (Visual Studio Installer > More > Import configuration) our .vsconfig LINK REDACTED. Make sure to rename the file to .vsconfig before trying to import.
We use clang-format for formatting. To enable clang-format support on your Visual Studio, follow the settings panel as "Options -> Text Editor -> C/C++ -> Formatting" and select "Enable ClangFormat support"
For a smoother experience with formatting, you will want to use these settings:
And, optionally, this extension to format on save: https://marketplace.visualstudio.com/items?itemName=mynkow.FormatdocumentonSave
Note that a custom clang-format.exe is used. You must install Clang 13.0.0 for support for the latest formatting features.
- Use the shortest path for includes, instead of using fully qualified file paths
- Order your includes like this
.h files:
#include "CoreMinimal.h"
#include "ParentClassInCaseOfInheiritance.h"
#include "InterfaceInCaseOfInheiritance.h"
#include "EngineDependency.h"
#include "PBDependency.h"
#include "PBClass.generated.hUse forward declaration as much as possible, instead of including new header files. This is to reduce compile times and linking when cpp classes include other header files but don't necessarily need to include all the class definitions that are in the header file.
.cpp files:
#include "PBClass.h"
#include "UnrealEngineClassA.h"
#include "ThirdPartyClassA.h"
#include "UnrealEngineClassB.h"
#include "ThirdPartyClassB.h"
#include "PBOtherClassA.h"
#include "PBOtherClassB.h"You can get AI assistance while you code to improve productivity and code quality! You can install IntelliCode from the Visual Studio Marketplace
We also recommend Resharper C++ or VisualAssistX.
- Right click on the
ProjectBorealis.uprojectfile in yourpbrepo folder. - Click Generate Visual Studio project files
- When launching the solution for the first time, you may be prompted to upgrade your SDK and compiler versions. Select latest installed Windows 10 SDK and compiler in your system.
- Select ProjectBorealis as the StartUp project:
You must regenerate the solution file every time the engine updates. You also may have to regenerate it if other programmers remove or create source files.
If you haven't already done so, you can set up VS extension for UE4 by following these guides if you wish:
https://docs.unrealengine.com/en-us/Programming/Development/VisualStudioSetup
https://docs.unrealengine.com/en-us/Programming/Development/VisualStudioSetup/UnrealVS
If you need to compile Linux binaries on Windows, you will have to set up cross compilation. That's not a requirement at the moment. https://docs.unrealengine.com/en-us/Platforms/Linux/GettingStarted
You can now change C++ in real time while the game is running. Just enable live coding and press Ctrl+Alt+F11 at any time, even when the game is running to recompile.
Live coding currently does not support code structure updates (header file additions/removals).
If you want to debug graphics, download RenderDoc, which our project has integrated support for: https://renderdoc.org/builds
To help with managing GitHub, you can use the GitHub CLI to run common GitHub tasks from the command line.
In our engine, Unreal Build Tool by default will not attempt to build missing or mismatched modules (window that says Would you like to rebuild them now? Yes/No). You can change this behavior by setting the following in Saved/Config/Windows/EditorPerProjectUserSettings.ini:
[/Script/UnrealEd.EditorLoadingSavingSettings]
bAlwaysSkipCompile=FalseThis will change the behavior to instead of failing automatically, build the modules without any prompting. If it fails, it will prompt you to try building in your IDE, or look at logs.