BlendUnreal Toolkit — Documentation

A Blender → Unreal Engine 5 export pipeline: a Blender add-on that builds a stamped SmartPackage, and an Unreal plugin that brings it in — correct scale and axes, skeletal mesh / animation split, LODs, collision, ORM-packed textures, and material parameters, in one pass.

Contents

1. Installation
2. Quick start
3. Blender side — full reference
4. Unreal side — full reference
5. Workflow guides
6. Known limitations
7. Troubleshooting
8. FAQ

Installation

Blender add-on

1. Edit → Preferences → Get Extensions, or drag-and-drop the .zip release onto the Blender window.
2. Enable BlendUnreal Toolkit.
3. Open the 3D View → N-Panel → BlendUnreal tab.

Default preferences (output folder, LiveTransmit host/port/token) live under Edit → Preferences → Add-ons → BlendUnreal Toolkit.

Unreal plugin

1. Copy the BlendUnrealTool folder into your project's Plugins\ directory (create the folder if it doesn't exist): <YourProject>\Plugins\BlendUnrealTool\
2. Open the project. Unreal will detect the new plugin automatically.
3. Confirm it's enabled: Edit → Plugins, search "BlendUnreal" — should already be checked.
4. The plugin is pure Python (uses Unreal's built-in Python Script plugin) — no C++ compile step, no restart required beyond the normal plugin-detection reload.
5. A new BlendUnreal menu appears in the main menu bar. The live receiver starts automatically in the background when the project opens (you'll see a confirmation line in the Output Log).

Quick start

1. In Blender, select the object(s) you want to export.
2. Open the BlendUnreal panel (N-panel) → Export tab.
3. Pick a preset (Mobile/VR, PC/AAA, or WebGL — controls LOD reduction ratios).
4. Click Export → FBX + SmartPackage.
5. In Unreal: BlendUnreal menu → Import SmartPackage, and pick the folder that was just created. Everything — meshes, materials, textures, collision, LODs, animations — imports and wires together automatically.

Or, skip step 5 entirely: enable TCP Transmit on Export in Blender's Live tab, leave Unreal open, and every export pushes over automatically.

Blender side — full reference

Export tab

Skeletal / Animation tab

Colliders tab

Materials / Atlas tabs

Scene / Output tab

Live tab

Unreal side — full reference

Accessed via the BlendUnreal menu in Unreal's main menu bar.

The live receiver

Starts automatically when the project opens. Listens on 127.0.0.1:61501 by default. Every incoming push is checksum-verified (SHA-256) before extraction. To require a shared token, set an environment variable on the machine running Unreal:

BLENDUNREAL_TOKEN=your-shared-secret

Without it, the receiver accepts any push that reaches that port — fine on a local machine or trusted LAN, not recommended if the machine is reachable from an untrusted network.

Material assignment

On import, materials and textures always land correctly as Unreal assets. Assignment onto a mesh's actual material slots works by matching the slot name against material instance names — including a fuzzy match for naming variations — and then discovers your master material's actual exposed parameters at runtime rather than assuming fixed names, so it adapts to however your M_BlendUnreal_Master material is actually set up.

If a slot can't be matched, the Output Log names the exact slot it was searching for and lists every material instance name it had to search against — so a mismatch is always visible, never silent. See Known limitations.

Workflow guides

Basic static prop export

1. Select your mesh(es) in Blender.
2. Export tab → leave Split Skeletal Mesh / Animations off.
3. Export → Import SmartPackage in Unreal.

Rigged character with animation

1. Select the armature and its mesh children.
2. Export tab → Split Skeletal Mesh / Animations on, Export All Actions on (or off, to export only the currently-active action per armature).
3. With multiple characters in one export, each armature's actions are matched automatically by which bones they actually target — no manual separation needed.

Multi-part assembly (a car, a building with separate trim pieces, etc.)

1. In Blender, parent all the parts of one assembly together — select the parts, Shift-click whichever should be the parent last, Ctrl+P → Object (Keep Transform).
2. Confirm in the Outliner that the parts are now genuinely nested under the parent (indented), not just sitting at the same flat level.
3. Export with Combine Parented Meshes on. Check the console's "Mesh Grouping" section — it lists exactly which groups it found and how many parts are in each.
4. In Unreal, the whole assembly imports as one combined static mesh asset.

Note: LODs and auto collider proxies aren't generated per-part for combined groups (Unreal's Combine Meshes import flattens everything into one LOD0 mesh, so per-part LOD/collision doesn't apply). Generate a single manual LOD or collision mesh for the assembled whole if you need one.

LiveTransmit (no manual import step)

1. Unreal: leave the project open (the receiver starts automatically).
2. Blender: enable TCP Transmit on Export in the Live tab.
3. Every export now pushes straight to Unreal and imports automatically. Check Blender's console for LiveTransmit OK and Unreal's Output Log for Auto-import complete.

Known limitations

• Material auto-assignment isn't guaranteed on every mesh yet. Materials and textures always import correctly as assets; slot assignment works reliably for standard setups and adapts to your master material's actual parameter names, but unusual naming schemes may still need a manual assignment. The Output Log always tells you exactly what matched and what didn't.
• Skeletal mesh LODs need one manual step. They export as separate files but currently need to be added to the skeletal mesh's LOD slots by hand in the Skeletal Mesh editor — the Output Log flags which files are waiting.
• LiveTransmit is unauthenticated by default. Set BLENDUNREAL_TOKEN on the Unreal machine if you want pushes to require a matching token.

Troubleshooting

"Pillow not available — ORM packing skipped" Blender's bundled Python doesn't include Pillow by default. Install it:

"C:\Program Files\Blender Foundation\Blender <version>\<version>\python\bin\python.exe" -m pip install Pillow

(Adjust the path to match your actual Blender install and version folder.)

Export includes fewer objects than expected Check whether Export Selected Only is on — if so, only your current selection exports. If it's off and objects are still missing, check the "Mesh Grouping" console output; a part that got excluded as an outlier (see Combine Parented Meshes above) still exports, just as its own separate asset rather than being silently dropped.

A combined mesh looks huge, tiny, or stretched across empty space One part of the group is very likely sitting far from where it should be — an accidental duplicate or a stray drag in Blender. The pipeline now detects and automatically excludes outliers like this rather than baking them into the combined mesh, but the source data mistake itself still needs fixing in the scene: check the Outliner for a .001-suffixed duplicate, or check the object's Location values directly.

"Auto-import failed" in Unreal's Output Log Read the specific error text — it names the failing step. Common causes: the SmartPackage folder was moved/deleted before Unreal could read it, or a mesh/material asset name collided with something already in the project.

Nothing happens when I click a BlendUnreal menu item Confirm the plugin is actually enabled (Edit → Plugins, search "BlendUnreal") and that you see the "Menu registered" line in the Output Log at project startup. If the log shows Python errors at startup instead, the plugin failed to initialize — check that no required files are missing from Plugins\BlendUnrealTool\Content\Python\.

FAQ

Do I need to compile anything on the Unreal side? No. The Unreal plugin is pure Python — no C++ module, no rebuild step.

Does it work with multiple characters in one export? Yes. Animations are matched to the correct skeleton by which bones they actually target, not just by import order, so multiple rigs in one package each get only their own actions.

What happens if part of my model is broken or misplaced? For combined multi-part assemblies, a part sitting far outside the rest of its group is automatically excluded from the combined mesh (with a console warning naming it) instead of corrupting the whole asset.

Can I use this without LiveTransmit, fully offline/manual? Yes — LiveTransmit is optional. Export in Blender, then use BlendUnreal menu → Import SmartPackage in Unreal whenever you're ready.

Which Blender and Unreal versions are supported? Blender 4.2+, Unreal Engine 5.2+.

Is this safe to use on a shared network? The live receiver checksum-verifies every push. It doesn't require authentication unless you set BLENDUNREAL_TOKEN — do that if the machine running Unreal is reachable from anyone other than you.

What if it doesn't handle my scene well? Send your Output Log from both the Blender console and Unreal's Output Log — the pipeline names exactly which step ran, what it matched, and what it skipped, which usually identifies the issue immediately. Include your Blender and Unreal versions.