Skip to content
Desuq Café
Documentation menu

Unity Quick Start

Stream your Blender scene live into the Unity editor, then bake it to real prefabs. This guide gets you from install to a synced scene in a few minutes.

Requirements: Blender 5.0+, Unity 2021.3 LTS or newer with the Universal Render Pipeline (URP), both on the same machine (loopback TCP).

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 Unity package

  1. In Unity, open Window → Package Manager.
  2. Click + → Add package from disk… and select unity/com.desu.loom/package.json. A UPM git-URL install also works.
  3. Make sure your project uses URP. Loom’s generated shaders target it, and it logs a warning in the Console if URP is not active.

3. Connect

  1. In Unity, open 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 Unity window shows Connected, is streaming, and your synced objects appear under a single Loom GameObject (rename it under Root object) in the active scene.

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 Unity live. Moving an object sends a tiny transform packet, and sculpting or animating streams positions only.

What you are looking at is a stand-in. The objects Loom places are live previews and are not saved with the scene; 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 scene, and the Loom window 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 (or the Unity window) to push Principled materials and node-graph shaders. Supported graphs become real compiled URP shaders, and unsupported ones fall back to a faithful Principled material. The diagnostics panel tells you which.

Stylized and toon materials (lilToon, UTS, custom)

A non-Principled material has no PBR factors to translate, so Loom will not fake its look on URP/Lit. 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 toon shader with them. Two steps:

  1. Pin your shader. Assign a LoomMaterialOverrides asset mapping the Blender material’s uid, or name, to your toon Material.
  2. Route the maps. Set LoomSession.NamedTextureRules (persisted in EditorPrefs as Loom.NamedTextureRules), a ;-separated list of pattern=parameter rules. Each pattern is a case-insensitive substring of the Blender image name; each parameter is a texture property on your pinned shader. For example _base=_MainTex;_ilm=_ShadowColorTex;_sss=_SubsurfaceTex.

Loom instances the pinned material, so the shared asset is never mutated, and sets those texture properties from the synced maps. There is no window UI for this yet; it is prefs-first.

5. Bake to a prefab

When you are happy with the preview, press Bake to Prefab… in the Unity window. Loom dedups shared meshes and generated materials into single assets, writes node-graph shaders as real .shader files, and saves a prefab over the synced tree. Toggle lightmap UVs, LOD groups and colliders at bake time.

To bake only part of the scene, select any synced objects in the Hierarchy and press Bake Selected…. Loom bakes those subtrees plus the ancestors needed to keep their transforms, and leaves everything else out.

6. Replace greybox with your real prefabs

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 Unity, create a Loom › Prefab Registry asset (Assets ▸ Create) and fill the table: key → the prefab to spawn.
  3. Open the Loom window ▸ OVERRIDES & REGISTRIES ▸ Prefab Registry and pick the asset.

Every keyed object then spawns your prefab 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 prefab changed.

Assign from Unity. You do not have to go back to Blender. Select synced objects in the Hierarchy and open the Loom window ▸ REPLACE GREYBOX. The summary says what you picked and who owns it — Pillar_Grey.003 · greybox mesh · shared by 90 synced objects, with Blender owns this geometry until you assign a key. underneath. Apply to chooses All 90 sharing the mesh or This placement only, and the warning above the buttons states the blast radius before you press anything: Replaces 90 placements. Their Blender geometry stops streaming; the prefab becomes the source of truth. Undo in Blender (Ctrl+Z). Assign writes it, Clear to greybox takes it back, and the status line reports what Blender actually answered.

Variants, by name. A registry key can list variants — the base prefab plus alternates. Each placement picks one by index or, better, by the variant asset’s name: index 2 means a different piece the moment someone inserts a row, a name does not. A name that is not in the pool shows the base prefab and logs a warning, never a silent wrong piece.

Scatter a pool. Ninety copies of one pillar all showing the same variant is not a level. With keyed placements selected, press Scatter pool…, set a Seed, and press Scatter. One loom_variant per placement is written into the .blend, so the arrangement survives a resync and Ctrl+Z in Blender takes it back. The same seed over the same placements produces the same layout in Blender and in both engines.

Blockouts and PREFAB CHECK. Mark stand-ins as blockouts, in Blender or by right-clicking a synced object’s status dot in the Hierarchy ▸ Loom › Mark as blockout. PREFAB CHECK then lists every key in the scene with its placements 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 progress line.

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. Nothing is applied locally first, so a refused write leaves nothing to undo in Unity.

How replacement works › on the REPLACE GREYBOX header opens a four-page explainer: What streams, What a key does, Variants and pools, Greybox → final. It also has its own menu entry, Window ▸ Loom Guide. 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-controller prefab. It lands where the empty is, live colliders already work, and Sync during Play keeps the level updating while you run around in it.

7. Colour blocking: override every synced material

Sometimes you want to see the level, not the materials. In the Loom window, open OVERRIDES & REGISTRIES:

  1. Global Material — pick any Material asset, such as a colour-blocking or vertex-colour shader.
  2. Override all synced materials — turn it on. Every synced object is drawn with that one Material immediately; turn it off and everything snaps back.

Prefab-reference instances keep their own materials, because they are your finished assets rather than blockouts. Bakes always use the real materials: Bake to Prefab…, Bake Selected… and the headless bake lift the override for the duration of the bake and put it back afterwards. The choice survives domain reloads and editor restarts.

Vertex colours are already on every synced mesh, so any Unity material that reads them just works. If the Blender material itself uses a Color Attribute node, Loom’s generated shader renders it with no override needed.

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 Unity only when you Untrack it. Exclude / Include work in any scope; an excluded object never streams and is removed from Unity the moment you exclude it. 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, while the cut result streams and re-streams live as you move the cutter. Turn it off under Scene Structure › Skip Boolean cutters.
  • Parenting. A Blender parent becomes a real Unity hierarchy link when both are tracked. A tracked child of an untracked parent sits at the root until you track the parent.
  • Root object. Synced objects land under a GameObject named Loom by default. Rename it under Root object in the Loom window; it renames the existing root live.
  • Target scene. Pick another open, saved scene under Target scene to drop the whole synced tree there instead of the active scene.
  • Hand-edit protection. Blender is the source of truth, but if you nudge a synced object in Unity, Loom pauses updates to it rather than overwriting, until you press Release all.
  • Per-object status and pause. Each synced object shows a status dot on its Hierarchy row (green streaming, amber paused). Right-click the dot for Pause Loom sync (protect from Blender) or Resume Loom sync, without opening the Loom window.
  • Two-way edits. Flip Push edits to Blender to send transform and selection changes back.
  • Play mode. Enable Sync during Play to stream live edits into a running Play session. It keeps ticking even when Unity is unfocused.
  • Colliders and LOD. Name proxies UCX_, UBX_, USP_, UCP_, UMC_ and siblings <base>_LOD0..n. They become Unity colliders and LODGroups live and at bake.
  • Rigid bodies. A Blender rigid body arrives as a Rigidbody, a collider and a physics material, and simulates when you press Play. The PHYSICS section of the Loom window lists where your project’s gravity, physics step and friction model differ from Blender’s, and Use Blender’s physics settings matches them; they are project-wide, so Loom changes them only when you click. Bakes keep the bodies unless you turn Rigid bodies off in the bake options.

Troubleshooting

  • Blender says “Waiting for the editor…”. Press Start Listener in the Unity window first. This is a calm wait, not an error.
  • An object is not in Unity. 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.
  • Nothing renders, or it is pink. Confirm the project is on URP — Loom warns in the Console if it is not.
  • An assign from Unity 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.
  • Background updates feel slow. Unity throttles its background repaint. Raise it under Preferences ▸ General ▸ Interaction Mode ▸ “No Throttling”.

The Blender half is in the Blender Producer Guide. See Architecture for how the link works.