Nativizing Blueprints

When teams script gameplay with Blueprints, they're creating new UClasses without having to write or compile native C++ (CPP) code. As a result, Blueprints work well for game teams that don't have the technical expertise of native CPP programmers. The reason that non-programmers can work strictly with Blueprints, is because Blueprint nodes run in a virtual machine (VM), enabling them to call native CPP functions. Unfortunately, relying on a VM that translates Blueprints into native CPP code comes at a cost; and as you can imagine, translating Blueprint nodes into native CPP functions can potentially slow your game's performance per frame.

When the cost of running Blueprints in a VM isn't noticeable, the VM overhead can be an acceptable cost to bear; however, there are times when you'll want your game to run as fast as possible (especially, when you're shipping to devices that have limited hardware capabilities). This is where Unreal Engine's Blueprint Nativization tool can help.

Here at Epic, we've successfully used Blueprint Nativization while developing our newest VR title, Robo Recall .

Reducing VM Overhead

The main goal of Blueprint Nativization is to reduce VM overhead in the runtime version of your project by generating native CPP code from your project's Blueprints. In general, all of the Blueprint Classes are replaced by the newly generated native CPP classes that will then be compiled with the project during the cooking process . Although you'll be able to read the translated CPP code from a text editor, you'll notice that the code isn't formatted to be reusable (or generated to be "reader friendly").

Blueprint

Nativized Blueprint

Here, we compare a Player Character Blueprint with its nativized code.

This page will get you started with nativizing your project's Blueprints, and for Blueprint-only projects, this should be a straightforward task. To get started, you'll need to know where to find the user interface (UI) that you'll need to disable and enable Blueprint Nativization.

Enabling Blueprint Nativization

When you first create a project, Blueprint Nativization is disabled by default. To locate the Blueprint Nativization settings, open the Project Settings menu from Unreal Editor, and select Packaging from the left side bar. You should be able to see the Blueprints dropdown menu from inside of the Project - Packaging menu.

Click for full image.

At any time during development, if you choose to disable Blueprint Nativization, select Disable from the Blueprint Nativization Method dropdown list.

BPNativization_DisabledUI1.png

As you can see from the dropdown list, there are two additional options that are available to you, namely:

  • Inclusive Nativization

  • Exclusive Nativization

Inclusive Nativization

When you select Inclusive nativization, you're electing to nativize all of the supported Blueprint classes in your project.

BPNativization_InclusiveUI.png

After selecting the Inclusive nativization method, it's important to note that during the packaging process , Unreal Automation Tool (UAT) will nativize the following supported Blueprint assets:

  • Blueprint Classes

  • Blueprint Function Libraries

  • Blueprint Interfaces

  • Anim Blueprints

  • Widget Blueprints

  • User Defined Structures

  • User Defined Enums

At this time, Level Blueprints and Blueprint Macros aren't supported by the Blueprint Nativization tool, and won't be converted into native CPP code.

Excluding Blueprints from Conversion

When the Blueprint Nativization tool converts Blueprint nodes to native CPP code, the resulting executable is compiled with additional machine instructions, dependencies, and embedded metadata to support the conversion.

So, it's important to be aware that when you opt into the Inclusive Blueprint Nativization Method, your executable size will grow to a size that may be unacceptable for the platform that you're shipping for.

You can mitigate the bloating of your executable's size by specifying which Blueprints you want to exclude from the conversion process. To exclude Blueprints from conversion, open your project's DefaultEditor.ini file, and create a [BlueprintNativizationSettings] heading with the following configuration properties:

  • To exclude a certain type of Blueprint asset, set the ExcludedBlueprintTypes configuration property.
    For example, +ExcludedBlueprintTypes=/Script/UMGEditor.WidgetBlueprint, won't convert any Widget Blueprint assets.

  • To exclude a specific Blueprint asset, set the ExcludedAssets configuration property.
    For example, +ExcludedAssets=/Engine/Tutorial/SubEditors/TutorialAssets/Character/TutorialCharacter, won't convert the Tutorial Character Blueprint asset.

DefaultEngineINI.png

Note that Blueprint assets are nativized during the packaging process only if they're cooked as part of that process. So, if you haven't specified any Blueprint assets or maps for cooking, Unreal Engine will cook everything that's located inside of your Content directory. If, after selecting the Inclusive method, you notice that unused Blueprints are being nativized, you should probably opt into the Exclusive Blueprint Nativization Method.

Exclusive Nativization

For larger projects being shipped to devices with limited hardware resources, we recommend that you select the Exclusive Blueprint Nativization Method.

BPNativization_ExclusiveUI.png

While the Inclusive method is available for smaller projects that aren't in danger of bloating the executable beyond the target hardware's capacity to host the application, there are several advantages when choosing to use the Exclusive Blueprint Nativization method. Some of the advantages include:

  • Limiting the final size of the executable.

  • Actively preventing unused Blueprint assets from being converted.

  • Having the ability to explicitly select which Blueprint assets to convert.

In general, it's recommended that you opt into the Exclusive Blueprint Nativization Method when you have Blueprints that are computationally expensive; including (but, not limited to):

  • Blueprints with lots of nodes.

  • Blueprints that require optimized loops.

  • Blueprints that perform complex mathematical operations.

Selecting Blueprints to Nativize

If you don't have a project containing Blueprint assets, go ahead and create a new project using one of the available project templates. For illustrative purposes, we're using the Puzzle Project Template.

Perform the following steps to select Blueprint assets that you want to nativize, using the Exclusive Blueprint Nativization Method.

  1. First, open the Edit menu and select Project Settings....

    Click for full image.

  2. With the Project Settings menu open, go ahead and click Packaging, opening the Project Settings - Packaging menu.

    Click for full image.

  3. From the Blueprints submenu, click on the Blueprint Nativization Menu dropdown list.

    Click for full image.

  4. Select the Exclusive option to opt into the Exclusive Blueprint Nativization Method.

    Click for full image.

  5. Go ahead and select the expansion arrow at the bottom of the submenu, revealing an empty array.

    Click for full image.

    This array will contain the list of Blueprint assets that you'll explicitly select for nativization. BPNativization_ExclusiveStep_5Note.png

  6. After exiting the Project Properties menu, navigate to the folder containing your Blueprint assets.

    Click for full image.

  7. Now, open the Blueprint asset(s) that you'd like to nativize.

    Click for full image.

  8. After the Blueprint Editor opens, click the Class Settings button.

    Click for full image.

  9. To mark this Blueprint asset for nativization, go ahead and click the Nativize checkbox located in the Packaging submenu in the Details panel.

    Click for full image.

  10. Make sure to click the Save button before closing the Blueprint Editor for this asset.

    Click for full image.

  11. To verify the Blueprint asset that you've selected for Exclusive nativization, open the Project Settings menu to view the array containing the list of Blueprint asset(s) that you've marked for nativization.

    Click for full image.

At this point, you're ready to Cook and Package your project using the Exclusive Blueprint Nativization Method.

Note that all supported dependencies required to build the Blueprint(s) that you've selected for Nativization, will also be flagged for Nativization.

Locating Nativized Code

You can find your nativized code in [ProjectDirectory]\Intermediate\[Platform That Was Cooked For]\NativizedAssets\Source\NativizedAssets\

NativizedAssetsLocation.png

Setting the Nativization Flag

If you navigate back to the Project Settings > Project - Packaging menu, you'll notice that there is a checkbox next to the Warn if Packaged Without Nativization Flag label.

Click for full image.

This flag is intended for Advanced users who build/cook their projects from the command line (such as a server-side build engineers). Basically, if you enable this flag while also enabling nativization in the Project Settings menu, a warning will be emitted if you don't use the nativization flag from the command line at build/cook time. To learn how to use the nativization switch from the command line, please read the Advanced Blueprint Nativization documentation.

Tags