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
- Install
- Quick start (editor)
- Quick start (command line)
- What each step does
- Commands and options
- Files it writes
- What is checked
- Limits
- FAQ
- Support
Install
- Install the plugin from Fab into your engine (Fab Library > Install to Engine), or copy the
BlueprintTypeMigratorfolder into your project'sPluginsfolder. - Open your project and enable Edit > Plugins > Editor > Blueprint Type Migrator, then restart the editor.
- Your project needs a C++ game module (a folder under
Sourcewith a.Build.cs). The new C++ types go there. A Blueprint-only project can get one from Tools > New C++ Class.
Quick start (editor)
- 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.
- 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++...
- 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.
- 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.
- Read the results. Every recorded value matches means you're done. If anything is listed, see What is checked.
- 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)
- Reads the Blueprint types you picked and decides the C++ names of the types, their members and their values.
- Writes a C++ header with matching
USTRUCT/UENUMtypes: members, defaults, tooltips, display names, SaveGame flags, clamp ranges and the DataTable row base (FTableRowBase, added when a DataTable uses the struct). - Writes the CoreRedirects: struct, enum, every member and every enum value, plus the
ObjectRedirectswithOverrideClassNamethat Blueprint structs need and theSTRUCT_REINST_names some assets were saved against. - Lists every asset that uses the types, including those that only use them through another Blueprint struct.
- Lists problems (which block Apply) and warnings (things that can't carry over exactly; Verify then finds every asset affected).
Apply (editor closed)
- Loads every asset that uses the types and records every value stored in them.
- Copies those assets into the plan folder, so Undo can restore them later.
- Writes the header into your module and the redirects into
Config/DefaultEngine.ini, between marker comments. - Moves the old Blueprint assets out of
Contentinto the plan folder. The redirects don't take effect while they're still there.
Then build your module.
Verify
- Loads everything again with the C++ types, compiles every Blueprint that uses them and compares every value with the record made by Apply.
-Repairwrites the recorded value back wherever it changed (for example a default the C++ type can't express).-Savesaves the assets it repaired.-SaveAllsaves every asset that uses the types, so they no longer need the redirects.
Undo
- Moves the Blueprint assets back, removes the redirects and moves the generated header out of your module.
- Restores the assets the migrator saved (Verify
-Save) from the copies Apply made. If you edited an asset yourself after the migration, it's left as it is and listed inUndo.md, together with where the old copy is. - Then build your module.
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:
- DataTable rows (including tables whose row struct is migrated)
- Blueprint class defaults and component defaults
- Actors placed in levels (World Partition external actors too)
- Other Blueprint structs that contain a migrated type, and the assets that use those
- Arrays, sets and maps of migrated types, at any depth, and enums as map keys or set elements
- Instanced structs holding a migrated type
- Save files you list with
-SaveFiles
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:
- A value differs: Verify with Repair writes the recorded value back and saves it (
-Repair -Save). - A key ends in
.Num: the number of entries in an array, set or map changed. That can't be repaired automatically. Fix it by hand or Undo. - A save file differs: save files can't be rewritten by the plugin. Check how your game loads them; the redirects usually take care of it. Keep the redirects.
- A Blueprint has compile errors: open it; usually a pin needs reconnecting or a cast (see Limits).
Limits
- Migrate types together with the Blueprint structs and enums they contain. C++ can't refer to a Blueprint type. The plan says which ones are missing, and Apply is blocked until they're added.
- Members that point at a Blueprint class use the nearest C++ parent class instead. Saved values still load, but Blueprint pins may need a cast. The report lists each one.
- Members whose type is a Blueprint interface block the plan. Move the interface to C++ first.
- Object references as defaults (for example a default mesh) can't be loaded in a C++ struct constructor, so the C++ default is empty. Verify finds every asset that relied on the old default and Repair puts it back.
- Default entries in arrays, sets and maps become empty C++ defaults, handled the same way.
- Default text is copied as culture-invariant text. The Blueprint's localization key isn't kept.
- Blueprint "Float" members are doubles in UE5, so they become
double(no precision change). - Enum values above 255 block the plan (Blueprint enums are stored as bytes).
- Keep the redirects until every asset has been saved with the new types (
-SaveAlldoes that). For save files in players' hands, keep them for good. - Apply and Undo need the editor closed. In the editor they close and reopen it for you.
- Windows only for now.
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
- 1.0.0: First release. Plan, Apply, Verify (with Repair), Undo (including assets saved by the migrator), editor UI, UE 5.6 to 5.8.