Create custom scalers

Create custom scalers to automatically adjust quality settings based on device performance.

Custom scalers allow you to extend the Adaptive Performance system with your own logic for controlling quality settings. For more information about scalers, refer to Modifying asset quality with scalers.

There are two ways to create custom scalers:

Using a ScriptableObject in the Unity Editor interface
Using a script-only method

The method you choose determines how you configure the scaler and how it applies at runtime.

Important: These two workflows are mutually exclusive. If you add a custom scaler through the Editor interface, Unity disables the automatic runtime scan for script-only scalers. Choose one method for your project.

Add a custom scaler in the Editor interface

Create a ScriptableObject asset from your scaler script to configure the scaler’s properties directly in the Editor for each scaler profile.

To add a custom scaler in the Editor, you need to create the custom scaler script and add the scaler asset to a scaler profile.

Create the custom scaler script

To create the script:

Create a new C# script that inherits from AdaptivePerformanceScaler.
Add the CreateAssetMenu attribute to the class. This exposes the script in the Assets > Create menu.
Define the scaler’s behavior by overriding methods like OnLevel, OnEnabled, and OnDisabled.

Add the scaler asset to a scaler profile

To add and configure the asset:

In the Editor, from the main menu, go to Assets > Create and select the menu item you defined in the CreateAssetMenu attribute. This creates a new scaler asset file in your Project window.
Go to Edit > Project Settings > Adaptive Performance.
Select a scaler profile.
Add the asset to the custom scalers list.
Configure the scaler’s settings directly in the Editor. Use the Normal Mode, Battery Mode, and Stable Frame Mode tabs to set separate settings for each operation mode.

Note: Settings defined in the script override settings configured in the Editor. Therefore, it’s best practice to define the scaler’s behavior in the script and its settings in the Editor.

After you complete these steps, a scaler asset appears in your Project window that you can add to any scaler profile and configure independently.

After you add the asset, be aware of the following behavior:

Adaptive Performance creates a clone of your scaler asset and manages it internally within the profile. If you make changes to the original asset file in your Project window, you must remove the old scaler from the profile and add the updated asset again for the changes to take effect.
The scaler’s name in the list is taken from the asset’s file name. You can’t add multiple scalers with the same name to a single profile.

Example: UI-based scaler

This example demonstrates a script for the Editor interface workflow. All settings are configured in the Editor.

using UnityEngine;
using UnityEngine.AdaptivePerformance;

// This attribute allows you to create an asset from this script
// via Assets > Create > Scriptable Objects > Texture Quality Scaler UI.
[CreateAssetMenu(fileName = "TextureQualityScaler_UI", menuName = "Scriptable Objects/Texture Quality Scaler UI")]
public class TextureQualityScalerUI : AdaptivePerformanceScaler
{
    private int m_DefaultTextureLimit;

    protected override void OnEnabled()
    {
        // Store the original texture quality setting when the scaler is enabled.
        m_DefaultTextureLimit = QualitySettings.globalTextureMipmapLimit;
    }

    protected override void OnDisabled()
    {
        // Restore the original setting when the scaler is disabled.
        m_DefaultTextureLimit = QualitySettings.globalTextureMipmapLimit;
    }

    // This method is called when the performance level changes.
    protected override void OnLevel()
    {
        // The base class calculates the new `Scale` value based on the current performance level.
        // Apply the new scale to the global mipmap limit.
        // A higher scale (better quality) maps to a lower mipmap limit (better quality).
        if (ScaleChanged())
        {
            // Adjust the global texture mipmap limit based on the new scale.
            Debug.Log($"TextureQualityScalerUI new scale: {Scale}");
            QualitySettings.globalTextureMipmapLimit = (int)MaxBound - ((int)(MaxBound * Scale));
        }
    }
}

Create a scaler with a script only

In this workflow, you define the scaler’s settings directly in the script. At runtime, Unity scans your project for any scripts that inherit from AdaptivePerformanceScaler and adds them automatically. The settings defined in the script apply globally to all scaler profiles.

In Awake, apply the settings for each operation mode by calling the corresponding method as scaler stores separate settings for each operation mode:

Normal mode settings with ApplyDefaultSetting.
Battery mode settings with ApplyBatteryModeSetting.
Stable frame mode settings with ApplyStableFrameModeSetting.

If you don’t apply the settings for a mode, the scaler uses empty settings and stays in non-active state while the application is in that operation mode.

To create a script-only custom scaler:

Create a new C# script that inherits from AdaptivePerformanceScaler.
In each AdaptivePerformanceScalerSettingsBase you define, set name to the exact class name.
Define and apply the scaler’s normal mode, battery mode, and stable frame mode settings.
Define the scaler’s behavior.

After you complete these steps, you have a custom scaler script in your project. When you enter Play mode, Adaptive Performance automatically detects and applies this scaler, provided you haven’t added any scalers using the Editor interface.

Example: Script-only scaler

This example defines separate settings for normal mode, battery mode, and stable frame mode in the script.

using UnityEngine;
using UnityEngine.AdaptivePerformance;

public class TextureQualityScalerScriptOnly : AdaptivePerformanceScaler
{
    // Settings used in normal mode.
    private AdaptivePerformanceScalerSettingsBase m_NormalModeSettings = new AdaptivePerformanceScalerSettingsBase
    {
        // This name must exactly match the class name.
        name = "TextureQualityScalerScriptOnly",
        enabled = false,
        scale = 1.0f,
        visualImpact = ScalerVisualImpact.High,
        target = ScalerTarget.GPU,
        minBound = 0,
        maxBound = 4,
        maxLevel = 4
    };

    // Settings used in battery mode. Tune these to push quality lower to save power.
    private AdaptivePerformanceScalerSettingsBase m_BatteryModeSettings = new AdaptivePerformanceScalerSettingsBase
    {
        name = "TextureQualityScalerScriptOnly",
        enabled = true,
        scale = 1.0f,
        visualImpact = ScalerVisualImpact.High,
        target = ScalerTarget.GPU,
        minBound = 0,
        maxBound = 4,
        maxLevel = 4
    };

    // Settings used in stable frame mode. Tune these to trade quality for steadier frame pacing.
    private AdaptivePerformanceScalerSettingsBase m_StableFrameModeSettings = new AdaptivePerformanceScalerSettingsBase
    {
        name = "TextureQualityScalerScriptOnly",
        enabled = true,
        scale = 1.0f,
        visualImpact = ScalerVisualImpact.High,
        target = ScalerTarget.GPU,
        minBound = 0,
        maxBound = 4,
        maxLevel = 4
    };

    private int m_DefaultTextureLimit;

    protected override void Awake()
    {
        base.Awake();
        // Apply the settings for each operation mode.
        ApplyDefaultSetting(m_NormalModeSettings);
        ApplyBatteryModeSetting(m_BatteryModeSettings);
        ApplyStableFrameModeSetting(m_StableFrameModeSettings);
    }

    protected override void OnEnabled()
    {
        m_DefaultTextureLimit = QualitySettings.globalTextureMipmapLimit;
    }

    protected override void OnDisabled()
    {
        QualitySettings.globalTextureMipmapLimit = m_DefaultTextureLimit;
    }

    protected override void OnLevel()
    {
        if (ScaleChanged())
        {
            Debug.Log($"TextureQualityScalerScriptOnly new scale: {Scale}");
            QualitySettings.globalTextureMipmapLimit = (int)MaxBound - ((int)(MaxBound * Scale));
        }
    }
}

Additional resources

Scalers reference

Use scaler profiles

Unity Manual