Avatar Customization#

The Unreal renderer microservice supports various types of avatar scenes.

How to bring your MetaHuman to the ACE pipeline#

The goal of this process is to integrate your own custom MetaHuman into the ACE pipeline.

Warning

We only support Windows.

You need to do all the following steps on a Windows machine and then cross compile for Linux.

We are working on Linux support, but currently it is not possible to download a MetaHuman on Linux.

Step by step#

  1. Download Unreal Engine 5.3.2

  2. Set up Visual Studio

  3. Create a new blank project.

    In the Unreal Project Browser, go to 'Games', select 'Blank', set a project location and name. Then click 'Create'.

  4. Next, access Quixel Bridge.

    Click on the icon showing a white cube with a green plus. From the dropdown select 'Quixel Bridge'.

Note

If you don’t see this you may be on Linux where the plugin currently isn’t available, or you need to activate it in the Plugins.

Note

You might get asked by Windows Security, that Quixel is trying to be accessed. Click on “Allow” to be able to download MetaHumans.

  1. In Quixel Bridge, go to the tab for MetaHumans. and download the one you’d like to use. For this you will need to be logged in to your Epic Games account. Any custom MetaHumans you have created using MetaHuman Creator (metahuman.unrealengine.com) will be listed here as well, given they were created with the same account. Once downloaded you can add the MetaHuman to your project by clicking the “Add” button.

    Select the desired MetaHuman from the grid.

    Select MetaHuman and click ‘Download’.

    ../../_images/unreal_download-metahuman.png

    After download click ‘Add’.

  2. There will now be a “MetaHumans” folder in your Content Browser.

  3. In that same directory right click and create a new “Blueprint Class”.

    ../../_images/unreal_blueprint.png

  4. Select “Actor”.

    ../../_images/unreal_actor.png

  5. Name this new asset “BP_Avatar”

    ../../_images/unreal_bp-avatar-file.png

  6. Open BP_Avatar.

  7. With that window open, in the Content browser open the directory with the name of your MetaHuman. In my example “Bernice”. In there you will find one Blueprint asset. Drag and drop that asset into BP_Avatar’s Viewport. This can freeze the Editor for a while as the asset is loading.

    ../../_images/unreal_drag-and-drop.gif

  8. If you get these pop ups about missing dependencies, enable them by clicking “Enable Missing”. At that point you may be prompted to restart the Editor. Do so.

    ../../_images/unreal_messages.png

  9. Hit “Compile” and then the Save icon.

    ../../_images/unreal_bp-avatar-compile.png

  10. Close the editor and download the ‘ACE_Template_Scene’ using the NGC CLI. Do not open this project yet - It relies on a MetaHuman asset and won’t work without it.

ngc registry resource download-version "nvidia/ace/ia-unreal-engine-project-template:0.1.0"

Note

Windows has issues with paths longer than 260 characters. Therefore, make sure your paths are short. Maybe rename and move the template project folder to C:\\UnrealProjects\\ACE_Template_Scene.

  1. Find the file location of the project you created previously. From inside the subfolder “Content” copy the folder “MetaHumans” and paste it to the “Content” folder of the ACE_Template_Scene project.

    ../../_images/unreal_metahuman-folder.png ../../_images/unreal_metahuman-folder_paste.png

  2. For the project to run, you’ll first need to install 3 special plugins. Using the NGC CLI download these resources:

    ngc registry resource download-version "nvidia/ace/ace-unreal-renderer-plugin:2.2.0"

    Then place this plugin in a folder named “Marketplace” in the installation folder of the Unreal Engine (e.g. C:\Program Files\Epic Games\UE_5.3\Engine\Plugins\Marketplace). If the folder doesn’t exist, create it.

    ngc registry resource download-version "nvidia/ace/ace-unreal-renderer-http-api-plugin:0.1.0"

    ngc registry resource download-version "nvidia/ace/ace-unreal-renderer-stream-helper-plugin:0.1.0"

    Then place these plugins in a folder named “Marketplace” in the ACE_Template_Scene project (e.g. C:\UnrealProjects\ACE_Template_Scene\Plugins\Marketplace). If the folder doesn’t exist, create it.

  3. Now you can open the “ACE_Template_Scene”, and when you press play, you should see your metahuman. It’s possible they won’t be framed nicely by the camera. This is because MetaHumans differ in height. To adjust the camera or the environment, see the next chapter.

  4. When you open the project for the first time, you might get asked to rebuild the plugins. Just click “Yes”.

    ../../_images/unreal_project-rebuild-plugins.png

How to customize the camera and environment in the MetaHuman scene#

If you’d like to customize the background, lighting and camera of your MetaHuman scene, this is how:

  1. Open the ACE_Template_Scene

  2. Inside the folder “Scene” there’s a Level named “Environment”

    ../../_images/unreal_environment-asset.png

  3. Open Environment and design it to your liking. In the final result the MetaHuman will be placed in the center of the scene facing the positive Y direction. You may want to place something there as a reference, but remember to remove it before saving the scene.

  4. To customize the camera, open BP_DefaultCamera. In there you’ll see a “Cine Camera”. This defines where the camera will be in your environment. You may adjust it to your liking.

    ../../_images/unreal_cine-camera.png

How to adjust quality / scalability settings#

In the top right corner under “Settings” are the “Engine Scalability Settings”. These are the different render qualities available (To customize them, please consult the Epic documentation Scalability Reference)

../../_images/unreal_scalability.png

By default Unreal will use the ‘Epic’ setting and scale down based on your hardware. But you may want to set a specific scalability instead. The template scene includes a debug blueprint that allows you to adjust the settings on runtime using the number keys. This blueprint can easily be adapted to set a specific setting on startup.

  1. Open the blueprint named ‘BP_ScalabilityDebugControlls’ located in the ‘Core’ folder.

  2. Delete the number key nodes on the left. Then Connect the ‘Event BeginPlay’ Node to the scalability setting you want to set as the default. (SCALABILITY 0 = Low, SCALABILITY 1 = Medium, SCALABILITY 2 = High, SCALABILITY 3 = Epic)

    ../../_images/unreal_default_scalability.gif

    Note

    You should probably not use the “Low” setting with MetaHumans as their hair will no longer be rendered.

  3. Compile and save the blueprint.

How to package and upload the project#

  1. You can now package the project for Linux. Under “Platforms” select “Linux” and then “Package Project”. If you don’t have Linux listed there are two ways of making this work:

    1. Set up Windows for Cross Compiling: Development Requirements

    2. Save the project, reopen it on a Linux machine and package it from there.

    ../../_images/unreal_package-project.png

Note

If you run into a build error like Error: HttpListener unable to bind to 127.0.0.1:8021, close the editor and build the project from the command line.

"C:\Program Files\Epic Games\UE_5.3\Engine\Build\BatchFiles\RunUAT.bat" BuildCookRun -clientconfig=Development -serverconfig=Development -project=C:\UnrealProjects\ACE_Template_Scene\ACE_Template_Scene.uproject -utf8output -nodebuginfo -allmaps -noP4 -cook -build -stage -prereqs -pak -archive -archivedirectory=C:\UnrealProjects\ACE_Template_Scene\dist -platform=Linux

  1. Packaging can take a long time. The result will be a folder named “Linux” in your chosen location. Once complete, upload the contents of that folder to NGC by following the Uploading a Version to the NGC Resource section.

  2. Usually, you now also want to update the links to your new resource in an UCS application that uses the Unreal Renderer microservice. The parameters under remoteResourcePath need to be updated to point to the new resource. You can also find more information about individual parameters in the Microservice Parameters section.

...
avatar-renderer:
  resourceDownload:
    remoteResourcePath:
      unrealEngineProject: "<ORG>/<TEAM>/<RESOURCE_NAME>:<RESOURCE_VERSION>" # e.g. "your-org/your-team/ia-unreal-renderer-asset-metahuman-example:0.1.0"
    secretName: ngc-api-key-secret
    image: nvcr.io/nvidia/ace/ngc-resource-downloader:1.1.4
...
On this page