UnityGLTF Documentation

UnityGLTF provides a plugin system to modify node structures, extension data, or materials during the import/export process. Plugins are ScriptableObjects enabled via Project Settings > UnityGLTF.

To create a plugin:

1. Create a class inheriting from GLTFImportPlugin or GLTFExportPlugin (this holds the settings).
2. Create a class inheriting from GLTFImportPluginContext or GLTFExportPluginContext (this contains the actual callbacks).
3. Implement CreateInstance in the plugin class to return the context instance.
4. Override the desired callbacks in the context class.

If your plugin handles custom extension data, implement GLTF.Schema.IExtension for serialization.

// Example for custom export plugin
public class MyExportPlugin : GLTFExportPlugin
{
    public override string DisplayName { get => "My Custom Plugin"; }
    public override bool EnabledByDefault => true;
    public override bool AlwaysEnabled => false;
    
    public override GLTFExportPluginContext CreateInstance(ExportContext context)
    {
        return new MyExportPluginContext();
    }
}

public class MyExportPluginContext: GLTFExportPluginContext
{
    public override bool ShouldNodeExport(GLTFSceneExporter exporter, GLTFRoot gltfRoot, Transform transform)
    {
        return !transform.CompareTag("ignore");
    }
}

// Example for custom import plugin
public class MyImportPlugin: GLTFImportPlugin
{
    public override string DisplayName => "My Import Plugin";
    public override string Description => "";
    
    public override GLTFImportPluginContext CreateInstance(GLTFImportContext context)
    {
        return new MyImportPluginContext();
    }
}

public class MyImportPluginContext: GLTFImportPluginContext
{
    public override void OnAfterImportScene(GLTFScene scene, int sceneIndex, GameObject sceneObject)
    {
        // Set all to static
        var objs = sceneObject.GetComponentsInChildren<Transform>();
        foreach (var obj in objs)
            obj.gameObject.isStatic = true;
    }
}

The Visual Scripting Graph Exporter converts Unity Visual Scripting logic into KHR_interactivity graphs. To maintain compatibility with the glTF extension, certain Unity features are "flattened" during export:

• SubGraphs: These are flattened into the main graph.
• Variables: Scoped variables are exported as variables with unique names to prevent conflicts. Note that "Saved" variables are not supported.
• Multiple Graphs: Multiple Visual Scripting Graphs in a single glTF file are merged into one single KHR_interactivity graph.
• Lists/Arrays: Capacity cannot be changed at runtime; ensure lists are created with sufficient size in the graph.

Supported Logic & Operations

• Math, Vector, and Matrix operations.
• Logic operations.
• Material editing (Get/Set of floats, colors, texture offset/scale).
• Property interpolation (using the "Interpolate ..." family of nodes).
• Custom Events and Coroutines.
• Partial Animator support (starting an animation is supported, but automatic graph transitions are not).

Limitations

• String manipulation is not supported by the KHR_interactivity extension.
• Some nodes have specific limitations. You can check compatibility in the Visual Scripting Editor (supported nodes are highlighted) or by clicking Project Settings > UnityGLTF > Export > KHR_interactivity (VisualScripting) > Log supported Visual Scripting Units to see the full list in the console.

When modifying materials at runtime (e.g., using Material.EnableKeyword to toggle features like normal maps, emission, or alpha modes), Unity's standalone player may not include the required shader variants unless they are explicitly referenced. Because GLTFSceneImporter.cs enables these keywords dynamically based on glTF data, you must ensure the variants are compiled into your build using one of the following two methods:

Method 1: Use a ShaderVariantCollection

Create a ShaderVariantCollection asset and add the specific keywords/variants required by your glTF assets to the collection.

Method 2: Use the Resources folder

Add a material to the Assets/Resources folder that uses the required shader configuration. To ensure Unity includes the variant, the material must actually use the features:

• Assign textures to the texture fields.
• Change Colors to something other than black.
• Change float values to something other than 0.

Note: The material does not need to be assigned to an object in a scene; its presence in the Resources folder is sufficient for Unity to include its shader variants in the build.

To render materials like glass (transmission) or colored jelly (volume/attenuation) using UnityGLTF/PBRGraph, follow these steps:

1. Material Setup

• On the UnityGLTF/PBRGraph material, check Enable Transmission.
• Optionally check Enable Volume.
• Adjust Transmission, Thickness, Index of Refraction, and Attenuation values.

2. Render Pipeline Setup

Depending on your pipeline, you must add specific features to see these effects:

Universal Render Pipeline (URP)

• Select your URP Renderer Asset.
• In the Renderer Features section, add an Opaque Texture (Rough Refraction) feature.

Built-In Render Pipeline

• Add the RoughRefraction component to your Main Camera.

High Definition Render Pipeline (HDRP)

• HDRP has its own rough refraction support. There is currently no automatic import/export support to convert to HDRP shaders. Use glTFast if you require this workflow.