feat: mode to manually add SoftMaskable components

close #253

Author: mob-sakai

Packages/src/README.md

@@ -375,7 +375,7 @@ tutorial.
 
 ### Project Settings
 
-![](https://github.com/user-attachments/assets/5e27df42-f117-421c-adc5-f6e53154ee4c)
+![](https://github.com/mob-sakai/mob-sakai/releases/download/docs/1759018902322.png)
 
 You can adjust the project-wide settings for SoftMaskForUGUI. (`Edit > Project Settings > UI > Soft Mask`)
 
@@ -384,6 +384,9 @@ You can adjust the project-wide settings for SoftMaskForUGUI. (`Edit > Project S
 - **Transform Sensitivity**: `Low`, `Medium`, `High`
     - Adjust the transformation sensitivity for the soft mask buffer update.
     - The higher the sensitivity, the more frequently the soft mask buffer is updated.
+- **Soft Maskable**: Determines how to add `SoftMaskable` components under `SoftMask`.
+    - `Automatic`: `SoftMaskable` components are added automatically as needed.
+    - `Manual`: You need to add `SoftMaskable` components explicitly.
 - **Hide Generated Component**: Automatically hide the generated `MaskingShapeContainer` and `TerminalMaskingShape`
   components.
 - **Optional Shaders (SoftMaskable)**: A list of shaders that will be prioritized when a soft-maskable shader is

Packages/src/Runtime/SoftMask.cs

@@ -528,9 +528,9 @@ private void SetDirtyAndNotifyIfBufferSizeChanged()
 
         private void AddSoftMaskableOnChildren()
         {
-            if (!isActiveAndEnabled || !SoftMaskingEnabled()) return;
+            if (!SoftMaskingEnabled()) return;
 
-            this.AddComponentOnChildren<SoftMaskable>(true);
+            SoftMaskUtils.AddSoftMaskableOnChildren(this, true);
         }
 
         private void OnBeforeCanvasRebuild()

Packages/src/Runtime/SoftMaskable.cs

@@ -128,7 +128,8 @@ public float power
         private void OnEnable()
         {
             UpdateHideFlags();
-            this.AddComponentOnChildren<SoftMaskable>(false);
+            SoftMaskUtils.AddSoftMaskableOnChildren(this, false);
+
             _shouldRecalculateStencil = true;
             if (TryGetComponent(out _graphic))
             {
@@ -192,7 +193,7 @@ private void OnDestroy()
 
         private void OnTransformChildrenChanged()
         {
-            this.AddComponentOnChildren<SoftMaskable>(false);
+            SoftMaskUtils.AddSoftMaskableOnChildren(this, false);
         }
 
         private void OnTransformParentChanged()
@@ -280,6 +281,7 @@ Material IMaterialModifier.GetModifiedMaterial(Material baseMaterial)
                 }, baseMaterial);
                 Profiler.EndSample();
             }
+
             Profiler.EndSample();
 
             Profiler.BeginSample("(SM4UI)[SoftMaskableMaterial] Create > Set Properties");

Packages/src/Runtime/UISoftMaskProjectSettings.cs

@@ -12,6 +12,12 @@ namespace Coffee.UISoftMask
 {
     public class UISoftMaskProjectSettings : PreloadedProjectSettings<UISoftMaskProjectSettings>
     {
+        public enum SoftMaskableTracker
+        {
+            Automatic,
+            Manual
+        }
+
         private static bool s_UseStereoMock;
 
         [Header("Setting")]
@@ -27,6 +33,12 @@ public class UISoftMaskProjectSettings : PreloadedProjectSettings<UISoftMaskProj
         [SerializeField]
         private TransformSensitivity m_TransformSensitivity = TransformSensitivity.Medium;
 
+        [Tooltip("Determines how to add SoftMaskable components under SoftMask.\n" +
+                 "Automatic: SoftMaskable components are added automatically as needed.\n" +
+                 "Manual: You need to add SoftMaskable components explicitly.")]
+        [SerializeField]
+        private SoftMaskableTracker m_SoftMaskable = SoftMaskableTracker.Automatic;
+
         [Header("Editor")]
         [Tooltip("Hide the automatically generated components.\n" +
                  "  - MaskingShapeContainer\n" +
@@ -66,6 +78,14 @@ public static TransformSensitivity transformSensitivity
             set => instance.m_TransformSensitivity = value;
         }
 
+        public static bool addSoftMaskableAutomatically
+        {
+            get => instance.m_SoftMaskable == SoftMaskableTracker.Automatic;
+            set => instance.m_SoftMaskable = value
+                ? SoftMaskableTracker.Automatic
+                : SoftMaskableTracker.Manual;
+        }
+
         public static bool useStereoMock
         {
             get => s_UseStereoMock;

Packages/src/Runtime/Utilities/SoftMaskUtils.cs

@@ -220,5 +220,16 @@ private static Material GetSoftMaskingMaterial(ref Material mat, BlendOp op)
 #endif
             return mat;
         }
+
+        /// <summary>
+        /// Adds SoftMaskable components to all children of the specified MonoBehaviour.
+        /// </summary>
+        public static void AddSoftMaskableOnChildren(MonoBehaviour self, bool includeSelf)
+        {
+            if (!self || !self.isActiveAndEnabled) return;
+            if (!self.isActiveAndEnabled) return;
+
+            self.AddComponentOnChildren<SoftMaskable>(includeSelf);
+        }
     }
 }