unreal-project-manager

Unreal Project Manager (UPM)

A lightweight Python module for managing Unreal projects across space, time, and platforms.

Who it's for:

Less-than-professional teams working with Git and VS Code.

How to get:

• UPM on PyPi:

  pip install unreal-project-manager
  

• UPM on GitHub:

  git clone https://github.com/crashtestbrandt/UnrealProjectManager
  

Features

• Platform-aware generation of VS Code tasks to cook, build, package, and launch your Unreal 5+ project without having to open the editor (or just use the UPM CLI).

• Projects can be cloned and set up for Windows, Mac, or Linux environments from a single config file with sane defaults.

• Central management of project/package versioning and patch notes.

• CLI commands for installing build dependencies and tools.

• UPM can self-copy itelf into existing repositories so there's no need to mess with submodules or forking.

Contents

• Prerequisites

• Quickstart

• UPM Config

• UPM Setup

• Usage

  • Build and Launch

  • Changelog

• Collaboration Guide

• Also Maybe Helpful

  • Installing Python

  • Installing Unreal

  • Starting an Unreal Project

Prerequisites

• Python 3.10+

• Unreal Engine 5+

Quickstart

• Download and install prerequisites.

• Install UPM:

  python3 -m pip install unreal-project-manager

• Use UPM to configure your project:

  python3 -m upm config --dir [project-path] --project-name [project-name]

• Use UPM to install build tools.

  • For Windows, install Visual Studio Community with python3 -m upm install-vs. This will prompt for privilege escalation.

  • For MacOS, install XCode with python3 -m upm install-xcode (STILL TESTING)

  Additionally, if you don't have VS Code installed, you can do:

  python3 -m upm install-vscode

• Navigate to your project directory and use UPM to perform project setup and generate project files:

  python3 -m upm setup

• With your new .code-workspace file open in VS Code, use Ctrl+Shift+B to open the build menu and build your project.

  To fully cook, build, and package a development version of your project, choose the Development Package option. This is required before launching the Development configuration for your game from the Run and Debug menu (Ctrl+Shift+D), as building and launching a Development target directly will result in shaders not being compiled.

  To work on your project in the editor, first select the Select-A-Build option from the build menu, selecting the Development and Editor options when prompted.

• Once your chosen target is built, navigate to the Run and Debug menu (Ctrl+Shift+D), select the target to launch from the dropdown menu, and click Start Debugging (green arrow). If this is your first time launching the Editor for your project, be prepared for it to hang a while as it compiles shaders.

UPM Config

Adds scripts and configuration files to your project you'll probably want to keep under source control for use by collaborators.

Generate Configuration Files

NOTE: Here we're using Epic's Lyra Starter Game sample as an example project.

• Install UPM:

  python3 -m pip install unreal-project-manager
  

• Use UPM to copy configuration files into your project directory:

  python3 -m upm config --dir ../LyraStarterGame
  

  This creates several items in your target directory:

  • config.upm: Contains UPM project configuration values upm setup uses to generate UPM project files and VS Code tasks.

  • Changelog.json: Used by upm changelog to centralize patch notes (initialized with version 0.0.0-Alpha; modify this as you see fit).

  • upm/: Directory containing UPM scripts used by generated VS Code tasks for build/cook/launch/package/deploy/change automation.

  • .gitignore: Default .gitignore file for use with Unreal 5+, C++, Python 3.10+, and UPM. Omit this argument if you already have a suitable .gitignore file in the target directory.

Configuration Options

If config.upm already exists in your project directory, UPM won't overwrite it. This allows you to keep a default config.upm under version control for your project. If you choose to do this but end up occasionally requiring a non-default config.upm, you can copy you custom config.upm into the .vscode directory of your project (which is ignored by the default .gitignore); upm setup will look here first for a config file.

To remove items created by upm config, do upm config --clean --dir your-project-dir/.

Do upm config -h to see options for modifying the default behavior of upm config, e.g. changing the default location of Unreal Engine or specifying a project name different from the project directory.

UPM Setup

Generates files required for project automation, including Python dependencies (installed to .venv by default), environment variables (.env by default), VS Code workspace configuration files, build/launch tasks, and Unreal project files. These are all excluded via the default .gitignore file added by upm config.

To set up your project with UPM:

• Ensure you've configured it using upm config as discussed in previous sections.

• Ensure build tools are installed for your platform, e.g. by doing python3 -m upm install-vs.

• Navigate to your project directory and do:

  python3 -m upm setup
  

The files and directories generated by upm setup are not intended to be placed under source control. When sharing your project for collaboration, you should include instructions for generating them with UPM.

You can remove UPM files generated by upm setup with upm setup --clean; this does not remove Unreal project files or the .code-workspace file.

Usage

Build and Launch

UPM adds several platform-specific tasks to .vscode/launch.json and .vscode/tasks.json, which are wrappers for the various upm build commands:

usage: upm build [-h] --project-dir PROJECT_DIR --build-type BUILD_TYPE --target-name TARGET_NAME [--clean] [--build] [--package]

options:
  -h, --help            show this help message and exit
  --project-dir PROJECT_DIR
                        Path to the project directory
  --build-type BUILD_TYPE
                        Type of build (debug, development, testing. release)
  --target-name TARGET_NAME
                        Name of target to build.
  --clean               Clean selected targets
  --build               Build selected targets
  --package             Package selected target for deployment

You can access the launch configurations from the Run and Debug menu (Ctrl+Shift+D) and the build tasks from the Build menu (Ctrl+Shift+B). You must build a target before launching it, i.e. use Select-A-Build from the Build menu before launching from the Run and Debug menu.

Changelog

Initialize Changelog / Increment Version

To create a changelog file (Changelog.json) with an initial version (0.0.1), you can either:

• Use the Build menu (Ctrl+Shift+B) to select Changelog: Add Version
• Use the UPM CLI: upm changelog --add-version

These same two commands can be used to increment the current version.

Add change

Add a change to the current version with either of the following:

• Use the Build menu (Ctrl+Shift+B) to select Changelog: Add Change and enter a change note when prompted.
• Use the UPM CLI: `upm changelog --add-version "Your change note."

Update DefaultGame.ini

Update the version in your project's DefaultGame.ini file with either:

• Use the Build menu (Ctrl+Shift+B) to select Changelog: Update INI File.
• Use the UPM CLI: upm changelog --update-ini

For all options, do upm changelog -h.

Collaboration Guide

Also Maybe Helpful

Installing Python

Windows

To initiate Python 3 installation on Windows, open Powershell and do:

python3

This opens the Microsoft Store and prompts you install Python 3.12.

Installing Unreal

Download and install the latest release of Unreal Engine 5.4 through the Epic Games Launcher.

Unreal Engine -> Library -> Engine Versions -> Add (+)

Launch Unreal Engine 5.4. Select Fix if prompted to correct file associations.

Starting an Unreal Project

...