Unitypackage Importer for Blender

English | 日本語 | Website | GitHub

A Blender Extension that imports .unitypackage files directly from File > Import, placing meshes (including armatures and shape keys) with the material settings and textures from the Unity side applied.

• Supported Blender: 4.5 or later (developed on 5.2 LTS, tested on 4.5 LTS and 5.2 LTS)
• What is imported: FBX / OBJ / glTF / VRM / Collada (Blender 4.5 only; removed in Blender 5.0) / bundled .blend files (opt-in), .mat files (lilToon / MToon / Poiyomi / Standard / URP / HDRP / VRChat Mobile (Quest) shaders; others on a best-effort basis using generic rules), and referenced textures
• What is not imported: shader source code, C# scripts, animations, Expression menus, etc. Prefab hierarchies, lights and cameras are reproduced only when a scene is imported.
• VRM: when the VRM format add-on is installed, .vrm models are handed to it (MToon materials, humanoid rig, spring bones and expressions are reproduced by the add-on). Without it, the glTF importer is used and materials are rebuilt from the bundled .mat files.

Installation

There are three sources and they all ship the same extension. Install from only one of them (see "Switching sources" below).

Register as an Extension Repository (recommended)

The extension is distributed via GitHub Pages. In Blender, open Preferences > Get Extensions > Repositories, click "+", choose "Add Remote Repository", and register the following URL. You can then install and update the extension from the list, and new versions show up as updates in Blender.

https://utagestudio.github.io/unitypackage_loader/index.json

The same page (the URL without index.json) shows the registration URL and a link to the zip.

extensions.blender.org (under review)

The extension has been submitted to Blender's official extensions platform. Once it is listed, you will be able to search for "Unitypackage" in Preferences > Get Extensions and install it from there.

Install from a zip

Drag the zip from the website onto the Blender window, or load it with "Install from Disk" in the menu at the upper right of Preferences > Get Extensions. Installed this way, the extension is not updated automatically. The same zip is also available for free on BOOTH, with optional support versions that contain the same file.

Switching sources

Blender treats each source (repository) as a separate extension. If the add-on is installed from two sources, both are enabled and override each other's features, so it stops working correctly. To switch, uninstall the current copy in Preferences > Get Extensions first, then install from the new source. Preferences are stored per source and are not carried over.

During development (use the repository directly)

ln -s "$PWD/unitypackage_loader" ~/.config/blender/5.2/extensions/user_default/unitypackage_loader

In Blender, open Preferences > Get Extensions, run "Refresh Local" from the menu in the upper right, and enable "Unitypackage Importer". Uninstall any copy from another source first.

Build the distribution zip with:

blender --command extension build --source-dir unitypackage_loader --output-dir dist

The website and the Extension Repository are generated by .github/workflows/pages.yml on every push to main (it runs Blender's extension build and extension server-generate in CI). Once, on first setup, set the repository's Settings > Pages > Source to "GitHub Actions".

Usage

• Drag and drop: drop a .unitypackage onto the 3D Viewport to open a popup with import options. Multiple files can be dropped at once.
• Menu: choose File > Import > Unitypackage (.unitypackage), pick the file in the file browser, adjust the options on the right as needed, and click Import.

The options show Material Mode and Scale; everything else is folded into the Model / Materials / Textures sections.

Section	Option	Description
(always shown)	Material Mode	Auto (Toon for toon-style shaders, Principled for PBR) / Principled BSDF / Toon (Node Group) / Unlit (Emission) / Names Only
	Scale	Scale passed to the model importer
Model	FBX Importer	Prefer the new C++ importer (Auto) / choose explicitly
	VRM via VRM Add-on	Import .vrm with the VRM format add-on when installed (default ON); otherwise fall back to the glTF importer and rebuild materials from .mat
	Import Bundled .blend Files	Append objects from .blend files inside the package (default OFF). See Security notes
Materials	Force Opaque	Ignore Unity's Cutout / Transparent settings
	Backface Culling / Normal Maps / Emission	Whether to apply each element
	Outlines (Solidify)	Add a Solidify outline from Unity's outline color and width (converted with Width Scale)
	Reuse Existing Materials	Reuse a material with the same name if one already exists instead of rebuilding it
	Bundled .blend Materials	Keep (default) / Rebuild materials from bundled .blend files (only when the option above is on)
	Store Unity Properties	Store GUIDs, shadow colors, etc. as custom properties
Textures	Extract To	Beside .blend (//textures/<package name>/) / Add-on Cache / Custom Path
	Pack Into .blend	Pack images into the .blend file
	Import Unreferenced Images	Also load images not referenced by any material (masks, icons, etc.) as image data

A summary appears in the Info bar. The "UPI" tab in the 3D View sidebar (N key) shows counts, per-material resolution status, and warnings. The system console prints details (the matched .mat for each material, textures used, and warnings). A Collection named after the package is created and the objects are placed in it.

Choosing what to import

When the package has more than one scene, prefab or model to choose from, a selection dialog opens after the options. Choose the unit at the top, then tick what to import in the list. In Scenes only the first importable scene is ticked by default, since importing several scenes at once tends to overlap buildings and lights (Prefabs and Models are all ticked):

• Scenes: imports what a scene (.unity) places, at the positions, rotations and scales set in Unity. Each scene gets its own Collection; the GameObjects above the models are recreated as Empties, and inactive objects are hidden. Only the scene's contents are imported. Copies of the same model with the same materials share their mesh data. Small props copied side by side under a common parent in Unity (for example several cups in a room) are placed one by one. Parts of a model file that a prefab or the scene does not use (for example unused LODs, extra nodes, or the other pieces of a model file that bundles many props) are not imported, matched by the mesh each Unity renderer references (turn off Unused Parts in the dialog to import them hidden instead). Where Unity has an LODGroup, only the most detailed level (LOD0) stays visible: the distant levels are imported and hidden (toggle this with LODs in the dialog; the hidden objects stay in the file and keep their level in the unity_lod custom property). Lights and cameras are imported too (toggle them with "Also Import"): light intensity is converted from values measured in Unity (Built-in and URP) and Blender's EEVEE, and the original values are kept as custom properties. The render pipeline is detected from the URP / HDRP additional data on lights and cameras, and from the materials' shaders. For HDRP scenes, the lights are scaled by the Volume's exposure (toggle it with Exposure in the dialog; automatic exposure is approximated with its upper limit). The Blender scene's exposure (Color Management) is left unchanged, so scenes from different pipelines can be mixed in one Blender scene. Lights that only affect lightmaps in Unity (baked and area lights) become real-time lights and are listed in the warnings. UI, terrain and meshes that are not in the package (such as Unity's built-in primitives) are not imported and are reported as warnings. For a model file (FBX) placed directly, the position of its root is read. Changes to objects inside it (materials, positions of parts such as open doors) are applied when the model's .meta is in the format of Unity 2018.2 and earlier, which has a name table; otherwise they are counted in the warnings.
• Prefabs: imports each prefab with its own material assignments, in its own Collection inside the package Collection. Color variants that share a model can be imported together. When two or more prefabs are selected, Arrange places them Side by Side (next to each other without overlapping, wrapping into a grid when there are many) or Stack at Origin. Prefabs with an LODGroup hide their distant LOD levels, and parts of a model file that the prefab does not use are not imported, as in scenes.
• Models: imports the model files (FBX etc.) as they are. Materials are resolved as described in .

One import uses one unit, so the same model is not imported twice by accident. Items that cannot be imported stay in the list, greyed out with the reason (for example no mesh in package or .blend import disabled). The dialog remembers the unit and the arrangement chosen last. With the Prefabs unit, the layout inside a prefab (positions of its child objects) is not reproduced: every model of a prefab is placed at the origin of the prefab's Collection. Import a scene that places the prefab to get the layout.

Defaults can be changed in Preferences (Edit > Preferences > Add-ons > Unitypackage Importer), including whether the selection dialog opens (Selection Dialog: Ask / All Models / First Model Only) and Arrange Prefabs. You can also register an additional GUID table for custom shaders (a JSON file in the same format as shader_guids.json). "Max Extract Size" (default 8 GiB, 0 = no limit) refuses an import before writing anything when the files to extract from one package would exceed it or the free space of the destination.

Security notes

• Bundled .blend files are not imported by default. A .blend can carry Python code (driver expressions, registered text blocks) that Blender runs when "Auto Run Python Scripts" is enabled, so appending a .blend from an untrusted package is equivalent to running its scripts. Turn on "Import Bundled .blend Files" only for packages you trust, and keep "Auto Run Python Scripts" off unless you need it.
• The add-on itself never executes code from the package. C# scripts, shaders, Python and other assets are ignored. Only the following are extracted to disk or read: model files (.fbx .obj .gltf .glb .vrm .dae, and .blend only with the option above), the textures referenced by materials (every image with "Import Unreferenced Images"), the .mtl next to an .obj and the .bin next to a .gltf. .mat, .meta and .prefab files are parsed in memory with the add-on's own readers (Unity YAML text, or Unity's binary serialized format) and never written out.
• Parsing the model and image files is done by Blender itself, not by this add-on: FBX / OBJ / glTF / Collada by Blender's importers, and PNG / TIFF / TGA / EXR / PSD etc. by its image libraries (OpenImageIO and friends). A crafted file that targets a bug in those components cannot be blocked here. Keep Blender on the latest LTS release, and open packages from unknown sources in an isolated environment (a virtual machine, a sandbox, or a separate Blender installation without other add-ons).
• Archive handling is hardened against common tricks: paths are validated (no .., absolute paths, drive letters, reserved device names or control characters), symbolic links are never followed while extracting, oversized metadata is ignored, and the total size to extract is checked against "Max Extract Size" and the free disk space before writing.

Matching meshes to materials

Materials are resolved in this order:

1. The "material name → .mat" entries in the model's .meta (ModelImporter externalObjects)
2. A .mat with a matching name (if several share the name, the one closest to the model's folder wins)
3. The .mat held for the same submesh by the Renderer of a GameObject with the same name inside a prefab

Materials that match none of these are left as the importer created them and are reported as warnings.

What Unity actually renders is the material set on a prefab's Renderer, so when a prefab assigns a .mat, it takes precedence over steps 1 and 2. For packages where the FBX shares a small number of materials and the prefab assigns a different .mat per part on the Unity side, Blender materials are split per slot following the prefab's assignments. When the model itself has no materials at all, a slot is created from the prefab's assignment and filled. A prefab's Renderers are applied only to the model whose mesh they reference, so objects with the same name in another model are not affected. With the Models unit, when several prefabs use the same model (for example, color variants), their assignments are merged, with the first one by path taking precedence; to use a specific prefab's assignments, import that prefab with the Prefabs unit. Material overrides in Prefab Variants and nested prefabs are read when the source is a prefab in the package; overrides applied directly to a model (FBX) instance are applied when a scene is imported and the model's .meta is in the Unity 2018.2-and-earlier format (which has a name table). Without a name table, material overrides are still applied when the model has only one mesh (so the overridden renderer is certain); otherwise they are reported as a warning. A prefab lists its materials in Unity's submesh order (the order in which the mesh's polygons first use each material), which can differ from Blender's slot order, so the entries are matched to slots in that order.

Selecting multiple .unitypackage files in the file browser imports them in one batch (one Collection per package, every model with the Models unit, without the selection dialog).

Material conversion policy

Unity shaders and Blender nodes do not map 1:1, so conversion happens in two stages: .mat → a shader-independent intermediate representation → Blender nodes.

• Toon (Node Group): the UnityToon node group reproduces shadow color (border, blur, strength), MatCap (Normal / Add / Screen / Multiply), rim light, emission, and alpha. It uses Shader to RGB for lighting, so it is intended for EEVEE (no shading in Cycles).
• Principled BSDF: connects base color, normal, emission, and Metallic / Roughness. The specular color of URP's specular workflow and Simple Lit, and of HDRP's Specular Color, is approximated with IOR and Specular Tint. HDRP's mask map is wired into Metallic and Roughness with its remap ranges applied.
• Unlit (Emission): the simplest setup, wiring the texture straight into Emission with no lighting.

There are dedicated rules for lilToon / Poiyomi / MToon / VRChat Mobile, Built-in Standard, URP (Lit / Complex Lit / Simple Lit / Unlit / Baked Lit) and HDRP (Lit / the first layer of LayeredLit / Unlit); other shaders are read from common property names. A material whose shader was switched can keep the previous shader's settings, so URP and HDRP materials are read only by that pipeline's names. When the shader's source (a Shader Graph or .shader) is in the package, settings the shader does not declare are ignored (the shader's logic itself is not interpreted, so shaders that build their color from custom names may come in white).

The intermediate representation itself is stored in the custom property unity_normalized (JSON), and values not used by Blender are stored in unity_props. "Rebuild in Another Mode" in the sidebar's Tools panel rebuilds the materials of the selected meshes in a different mode without the original package; its options (Force Opaque and so on) start from the settings used at import (or the last rebuild). Outlines can be added and removed from the same panel.

Development

# Unit tests (no bpy required)
python3 -m unittest discover -s tests -t .

# Generate a synthetic package (no real assets required) and run the integration test with it
blender -b --factory-startup --python tests/make_synthetic_package.py
blender -b --factory-startup --python tests/integration_import.py -- _local/unitypackages/synthetic_multi.unitypackage tests/expectations_synthetic.json

# Integration test with a real package on your machine (package in _local/unitypackages/, expectations.json in _local/)
blender -b --factory-startup --python tests/integration_import.py

Pull requests and pushes to main / release branches run .github/workflows/tests.yml: the unit tests on Python 3.11 and 3.13 (the versions bundled with Blender 4.5 and 5.2), and the integration tests with the synthetic packages on Blender 4.5 LTS and 5.2 LTS.

Test data (unitypackage files, extracted contents, expected values) goes in _local/ (packages themselves in _local/unitypackages/). This directory is gitignored, and the data of the assets used for testing is never committed (the committed test data is synthetic only). See tests/expectations.schema.md for the file format.

See DESIGN.md for design details.

Directory layout

unitypackage_loader/         The Extension itself
  blender_manifest.toml
  core/                      bpy-independent (YAML parser, tar index, .meta, material normalization, GUID tables)
  blender/                   bpy-dependent (import execution, node building, image loading)
  operators/                 File > Import operator and the model selection dialog
  ui/                        Preferences and the sidebar report panel
tests/                       Unit tests, integration tests, synthetic package generation

Feedback and bug reports

Bug reports, requests, and questions can be sent through the contact form (no account required). If you have a GitHub account, Issues works as well.

License

GPL-3.0-or-later (LICENSE), in line with the requirements for distribution as a Blender Extension.

The shader GUIDs in unitypackage_loader/core/profiles/shader_guids.json are identifiers collected from the .shader.meta files of the public repositories lilxyzw/lilToon and vrm-c/UniVRM (both MIT License), from the VRChat SDK's Mobile shaders (Sample Assets/Shaders/Mobile) as mirrored in public repositories, and from URP / HDRP (com.unity.render-pipelines.universal / high-definition 17.6) as bundled with Unity 6000.6. The GUIDs of the light additional-data, Volume and Exposure scripts (core/lights.py / core/exposure.py) are identifiers collected from the .cs.meta files of the same URP / HDRP / core packages. No shader or script code is included.

Reading binary .mat / .prefab files (unitypackage_loader/core/unity_binary.py) follows the descriptions in the public projects K0lb3/UnityPy (Copyright (c) 2019-2026 K0lb3) and Perfare/AssetStudio (Copyright (c) 2016 Radu, Copyright (c) 2016-2020 Perfare), both under the MIT License. The common string table in that file (a list of Unity type and field names) is the same table both projects publish. No code from them is included.

lilToon, MToon, Poiyomi, VRChat, Unity, and other names are trademarks or product names of their respective owners. This add-on is not affiliated with Unity Technologies, VRChat Inc., or any of the shader authors.