Preparing the Unreal Project

2024-FEB-05 Author: Aximmetry

Introduction

This document will guide you through the necessary steps to open, create, and run an Unreal Project in Aximmetry DE. These steps include:

Unreal Editor for Aximmetry Compared to the Standard Unreal Editor

We recommend building your entire scene within the Unreal Editor for Aximmetry due to its additional functionalities tailored for integration with Aximmetry DE. These include features such as adding an Aximmetry camera, managing triggers, and incorporating videos.
Aximmetry DE accesses the Unreal scene specifically through an Aximmetry camera blueprint, which is exclusive to the Unreal Editor for Aximmetry.

NOTE: While it's possible to build your scene using the standard Unreal Editor (vanilla Unreal Engine) and finalize it in the Unreal Editor for Aximmetry, this approach offers no advantages compared to using the Unreal Editor for Aximmetry from the start.

Installing Aximmetry DE

The Aximmetry DE installer also includes the Unreal Engine for Aximmetry. Follow the How to Install Aximmetry document for detailed instructions.

IMPORTANT: The Unreal Editor's cooking process requires Visual Studio 2022 to be installed with additional workloads. Refer to the Install document's Aximmetry DE Prerequisites section for guidance on installing Visual Studio with the correct workloads.

Open or Create the Unreal Project

Opening Existing Project

Upon opening a project created in the standard Unreal Engine within Unreal Editor for Aximmetry, you'll be prompted with a conversion window. We recommend selecting the "Open a Copy" option in this window. Further details regarding this process can be found in the Convert Project Prompt section below.

Afterwards, open Unreal's Project Settings:

And modify the following Project Settings:

Startup Map:
Go to Project - Maps & Modes / Default Maps and assign both Editor Startup Map and Game Default Map to your map:

NOTE: If you rename or move the map asset, you must clear and select the startup maps again due to Unreal not updating the Project Settings correctly.
Player Pawn:
By default, the player pawn appears in the scene as a gray sphere:

This can be resolved in two ways:
- A) Set the player model to an invisible one:
  Navigate to Project - Maps & Modes / Default Maps. Create a new Default GameMode by pressing the + button (1). Open the Selected GameMode section (2). Change the Default Pawn Class to None (3):
- B) Move the Player Start outside of the scene.
  Consequently, the gray sphere should spawn in an area not visible to the camera.
Clip Plane:
Go to Engine - Rendering / Postprocessing and enable Support global clip plane for Planar Reflections:

NOTE: The absence of this setting will result in the malfunctioning of Green Cameras and AR Cameras.
Depth-Stencil:
Navigate to Engine - Rendering / Postprocessing and set Custom Depth-Stencil Pass to Enabled with Stencil:

NOTE: The absence of this setting will result in the malfunctioning of Green Cameras.

Creating Project

Alternatively, you may start a new Aximmetry Blank project under the Film/Video & Live Events section when starting Unreal Editor for Aximmetry:

This blank project comes with the correct Project Settings configured, eliminating the need to manually adjust the settings described above.

Example Projects

The Tutorial content package of Aximmetry includes sample Unreal projects. These can be found in the Unreal folder ([Tutorials]:Unreal). Although these projects have the correct Project Settings and Cameras pre-configured, they must be cooked before use.
They include the following compounds:

Basic ([Tutorials]:Unreal\Basic.xcomp): Demonstrates a minimal setup of a simple Unreal scene with a virtual camera and a single billboard controlled by Aximmetry.
Basic_Combined_Render ([Tutorials]:Unreal\Basic_Combined_Render.xcomp): Highlights how an Unreal-rendered scene can be combined with Aximmetry-rendered objects. For more details, visit Aximmetry and Unreal Combined Render.
Basic_Virtual_Screen ([Tutorials]:Unreal\Basic_Virtual_Screen.xcomp): Features a virtual screen within an Unreal scene.
Complex ([Tutorials]:Unreal\Complex.xcomp): Showcases more advanced aspects, such as transparent objects in front of the billboard, high-quality reflections, two billboards with distinct advanced settings, and the capability to control a light's position from within Aximmetry.

Add an Aximmetry Camera

To use your scene with Aximmetry's camera compounds, place an Aximmetry camera blueprint in the scene. This can be done through the Aximmetry item in the menu bar by selecting Add Camera.
Choose the desired camera blueprint to be added to your project:

You can find information about the difference between Green, LED wall, and AR cameras here: Introduction to Different Studios for Virtual Production

IMPORTANT: If you plan to use the AR camera (tracked) or + AR camera compounds, you must also set the Project Settings detailed in the AR documentation.

NOTE: If your project utilizes blueprint or shader logic that strictly depends on a specific camera in the scene (for instance, effects visibility determined by the camera's position), it might be necessary to modify this logic to accommodate the newly added Aximmetry camera.
NOTE: Do not move or rename the Camera's asset directory in the Unreal project.
NOTE: The position and orientation of the camera actor in the scene don't affect the output because it will be controlled by Aximmetry during runtime.
NOTE: If there is already an Aximmetry camera in the scene and you want to change it, just use the Add Camera menu again and the camera will be replaced with the newly selected one.
NOTE: New versions of the Unreal assets and the corresponding Aximmetry compounds are released regularly. When a new version is available, a notification will pop up in the lower right corner when you open the project, prompting you to update. Updating the camera assets is necessary to maintain compatibility with Aximmetry.

Cook the Project for Aximmetry

To utilize Aximmetry DE in Cooked mode, the Unreal scene must be cooked before importing it into Aximmetry DE.
Open the Aximmetry menu and select Cook Content for Aximmetry DE:

Cooking your Unreal project may vary in duration based on its complexity. The initial cooking process can be particularly lengthy as it involves compiling files and shaders of the .uproject file.

In Cooked mode, Aximmetry uses the cooked version of the project. This means that if you edit the scene in Unreal, you have to cook the project again. You can leave Aximmetry running with the Unreal Project module in Cooked mode - it will pick up the changes when cooking is finished and reload the project automatically.

An alternative to Cooked mode is Live Sync mode, which is comprehensively described in the document, Interactive Editing with Live Sync.

NOTE: If you experience crashes with Unreal, use the Cook Content for Aximmetry DE (Debug) to generate an error log. Also, you will have the option to generate a dump file on a crash, which you can share with Aximmetry for detailed troubleshooting. Otherwise, the project is cooked in an optimized configuration that does not allow dump creation but provides better performance.
NOTE: Disabling Iterative Cooking can fix various issues that only appear in Cooked mode. For example, if your changes in the Unreal Editor don't show up in Cooked mode, disabling this feature may help. However, this will also cause the project to take longer to cook.
NOTE: Having the Unreal Editor open consumes a considerable amount of computational resources. When you are operating an Unreal project in cooked mode, there is no necessity to keep the Unreal Editor open. Therefore, we strongly recommend closing the Unreal Editor during live productions to optimize resource allocation and ensure smoother operation.

Set Up the Project in Aximmetry

Open Aximmetry Composer and create a new Compound:

Drag in the .uproject file from your Unreal project root directory. This will create an Unreal Project module node:

NOTE: If the .uproject file was imported into Aximmetry before adding or changing the Aximmetry Camera in Unreal, you must refresh the pin list by clicking the chain button located in the upper right corner of the Unreal module. The chain button will only appear if the compound is active. To activate the compound, click on the play button found in the top menu bar:

Then, drag a Camera compound (.xcomp) from the folders at [Common_Studio]:Camera\ that matches the Camera blueprint that you added from the Add Camera menu.

The following Camera blueprints match with the following Camera compounds:

Green camera (virtual, 1-3 billboards):
- [Common_Studio]:Camera\VirtualCam_Unreal\VirtualCam_Unreal_3-Cam.xcomp
- [Common_Studio]:Camera\VirtualCam_Unreal\VirtualCam_Unreal_3-Cam_A-B-C.xcomp
- [Common_Studio]:Camera\VirtualCam_Unreal\VirtualCam_Unreal_8-Cam.xcomp
- [Common_Studio]:Camera\VirtualCam_Unreal\VirtualCam_Unreal_8-Cam_A-B-C.xcomp
Green camera (tracked, 1-3 billboards):
- [Common_Studio]:Camera\TrackedCam_Unreal\TrackedCam_Unreal_3-Cam.xcomp
- [Common_Studio]:Camera\TrackedCam_Unreal\TrackedCam_Unreal_8-Cam.xcomp
Green camera (virtual + tracked, 1-3 billboards):
- [Common_Studio]:Camera\MixedCam_Unreal\MixedCam_Unreal_3+3-Cam.xcomp
- [Common_Studio]:Camera\MixedCam_Unreal\MixedCam_Unreal_8+8-Cam.xcomp
Green + AR camera (tracked, 1-3 billboards):
- [Common_Studio]:Camera\TrackedCam_Unreal\TrackedCam+AR_Unreal_3-Cam.xcomp
- [Common_Studio]:Camera\TrackedCam_Unreal\TrackedCam+AR_Unreal_8-Cam.xcomp
LED wall camera (tracked, 1-4 walls):
- [Common_Studio]:Camera\LEDWallCam\LEDWallCam_3-Cam_4-Wall.xcomp
LED wall camera (tracked, 1-9 walls):
- [Common_Studio]:Camera\LEDWallCam\LEDWallCam_8-Cam_9-Wall.xcomp
LED wall + AR camera (tracked, 1-9 walls):
- [Common_Studio]:Camera\LEDWallCam\LEDWallCam+AR_3-Cam_4-Wall.xcomp
- [Common_Studio]:Camera\LEDWallCam\LEDWallCam+AR_8-Cam_9-Wall.xcomp
AR camera (tracked):
- [Common_Studio]:Camera\ArCam_Unreal\ARCam_Unreal_3-Cam.xcomp
- [Common_Studio]:Camera\ArCam_Unreal\ARCam_Unreal_4-Cam.xcomp

Connect the Camera compound to the Unreal module, ensuring that input and output pins with matching names are connected on both nodes.
For example, the Green camera (virtual, 1-3 billboards) connected with the [Common_Studio]:Camera\VirtualCam_Unreal\VirtualCam_Unreal_3-Cam.xcomp compound:

NOTE: To easily connect all the output pins of the Camera compound with a single click, first, select both the Camera compound and the Unreal module by holding down the CTRL key and clicking the left mouse button. Then, right-click on the Camera compound and choose the Connect All Identical Pins option from the context menu.

Additionally, expose the camera compound's Preview and Out pins as shown in the above image. Subsequently, the rendered camera images will be visible in Aximmetry's preview panels.
The camera is placed at the origin by default, potentially causing an intersection with the scene's geometry. To address this for a Green Camera (virtual), make a Virtual Camera Movement setup. For other camera types, configure the Tracking Device in the Inputs.

To delve deeper into Unreal-related setups for specific production types, continue with one of the following documents:

Alternatively, continue with the general Unreal documentation on the Interactive Editing with Live Sync page.

Convert Project Prompt

Please note that Aximmetry DE only works with the corresponding version of Unreal Editor for Aximmetry.
New releases of Unreal Engine are documented in the Software Version History.

Attempting to open an Unreal project created in an earlier version of Unreal Engine with a newer version will trigger a Convert Project window.

Once a project is converted, the process is irreversible — the project cannot be reverted to be compatible with previous versions of the Unreal Engine. Therefore, we strongly advise creating a complete copy of the original project before proceeding.
This should leave you with two versions of your project:

a backup file archived that you can return to later if needed.
a work file that you continue to work with and modify.

While several options are available, we suggest using one of these two methods:

Convert in-place
Independently create a backup file of your project for safety.
Open your work file in Unreal Engine. Once the Convert Project window appears, choose More Options...:

Then select Convert in-place to convert your .uproject file:
Open a copy
Selecting the Open a copy option will create a duplicate of the project in a nearby folder, appending the version number to the project folder’s name, thereby preserving the original version.

We strongly recommend creating this duplicate and then securing it within a secure archive for protection.

Search

Preparing the Unreal Project

Introduction

Unreal Editor for Aximmetry Compared to the Standard Unreal Editor

Installing Aximmetry DE