🧱 matbridge

One command. Hundreds of materials. Blender and Unity, finally in sync.

matbridge automates the whole Poly Haven → Unity + Blender pipeline. It downloads textures, packs them for Unity, drops them into your project, and builds a matching Blender asset library, all with name-matched materials so your FBX exports link themselves up on import.

So you can stop dragging textures into slots by hand, and stop wondering why everything imported pink.

---

Why?

Moving a model from Blender to Unity is death by a thousand clicks.

You find a material, download the textures, and wire them up in Blender by hand. Then you build your model, export the FBX, drag it into Unity, and every material is blank. So you make a new material asset, copy the textures again, create the folders, and hook up every map one by one. 😤

matbridge kills that loop. Both sides build materials with the same names (M_oak_planks, M_brushed_metal, and so on), so Unity's FBX importer finds the matching .mat and links it for you. You model in Blender, drop the FBX in Unity, and the materials are already there.

You also stop hunting material sites mid-build. Pull once from Poly Haven and the whole library lives inside your project, in both Unity and Blender. Need a wooden box? Model it and grab the closest material you've already got, without switching tabs or downloading anything twice.

Pull ~750 production-ready PBR materials from Poly Haven into both tools in one run. ☕ Grab a coffee while it downloads.

---

What it does

       polydown                    Pillow
Poly Haven  ───►  ~/3D/Textures/PolyHaven/  ───►  metallicSmoothness PNGs
                              │
                              ├──────► Unity:   Assets/PolyHaven/{Textures,Materials}/
                              │                 + Assets/Editor/PolyHavenImporter.cs
                              │
                              └──────► Blender: ~/3D/BlenderLibrary/{wood,metal,...}.blend
                                                 + blender_assets.cats.txt

Four idempotent stages, one orchestrator. Run it all, or re-run any piece.

---

Features

• 🔗 Auto-linking materials — name-matched M_* materials mean zero manual reassignment on FBX import.
• 🎨 Both engines, one source — Unity and a browsable Blender asset library from the same textures.
• ♻️ Idempotent & resumable — every stage skips work that's already done. Crash halfway? Just run it again.
• 🧭 Smart categorization — materials auto-sort into Wood / Metal / Stone / … catalogs in Blender.
• 🧩 Render-pipeline aware — URP out of the box, with HDRP / Built-in switchable in one config line.
• 🔄 Normal-map smart — grabs both OpenGL and DirectX normals, feeds each tool what it wants, skips the bloat.

---

🚀 Quick start

Tip

Do a test run first with DOWNLOAD_LIMIT = 5 in cfg.py to verify everything works before pulling the full ~750-material library.

1. Edit cfg.py — at minimum, set:

Setting	What it is
TEXTURE_ROOT	Where textures get stored (e.g. ~/3D/Textures/PolyHaven)
UNITY_PROJECT	Path to your Unity project folder
BLENDER_LIBRARY	Where to write the Blender library
BLENDER_EXECUTABLE	Full path to blender if it's not on PATH
UNITY_SHADER	Change if you use HDRP or Built-in

2. Run the pipeline:

python run_all.py

Expect ~15–30 minutes for the full download on a 50 Mbps connection.

3. In Unity: open your project, wait for the C# script to recompile, then click Tools → Build PolyHaven Library. Materials appear in Assets/PolyHaven/Materials/.

4. In Blender: Edit → Preferences → File Paths → Asset Libraries → + and point at BLENDER_LIBRARY. Open the Asset Browser and pick that library from the dropdown.

5. Configure your Unity FBX importer defaults: Project Settings → Preset Manager. For new FBX imports, set the Materials tab to:

• Material Creation Mode: Standard
• Location: Use External Materials (Legacy)
• Naming: From Model's Material
• Search: Project-Wide

That's it. Any FBX from Blender with assigned M_* materials now auto-links on import. 🎉

---

Prerequisites

• Python 3.10+ with pip
• Blender 3.0+ on PATH (or set BLENDER_EXECUTABLE in cfg.py)
• Unity 2021.3+ with URP installed (HDRP / Built-in also work — change UNITY_SHADER)
• Python packages: polydown, Pillow (the pipeline installs polydown for you; install Pillow with pip install Pillow)

---

The files

File	Purpose
cfg.py	All paths, resolution, naming, options. Edit this first.
download.py	Stage 1 — invokes polydown to fetch textures.
pack_textures.py	Stage 2 — generates Unity MetallicSmoothness PNGs.
deploy_unity.py	Stage 3 — copies textures into Unity, writes PolyHavenImporter.cs.
build_blender_library.py	Stage 4 — runs inside Blender (--background) to build the asset library.
run_all.py	Orchestrator — runs all four stages.

---

Re-running

Each stage is independent and idempotent:

python download.py           # re-download (skips existing files)
python pack_textures.py      # re-pack MS maps
python deploy_unity.py       # re-copy textures + rewrite C# script
blender --background --python build_blender_library.py

Or with the orchestrator:

python run_all.py --skip-download --skip-pack    # just re-deploy

Set OVERWRITE_EXISTING = True in cfg.py to force overwrites.

---

⚠️ Gotchas

Naming consistency — don't change MATERIAL_PREFIX mid-project

Both sides hardcode MATERIAL_PREFIX from cfg.py. Change it mid-project and your Blender library ends up with M_oak_planks while Unity has Oak_planks — and the FBX auto-link breaks. Pick a convention, stick to it.

Normal map convention (OpenGL vs DirectX)

The pipeline downloads BOTH nor_gl (OpenGL) and nor_dx (DirectX). Blender uses nor_gl natively; Unity uses nor_dx. Disk cost: ~150 MB extra over the full library. The Unity deploy step skips copying nor_gl if nor_dx exists, so your Unity project doesn't get bloated.

If you only have nor_gl, both pipelines fall back: the Blender script wires it directly, and the Unity C# sets flipGreenChannel = true on import.

Render pipeline — shader property names differ on HDRP

UNITY_SHADER defaults to Universal Render Pipeline/Lit. If your project uses HDRP or Built-in, change it before running. The shader properties the C# script writes to (_BaseMap, _BumpMap, _MetallicGlossMap, _OcclusionMap) are URP/Built-in. HDRP/Lit uses different names (_BaseColorMap, _NormalMap, _MaskMap) — for HDRP you'd want to edit the C# template in deploy_unity.py.

Blender thumbnail previews in background mode

preview_ensure() may not actually render previews when Blender runs headlessly — the rendering pipeline expects a viewport. If thumbnails are missing the first time you open the Asset Browser, Blender generates them lazily as you scroll. You can also force them via Asset Browser → right-click → Generate Preview.

Texture paths — moving TEXTURE_ROOT breaks the Blender library

The Blender library references textures at their absolute path in TEXTURE_ROOT. If you move that folder, the Blender library breaks. Either keep TEXTURE_ROOT permanent, or set BLENDER_PACK_TEXTURES = True in cfg.py to embed textures in the .blend files (cost: ~500 MB–1 GB extra across all category files).

Unity is unaffected — we copy textures into the project.

Category detection is heuristic

The keyword matcher in build_blender_library.py is heuristic — slugs like steel_painted_floor land in "Metal" even though the material is predominantly painted. You can:

• Adjust CATEGORY_KEYWORDS in build_blender_library.py, or
• Fix individual materials manually in Blender after the fact (catalog UUIDs live in blender_assets.cats.txt, so reassignment is easy).

---

Storage estimates

For ~750 materials at 1k JPG:

Location	Approx. size
TEXTURE_ROOT	500 MB – 1.2 GB
Unity Assets/PolyHaven/	400 MB – 1 GB (skips nor_gl)
Blender library (unpacked)	< 50 MB total (just .blend metadata)
Blender library (packed)	500 MB – 1.2 GB

---

Troubleshooting

Symptom	Fix
polydown: command not found	Script auto-installs it, but if pip isn't on PATH: python -m pip install polydown
Pillow import error	pip install Pillow
Unity says "Shader not found"	Install URP (Window → Package Manager → Unity Registry → Universal RP), or set UNITY_SHADER to your active shader
Materials all look pink in Unity	Wrong shader for your render pipeline — pink means the shader failed to compile or is missing. Check UNITY_SHADER.
Blender materials have inverted bumps	Script picked up nor_dx instead of nor_gl — check nor_gl was downloaded
Blender library doesn't appear in Asset Browser	Make sure you added BLENDER_LIBRARY itself (not its parent), and that blender_assets.cats.txt is in that folder

---

Built for people who'd rather make things than wire texture slots. 🛠️

_{Textures courtesy of Poly Haven — CC0. Go support them.}