md.Nuke.Unreal 1.0.3

Nuke.Unreal

Simplistic workflow for automating Unreal Engine project steps embracing Nuke.

Nuke + Unreal Engine workflow provides a consistent way to work with UE4/5 tools reducing the chore it comes with

Usage

For now, no Nuget release available but planned when it hits 1.0. When Nuget package will be available it'll be available as a simple package reference in your Nuke build project. If you still want to use this workflow you can install from script or go manually:

1. Set up the build project:

   • Via a script:

     iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/microdee/Nuke.Unreal.WorkflowTemplate/main/Setup.ps1'))
     

   • <details> <summary>Manually</summary>

     > dotnet tool install Nuke.GlobalTool --global
     
     > dotnet new sln --name Build
     
     > nuke :setup
     # preferably put your build project inside Nuke.Targets folder
     
     > git submodule add https://github.com/microdee/Nuke.Unreal.git Nuke.Unreal
     
     > dotnet sln .\Build.sln add .\Nuke.Unreal\src\Nuke.Unreal\Nuke.Unreal.csproj
     > dotnet add .\Nuke.Targets\_build.csproj reference .\Nuke.Unreal\src\Nuke.Unreal\Nuke.Unreal.csproj
     

     </details>

2. Inherit your Build class from either PluginTargets, ProgramTargets or ProjectTargets
3. Override abstract members, add own targets, set up dependencies
4. (optional) Set the path to your UE project if it's not trivially around your Nuke targets:

public override AbsolutePath ToProject => RootDirectory / ".." / "MyProject" / "MyProject.uproject";

• This is only necessary if
  • project file is not recursively inside one of the subfolders compared to the path of the .nuke folder
  • project file is not in one of the parent folders of the .nuke folder
  • there are multiple .uproject files so one needs to be specified. Nuke.Unreal targets support only one Unreal project.

5. (optional) Set the path to your target plugin if there are more in your test project, or if it's not trivially around your Nuke targets:

public override AbsolutePath ToPlugin => UnrealPluginsFolder / "MyPlugin" / "MyPlugin.uplugin";

• This is only necessary if
  • there are multiple plugins in the test project so one needs to be specified. Nuke.Unreal targets support only one Unreal plugin to be worked on.

Features:

• All what the great Nuke can offer
• Common UE4 build tasks (generate project files, build editor, cook, package, etc)

  > nuke generate
  > nuke build-editor
  > nuke build --config Shipping
  > nuke build --config DebugGame Development --run-in Editor
  > nuke cook
  > nuke package
  

• Prepare plugins for release in Marketplace

  > nuke make-release --for-marketplace
  

• Bind Unreal tools to Nuke with fluent C# API [very WIP]
• Generate boilerplate code and scaffolding from Scriban templates so no editor needs to be opened

  > nuke new-actor --name MyActor
  > nuke new-plugin --name MyPlugin
  > nuke new-module --name MyModule
  etc...
  

Custom UBT or UAT arguments

Nuke.Unreal supports passing custom arguments to UBT or UAT via --ubt-args or --uat-args. These are regular array properties exposed as Nuke target parameters. This means however that doing --ubt-args -DisableUnity wouldn't actually add -DisableUnity to the argument list. This happens because Nuke stops parsing the array argument when it hits a - character. For this reason Nuke.Unreal has a special escape mechanism where ~- is replaced with -, or if the argument starts with ~ then that's also replaced with a -.

So doing --ubt-args ~DisableUnity ~2022 will correctly pass arguments -DisableUnity -2022 to UBT.

For convenience the sequence '' is also replaced with a double quote " hopefully escaping command line parsers.

This is especially useful for doing temporary debugging with UBT and the compiler: (not an actual usecase)

> nuke build ... --ubt-args "~CompilerArguments=''/diagnostics:caret /P /C''" ~DisableUnity
> nuke build ... --ubt-args "~LinkerArguments=''/VERBOSE''"
> nuke build ... --ubt-args ~Preprocess

Generators

Unreal boilerplate templates

Nuke.Unreal provides some targets which creates boilerplate code for common Unreal entities, such as

• Plugins
• Modules
• Unreal Object/Actor/Structs/Interfaces
• Slate widgets

without the need for opening the UE4 editor or extend heavy weight IDE's. These boilerplate targets work with Scriban templates. The path to these templates can be overridden in the actual Nuke build class in case a project requires further boilerplate. Example:

In any folder in your project

> nuke NewActor --name MyPreciousActor

This will generate MyPreciousActor.h and ~.cpp at their respective places (taking public and private folders into account) and the minimal actor class boilerplate for unreal.

Optional Custom templates folders are required to contain generator specific subfolders. If a subfolder doesn't exist for a generator the default will be used. Example:

Scaffolding:

• RootDirectory
  • Nuke.Targets
    • ...
    • Build.cs
  • ...
  • MyTemplates
    • Actor
    • Object

In Nuke.Targets/Build.cs override TemplatesPath property

public override AbsolutePath TemplatesPath { get; set; } = RootDirectory / "MyTemplates";

This way Actor and Object generators will have their project specific Scriban templates but the remaining generator types will use the default templates of Nuke.Unreal.

Generators for Unreal Tools [WIP]

Nuke.Unreal can generate type-safe fluent API for UE tooling with similar mindset as Nuke tools using direct reflection data from Unreal tools written for .NET. The Tool Generators project directly reference those programs as .NET assemblies. It's only done like this in the generator, and not actually inside the build project because the assemblies are referred with an absolute path, but the location of Unreal is a dynamic data during runtime ("build-time" if you prefer). So there's no extra ceremony for the user during setting up their build environment with Nuke.Unreal. As an added extra this way we can still somewhat treat these tools as executable black-boxes during runtime/build-time, so we don't run into any problems regarding different .NET environment requirements.

On the other hand Contributors to Nuke.Unreal need to modify LocalUnrealAssemblies.targets in order to explicitly point to their own location of their unreal installation depending on their development platform. Again this is only necessary for generating the fluent tool API, but not for running the actual Nuke.Unreal targets.