Skip to content
Desuq Café
Documentation menu

Unreal Quick Start

Stream your Blender scene live into the Unreal editor, then bake it to a reusable Blueprint over real assets. This guide gets you from install to a synced scene in a few minutes.

Requirements: Blender 5.0+, Unreal Engine 5.6 (developed, built and tested against 5.6; other 5.x untested), a C++ project (the editor compiles the plugin on open), both on the same machine (loopback TCP), Win64.

1. Install the Blender add-on

  1. In Blender, open Edit → Preferences → Add-ons.
  2. Use the ▾ menu and choose Install from Disk…, then pick a zip of the blender/loom/ folder.
  3. Enable Loom in the list.
  4. The panel appears in the 3D Viewport → N sidebar → Loom tab (“Loom Live Sync”). The producer side is covered in the Blender Producer Guide.

2. Install the Unreal plugin

  1. Copy (or junction) unreal/Loom/ into your project’s Plugins/ folder.
  2. Open the project. If prompted to rebuild the Loom module, accept. The editor compiles it.
  3. In Edit → Plugins, confirm Loom Live Link is enabled (search “Loom”), and restart if asked.
  4. Open the panel from Tools → Loom (also Window ▸ Loom). The dockable tab is titled Loom.

3. Connect

  1. In Unreal, open Tools → Loom (or Window ▸ Loom) and press Start Listener. The status reads Listening on 127.0.0.1:8787…
  2. In Blender’s Loom sidebar panel, select the objects you want, then press Connect. Both sides default to 127.0.0.1:8787, so on one machine it just connects.
  3. The Loom tab shows Connected, is streaming, and your synced objects appear in the level, re-based into Unreal space (Z-up, centimetres), under an actor named Loom (rename it under Root actor).

By default Loom streams the objects you select — selecting an object tracks it, and it keeps streaming until you Untrack it. Set Scope to Whole scene or a Collection to send more; the panel shows a live in-scope count (N objects will sync · K excluded) before you connect. Selecting any part of a model tracks the whole model (Track the whole model, on by default). With nothing selected, Blender’s panel asks What do you want to send? and offers the whole scene or the active collection as one-click buttons, with their counts.

Now edit in Blender. Meshes, rigs, lights and cameras stream into Unreal live as UDynamicMeshComponents. Moving an object sends a tiny transform packet, and sculpting or animating streams positions only (CPU linear-blend skinning for rigs).

What you are looking at is a stand-in. The actors Loom spawns are transient previews and are not saved with the level; that is what Bake is for. If Blender disconnects, the stand-ins stay where they are, so a Blender restart does not wipe and re-stream the level, and the Loom tab says so under the status line, with Bake Scene…, Clear Synced Objects and Keep for now beside it.

4. Sync materials

Materials are kept off the realtime path. Press Sync Materials in the Blender panel to push Principled materials and node-graph shaders. Loom builds a C++-authored LoomLit UMaterial and ports supported node graphs to HLSL in a per-material Custom node, compiled in-editor. Unsupported graphs fall back to a faithful Principled material.

Stylized and toon materials (lilToon, UTS, custom)

A non-Principled material has no PBR factors to translate, so Loom will not try to fake its look on LoomLit. Instead it transfers the material’s named textures — every image in the surface graph, keyed by its Blender image name — so you can drive your own engine-side shader with them. Two steps:

  1. Pin your shader. Assign a LoomMaterialOverrides asset mapping the Blender material’s uid to your toon UMaterial or UMaterialInstance.

  2. Route the maps. Set NamedTextureRules under the [Loom] section of the project’s EditorPerProjectUserSettings.ini, a ;-separated list of pattern=parameter rules. Each pattern is a case-insensitive substring of the Blender image name; each parameter is a texture parameter on your pinned shader:

    [Loom]
NamedTextureRules=_base=_MainTex;_ilm=_LightMap;_sss=_ShadowColorTex

Loom wraps the pinned material in a dynamic instance and sets those texture parameters from the synced maps. There is no window UI for this yet; it is ini-first, like the root actor and target level.

5. Bake to a Blueprint

When you are happy with the preview, use the BAKE TO ASSETS section of the Loom tab. Loom saves the meshes, materials and textures as real UStaticMesh, USkeletalMesh, UMaterial and UTexture2D assets, plus a reusable BP_LoomBake Blueprint whose component hierarchy mirrors the scene. Toggle skeletal meshes, prefab Blueprint, lightmap UVs and static GI, and colliders before baking.

To bake only part of the scene, select any synced actors in the viewport or Outliner and press Bake Selected…. Loom bakes each selection’s whole subtree plus its parent chain, and leaves out everything else, including the meshes, materials and textures the selection does not use.

6. Replace greybox with your real Blueprints

Loom’s live scene is a blockout; your finished props live in the project. Wire the two together with a prefab reference:

  1. In Blender, select the blockout objects and press Set Prefab Key… (Active Object › Prefab reference). Give it a key (pillar_a) and leave Apply to at All sharing the mesh: the key lives on the mesh datablock, so every linked duplicate (Alt+D) follows it. Choose This placement only to key one placement differently.
  2. In Unreal, create a LoomPrefabRegistry data asset (Content Browser ▸ Miscellaneous ▸ Data Asset ▸ LoomPrefabRegistry) and fill the table: key → the Blueprint (actor class) to spawn.
  3. Open the Loom window ▸ PREFAB REGISTRY and pick the asset. Loom remembers it across sessions and editor restarts.

Every keyed object then spawns your Blueprint at the Blender transform, moves with it, and is removed with it. An unmapped key places a tracked placeholder and logs one warning per key; map it and press Reapply Prefabs, which rebuilds only the instances whose Blueprint changed.

Assign from Unreal. Select the synced actors in the Outliner and open the Loom window ▸ REPLACE GREYBOX:

Pillar_Grey.003 · greybox mesh · shared by 90 synced objects
Blender owns this geometry until you assign a key.

Key       [ pillar_a                    ] ▾
Variant   [ Pillar_A_Broken             ▾ ]   pool: base + 3
Apply to  (•) All 90 sharing the mesh   ( ) This placement only

⚠ Replaces 90 placements. Their Blender geometry stops streaming; the Blueprint becomes
  the source of truth. Undo in Blender (Ctrl+Z).

[ Assign ]  [ Scatter pool… ]  [ Clear to greybox ]
✓ Assigned pillar_a to 90 placements (mesh data) — 2 s ago

The warning states the blast radius before you press anything, and the result line underneath is the producer’s own verdict — one sentence per click, however many requests it took. With no Blender connected it reads ✗ Not sent — no Blender connected, rather than counting refusals of writes that never left the editor.

Variants, by name. A registry row can list variants — the base Blueprint plus alternates. loom_variant can hold the Blueprint’s asset name instead of a number, matched case-insensitively. Insert a variant in the middle of a pool and every numbered placement shifts by one, whereas a named placement keeps pointing at the same Blueprint. A name that is not in the pool shows the base Blueprint and logs one warning per name, never a silent wrong piece.

Scatter a pool. With keyed placements selected, press Scatter pool…, set a Seed, and press Scatter. One loom_variant per placement is written into the .blend, and the seed is stored on the mesh datablock, so the arrangement is in the file and Ctrl+Z in Blender takes it back. Re-roll only steps the number in the field; nothing is written until you press Scatter. The same seed over the same objects produces the same level from either side.

Blockouts and PREFAB CHECK. Right-click synced actors in the Outliner for Loom › Mark as blockout / Unmark blockout. PREFAB CHECK under the same section lists one row per key in the live scene with its placement count and pool size, tagging anything resolving to something else — an unmapped key, a variant name not in the pool, an index past the end of it — plus a Blockouts 62 of 210 replaced line and a progress bar.

Blender decides. These writes go back over the reverse channel and Blender applies them: Loom › Routing & Selection › Accept property edits from the editor (on by default). Only Loom’s own authoring properties are ever written — prefab key, variant, blockout, tracked/excluded/freeze, routing — never geometry, only on objects Loom is currently streaming, and each write pushes an undo step. A datablock linked from another .blend is always refused, naming the file to make local.

How replacement works › in the section header opens a four-page explainer: What streams, What a key does, Variants and pools, Greybox → final. The ? beside PREFAB CHECK opens the variants page, and Loom Guide sits beside Loom in the Tools menu. It documents, it never acts.

Drop a character in to playtest. Place an empty in Blender, give it the key player_start, and map that key to your character or player-start Blueprint. It lands where the empty is, live colliders already work, and Play-In-Editor sync keeps the level updating while you run around in it.

7. Colour blocking (a global material)

Loom window ▸ MATERIAL OVERRIDES ▸ Global material (colour blocking): pick any material — colour blocking, vertex colour, flat unlit — and turn on Override all synced materials. Every synced mesh and instance group shows it at once; turn it off and everything reverts. The choice is remembered across sessions.

Placed Blueprints (prefab references) are your finals and are never overridden, and the bake ignores the global material, so baked assets get the real ones. Every synced mesh already carries its Blender vertex colours, so a material with a VertexColor node shows them with no extra setup, and a Blender material that uses a Color Attribute node is transpiled too.

Linked duplicates vs. instances. A Blender instance (a particle or Geometry Nodes scatter, an instanced collection) has no object of its own, so it streams as a template plus placements and Loom batches it into an Instanced Static Mesh component. A linked duplicate (Alt+D) is a real Blender object, so it keeps its own actor here and stays selectable and individually keyable; only its geometry is shared on the wire. The trade-off is memory: each linked-duplicate actor currently holds its own copy of the shared geometry, so ninety duplicates of a heavy mesh cost ninety copies in the editor. Blockouts, the normal case, are small.

Tips and toggles

  • What streams: the tracked set. Under Selected only, selecting an object tracks it (with Track the whole model, on by default, its whole parent tree, so a character’s hair brings the whole character): it streams, keeps streaming while deselected, survives a reconnect or a Blender relaunch, and leaves Unreal only when you Untrack it. Exclude / Include work in any scope. Turn off Track on select to manage the set with the buttons alone. The Tracked Objects list says exactly which objects are in play.
  • Boolean cutters. An operand that only exists to cut a Boolean modifier (shown as Wire / Bounds, or hidden from render) is skipped automatically; the cut result streams and re-streams live as you move the cutter. Scene Structure › Skip Boolean cutters turns it off.
  • Parenting. A Blender parent becomes a real actor attachment when both are tracked. A tracked child of an untracked parent sits at the root until you track the parent.
  • Root actor. Synced objects land under an actor named Loom by default; rename it under Root actor in the Loom window.
  • Target level. Synced actors spawn into the persistent level by default. Pick another loaded level under Target level to drop the synced scene there. Unreal cannot move an existing actor tree across levels in one step, so switching the target re-streams the scene into the chosen level.
  • Hand-edit protection. Blender is the source of truth; a hand-edit in Unreal is protected (updates pause) rather than overwritten, until you release it.
  • Per-object pause. Select synced actors and press Pause selected in the Loom tab to pin them, or Resume selected to let Blender drive them again. A paused actor carries a Loom.Paused tag, shown in its Details panel and searchable in the World Outliner.
  • Play and PIE. Live Blender edits stream into a running Play-in-Editor session.
  • Colliders and LOD. Name proxies with the UE collision prefixes (UCX_, UBX_, USP_, UCP_) plus Loom’s UMC_, and siblings <base>_LOD0..n for LODs.
  • Rigid bodies. A Blender rigid body arrives as a simulated body on the actor’s own component and simulates in PIE. The Loom window lists where your project’s physics settings differ from Blender’s, and Use Blender’s physics settings matches them, only when you click. Bakes keep the bodies unless you turn Rigid bodies off in the bake options.

Troubleshooting

  • No Loom tab. Confirm Loom Live Link is enabled in Edit → Plugins, then look under Tools → Loom or Window ▸ Loom.
  • Plugin will not build. Loom is a C++ editor plugin. Open it from a C++ project (or convert a Blueprint-only project once so the editor can compile modules). Win64 only.
  • Blender says “Waiting for the editor…”. Press Start Listener in the Loom tab first. This is a calm wait, not an error.
  • An object is not in Unreal. Select it in Blender and read Active Object: the status line names the reason and the pref that undoes it.
  • Materials look flat or default. Press Sync Materials. Materials do not ride the live geometry stream.
  • An assign from Unreal comes back refused. Either Accept property edits from the editor is off, or the object’s datablock is linked from another .blend. The message says which, and names the file.

The Unreal consumer is a peer of the Unity one on the same wire. The Blender half is in the Blender Producer Guide; see Architecture for the shared design.