Merge pull request #8122 from Unity-Technologies/internal/6000.0/staging

Internal/6000.0/staging

Author: UnityAljosha

Packages/com.unity.render-pipelines.core/Documentation~/Images/customsettings-addsetting.png

@@ -20,11 +20,13 @@
   * [RTHandle fundamentals](rthandle-system-fundamentals.md)
   * [Using the RTHandle system](rthandle-system-using.md)
 * [Custom Material Inspector](custom-material-inspector.md)
-* [Custom settings](settings.md)
+* [Custom graphics settings](settings.md)
   * [Adding properties in the menu](adding-properties.md)
-  * [Add custom graphics settings](add-custom-graphics-settings.md)
+  * [Add a settings group](add-custom-graphics-settings.md)
+  * [Add a setting](add-custom-graphics-setting.md)
+  * [Customize the UI of a setting](customize-ui-for-a-setting.md)
   * [Get custom graphics settings](get-custom-graphics-settings.md)
-  * [Include or excude a setting in your build](choose-whether-unity-includes-a-graphics-setting-in-your-build.md)
+  * [Include or exclude a setting in your build](choose-whether-unity-includes-a-graphics-setting-in-your-build.md)
 * [Shaders](shaders.md)
   * [Use shader methods from the SRP Core shader library](built-in-shader-methods.md)
   * [Synchronizing shader code and C#](generating-shader-includes.md)

Packages/com.unity.render-pipelines.core/Documentation~/Images/customsettings-settingsgroup.png

@@ -0,0 +1,60 @@
+# Add a setting
+
+Add a simple property or a reference property to a [custom graphics settings group](add-custom-graphics-settings.md). You can change the values of the setting in the Unity Editor while you're editing your project.
+
+Unity serializes the graphics settings you add. For more information, refer to [Script serialization](xref:um-script-serialization).
+
+**Note:** The value of a custom setting is static in a built project. You can't change the setting at runtime.
+
+## Add a simple property
+
+To add a simple property, add a field to your `IRenderPipelineGraphicsSettings` class using the `[SerializeField]` attribute. For example:
+
+```c#
+using System;
+using UnityEngine;
+using UnityEngine.Rendering;
+using UnityEngine.Rendering.Universal;
+
+[Serializable]
+[SupportedOnRenderPipeline(typeof(UniversalRenderPipelineAsset))] 
+
+// Create a new settings group by implementing the IRenderPipelineGraphicsSettings interface
+public class MySettings : IRenderPipelineGraphicsSettings
+{
+  // Add a private field for the version property
+  int internalVersion = 1;
+
+  // Implement the public version property
+  public int version => internalVersion;
+
+  // Add a float setting
+  [SerializeField]
+  private float mySetting = 1.0f;
+
+  // Add a Material reference property
+  [SerializeField]
+  public Material myMaterial;
+}
+```
+![](Images/customsettings-addsetting.png)<br/>
+The **Edit** > **Project Settings** > **Graphics** window with the new custom setting from the example script.
+
+## Set the default asset for a reference property
+
+To set a default asset for a [reference property](xref:um-editing-value-properties#references), for example a material, add a [`[ResourcePath]`](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.ResourcePathAttribute.html) attribute. For example:
+
+```c#
+public class MySettings: IRenderPipelineGraphicsSettings
+{
+  ...
+  [SerializeField]
+  [ResourcePath('path-to-default-file')]
+  public Material myMaterial;
+}
+```
+
+## Additional resources
+
+- [SerializeField](xref:UnityEngine.SerializeField)
+- [Reference properties](xref:EditingValueProperties#references)

Packages/com.unity.render-pipelines.core/Documentation~/TableOfContents.md

@@ -1,92 +1,57 @@
-# Add custom graphics settings
+# Add a settings group
 
-You can add custom graphics settings to the **Edit** > **Project Settings** > **Graphics** window, then use the values of the settings to customize your build.
+To add a custom graphics settings group to a Scriptable Render Pipeline, implement the `IRenderPipelineGraphicsSettings` interface.
 
-You can change the values of settings while you're editing your project. Unity makes the values static when it builds your project, so you can't change them at runtime.
+Follow these steps:
 
-## Add a setting
+1. Create a class that implements the `IRenderPipelineGraphicsSettings` interface, then add a `[Serializable]` attribute.
 
-To add a setting, follow these steps:
-
-1. Create a class that implements the `IRenderPipelineGraphicsSettings` interface, and add a `[Serializable]` attribute. This becomes a new settings group in the **Graphics** settings window.
 2. To set which render pipeline the setting applies to, add a `[SupportedOnRenderPipeline]` attribute and pass in a `RenderPipelineAsset` type.
-3. Add a property. This becomes a setting.
-4. Implement the `version` field and set it to `0`. Unity doesn't currently use the `version` field, but you must implement it. 
 
-For example, the following script adds a setting called **My Value** in a settings group called **My Settings**, in the graphics settings for the Universal Render Pipeline (URP).
+    **Note:** If you don't add a `[SupportedOnRenderPipeline]` attribute, the setting applies to any Scriptable Render Pipeline. However each Scriptable Render Pipeline stores its own value for the setting.
+
+3. Implement the `version` property. Unity doesn't currently use the `version` property, but you must implement it. 
+
+Unity adds the new settings group to the **Edit** > **Project Settings** > **Graphics** window.
+
+For example, the following script adds a settings group called **My Settings** in the **Graphics** settings window of the Universal Render Pipeline (URP).
 
 ```c#
+using System;
 using UnityEngine;
 using UnityEngine.Rendering;
-using System;
+using UnityEngine.Rendering.Universal;
 
 [Serializable]
 [SupportedOnRenderPipeline(typeof(UniversalRenderPipelineAsset))] 
 
 // Create a new settings group by implementing the IRenderPipelineGraphicsSettings interface
 public class MySettings : IRenderPipelineGraphicsSettings
 {
-  // Implement the version field
-  public int version => 0;
+  // Add a private field for the version property
+  int internalVersion = 1;
+
+  // Implement the public version property
+  public int version => internalVersion;
 
-  // Create a new setting and set its default value to 100.
-  public int myValue = 100;
 }
 ```
 
-## Add a reference property
-
-[Reference properties](https://docs.unity3d.com/2023.3/Documentation/Manual/EditingValueProperties.html#references) take compatible project assets or GameObjects in the scene as inputs.
+![](Images/customsettings-settingsgroup.png)<br/>
+The **Edit** > **Project Settings** > **Graphics** window with the new custom settings group from the example script.
 
-To add a reference property, follow these steps:
+## Change the display order of settings groups
 
-1. Create a class that implements the `IRenderPipelineResources` interface. This becomes a new settings group in the Graphics Settings window.
-2. Add a property. This becomes a reference property.
-3. Implement the `version` field and set it to `0`. Unity doesn't currently use the `version` field, but you must implement it. 
-
-For example, the following script adds a reference property called **My Material** that references a material.
+To change where a settings group appears, use the `[UnityEngine.Categorization.CategoryInfo]` attribute. For example, the following code gives the settings group the name **My Settings** and moves the group to the top of the graphics settings window.
 
 ```c#
-using UnityEngine;
-using UnityEngine.Rendering;
-using System;
-
-[Serializable]
-[SupportedOnRenderPipeline(typeof(UniversalRenderPipelineAsset))] 
-
-// Create a new reference property group by implementing the IRenderPipelineResources interface
-public class MySettings: IRenderPipelineResources
+[UnityEngine.Categorization.CategoryInfo(Name = "My Settings", Order = 0)]
+public class MySettings : IRenderPipelineGraphicsSettings
 {
-  // Implement the version field
-  public int version => 0;
-
-  // Create a new reference property that references a material
-  [SerializeField] public Material myMaterial;
+  ...
 }
 ```
 
-To set a default asset, use a [`[ResourcePath]`](https://docs.unity3d.com/2023.3/Documentation/ScriptReference/Rendering.ResourcePathAttribute.html) attribute above the reference property. For example, in the example, add the following line above `public Material myMaterial`.
-
-```c#
-[ResourcePath('path-to-default-file')]
-```
-
-## Change the name and layout of a settings group
-
-To change the name of a settings group in the **Graphics** settings window, follow these steps:
-
-1. Add `using System.ComponentModel` to your script.
-2. Add a `[Category]` attribute to your script. For example, `[Category("My Category")]`.
-
-You can also use the [PropertyDrawer](https://docs.unity3d.com/ScriptReference/PropertyDrawer.html) API to further customize the layout of custom settings.
-
-## Set which render pipeline a setting applies to
-
-To set which render pipeline a setting applies to, use the `[SupportedOnRenderPipeline]` attribute and pass in a `RenderPipelineAsset` type.
-
-For example, if your project uses the Universal Rendering Pipeline (URP) and you want your setting to appear only in the **URP** tab of the **Graphics** settings window, use the following code:
-
-```c#
-[SupportedOnRenderPipeline(typeof(UniversalRenderPipelineAsset))]
-```
+## Additional resources
 
+- [Add a setting](add-custom-graphics-setting.md)

Packages/com.unity.render-pipelines.core/Documentation~/add-custom-graphics-setting.md

@@ -1,31 +1,35 @@
 # Include or exclude a setting in your build
 
-By default, Unity doesn't include a setting ("strips" the setting) in your built project. For example, if you create a custom reference property where you set a shader asset, Unity doesn't include that property in your build.
+By default, Unity doesn't include a setting ("strips" the setting) in your built project to optimize performance and reduce build size. For example, if you create a custom reference property that points to a shader asset, by default Unity doesn't include that property in your build.
 
-You can choose to include a setting in your build instead. You can then get the value of the setting at runtime. The value is read-only.
+You can choose to include a setting in your build instead. The value of the property is read-only at runtime.
 
 ## Include a setting in your build
 
-To include a setting in your build by default, set the `IsAvailableInPlayerBuild` property of your [settings class](add-custom-graphics-settings.md) to `true`. 
+To include a setting in your build by default, set the `IsAvailableInPlayerBuild` property of your [settings group class](add-custom-graphics-settings.md) to `true`. 
 
-For example, add the following line:
+For example:
 
 ```c#
-public bool IsAvailableInPlayerBuild => true;
+public class MySettings: IRenderPipelineGraphicsSettingsStripper
+{
+  ...
+  // Make settings in this class available in your build
+  public bool IsAvailableInPlayerBuild => true;
+}
 ```
 
 ## Create your own stripping code
 
-You can override the `IsAvailableInPlayerBuild` property by implementing the `IRenderPipelineGraphicsSettingsStripper` interface, and writing code that conditionally strips or keeps the setting.
+To conditionally control whether Unity includes or excludes a setting in your build, override the `IsAvailableInPlayerBuild` property by implementing the `IRenderPipelineGraphicsSettingsStripper` interface.
 
 Follow these steps:
 
 1. Create a class that implements the `IRenderPipelineGraphicsSettingsStripper` interface, and pass in your [settings class](add-custom-graphics-settings.md).
 2. Implement the `active` property. If you set `active` to `false`, the code in the class doesn't run.
-3. Implement the `CanRemoveSettings` method with your own code that decides whether to include the setting.
-4. In your code, return either `true` or `false` to strip or keep the setting.
+3. Implement the `CanRemoveSettings` method with your own code that decides whether to include the setting. Return `true` to strip the setting, or `false` to include the setting.
 
-For example, in the following code, the `CanRemoveSettings` method returns `true` and strips the setting if the value of the setting is larger than 100.
+For example:
 
 ```c#
 using UnityEngine;
@@ -41,8 +45,8 @@ class SettingsStripper : IRenderPipelineGraphicsSettingsStripper<MySettings>
   // Implement the CanRemoveSettings method with our own code
   public bool CanRemoveSettings(MySettings settings)
   {
-    // Strip the setting (return true) if the value is larger than 100
-    return settings.myValue > 100;
+    // Strip the setting (return true) if useMyFeature is false
+    return !settings.useMyFeature;
   }
 }
 ```
@@ -55,8 +59,9 @@ You can check if a setting exists at runtime. A setting might not exist at runti
 
 - Unity didn't include the setting in your build.
 - The current pipeline doesn't support the setting.
+- The setting is in an assembly that Unity doesn't include in your build. Refer to [Organizing scripts into assemblies](xref:um-script-compilation-assembly-definition-files) for more information.
 
-Use `TryGetRenderPipelineSettings` to check if the setting exists. `TryGetRenderPipelineSettings` puts the setting in an `out` variable if it exists. Otherwise it returns `false`.
+To check if the setting exists, use the `TryGetRenderPipelineSettings` API. `TryGetRenderPipelineSettings` puts the setting in an `out` variable if the setting exists. Otherwise it returns `false`.
 
 For example, the following code checks whether a settings group called `MySettings` exists at runtime:
 
@@ -65,3 +70,7 @@ if (GraphicsSettings.TryGetRenderPipelineSettings<MySettings>(out var mySetting)
   Debug.Log("The setting is in the build and its value is {mySetting.myValue}");
 }
 ```
+
+## Additional resources
+
+- [Organizing scripts into assemblies](xref:um-script-compilation-assembly-definition-files)

Packages/com.unity.render-pipelines.core/Documentation~/add-custom-graphics-settings.md

@@ -0,0 +1,77 @@
+# Customize the UI of custom settings
+
+To change the look of custom settings in the **Graphics** settings window, use the `PropertyDrawer` API.
+
+Follow these steps:
+
+1. Create a class that inherits from the [`PropertyDrawer`](xref:UnityEditor.PropertyDrawer) class.
+2. Add the `[CustomPropertyDrawer]` attribute to the class, with a reference to your settings class.
+3. Override the `PropertyDrawer.CreatePropertyGUI` method, and return a `VisualElement` object that contains the UI elements you want to display.
+
+The following example creates a custom UI for a `MySettings` class that contains a Boolean and a float field. The Graphics settings window displays the float only when the Boolean field is enabled.
+
+For more information, refer to [PropertyDrawer](xref:UnityEditor.PropertyDrawer).
+
+```c#
+using UnityEngine;
+using UnityEditor;
+using UnityEngine.UIElements;
+
+// Create a custom UI for the properties in the MySettings class
+[CustomPropertyDrawer(typeof(MySettings))]
+public class MySettingsPropertyDrawer : PropertyDrawer
+{
+    // Override the CreatePropertyGUI method to define the custom UI
+    public override VisualElement CreatePropertyGUI(SerializedProperty property)
+    {
+        // Create a container to hold the UI elements
+        var container = new VisualElement();
+
+        // Find the properties to display
+        var useProperty = property.FindPropertyRelative("m_UseMyFeature");
+        var intensityProperty = property.FindPropertyRelative("m_MyFeatureIntensity");
+
+        // Create property fields for each property
+        var usePropertyField = new PropertyField(useProperty);
+        var intensityPropertyField = new PropertyField(intensityProperty);
+
+        // Enable or disable the intensity field based on the value of m_UseMyFeature
+        usePropertyField.RegisterValueChangeCallback(evt =>
+        {
+            intensityPropertyField.SetEnabled(useProperty.boolValue);
+        });
+
+        // Add the property fields to the container
+        container.Add(usePropertyField);
+        container.Add(intensityPropertyField);
+
+        // Return the container to be displayed in the Graphics settings window
+        return container;
+    }
+}
+```
+
+## Customize the More (⋮) menu of a settings group
+
+To add items to the **More** (⋮) menu of a settings group, follow these steps:
+
+1. Create a class that implements the [`IRenderPipelineGraphicsSettingsContextMenu`](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.IRenderPipelineGraphicsSettingsContextMenu.html) interface.
+2. Implement the `PopulateContextMenu` method.
+3. To add an item, use the `AddItem` API.
+
+For example:
+
+```c#
+public class MySettingsContextMenu : IRenderPipelineGraphicsSettingsContextMenu<MySettings>
+{
+    void IRenderPipelineGraphicsSettingsContextMenu<MySettings>.PopulateContextMenu(MySettings setting, PropertyDrawer _, ref GenericMenu menu)
+    {
+        menu.AddItem(new GUIContent("My custom menu item"), false, () => { Debug.Log("Menu item was selected."); });
+    }
+}
+```
+
+## Additional resources
+
+- [PropertyDrawer](xref:UnityEditor.PropertyDrawer)
+- [IRenderPipelineGraphicsSettingsContextMenu](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.IRenderPipelineGraphicsSettingsContextMenu.html)

Packages/com.unity.render-pipelines.core/Documentation~/choose-whether-unity-includes-a-graphics-setting-in-your-build.md

@@ -2,9 +2,7 @@
 
 To get a custom setting and read its value, use the `GetRenderPipelineSettings` method.
 
-If you want to get a setting at runtime, you must [include the setting in your build](choose-whether-unity-includes-a-graphics-setting-in-your-build.md).
-
-For example, the following script gets the `MySettings` settings class from the example in the [Add custom graphics settings](add-custom-graphics-settings.md) page, then logs the value of the `MyValue` setting:
+For example, the following script gets the `MySettings` settings class from the example in the [Add a setting](add-custom-graphics-setting.md) page, then logs the value of the `mySetting` setting:
 
 ```c#
 using UnityEngine;
@@ -19,16 +17,16 @@ public class LogMySettingsValue : MonoBehaviour
         var mySettings = GraphicsSettings.GetRenderPipelineSettings<MySettings>();  
 
         // Log the value of the MyValue setting
-        Debug.Log(mySettings.myValue);
+        Debug.Log(mySettings.mySetting);
     }
 }
 ```
 
-## Detect when a setting changes
+## Get a notification when a setting changes
 
-You can configure a property so it notifies other scripts when its value changes. This only works while you're editing your project, not at runtime.
+To configure a property so it notifies other scripts when its value changes, use the `SetValueAndNotify` method. You can use this to debug, update UI elements, or trigger other actions when a setting changes.
 
-You can use this to fetch the value only when it changes, instead of every frame in the `Update()` method.
+This only works while you're editing your project, not at runtime. If you use `SetValueAndModify` in a built application, Unity throws an exception.
 
 Follow these steps:
 
@@ -63,8 +61,6 @@ Follow these steps:
     }
     ```
 
-    If you use `SetValueAndModify' in a standalone application, Unity throws an exception.
-
 3. Use the `GraphicsSettings.Subscribe` method to subscribe to notifications from the setting, and call an `Action` when the setting changes.
 
     For example:
@@ -101,4 +97,6 @@ To stop calling a method when a setting changes, use the `GraphicsSettings.Unsub
 GraphicsSettings.Unsubscribe<MySettings>(onSettingChanged);
 ```
 
+## Additional resources
 
+- [`IRenderPipelineGraphicsSettings`](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.IRenderPipelineGraphicsSettings.html)