Proposed RFC Feature - Quality Settings Editor Tool

[AMZN-alexpete]

Summary:

The Editor Quality Settings Tool gives users the ability to see current quality settings for each platform, edit settings and preview the results in Editor.

What is the relevance of this feature?

Giving the users a graphical tool for Quality Settings lets them visualize the current settings in a way they cannot by reading JSON files and it gives users a way to edit Quality Settings JSON files with less risk of syntax or formatting errors.

Feature design description:

An Editor tool will exist with the following requirements:

1. As a user, I can open the Quality Settings Tool from the Editor main menu at Tools > Quality Settings and from Edit > Settings > Quality > Edit Quality Settings

2. As a user, I can view the CVar (console variable) quality settings for all platforms in the Quality Settings Tool

   1. A Platform drop down widget exists at the top of the tool
   2. The current platform is shown in the Platform widget by default
   3. The platform drop down contains every supported platform
   4. When the user selects a different platform in the drop down, all the CVar fields and groups update to reflect the settings for that platform

3. As a user, I can view the CVar’s by quality level (e.g. low, medium, high, very high)

   1. Each column header displays the quality level for that column (e.g. low, medium, high, very high)
   2. The number of columns is dynamic depending on how many quality levels are defined for the active platform (e.g. mobile platforms may only have 2 or 3 quality levels)
   3. A row exists for every quality group CVar and indented rows exist for every CVar setting in that quality group.
      e.g. q_graphics (quality group)
      r_cvar1 (CVar 1 in the q_graphics quality group)
      r_cvar2 (CVar 1 in the q_graphics quality group)

4. As a user, I can edit CVar settings for a specific platform and quality level

   1. Every cell in the table contains an editable text field
   2. When values are updated they are saved to project quality settings for that platform in real time
   3. Edits support undo/redo

5. As a user, I can preview changes made in the Quality Settings Tool immediately

   1. A Preview Platform drop-down exists to select what platform to preview in the editor.
   2. A Preview Level drop-down exists to select what quality level to preview in the editor.

6. As a user, I can undo my quality settings changes to their previous values

7. As a user, I can revert my quality settings changes to defaults

8. As a user, I can close the Quality Settings Tool and re-open it and the UI shows the settings values persist and the selected UI Platform and preview settings are persisted.

Technical design description:

The editor UI will need to retrieve content to display and make changes to quality settings using the Quality System API outlined below.

class QualitySetting
{
    // String values for this setting at each quality level e.g. Low, Medium, High
    AZStd::vector<AZStd::string> m_qualityLevelValues;

    // Quality Setting CVar name e.g. r_streamingMemoryBufferSize
    AZStd::string m_name;
};

class QualityGroup
{
    // Default quality level for this group
    QualityLevel m_defaultQualityLevel;
    
    // Quality group description
    AZStd::string m_description;
    
    // Quality Group CVar name
    AZStd::string m_name;
    
    // Quality level names e.g. Low, Medium, High
    AZStd::vector<AZStd::string> m_qualityLevelNames;

    // Quality settings for this group
    AZStd::vector<QualitySetting> m_settings;
};

class QualitySystemToolsInterface
{
    // Gets the selected platform from user settings
    AZ::Platform GetSelectedPlatform();
    // Set the selected platform in user settings
    void SelectPlatform(AZ::Platform platform);

    // Gets the selected preview platform from user settings
    AZ::Platform GetPreviewPlatform();
    
    // Set the selected preview platform in user settings
    // Applies the settings for this platform and current level
    void SetPreviewPlatform(AZ::Platform platform);  
    
    // Gets the quality level to preview in the Editor from user settings
    QualityLevel GetPreviewQualityLevel();
  
    // Set the selected preview quality level in user settings
    // Applies the settings for this platform and level
    void SetPreviewQualityLevel(QualityLevel qualityLevel);

    // Get all quality settings group data for a platform
    const AZStd::vector<QualityGroup>& GetQualitySettingsGroups(AZ::Platform platform);
    
    // Get all platforms
    AZStd::vector<AZ::Platform> GetPlatforms();
    
    // Get the value for a quality setting
    AZStd::string_view GetQualitySetting(AZ::Platform platform,
                           AZStd::string_view groupName, 
                           AZStd::string_view settingName);

    // Set the value for a quality setting
    // Return outcome with success or failure with error message
    AZ::Outcome SetQualitySetting(AZ::Platform platform,
                           AZStd::string_view groupName, 
                           AZStd::string_view settingName, 
                           AZStd::string_view value);
};

What are the advantages of the feature?

See the section on relevance above.

What are the disadvantages of the feature?

As with any tool, added code means longer compile times for the Editor.

How will this be implemented or integrated into the O3DE environment?

The tool will be accessible in the Editor from the main menu.

Are there any alternatives to this feature?

• Currently, users can edit the quality settings JSON files manually and use the console to get and set the Quality Settings values at runtime.

How will users learn this feature?

• A simple overview of the tool should be provided on the o3de.org docs site

Are there any open questions?

• When a user changes a setting, which file does the update get written to?
  By default, the settings should be written to a platform-specific quality.setreg file in their project folder so that the settings will override any engine or gem settings. In the future, functionality can be added to give users the ability to choose where to write the settings which will be useful for engine and gem developers.