UEPyScripts 1.2.1

Collection of Python tools and helpers designed to automate common Unreal Engine project tasks (builds, packaging, editor control, CI tasks, etc.).

UEPyScripts

---

Overview ✅

UEPyScripts is a collection of Python tools and PowerShell helpers designed to automate common Unreal Engine project tasks (builds, packaging, editor control, CI tasks, etc.).

---

Table of Contents 📚

• Features
• Requirements
• Installation
• Quick Start
• Usage Examples
• Continuous Integration
• Engine Installation
• Development & Testing
• Contribution Guide
• Support & Troubleshooting
• License & Credits

---

Features ✨

• Multiple helper scripts:
  • Engine Utilities
    • ue-run-buildgraph
    • ue-close-editor
    • ue-compile-editor
    • ue-run-editor
    • ue-check-engine-installation
  • Continuous Integration helpers:
    • ue-ci-cleanup
    • ue-ci-run-buildgraph

---

Requirements ⚙️

• Python 3.10 or newer
• Windows (primary target; other platforms may work)
• Unreal Engine (project-specific; config in Config/)

---

Installation 🛠️

Clone into your UE project:

• You can download the sources and put them directly in your project

• Or add as a submodule:

  git submodule add [e-mail]:TheEmidee/UEPyScripts Scripts/PyScripts

Quick Start 🚀

Bootstrap the project:

• Execute the script Bootstrap.ps1 in the folder Tools. This script will create:
  • Setup.ps1 at the root of the project.
  • Config.ini in Config/PyScripts
  • CompileAndRunEditor.ps1 also at the root
  • BuildgraphTask.ps1 in the folder Scripts/Project
• Execute Setup.ps1 to:
  1. check if python is installed, and install it if not
  2. create the python virtual environment
  3. call the script ue-check-engine-installation
• Execute CompileAndRunEditor.ps1 to compile your C++ code and run the editor when done !
• If you use buildgraph in your project:
  1. Uncomment the buildgraph properties in Config/PyScripts/config.ini and adapt to your project
  2. Duplicate the script BuildgraphTask.ps1 and adapt it to run your own targets.

Usage Examples 🔧

• Execute a buildgraph target

  ue-run-buildgraph.exe --target "Buildgraph Task Name" -set:Clean=True -set:Targets=MyGameClient+MyGameServer -set:TargetConfigurations=Development+Shipping
  

• You can directly call UAT or UBT:

    ue-run-uat.exe turnkey
  

• You can generate the visual studio solution:

    ue-generate-solution.exe
  

• You can update your engine locally if it can't be found for your projectn (See below for more explanations):

  ue-check-engine-installation.exe
  

Continuous Integration ⚙️

This repository contains several modules that you can call from a continuous integration pipeline. We use Jenkins here but this should work for other tools.

All those modules are very opinionated and work with specific rules. This may lack a bit of flexibility, but this is the result of years of iterations, and it works for us.

Ideally you should be using https://github.com/TheEmidee/JenkinsFileGenerator to generate jenkinsfiles that would use the following modules.

• uepyscripts.tools.ci.buildgraph : This executes a buildgraph task. This module will call the internal uepyscripts.run.buildgraph but will inject all arguments that are required to execute a single node, using a shared storage folder to store the artifacts of the task. This basically allows to execute buildgraph tasks in parallel. A typical usage of this module in a jenkins pipeline script would look like:

  pwsh """
      ."Scripts/PyScripts/.venv/Scripts/ue-ci-run-buildgraph.exe" `
        --target="${taskName}" `
        --build_tag = "${BUILD_TAG}"
        -set:Clean=True
        -set:Targets=MyGameClient+MyGameServer
        -set:TargetConfigurations=Development+Shipping
   """
  

  You will have to uncomment or add the entry BuildgraphSharedStoragePath in your config.ini file in Config/PyScripts:

   [Jenkins]
   ; Path to the shared storage directory
   BuildgraphSharedStoragePath = \\nas\cache\UE-BuildGraph
  

• uepyscripts.tools.ci.cleanup : This should be used when your pipeline ends, if you use uepyscripts.tools.ci.buildgraph. This will delete all the files that could have been created as part of the pipeline, in the shared storage folder.

   stage( 'Cleanup' ) {
      pwsh """
      ."Scripts/PyScripts/.venv/Scripts/ue-ci-cleanup.exe" --build_tag="${BUILD_TAG}"
      """
   }
  

Engine installation 🛠️

You can use the module uepyscripts.tools.ue.check_engine_installation to automatically install the engine version that your project requires.

The requirements for this to work are as follow:

• For now, it is not possible to install automatically engine versions from the Epic Games Launcher as it seems not possible to give arguments to EGS to do so
• You must use an installed build engine that you build from the engine sources from Perforce or Github
• The installed build engine must be zipped into a 7z archive (No sub-folders, the Engine folder must be at the the root of the archive)
• The archive name must match the EngineAssociation property of the uproject file. You can add additional version numbers at the end of the archive name. (For example if the EngineAssociation property is UE-MyProject-5.2, you can name your archive UE-MyProject-5.2.7z, or UE-MyProject-5.2.1.297.7z if you want to keep multiple versions of the engine)
• You must place your archives either on a shared local folder, or in an amazon S3 bucket (The engine archives must be placed in a folder named Engine at the root of the bucket)
• You must have installed 7-zip on your machine, and it must be accesible from the PATH

How the script works:

• It will try to resolve the project and the engine the project needs. If this succeeds, nothing has to be done, since the project can be open
• If the engine resolution fails, then an update is executed:
• Try to determine the folder where the engine must be installed by reading the environment variable NODE_UE_ROOT. If this environment variable exists and points to a valid folder, then this is used. Otherwise the script will prompt the user for a destination. (The environment variable is useful on build machines to allow unattended installations as part of the build pipeline)
• Choose a source for where to get the engine archives: You can configure which sources to use by updating the property [EngineUpdate.Sources].Sources in the config.ini. You can use Local, AWS, or both with Local+AWS.
  • You can define where the Local source can fetch the archives by setting the property [EngineUpdate.Source.Local].LocalFolder.
  • You can define the amazon S3 properties AWS_SecretKey, AWS_AccessKey, AWS_BucketName and AWS_Region under the category EngineUpdate.Source.AWS. Please note that the script will look for the engine archives in the folder Engine of the bucket.
  • The script will try each source one at a time, and select the first source that it can reach, and that has an engine archive which has a valid name
• Create the destination folder if it does not exist, using the EngineAssociation property (So if the destination folder is C:/UE and the EngineAssociation is UE-MyProject-5.2, you will have a folder C:/UE/UE-MyProject-5.2)
• Copy the engine archive from the source to the destination folder
• Decompress the engine archive in-place in the destination folder (You would now have the folder C:/UE/UE-MyProject-5.2/Engine)
• Delete the engine archive
• Register the engine in the windows registry by creating a key named UE-MyProject-5.2 at HKCU\SOFTWARE\Epic Games\Unreal Engine\Builds with the value C:/UE/UE-MyProject-5.2/Engine
• Update the SDKs you need to build the platforms of the project with turnkey. For this, you will have to list all the platforms in the config file by setting the property [EngineUpdate.TurnKey] with all the platform names, separated by +. Ex: Platforms = Win64+PS5+Switch. This will run the command turnkey -command=VerifySdk -platform=PLATFORM -UpdateIfNeeded -unattended for each platform.

Development & Testing 🧪

• Setup dev environment and install dependencies:

  .\setup_venv.ps1
  .\.venv\Scripts\Activate.ps1
  pip install -r requirements.txt
  

• Linting & formatting

  • Use black and ruff (or your chosen formatters/linters). Add checks to CI as required.

---

Contribution Guide 🤝

We welcome contributions — please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-change
3. Run lint locally
4. Submit a pull request describing the change

---

Support & Troubleshooting ❓

• Check Config/ and uepyscripts/internal/config.py for project-specific settings.
• If buildgraph fails, ensure Config/Project has a valid BuildgraphPath and the UAT tool is accessible.
• When reporting issues, include:
  • Python version
  • Unreal Engine version
  • Exact command and full logs

---

License & Credits 📝

License: MIT — see the LICENSE file.

Maintainers: Michael Delva and contributors (see AUTHORS or repository metadata).

Changelog: See CHANGELOG.md

---

Made with ❤️ for Unreal Engine developers — contributions and feedback are welcome! If this helped you, consider starring the repository. ⭐