Splicing Juncture

Blueprint Type Migrator

Move Blueprint structs and enums to C++ without losing data.

When you replace a Blueprint struct or enum with a C++ one, things tend to break without any warning. DataTable cells empty out, enum values reset, Blueprint pins disconnect and old save files load with missing fields. Avoiding that takes a set of CoreRedirects that has to be exactly right, including a few that aren't documented.

Blueprint Type Migrator writes the C++ types and the redirects for you. It then proves nothing was lost: it records every stored value before the change and compares each one afterwards, in DataTables, Blueprint defaults, components, placed actors, other Blueprint structs and save files. Values that came out different are written back, and you can undo the whole migration.

Supported: Unreal Engine 5.6, 5.7 and 5.8 on Windows. Editor-only (nothing is added to your packaged game).


Contents

  1. Install
  2. Quick start (editor)
  3. Quick start (command line)
  4. What each step does
  5. Commands and options
  6. Files it writes
  7. What is checked
  8. Limits
  9. FAQ
  10. Support

Install

  1. Install the plugin from Fab into your engine (Fab Library > Install to Engine), or copy the BlueprintTypeMigrator folder into your project's Plugins folder.
  2. Open your project and enable Edit > Plugins > Editor > Blueprint Type Migrator, then restart the editor.
  3. Your project needs a C++ game module (a folder under Source with a .Build.cs). The new C++ types go there. A Blueprint-only project can get one from Tools > New C++ Class.

Quick start (editor)

  1. Commit your project to source control (or copy it). The plugin keeps its own copies for Undo, but a commit is still the safest backup.
  2. In the Content Browser, select the Blueprint structs and enums to move (or right-click a folder). Right-click > Blueprint Type Migrator > Plan migration to C++...
  3. Check the C++ module and, if you like, the header path and the C++ names. Click Plan. Planning changes nothing. The results window shows the report: the C++ types, every member and value, every asset that uses the types, and anything that can't carry over exactly.
  4. Click Apply.... The editor saves your work and closes. A console window records every value, writes the header and the redirects, moves the old assets aside, builds your module, then checks and repairs every value. After that the editor reopens with the results.
  5. Read the results. Every recorded value matches means you're done. If anything is listed, see What is checked.
  6. Changed your mind? Open Tools > Blueprint Type Migrator and click Undo....

After Apply the Blueprint assets are no longer in the Content Browser, so use Tools > Blueprint Type Migrator to find the results window, Verify and Undo. The window lists every plan you've made.

Quick start (command line)

Close the editor, then from a command prompt:

set UE=D:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor-Cmd.exe

"%UE%" MyGame.uproject -run=BlueprintTypeMigrator -Plan -Types=/Game/Data/S_Item+/Game/Data/E_ItemKind -Module=MyGame
"%UE%" MyGame.uproject -run=BlueprintTypeMigrator -Apply
(build MyGameEditor, e.g. from your IDE)
"%UE%" MyGame.uproject -run=BlueprintTypeMigrator -Verify -Repair -Save

Every step prints where its report is. The exit code is 0 when the step succeeded, so the steps can run in CI.

What each step does

Plan (changes nothing)

Apply (editor closed)

  1. Loads every asset that uses the types and records every value stored in them.
  2. Copies those assets into the plan folder, so Undo can restore them later.
  3. Writes the header into your module and the redirects into Config/DefaultEngine.ini, between marker comments.
  4. Moves the old Blueprint assets out of Content into the plan folder. The redirects don't take effect while they're still there.

Then build your module.

Verify

Undo

Commands and options

Run as UnrealEditor-Cmd.exe <Project>.uproject -run=BlueprintTypeMigrator <step> [options] with the editor closed.

Step Options What it does
-Plan -Types=, -Module=, -Header=, -Names=, -SaveFiles= Writes the plan and its preview. Changes nothing.
-Apply -Batch= Records values, backs up the assets, writes the header and redirects, moves the old assets aside.
-Verify -Batch=, -Repair, -Save, -SaveAll Compares every value with the record, compiles the Blueprints that use the types, repairs and saves.
-Undo -Batch= Reverts Apply (and the saves made by Verify).
-WriteScript=Apply or Undo -Batch=, -NoRelaunch Writes the batch file the editor runs for Apply/Undo (for build machines).
Option Meaning
-Types=A+B Asset paths (/Game/Data/S_Item) or folders ending in / (every Blueprint struct and enum inside, subfolders included), joined with +.
-Module=Name Game module that will own the types (a folder under Source).
-Header=Public/ItemTypes.h Header path inside the module. Default Public/MigratedTypes.h (or MigratedTypes.h if the module has no Public folder). Must not exist yet.
-Names=S_Item=Item+E_Kind=ItemKind Choose C++ names. Default: the asset name without S_, F_, STR_, E_, ENM_ and similar prefixes. The struct Item becomes FItem; the enum ItemKind becomes EItemKind.
-SaveFiles=Saved/SaveGames Also check these save files (.sav files or folders, joined with +; relative paths start at the project folder).
-Batch=20261110-031500 Which plan to use. Default: the latest.

In the editor, the same steps are on the Content Browser right-click menu of Blueprint structs and enums (Blueprint Type Migrator), on folders (Plan Blueprint struct/enum migration to C++...), and in Tools > Blueprint Type Migrator (results window with Apply, Verify, Verify and repair, Undo, Open folder).

Files it writes

Everything goes into Saved/BlueprintTypeMigrator/<plan>/:

File Contents
Report.md The plan: types, members, values, assets that use them, problems, warnings, Build.cs changes needed.
Preview/ The header and the redirects exactly as Apply will write them.
Plan.json The plan in machine-readable form (also tracks what Apply moved and what Verify saved).
Snapshot-Before.json, Snapshot-After.json Every recorded value, before and after.
Verify.md The last Verify: values that changed, Blueprints with compile errors, anything that couldn't be checked.
Undo.md The last Undo, and anything it left alone.
Backup/, Retired/ Copies of the assets that use the types, and the old Blueprint types themselves.
DefaultEngine.ini.bak DefaultEngine.ini as it was before Apply.
Apply.bat, Undo.bat and their logs The editor's Apply/Undo runs: Apply.log summarises the run, Apply-Apply.log, Apply-Build.log and Apply-Verify.log hold each step's full output (likewise for Undo).

The plugin only changes your project in three places: the new header in your module, a marked block in Config/DefaultEngine.ini, and the assets that use the types (only when you Verify with -Save/-SaveAll or click Verify and repair).

What is checked

Values are recorded wherever a migrated type is stored:

Each value is compared by its member and value names in their C++ form, so a renamed member or enumerator counts as the same value.

If Verify lists differences:

Limits

FAQ

Will my DataTables, levels and save games still work? That's what Verify is for. It compares every stored value with the record made before the change and tells you if anything differs. In our tests (UE 5.6, 5.7 and 5.8) every DataTable row, Blueprint default, placed actor and save-file value matched after Apply and Repair, including enums renamed from NewEnumerator0 to real names.

Do I have to re-save every asset? No. The redirects make old assets load correctly. Re-saving (-SaveAll) lets you remove the redirects one day. Don't remove them while any save file written with the old types may still be loaded.

Can I undo after saving? Yes. Apply keeps copies of every asset that uses the types, and Undo restores the ones the migrator saved. Assets you changed yourself afterwards are left alone and listed.

How are names chosen? Members: the name shown in the Blueprint editor, made into a C++ identifier (Max Health becomes MaxHealth, a boolean Is Active? becomes bIsActive). Enum values: their display name (Lightning Bolt becomes LightningBolt). Types: the asset name without its prefix. Use -Names= (or the plan dialog) to choose type names. Edit the preview header before Apply if you want different member names; the redirects in Preview/Redirects.ini must then match.

Does it convert Blueprint graphs (functions, events) to C++? No. It moves data types: structs and enums. Graph conversion is a different problem.

What if the header doesn't compile? Usually a missing module dependency. The report's "Build.cs" section lists the modules to add to your module's .Build.cs. If it's something else, Undo, then email us the header and the report.

Does it work with source control? Yes. It only writes files (no checkout API). With Perforce, check out Config/DefaultEngine.ini, your module folder and the assets listed in the report first, or make them writable.

Support

Email splicingjuncture@proton.me with the plan folder's Report.md and Verify.md (and the .log files if Apply or Undo stopped).

Version history