UnityGLTF

Unity3D library for importing and exporting glTF 2.0 assets.

	Editor	Runtime
Import	✅	✅
Export	✅	✅

UnityGLTF doesn't have any native dependencies (pure C#) and thus works on all platforms that Unity supports. This includes WebGL import and export.

The library is designed to be easy to extend with additional extensions to the glTF specification. Both import and export allow attaching custom plugins and callbacks and can be heavily modified to fit into specific pipelines. Many glTF extensions are supported.

Contents

• Installation
• Unity Version and Render Pipeline Compatibility
• UnityGLTF and glTFast
• Supported Features and Extensions
  • Import and Export
  • Import only
  • Export only
• glTF Interactivity
  • Visual Scripting Graph Exporter
  • Features
  • Unsupported
  • Viewer support
• glTF Materials
  • Material Conversions
  • Material and Shader Export Compatibility
  • Configure for Refractive Materials (Transmission and Volume)
    • Material Setup
    • URP
    • Built-In
    • HDRP
• Exporting glTF Files
  • Testing, debugging, compatibility
• Animation Export
  • Animator Controller
  • GLTFRecorder API
  • Timeline Recorder
  • Legacy Animation Component
  • KHR_animation_pointer support
• Blend Shape Export
• Importing glTF files
  • Runtime Import
    • Load via Gltf Component
    • Load via code example:
  • Ensure shaders are available in your build
  • Editor Import
  • Default Importer Selection
• Animation Import
• Extensibility
  • Example for custom export plugin
  • Example for custom import plugin
• Known Issues
• Contributing
  • Unity Package
  • GLTFSerializer
  • Tests

Installation

You can install this package from the Needle Package Registry with a one-click installer:

1. Download UnityGLTF Package Installer
2. Drop the downloaded .unitypackage into Unity and follow the steps.

You can also install this package from git, compatible with UPM (Unity Package Manager).

1. Open Window > Package Manager
2. Click +
3. Select Add Package from git URL
4. Paste
   复制

   https://github.com/KhronosGroup/UnityGLTF.git

5. Click Add.

Note: If you want to target a specific version, append #release/<some-tag> or a specific commit to the URL above. Example: https://github.com/KhronosGroup/UnityGLTF.git#release/2.14.1.

Unity Version and Render Pipeline Compatibility

Please use Long-Term Support versions of Unity (2021.3+, 2022.3+, 6000.0+).

Recommended:

• Unity 2021.3+, Unity 2022.3+, Unity 6+
• Linear colorspace
• Universal Render Pipeline (URP) and Built-In Render Pipeline (BiRP)

HDRP:

• Currently limited functionality.

Legacy:

• When using Unity 2020.3, please use an older version of UnityGLTF, like 2.9.1-rc and before.

Note: Issues on non-LTS Unity versions (not on 2021.3, 2022.3, 6000.0...) will most likely not be addressed. Please use LTS (Long-Term Support) versions where possible.

UnityGLTF and glTFast

A separate glTF implementation for Unity, glTFast, is available from the Unity Registry.
glTFast being supported by Unity means, in a nutshell, that it sticks to standards pretty strictly and can't easily ship non-ratified extensions or experimental features that work for the majority, but not all, of users.

• UnityGLTF aims to be the more flexible framework, with extensive import/export plugin support and useful plugins out of the box.
• glTFast aims to be the more performant framework, with a focus on leveraging Unity-specific features such as Burst and Jobs.
• UnityGLTF has a versatile plugin/extension infrastructure. This allows for a lot of flexibility during import/export.
• UnityGLTF enables the use of and ships with non-ratified extensions such as KHR_animation_pointer, KHR_audio, and KHR_materials_variants.
• glTFast leverages Unity-specific features such as Burst and Jobs and thus can have better performance in some cases.
• glTFast has better HDRP support.

glTFast and UnityGLTF can coexist in the same project; you can for example use glTFast for import and UnityGLTF for export.
For imported assets, you can choose which importer to use with a dropdown.
glTFast import has precedence if both are in the same project. See also Default Importer Selection.

Supported Features and Extensions

The lists below are non-conclusive and in no particular order. Note that there are gaps where features could easily be supported for im- and export but currently aren't. PRs welcome!

Import and Export

• Animation and Animator with multiple clips
• Skinned Mesh Renderers
• Blend Shapes
  • Sparse accessors for Blend Shapes
• Linear and Gamma colorspace support (Gamma won't be maintained anymore)
• Vertex Colors
• Cameras (perspective, orthographic)
• URP and Built-In Render Pipeline Learn More
• KHR_lights_punctual (point, spot, and directional lights)
• KHR_texture_transform (UV offset, scale, rotation)
• KHR_materials_unlit (unlit surfaces)
• KHR_materials_transmission (glass-like materials)
• KHR_materials_volume (refractive materials)
• KHR_materials_ior (for transmission and volume)
• KHR_materials_emissive_strength (emissive values greater than 1)
• KHR_materials_iridescence (thin-film interference, like oil on water)
• KHR_materials_clearcoat (secondary specular layer, like a coat of varnish)
• KHR_materials_sheen (fabric surfaces)
• KHR_materials_specular (partial support)
• KHR_materials_dispersion (refractive index dispersion)
• KHR_animation_pointer (arbitrary property animations)
• MSFT_lod (level of detail)
• KHR_node_visibility (GameObject active state)
• KHR_node_hoverability
• KHR_node_selectability
• KHR_interactivity (Visual Scripting export as interactivity graph)

Import only

• KHR_mesh_quantization (smaller buffers / smaller filesize)
• KHR_draco_mesh_compression (requires com.unity.cloud.draco)
• KHR_texture_basisu (requires com.unity.cloud.ktx)
• EXT_mesh_gpu_instancing (instance data)
• EXT_meshopt_compression (requires com.unity.meshopt.decompress)

Export only

• KHR_materials_variants
• KHR_interactivity (Visual Scripting Graph exporter)
• Timeline recorder track for exporting animations in the editor and at runtime
• Lossless keyframe optimization on export
• All 2D textures can be exported, RenderTextures included – they're baked at export.
• Optional plugin: Bake TMPro 3D objects to meshes on export
• Optional plugin: Bake Particle Systems to meshes on export
• Optional plugin: Bake Canvas to meshes on export
• Included plugin sample: KHR_audio_emitter

glTF Interactivity

Visual Scripting Graph Exporter

This plugin allows you to export VisualScripting Graphs as KHR_interactivity graphs in glTF files.

Features

A wide range of nodes are supported for export. Additionally, many features that Unity's Visual Scripting has, but that are lacking in the KHR_interactivity extension, are "flattened" on export into compatible graph logic. For example, scoped variables get exported as variables with unique names, so that there are no conflicts in the exported graph. This allows a lot of flexibility for building complex graphs in the Unity editor, while still being able to export to a glTF file.

• SubGraph support
  • SubGraphs will be flattened on export
• Variables
  • "Saved" variables are not supported
• Custom Events
• Coroutines
• Multiple Visual Scripting Graphs in one glTF file
  • Multiple graphs will be merged into a single KHR_interactivity graph
• Partial List/Array support
  • Capacity of lists can't be changed at runtime, so make sure you create a List with enough size in th