Exporter Guide

Material Variants

Use the Material Variants panel to author and edit KHR_materials_variants assignments before you export. Each variant records which material is displayed on each mesh primitive when that variant is active.

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.

How the Exporter Reads Variant State

The exporter maintains its own variant state independently of the importer. The state is stored in a hidden network node called gltf2MaterialVariantsState in the current Maya scene, so it survives file save and reload.

Auto-bootstrap from an import:
When you import a glTF or GLB file that already contains KHR_materials_variants data, the exporter bootstraps its state automatically from the importer. The variant names and per-primitive material assignments are carried over. This means you can import, adjust materials in Maya, and re-export without any manual setup.

Starting from scratch:
If you are building variants without an imported file, open the panel and use the + button to create your first variant. Then assign materials to it as described below.

Panel Controls

File Selector

When multiple glTF files have been imported into the same scene, a dropdown at the top of the panel lets you select which imported file's variants to edit. The exporter merges variant state from all imported files, disambiguating any name collisions by appending a numeric suffix.

Variants List

Each row in the list shows:

Control	Purpose
Radio button	Marks the Original variant — the one that will be active when the asset first loads in a viewer. Only one variant can be marked Original.
Variant name	Click to select; double-click to rename inline.
✕ delete button	Removes the variant and all its primitive assignments.

Action Buttons

Button	Shortcut / Location	Effect
+ (Create)	Top-right of the list	Creates a new variant with an auto-generated name and immediately opens inline rename so you can type the real name.
↺ (Revert to Original)	Top-right of the list	Reconnects all shading engines in the scene to the materials recorded for the Original variant. Useful for undoing a preview.
− (Remove)	Top-right of the list	Same as the per-row ✕ button; removes the currently selected variant.
Display Variant	Bottom of the panel	Applies the selected variant's materials to the scene without changing the recorded assignments. Use this to preview a variant.
Assign Variant	Bottom of the panel	Reads the materials currently assigned to the selected Maya objects and records them as the assignment for the selected variant. See workflow below.

Authoring Workflow

1 — Prepare your materials

Create all material nodes you need for the different looks. For a mesh that will have three surface variants, you typically set up three separate Maya materials.

2 — Create or rename variants

Click + to add a variant. Type the name you want (e.g. Default, Metal, Worn). Repeat for each variant. Variant names may only contain letters, digits, and underscores — the panel sanitizes invalid characters automatically.

3 — Assign materials to a variant

In the Maya viewport, select the mesh objects whose material assignments you want to record.
Apply the material for this variant to those objects using any standard Maya workflow (Attribute Editor, Hypershade, right-click assign, etc.).
In the Material Variants panel, select the target variant in the list.
Click Assign Variant.

The panel reads the material currently connected to each shading engine on the selected shapes and stores it as the assignment for that variant. Repeat for every variant.

Per-primitive granularity

Each mesh shape can have multiple shading groups (one per material slot / UV shell island). The exporter tracks assignments per primitive slot, so different parts of the same mesh can switch to different materials independently across variants.

4 — Mark the Original variant

Click the radio button next to the variant that should be active by default when viewers load the asset. This sets the primary variant index in the exported KHR_materials_variants structure. When you set the Original, the panel also updates the stored default material for each primitive to match that variant's assignment.

5 — Preview a variant

Select any variant in the list and click Display Variant. Maya reconnects the shading engines to the materials for that variant so you can inspect the look without changing the recorded assignments. Click ↺ Revert to Original to switch back.

6 — Export

Run a normal glTF export. The exporter emits KHR_materials_variants automatically when variant assignments exist. Only variants that have at least one primitive assignment are written to the file — empty variants are skipped.

Editing Existing Variants

Rename: Double-click the variant name in the list. Type the new name and press Enter (or click away). Names are sanitized on commit.
Delete: Click the ✕ button on the row or select the variant and click −. All primitive assignments for that variant are removed. Variant indices above the deleted one are shifted down automatically.
Reassign: Select the mesh objects, apply a different material, select the variant, and click Assign Variant again. The new assignment overwrites the previous one for that variant.
Undo / Redo: All create, rename, delete, and assign operations are undoable with Z / Shift+Z.

Export Behavior

The KHR_materials_variants extension is only added to the output when at least one variant has a primitive assignment.
Variants without any assignments are pruned from the export list. The variant indices in the output file are renumbered to match only the assigned variants.
The material written to each glTF primitive's material field is taken from the Original variant's assignment for that primitive.
Each non-Original variant is written into the KHR_materials_variants extension on each primitive that has an assignment for it.

Tips and Limitations

Avoid running Edit → Delete Unused Nodes in Hypershade while working with variants. Materials that appear unused may still be recorded as variant assignments. Deleting them will cause the corresponding variant assignments to fail on the next Display or export.
The exporter records Maya material (shader) node names. If you rename a material node in the scene after assigning it, re-assign it to keep the reference current.
Variant state is per-scene. If you open a different Maya scene or create a new one, the variant state resets.
When importing multiple glTF files into the same scene, variants with the same name coming from different files are disambiguated by appending a numeric suffix (e.g. Metal_2).