/UE4Packager

Python scripts to quickly and easily build / cook / package UE4 games

Primary LanguagePythonMIT LicenseMIT

UE4 Packager

Python scripts to ( Build / Cook / Package / Archive / Patch ) Unreal Engine Projects

This is my very first program written in Python, so please be indulgent :)

And do not hesitate to propose pull requests to fix or improve stuff!

Usage

Call packager.py with the following mandatory positional arguments:

  • "Actions" can either be a concatenation of the following values [ "Build", "Cook", "Archive" ], separated with a '+'.

    It can instead be one of those values [ "Patch", "DLC", "Release" ]. When selecting one of those values, the packager will always Build, Cook and Archive the project. Some additional arguments may be needed to have those actions run successfully.

    A last possible value is "BuildEditor", which will build the editor DLLs of the game, and is useful to do before actually building or packaging the game.

  • "Platform" which must belong to the list [ "Win64", "XboxOne", "PS4", "Switch" ]

  • "Configuration" which must be an item of [ "Development", "Debug", "Shipping" ]

Another mandatory argument is the -c argument, which allows you to define an ini file where the script will pick some values which are "fixed" (like the path to the UE4 folder).

The full list of the accepted parameters can be found by calling the script with the -h flag.

The script does some sanity checks on the arguments you give to it to make sure everything is correct before calling RunUAT, and will exit prematurely with an error message so you can fix your command line. (For example, you must provide a version number when building a shipping package, or you must define against which release number you want to create a patch)

Some options worth noting:

  • --backup_version : if set, the packager will use a host application to copy the output located in the archive directory to a backup location of your choice (defined by the argument --backup_directory_root). If Release was chosen as an action, the Releases folder at the root of the project will also be backuped.
  • --stub : if set, the packager won't run any action, but will output in the console the processes it should use, with the arguments. This is useful to check if everything is allright before running the packager for real.
  • --build_option : if set, you define an option which can affect the packaging process globally. It can be used to select a particular in regions, add specific C++ defines, or call custom functions (see below). Please note that if you set this function, the archive directory will be updated from archive_directory_root\configuration\version_number to archive_directory_root\configuration\version_number\build_option.

As a convenience, you will find some batch files in the samples folder which will call package.py with predefined options to quickly use the packager.

Configuration override

You can use the [CONFIG_OVERRIDES] section of the ini file to conditionally override the arguments passed to the packager.

The packager will try to find options in the [CONFIG_OVERRIDES] which match a specific convention:

  • {build_option}_ARGUMENT_NAME
  • {platform}_ARGUMENT_NAME
  • {configuration}_ARGUMENT_NAME
  • {build_option}{platform}_ARGUMENT_NAME
  • {build_option}{configuration}_ARGUMENT_NAME
  • {platform}{configuration}_ARGUMENT_NAME
  • {build_option}{platform}{configuration}_ARGUMENT_NAME

For example, provided you give Demo to --build_option, you could override the version_number argument like that:

[CONFIG_OVERRIDES]
Demo_version_number = Demo

Or you could define on which devices you want your game to be deployed per-platform:

[CONFIG_OVERRIDES]
PS4_deploy_device = PS4@192.168.0.1

Note that this step is executed first in the pipeline. This means that the final value of the arguments will be used in the next steps.

Defines

You can use the [DEFINES] section of the ini file to add C++ preprocessor defines to the build. This is something we found useful when building our demos because this allowed us to add the DEMO_BUILD=True define.

The packager will try to find options in the [DEFINES] section, which match a specific convention:

  • Defines_{build_option}
  • Defines_{platform}
  • Defines_{configuration}
  • Defines_{build_option}{platform}
  • Defines_{build_option}{configuration}
  • Defines_{platform}{configuration}
  • Defines_{build_option}{platform}{configuration}

For example, provided you give Demo to --build_option, you could have:

[DEFINES]
Defines_Demo = [ "DEMO_BUILD=True" ]
Defines_Demo_Switch = [ "DEMO_BUILD_SWITCH=True" ]

Please note that the options must define a list of strings to work properly.

Regions

Consoles often require an additional parameter passed to RunUAT : -titleid, which is the identifier of your game in their store.

Since those ids are a bit cryptic to use, and are attached to a region of the world where the game is released, it's more convenient to use a --region flag to build the correct package.

You can use the config.ini file to define for each platform the regions you want to build your package for, and to specify the title id for each of those regions.

The packager script checks the ini file and will raise an exception if it can not find the region for the platform, or the title id for the region.

You can take as an example the config.ini file in this repository, which defines this REGIONS section:

[REGIONS]
PS4Regions = [ "Europe", "Japan" ]
PS4DefaultRegion = Europe
PS4Region_Europe = TitleId_Europe
PS4Region_Japan = TitleId_Japan

That config file defines the default region and 2 useable regions for the PS4 : Europe and Japan, and the title id for each region.

Right now, when given a --region parameter, the packager will copy the contents of the path Project\Config\Platform\TitleId inside Project\Config\Platform\ as a step prior to calling RunUAT, and copy the contents of the path Project\Config\Platform\DefaultTitleId (defined by the DefaultRegion of the ini file) as a post step.

This is useful as you can create specific configuration of the ini files used by the engine for each region.

Some platforms also have an additional pre-step (and a post-step which restores the state of the files):

  • the PS4 platform will copy the contents of Project\Build\PS4\sce_sys\TitleId in Project\Build\PS4\sce_sys\.
  • The Switch platform will copy the contents of Project\Build\Switch\Resources\TitleId in Project\Build\Switch\Resources\.

Please note that using the --region flag will make RunUAT archive your project in a sub directory whose name is the titleid of the selected region.

You can also define a specific title id based on the build_option parameter. The name resolution is the same as the Defines section above.

This is useful if for example, you need a different title id for a demo, you would need to pass Demo as the build_option:

SwitchRegion_Europe = Switch_TitleId_Europe
SwitchRegion_Demo_Europe = Switch_Demo_TitleId_Europe

Custom functions

Custom functions are a great way to extend the packager to your needs.

You can put python scripts in a folder (you need to pass as an argument with --custom_folder), to have custom functions called, depending on the selected build_option, platform, configuration.

The packager will automatically import any python file from that folder, and call any Custom_XXX_Initialize, Custom_XXX_PreExecute and Custom_XXX_PostExecute function inside.

Custom_XXX_Initialize is called right after the command line arguments and the config files are parsed, and is a great place to update the values which will be used by the packager. One useful thing we do for example is to change the version_number argument when the build_option is set to Demo. This allows us to archive the project in a dedicated directory.

Custom_XXX_(Pre|Post)Execute are called right after the calls to Platform.(Pre|Post)Execute and are a good opportunity to copy files around for example.

The naming convention follows what you can do for the defines above:

  • Custom_{build_option}_(Pre|Post)Execute( args, path_resolver )
  • Custom_{platform}_(Pre|Post)Execute( args, path_resolver )
  • Custom_{configuration}_(Pre|Post)Execute( args, path_resolver )
  • Custom_{build_option}{platform}_(Pre|Post)Execute( args, path_resolver )
  • Custom_{build_option}{configuration}_(Pre|Post)Execute( args, path_resolver )
  • Custom_{platform}{configuration}_(Pre|Post)Execute( args, path_resolver )
  • Custom_{build_option}{platform}{configuration}_(Pre|Post)Execute( args, path_resolver )

You can have a look at the file custom/demo_switch.py for a working example.

Here is an example of the arguments to pass if you have your config.ini in the parent folder of the packager scripts folder, and a folder named PackagerCustomScripts as a sibling of the packager scripts:

py.exe .\UE4Packager\packager.py Build+Cook+Archive Switch Shipping -c config.ini --backup_version --custom_folder PackagerCustomScripts --build_option Demo

Additional notes

Some few things to note, and which do not fit the above sections:

  • The packager has only been successfully used on a Windows Host. There exist a Linux and OSX abstraction in the host.py file, but was never used. I'll happily accept pull requests to fix any errors :)