Unity Material coming up as null from UIToolkit, and it won’t set custom attributes

by

Summary

A developer is attempting to animate a custom shader parameter (_RevealAmount) on a VisualElement in Unity’s UI Toolkit. The unityMaterial property appears as null at runtime, and setting attributes on it fails to update the screen. The root cause is that UI Toolkit materials are immutable copies used for inline styles. Attempting to mutate them directly is an anti-pattern; the correct approach is to assign a StyleSheet or manipulate the ComputedStyle to trigger a repaint with the new uniform values.

Root Cause

The failure stems from a misunderstanding of the UI Toolkit styling pipeline.

  • Direct Property Access: The code accesses renderTexture.style.unityMaterial.value. This retrieves the inline style value.
  • Immutable Objects: The object returned (if not null) is effectively a snapshot or a proxy used by the inline style system. It is not the live material instance rendered by the UI MeshGenerator.
  • Missing Write-Back: Setting SetFloat on that retrieved object does not notify the UI Toolkit StyleSheets system that a value has changed. Consequently, the UI Renderer never rebuilds the draw call with the updated uniform.
  • Debug Misinterpretation: If the unityMaterial is defined in USS (StyleSheets) rather than inline, style.unityMaterial.value often returns null because inline styles haven’t been explicitly set, even though the computed visual style has a material.

Why This Happens in Real Systems

In high-performance rendering engines (and UI Toolkit specifically), separating data from state is crucial for batching and validation.

  • Functional UI Updates: UI Toolkit is largely functional. You define a state (styles), and the engine calculates the render tree. Directly mutating an object that sits between the state and the render tree breaks this flow.
  • Batching Requirements: To render efficiently, the engine groups elements by shaders and textures. If you mutate a material instance in place, the engine may not detect the change, or it might try to batch it with other elements using the original material definition, leading to visual glitches or ignored updates.
  • Immutability for Predictability: Because USS allows styles to be overridden (e.g., hover states vs. default states), the system relies on copying and merging style values. Mutating a deep reference defeats the safety of this copy-on-write mechanism.

Real-World Impact

  • Visual Stagnation: The UI remains static; animations or dynamic effects (like reveals) do not play.
  • Debugging Confusion: Debug.Log returning Null makes developers check for asset loading errors, masking the actual architectural issue.
  • Wasted Cycles: DOVirtual executes every frame, calling SetFloat, but no pixels change, resulting in wasted CPU cycles.
  • Architecture Friction: Developers may resort to swapping the entire VisualElement or creating expensive new materials every frame to force updates, hurting memory and performance.

Example or Code

There are two main ways to handle dynamic shader properties in UI Toolkit. Direct mutation is not one of them.

Approach 1: The “Flipbook” or Class Swap (Best for discrete states)
If your shader accepts predefined values (0.0, 0.5, 1.0), define these in USS classes and swap them.

// C# - Toggling classes defined in USS
public class MyUI : MonoBehaviour
{
    private UIDocument ui;
    private void OnEnable()
    {
        ui = GetComponent();
        var root = ui.rootVisualElement;
        var renderTexture = root.Q("renderTexture");

        // Assuming you have USS classes: .state-0, .state-1, etc.
        StartCoroutine(AnimateReveal(renderTexture));
    }

    private System.Collections.IEnumerator AnimateReveal(VisualElement elem)
    {
        float t = 0f;
        while (t < 1f)
        {
            t += 0.05f;
            // Map t to discrete classes or pass uniform via custom property if using Approach 2
            // elem.RemoveFromClassList("state-0");
            // elem.AddToClassList("state-1");
            yield return new WaitForSeconds(0.05f);
        }
    }
}

Approach 2: Custom CustomStyle (Best for continuous animation like floats)
To animate a continuous float (_RevealAmount), you must use the CustomStyle system to inject values into the shader at the layout generation phase.

  1. Register the property.

  2. Update the value on the VisualElement.

  3. Create a custom usage hint to force a repaint if needed.

    // C# - Correct way to animate a custom shader float
public class MyUI : MonoBehaviour
{
private UIDocument ui;
private VisualElement renderTexture;

// Define the key matching the shader property name
private const string RevealKey = "_RevealAmount";

private void OnEnable()
{
    ui = GetComponent();
    var root = ui.rootVisualElement;
    renderTexture = root.Q("renderTexture");

    // 1. Register interest in this custom property so the system knows to look for it
    // This is critical for the system to read the value.
    // Note: This step is often implicit if you use the .style accessors correctly,
    // but strictly managing CustomStyle is safer for complex shaders.

    StartCoroutine(AnimateReveal());
}

private System.Collections.IEnumerator AnimateReveal()
{
    float v = 0f;
    bool goingUp = true;

    while (true)
    {
        v += goingUp ? 0.01f : -0.01f;
        if (v >= 1f) goingUp = false;
        if (v <= 0f) goingUp = true;

        // 2. We use the resolvedStyle (computed style) to set the value.
        // However, for custom shader properties, we often need to force a custom style update.
        // In newer Unity versions (2022.3+), you can often just set the float directly on the style object 
        // IF the material is applied correctly via USS.

        // However, to make it truly dynamic without USS hassles, we use CustomStyle:
        renderTexture.style.SetCustomProperty(RevealKey, v);

        // If the above doesn't work in your specific version, the robust "Senior Engineer" fix
        // is usually to wrap the material in a way that forces a repaint or use USS variables.

        yield return new WaitForSeconds(0.02f);
    }
}
}

Note: If SetCustomProperty is unavailable or behaves inconsistently in your specific Unity version, the reliable architectural pattern is to use USS Variables with StyleFloat if possible, or fallback to a StyleSheet swap.

How Senior Engineers Fix It

Senior engineers do not mutate returned style objects. They treat the VisualElement as a state container.

  1. Data-Driven Approach: Instead of asking the UI for the material, the engineer asks: “What is the current state of the logic?” (e.g., RevealValue = 0.5).
  2. Separation of Concerns: The state drives the UI, not the other way around.
  3. Use the Correct API:
    • Static/Semi-Static: Define the shader and properties in a .uss file. Use .AddToClassList / .RemoveFromClassList to swap styles.
    • Dynamic/Animated: Use the StyleSheets API (sheet.AddOrUpdateProperty) or the CustomStyle system to inject values. In modern UI Toolkit, setting element.style.fontSize (for example) triggers a repaint. While unityMaterial is tricky, using element.style.backgroundImage is the standard way to change visuals.
    • Alternative: If the shader is truly complex, a Senior Engineer might implement a custom VisualElement subclass that overrides ExecuteDefaultAction or uses GenerationData to manipulate the mesh directly, or simply use a RenderTexture in a UIDocument and animate that RenderTexture via a standard MonoBehaviour on a separate camera, decoupling the complex shader logic from the UI Toolkit hierarchy entirely.

Why Juniors Miss It

  • Object-Oriented Bias: Juniors expect GetComponent<Renderer>().material style behavior where accessing a property returns a mutable object.
  • Documentation Gaps: Unity’s documentation on the specific lifecycle of unityMaterial in USS vs. Inline styles is dense and scattered.
  • “It looks like it should work”: Accessing style.unityMaterial.value returns a Material object type. It looks like a real material. It feels like a real material. It is deceptive.
  • Lack of Awareness of “Styling Systems”: Juniors often view UI as a hierarchy of GameObjects (immediate mode) rather than a functional, state-based system (retained mode) where “styles” are data and “elements” are views. They try to manipulate the view directly rather than updating the data.