Exporter Guide

Material Variants

Use the Material Variants panel to author and edit KHR_materials_variants assignments before you export. Each File is one imported glTF, or a File you create here. The list shows only that File’s variants.

Open Exporter Overview Install the Plug-in View Supported Features

Opening the Panel¶

Go to glTF2.0 -> Material Variants in the Maya menu bar. The panel is dockable and can also be used as a floating window. The ? button in the window repeats this workflow.

How the Exporter Reads Variant State¶

Variant state is stored in the current Maya scene, so it survives file save and reload.

From an import:
When you import a glTF or GLB file that already contains KHR_materials_variants, that file becomes its own File in the dropdown. A second import adds another File. It does not append those variants onto the first File, and it does not wipe variants you already authored there. The same variant name on two Files stays two variants on export.

From scratch:
If the list is empty, opening the window creates Scene1. Create File adds Scene2, Scene3, and so on.

Saving the Maya scene:
Each File keeps its own export slots after you save and reopen the scene.

Panel Controls¶

File¶

Control	Effect
File dropdown	Shows the variants for that File only.
Create File	Adds the next Scene name so you can author variants without importing a glTF.
Rename File	Changes the dropdown label. Variants, assignments, and export slots stay on that File.
Remove File	Drops that File from the list and from the exported glTF. Maya materials stay in the scene. Other Files keep their variants.

Variant rows¶

Each row shows a drag handle, an Original radio button, the variant name, Empty or Assigned:N, and row icons.

Control	Effect
⋮ handle	Drag to set the order written into the glTF.
Radio button	Marks Original. Viewers show that look when no variant is selected. Only one variant on this File can be Original.
Variant name	Click to select the row. Double-click to rename. Clicking the name does not select meshes.
Empty	This variant has no mesh assignments. Click it to assign the meshes selected in the viewport. With nothing selected, Assign Variant is focused.
Assigned:N	How many meshes this variant records.
Display (eye)	Shows that look in Maya. On a combined skinned mesh, each primitive’s faces get that primitive’s material.
Select Meshes	Selects the Maya meshes assigned to this variant. Stays off while the variant is Empty.
Duplicate	Copies this variant and its mesh assignments onto a new name in the same File. Maya materials stay in the scene.
Delete	Removes the variant from this File. Maya materials stay in the scene. Deleting the last item does not restore an imported list.

Actions¶

Button	Effect
Assign Variant	Records the current material on the meshes selected in the viewport. The mesh keeps that material. The variant stores it.
Assign All	Records the current material of every mesh already on this File. Meshes on other Files are left alone.
Unassign	Clears the mapping. Selected meshes are unassigned first. With nothing selected, the variant becomes Empty. Maya materials stay in the scene.
Create Variant	Plus icon next to Revert to Original. Adds a variant named Variant, then Variant_1, and so on. Double-click the name to rename it.
Revert to Original	Shows the Original variant on this File’s meshes only.
Export Empty variants	Includes looks that have no mesh assignments. Off by default. A viewer can list the empty name, and selecting it does not change materials.

Authoring Workflow¶

1 - Choose or create a File¶

Pick the imported file in the dropdown, or click Create File. The list shows only that File’s variants.

2 - Prepare materials¶

Create the Maya materials you need for each look. For three surface variants, set up three materials.

3 - Create variants¶

Click the Create Variant plus. The new row is named Variant, then Variant_1, and so on. Double-click the name to rename it (for example Default, Metal, Worn). Names may contain letters, digits, and underscores. Other characters become underscores.

4 - Assign materials¶

In the viewport, select the meshes for this look.
Assign the material with any Maya workflow (Attribute Editor, Hypershade, or right-click assign).
In the panel, select the variant, or click Empty.
Click Assign Variant.

Repeat for every variant. Assign All records every mesh already on this File in one step.

5 - Mark Original¶

Click the radio button next to the variant viewers should show when none is selected. Export writes that material as the primitive’s material when the shader is still in the scene.

6 - Preview and export¶

Use the eye icon to preview a look. Revert to Original switches this File back. Drag the ⋮ handle if the glTF list order matters, then export as usual.

Empty variants are left out of the glTF unless Export Empty variants is on.

Export Behavior¶

KHR_materials_variants is written when this scene has variant assignments, or when Export Empty variants is on and empty names should be included.
With Export Empty variants off, variants that have no mesh assignments are omitted. The Export Log says which empty looks were left out.
The material on each glTF primitive is that File’s Original variant, when that shader still exists.
The same variant name on two Files is exported as two variants.
Removing a File removes that File’s mappings from the glTF. Other Files stay.

The Export Log also reports an Original with no assignment, and an assigned shader that is missing from the scene.

Python¶

After the plugin is loaded:

from gltf2_exporter.maya.material_variants_api import (
    create_file, create_variant, assign_selection, set_original, list_stats,
)
create_file('Scene1')
create_variant('Red', file='Scene1')
assign_selection('Red', file='Scene1')
set_original('Red', file='Scene1')
list_stats(file='Scene1')

The same actions are cmds.gltf2MaterialVariants with createFile, createVariant, assignSelection, setOriginal, and listStats. Pass -file when more than one File exists.

Tips and Limitations¶

Avoid Edit -> Delete Unused Nodes in Hypershade. Materials that look unused may still be recorded on a variant. Deleting them breaks Display and export for that look.
The exporter stores Maya shader names. If you rename a material after assigning it, assign it again.
Variant state belongs to this Maya scene. A new scene starts empty.
Removing a variant or a File leaves the Maya materials in the scene.