How Version Forge Works
How Version Forge sources and uses version details.
Every version string is built from values and settings that come from your project settings, the build process, and a format template you configure.
Where each value is pulled from
| Value | Source |
|---|---|
| Major Minor Project Patch | The first three segments of your project's Project Version settings. |
| Patch | Resolved from the Patch Source setting, either Project Patch, Build Number, or Changelist. |
| Build Number | Your CI system, an environment variable, or a command-line argument. |
| Changelist | Your CI system, source control, an environment variable, or a command line argument. |
| Platform | The platform the game is built for, such as Windows or IOS. |
| Configuration | The build configuration, such as Development or Shipping. |
| Build Date | The UTC time when the game was built, an environment variable, or a command line argument. |
| Pre-release Tag | The Pre Release Tag setting. |
Project Version lives in Project Settings → Project → Description. Enter it as three numbers, such as 1.5.7. The version file and platform sync read it from your project's config at build time.
When values are captured
The build number, changelist, build date, and network version are all captured when your project builds. They are embedded in the packaged build and cannot change at runtime. See Capturing build details for options.
Local builds
Version Forge assumes that any build with a Build Number set to 0 is not being built by CI and is considered to be a local build, such as an engineer compiling during everyday work or a local test package.
When this is the case, Version Forge will:
- Use midnight UTC of the current date as the Build Date to avoid unnecessary recompilation.
- Skip generating a version file artifact in your local workspace.
- Skip iOS and Android sync so as not to modify ini files in your local workspace.
If you don't use a CI system for packaging and want Version Forge to use it's standard build flow, pass a build number with -BuildNumberOverride= or set an environment variable from your build scripts.
Editor builds
Editor builds will also be treated as local builds and follow the same rules as above. When in the editor or during PIE the real currently known version data will be displayed, with these differences:
- The Build Date will be midnight UTC of the current date.
- The Build Number will be
0. - The Configuration will show as 'Editor'.
- The Network Version will be Unreal's default unless you enable Apply in Editor. See Network version.
Distributed builds
If your compile and packaging steps run on different BuildGraph agents, Version Forge's generated files will not be moved between them automatically:
- The build values file:
VersionForgeBuild.ini - The version file, if enabled:
version.{config}.txt
They are written during the compile step but are not automatically tagged by the Compile node with the binary artifacts. Add the Tag and TagReceipt lines below to your compile node so that they get tagged:
<Node Name="Compile Game" Produces="#MyCompileTag">
<Compile Target="MyGame" Project="$(ProjectPath)" Platform="Win64" Configuration="Development" Tag="#MyCompileTag"/>
<Tag Files="#MyCompileTag" Filter="*.target" With="#VersionForgeReceipts"/>
<TagReceipt Files="#VersionForgeReceipts" RuntimeDependencies="true" With="#MyCompileTag"/>
</Node>
<Node Name="Package Game" Requires="#MyCompileTag">
...
</Node>Replace #MyCompileTag with whatever your Compile node already uses.
Important: If these files are not tagged, a clean packaging agent will fail with Failed to copy ... VersionForgeBuild.ini, or a stale file left over from a previous build could be packaged instead.