See Also Advanced Blueprint Nativization

When teams script gameplay with Blueprints, they're creating new UClasses without having to write or compile native C++ code. As a result, Blueprints work well for game teams that don't have the technical expertise of native C++ 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 C++ functions. Unfortunately, relying on a VM that translates Blueprints into native C++ code comes at a cost; and as you can imagine, translating Blueprint nodes into native C++ 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 C++ code from your project's Blueprints. In general, all of the Blueprint Classes are replaced by the newly generated native C++ classes that will then be compiled with the project during the cooking process . Although you'll be able to read the translated C++ code from a text editor, you'll notice that the code isn't formatted to be reusable (or generated to be "reader friendly").

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.

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

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.

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 C++ code.

Excluding Blueprints from Conversion

When the Blueprint Nativization tool converts Blueprint nodes to native C++ 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.

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.

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.

First, open the Edit menu and select Project Settings.... With the Project Settings menu open, go ahead and click Packaging, opening the Project Settings - Packaging menu. From the Blueprints submenu, click on the Blueprint Nativization Menu dropdown list. Select the Exclusive option to opt into the Exclusive Blueprint Nativization Method. Go ahead and select the expansion arrow at the bottom of the submenu, revealing an empty array. This array will contain the list of Blueprint assets that you'll explicitly select for nativization. After exiting the Project Properties menu, navigate to the folder containing your Blueprint assets. Now, open the Blueprint asset(s) that you'd like to nativize. After the Blueprint Editor opens, click the Class Settings button. To mark this Blueprint asset for nativization, go ahead and click the Nativize checkbox located in the Packaging submenu in the Details panel. Make sure to click the Save button before closing the Blueprint Editor for this asset. 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.

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\Plugins\NativizedAssets

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.

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.

Additional Resource

Additional information covering Blueprint Nativization can be found in the following Feature Highlight video.