unity-to-glb User Guide
Batch-convert Unity content to GLB files with textured PBR materials. Three entry points: shipped Unity games, .unitypackage archives, and plain folders of .fbx files. macOS arm64 binary ships inside the package; no .NET or Unity install required at runtime.
Installation
Verify:
The tool bundles three pieces: a C# native binary built on AssetRipper for cooked projects + shipped games, the fbx2gltf npm package for raw FBX conversion, and a TypeScript orchestrator that glues them together.
Quick Start
Pick the command that matches your input:
Each produces ./out/<path>/<asset>.glb mirroring the source hierarchy, plus ./out/_report.json summarizing what was converted and what was skipped.
Three Commands, Three Inputs
| Your input | Use |
|---|---|
Raw Unity project with a built Library/ cache | convert |
Shipped Unity game (the <Game>_Data/ folder inside a .app, or alongside a .exe) | convert |
Unity Asset Store .unitypackage file | unpackage |
Folder of .fbx files with no Unity metadata | fbx |
convert — AssetRipper path
Handles cooked Unity content. Requires either (a) a Unity project whose Library/ was populated by opening it once in Unity Editor, or (b) a shipped game's <Game>_Data/ folder.
Unity's standard shader properties (_MainTex, _BumpMap, _MetallicGlossMap, _OcclusionMap, _EmissionMap) are mapped onto glTF PBR channels automatically. _MetallicGlossMap gets channel-swizzled: Unity's R=metal / A=smoothness becomes glTF's G=roughness / B=metal.
unpackage — Unity Asset Store packages
A .unitypackage is a gzipped tar of GUID-named directories. It does not contain Unity's serialized Library/, so the AssetRipper path can't read it directly. Instead this command extracts the archive, reconstructs the Assets/ tree, and converts each raw .fbx inside it via FBX2glTF.
Output preserves the package's Assets/ hierarchy (without the leading Assets/ segment).
Caveat: Unity .mat / .prefab / .unity YAML files inside the package are not converted by this flow — they require a Unity-built Library/. Import the package into Unity first and run convert if you need authored materials or scene hierarchies.
fbx — Raw FBX folders
For assets that arrive as plain FBX files with no Unity wrapper at all — Synty "SourceFiles" drops, ArtStation packs, anything else. Recursive by default.
Palette Wiring for Synty / Low-Poly Packs
Synty packs (and many low-poly asset packs) share a single palette texture across hundreds of meshes — the mesh UVs point to specific colored regions. The FBX binaries themselves reference .psd files at authoring paths that no longer exist when you unzip the download, so FBX2glTF writes meshes with bare grey materials.
If the pack ships a MaterialList_*.txt index and a sibling Textures/ folder, wire them up with two flags:
The parser handles Synty's indentation-based format:
For every GLB whose mesh name appears in the list, the tool reads the corresponding PNG from --textures and wires it as baseColorTexture. Verified against a real Synty pack: 1187 of 1193 meshes wired correctly; the 6 stragglers are particle FX meshes that Unity assigns materials to at runtime and simply don't appear in the MaterialList.
Material Mapping Reference
Unity standard / URP Lit shaders (used by convert)
| Unity property | glTF channel |
|---|---|
_MainTex, _BaseMap, _BaseColorMap | baseColorTexture |
_BumpMap, _NormalMap, _DetailNormalMap | normalTexture |
_MetallicGlossMap, _SpecGlossMap, _MetallicSmoothnessMap | metallicRoughnessTexture (R=metal, A=smooth swizzled → G=rough, B=metal) |
_OcclusionMap, _AOMap | occlusionTexture |
_EmissionMap, _EmissiveMap | emissiveTexture |
_Metallic (float) | metallicFactor |
_Glossiness, _Smoothness (float) | roughnessFactor (inverted: 1 − value) |
Properties outside this set land as warnings in _report.json.
FBX-embedded materials (used by unpackage and fbx)
FBX2glTF consumes whatever the FBX binary embeds: typically one diffuse texture per material, plus scalar PBR factors if the FBX was authored with them. Normal / metallic / AO / emission maps rarely survive the Unity → FBX round-trip unless the source pack went out of its way to embed them.
Output Structure
_report.json
Scan warnings for specific asset failures. paletteWired only appears on fbx runs that used --material-list.
Examples
Convert a shipped game, compress textures, drop normal/metallic channels
Convert a Synty pack end-to-end (the common case)
Debug a single asset inside a .unitypackage
Troubleshooting
unpackage produces 0 GLBs even though the package has models
The archive may not contain .fbx files — some asset store packs ship only .mesh or Unity-serialized binaries. Check the extracted Assets/ tree with --keep-staging and confirm there are raw FBXs present.
"Just yellow" / bare grey materials after an fbx run
The FBX files reference textures that FBX2glTF couldn't find. If the pack includes a MaterialList_*.txt index, pass --material-list and --textures. For generic FBXs, copy the referenced textures into the same folder as the FBX before running.
convert returns 0 assets on a raw Unity project
You need a built Library/ cache. Open the project in Unity Editor once (let it import). Then re-run convert.
macOS Gatekeeper flags the bundled binaries
The native Unity extractor and FBX2glTF binary aren't notarized. Run once:
Known CUE4Parse-style AnimSequence warnings (AssetRipper path)
Occasional Object reference not set errors on animations in some Unity versions. Meshes still export correctly. Warnings are non-fatal.
How It Works
Two-phase wherever possible: a dedicated parser writes intermediate artifacts to a staging directory, then a TypeScript post-processor reads them, wires materials, and streams final GLBs into the output directory as each finishes.
Source + License
- GitHub: babylonjsmarket/unity-to-glb
- npm: @babylonjsmarket/unity-to-glb
- License: GPL-3.0-or-later (AssetRipper is GPL-3.0; our tool inherits). You can modify and redistribute the source freely; GLB outputs are unrestricted.