mob-sakai/SoftMaskForUGUI

SoftMaskForUGUI v3

<< 📝 Description | 📌 Key Features | 🎮 Demo | ⚙ Installation | 🚀 Usage | 🤝 Contributing >>

📝 Description

Enhance Unity UI (uGUI) with advanced soft-masking features to create more visually appealing effects!

• 📌 Key Features
• 🎮 Demo
• ⚙ Installation
  • Install via OpenUPM
  • Install via UPM (with Package Manager UI)
  • Install via UPM (Manually)
  • Install as Embedded Package
  • Import Additional Resources
• 🔄 Upgrade All Assets For V3
• 🚀 Usage
  • Getting Started
  • RectMask2D vs SoftMask
  • Comparison of Masking Mode
  • Component: SoftMask
  • Component: SoftMaskable
  • Component: MaskingShape
  • Component: RectTransformFitter
  • Project Settings
  • Usage with Scripts
  • Usage with TextMeshPro or Spine
  • Usage with Your Custom Shaders
  • Usage with Canvas ShaderGraph
  • Usage with UIEffect
  • :warning: Limitations
• 🤝 Contributing
  • Issues
  • Pull Requests
  • Support
• License
• Author
• See Also

📌 Key Features

• Compatibility with Mask: SoftMask is fully compatible with the existing Mask component. You can convert an existing Mask to SoftMask from the context menu.
  
• Adjustable Visible Part: You can freely adjust the visible part of the mask.
  
• Versatile Masking Options: Text, Image, RawImage can be used as a masking graphic.
• Support for Multiple Sprites and SpriteAtlas: SoftMask supports multiple sprites and SpriteAtlas.
• Nested Soft Masks: SoftMask supports up to 4 nested soft masks.
  
• ScrollRect Support: SoftMask supports ScrollRect component.
• All Render Mode Support: SoftMask supports overlay, camera space, and world space.
• Soft-Maskable UI Shader Included: The package includes a soft-maskable UI shader for UI/Dafault.
• Custom Shader Support: You can make your custom shaders soft-maskable with little modification. For details, please see soft-maskable shader.
• Performance/Quality Adjustment: You can adjust the soft mask buffer size to improve performance or quality.
  
• Efficient Rendering: The soft mask buffer will be updated only when needed to improve performance.
• SoftMaskable Component: SoftMaskable component will be added automatically at runtime as needed.
• Soft Mask Buffer Preview: You can preview the soft mask buffer in the inspector.
  
• Anti-Alias Masking Mode: If you don't need semi-transparent masks, you can use the more performant "Anti-Aliasing Masking Mode".
  
• Masking Shape: You can add or remove mask region using MaskingShape component.
  
• Inverse Masking: Use MaskingShape component to inverse masking. You can implement effects such as iris out.
  
• Ray-cast Filtering: Ray-casts are filtered only for the visible part. This feature is useful for preventing clicks on masked parts during tutorials.
  
• Stereo Support: Soft masking for VR.
  
• TextMeshProUGUI Support: Support TextMeshProUGUI by importing additional shaders.
  It also supports TextMeshPro v3.2/4.0 (pre-release) and uGUI 2.0 (Unity 2023.2+/6.0+). For details, please see Support TextMeshPro or Spine.
  
• Better Editor Experience: In the Scene view, objects outside the screen are displayed as stencil masks, allowing for more intuitive editing.
  
• Soft Maskable Shader Variant Stripping: SoftMaskable shaders are automatically included at build time. You can remove unused shader variants.
  
• Spine Support: Support Spine (SkeletonGraphic) by importing additional shaders.
  For details, please see Support TextMeshPro or Spine.
  

🎮 Demo

WebGL Demo

⚙ Installation

This package requires Unity 2019.4 or later.

Install via OpenUPM

• This package is available on OpenUPM package registry.
• This is the preferred method of installation, as you can easily receive updates as they're released.
• If you have openupm-cli installed, then run the following command in your project's directory:

  openupm add com.coffee.softmask-for-ugui
  

• To update the package, use Package Manager UI (Window > Package Manager) or run the following command with @{version}:

  openupm add [email protected]
  

Install via UPM (with Package Manager UI)

• Click Window > Package Manager to open Package Manager UI.
• Click + > Add package from git URL... and input the repository URL: https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/src
  
• To update the package, change suffix #{version} to the target version.
  • e.g. https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/src#3.2.0

Install via UPM (Manually)

• Open the Packages/manifest.json file in your project. Then add this package somewhere in the dependencies block:

  {
    "dependencies": {
      "com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/src",
      ...
    }
  }
  

• To update the package, change suffix #{version} to the target version.

  • e.g. "com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/src#3.2.0",

Install as Embedded Package

1. Download the Source code (zip) file from Releases and extract it.
2. Move the <extracted_dir>/Packages/src directory into your project's Packages directory.
   
   • You can rename the src directory if needed.
   • If you intend to fix bugs or add features, installing it as an embedded package is recommended.
   • To update the package, re-download it and replace the existing contents.

Import Additional Resources

Additional resources can be imported to extend functionality.

• Usage with TextMeshPro or Spine.
• Usage with Canvas ShaderGraph.

🔄 Upgrade All Assets For V3

If you are currently using SoftMaskForUGUI v1.x/v2.x, the following breaking changes are included when upgrading to v3:

1. (From v1) API changes: Some APIs are obsolete.

   • SoftMask.alpha: Use Graphic.color.a instead.
   • SoftMask.softness: Use SoftMask.softnessRange instead.
   • SoftMask.partOfParent: Use MaskingShape component instead.
   • SoftMask.ignoreParent: Removed.
   • SoftMask.ignoreSelfGraphic: Removed.
   • SoftMask.ignoreSelfStencil: Removed.
   • SoftMaskable.useStencil: Removed.
   • SoftMaskable.raycastFilter: Use SoftMask.alphaHitTest instead.
   • SoftMaskable.maskInteraction: If you want to use as inverse mask, use MaskingShape component and MaskingMethod=Subtract.

2. (From v1) SoftMaskable component: SoftMaskable component is no longer required to be added explicitly.

   • It will be added automatically at runtime as needed.

3. (From v1) SoftMaskable shader: SoftMask() function has been updated with additional arguments.

   // Before
   color.a *= SoftMask(IN.vertex, IN.worldPosition);
   // After
   color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);
   

4. (From v2) SoftMaskable shader: SOFTMASKABLE shader feature is now required.

   #pragma shader_feature_local _ SOFTMASKABLE
   

5. If you are installing via git URL, add ?path=Packages/src.

   // v1/v2
   "com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git",
   
   // v3
   "com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/src",
   

6. Hidden/UI/SoftMask, Hidden/UI/TerminalMaskingShape and SoftMaskable shader variants used at runtime must be registered in the Project Settings.

   • In v2, the SoftMaskable shaders were included in the "Always Included Shaders", but in v3, they must be registered automatically or manually.
   • You can strip unnecessary shader variants to reduce build time and file size.
   • If SoftMask does not display correctly in the player, open/play the scenes or prefabs in the editor. The shader variants will be automatically registered.

To apply these changes automatically, please follow the steps below:

1. Click Edit > Project Settings to open the Project Settings window and select UI > SoftMask category.

2. Click Upgrade All Assets For V3 to upgrade the assets.

• ⚠️ If you select Dry Run, you can check the changes before upgrading.
  

🚀 Usage

Getting Started

1. Install the package.

2. Add a SoftMask component instead of Mask component.
   Or, convert an existing Mask component to SoftMask component from the context menu (Convert To SoftMask).
   

3. Adjust the soft mask parameters in the inspector.
   

4. (Optional) By placing the MaskingShape component under SoftMask, you can add or remove the masking region.
   

5. Enjoy!

RectMask2D vs SoftMask

RectMask2D is a built-in component that supports soft masking.
SoftMask provides more advanced soft masking.

• RectMask2D:
  • uGUI built-in
  • Very fast
  • Supports only rectangular shapes
  • Supports only one level of nesting
  • Supports only limited rotation
• SoftMask:
  • Advanced soft masking
  • Supports any graphic shape
  • Supports up to 4 levels of nesting soft-masking
  • Supports fully rotation

Comparison of Masking Mode

• Soft Masking: Smooth mask with semi-transparency.
  Requires memory for RenderTexture and soft-maskable shader.
• Anti-Aliasing: Less jagged stencil mask.
  It does not require RenderTexture or soft-maskable shader, and works faster.
• Normal: Same as Unity UI default Mask component.

Component: SoftMask

• Masking Mode:
  • SoftMasking:
    • Smooth mask with semi-transparency.
    • Requires memory for RenderTexture and soft-maskable shader.
    • Use RenderTexture as a soft mask buffer.
    • The alpha of the masking graphic can be used.
    • ⚠️ Enable Project Settings > UI > Soft Mask > Soft Mask Enabled to use this mode.
  • AntiAliasing:
    • Less jagged stencil mask.
    • It does not require RenderTexture or soft-maskable shader, and works faster.
    • Suppress the jaggedness of the masking graphic.
    • The masking graphic cannot be displayed.
  • Normal: Same as Unity UI default Mask component.
• Show Mask Graphic (SoftMasking or Normal): Show the graphic that is associated with the Mask render area.
• Alpha Hit Test: The transparent part of the mask cannot be clicked.
  • Alpha hit test is not supported when the texture is in crunch format or non-readable.
  • ⚠️ Enable this only if necessary, as it will require more graphics memory and processing time.
• Anti Aliasing Threshold (AntiAliasing only): Threshold for anti-alias masking. The smaller this value, the less jagged it is.
• Softness Range (SoftMasking only): The minimum and maximum alpha values used for soft masking. The larger the gap between these values, the stronger the softness effect.
• Down Sampling Rate (SoftMasking only): The down sampling rate for soft mask buffer. The higher this value, the lower the quality of the soft masking, but the performance will improve.
• Preview Soft Mask Buffer (in editor, SoftMasking only): Preview the soft mask buffer in the inspector.

Component: SoftMaskable

• Ignore Self: The graphic is ignored when soft-masking.
• Ignore Children: The child graphics are ignored when soft-masking.
• Power: Soft masking power.
  • The higher this value, the faster it becomes transparent.
  • If overlapping objects appear see-through, please adjust this value.
    

[!TIPS] SoftMaskable components are added automatically to GameObjects under a SoftMask component.
If the properties are set to their default values, it is marked as HideFlag.DontSave and will not be saved in the scene or prefab.

Component: MaskingShape

• Masking Method: Additive, Subtract
• Show Mask Graphic (SoftMasking or Normal): Show the graphic that is associated with the Mask render area.
• Alpha Hit Test: The transparent part of the mask cannot be clicked.
  • Alpha hit test is not supported when the texture is in crunch format or non-readable.
  • ⚠️ Enable this only if necessary, as it will require more graphics memory and processing time.
• Softness Range (SoftMasking only): Override the softness range of the parent SoftMask component.
• Anti Aliasing Threshold (AntiAliasing only): Override the anti-alias threshold of the parent SoftMask component.
• Raycast Method:
  • Auto (Default): Same behavior as before. A mode similar to Masking Method is selected.
  • Additive: When the pointer is within this shape, the raycast is enabled.
  • Subtract: When the pointer is within this shape, the raycast is disabled.
  • Ignore: This shape is ignored in raycast determination.

[!TIPS] MaskingShape component allows you to add or remove the masking region.
Placing MaskingShape component (with any Graphic) under SoftMask component.

[!TIPS] You can use it not only with SoftMask component but also with Mask component.
If the MaskingMode is AntiAliasing or Normal, or if you are using the Mask component, the MaskingShape component must be placed above the masked Graphic in the hierarchy.
This is a limitation based on the stencil mask.
The available features depend on the Masking Mode.

Component: RectTransformFitter

• Target: The target RectTransform to follow.
• Target Properties: Position (X/Y/Z), Rotation (X/Y/Z), Scale (X/Y/Z), Delta Size (X/Y).

[!TIPS] RectTransformFitter component follows the target RectTransform.
You can specify the properties to follow (position, rotation, scale, delta size) with RectTransformFitter.targetProperties.
By combining it with the MaskingShape component, you can implement an effect that displays only the buttons during the tutorial.

Project Settings

You can adjust the project-wide settings for SoftMaskForUGUI. (Edit > Project Settings > UI > Soft Mask)

[!IMPORTANT] The setting file is usually saved in Assets/ProjectSettings/UISoftMaskProjectSettings.asset. Include this file in your version control system.
The setting file is automatically added as a preloaded asset in ProjectSettings/ProjectSettings.asset.
To hot-update the shader variants, see Advanced > Pre Load Settings In Build.

Setting

• Soft Mask Enabled: Enable soft masking.
  • If disabled, the Soft Masking mode will behave as Normal mode.
• Stereo Enabled: Enable VR mode.
• 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.

Editor

• Hide Generated Component: Automatically hide the generated MaskingShapeContainer and TerminalMaskingShape components.

Shader

• Optional Shaders (SoftMaskable): A list of shaders that will be prioritized when a soft-maskable shader is requested.
  • If the shader is included in the list, that shader will be used.
  • If it is not in the list, the following shaders will be used in order:
    • If the shader name contains (SoftMaskable), that shader will be used.
    • If Hidden/<shader_name> (SoftMaskable) exists, that shader will be used.
    • As a fallback, UI/Default (SoftMaskable) will be used.
• Registered Variants: A list of shader variants available at runtime. Use "-" button to remove unused variants, reducing build time and file size.
  • By default, the soft-maskable shaders will be included in the build, but you can remove it if you don't need it.
• Unregistered Variants: A list of shader variants that are not registered. Use "+" button to add variants.
• Error On Unregistered Variant: If enabled, an error will be displayed when an unregistered shader variant is used.
  • The shader variant will be automatically added to the Unregistered Variants list.

Advanced

• Pre Load Settings In Build: When enabled, this settings asset will be added to PlayerSettings.preloadedAssets in build.
• When disable, you should load this settings via Resources, AssetBundles or Addressables to use this package.
• You can overwrite the settings by re-enabling UISoftMaskProjectSettings. This allows you to hot update shader variants and presets.

private static IEnumerator HotUpdateCoroutine()
{
    const string k_SettingsAddress = "Assets/ProjectSettings/UISoftMaskProjectSettings.asset";
    yield return Addressables.LoadAssetAsync<UISoftMaskProjectSettings>(k_SettingsAddress);
    while (UISoftMaskProjectSettings.shaderVariantCollection.WarmUpProgressively(5) == false) yield return null;
}

Upgrade

• Upgrade All Assets For V3: Upgrade all assets for v3.
  • ⚠️ This will apply the changes to all assets in the project.
  • For details, please see Upgrade All Assets For V3.

Usage with Scripts

var softMask = gameObject.GetComponent<SoftMask>();
softMask.maskingMode = SoftMask.MaskingMode.SoftMasking;
softMask.downSamplingRate = SoftMask.DownSamplingRate.x2;
softMask.softnessRange = new MinMax01(0.5f, 0.75f);

Usage with TextMeshPro or Spine

To use SoftMask with TextMeshPro or Spine, you need to import additional resources.
When a shader included in the samples is requested, an import dialog will automatically appear.
Click the Import button.

Alternatively, you can manually import the resources by following these steps:

1. Open the Package Manager window and select the UI Soft Mask package from the package list.

2. Click the Import button for each sample to import the required resources.
   

   • TextMeshPro (Unity 2023.1 or earlier): TextMeshPro Support
   • TextMeshPro (Unity 2023.2, 6000.0 or later): TextMeshPro Support (Unity 6)
   • Spine: Spine Support

3. The assets will be imported under Assets/Samples/UI Soft Mask/{version}.

[!TIP] If you have moved TMPro_Properties.cginc and TMPro.cginc from their default install path (Assets/TextMesh Pro/Shaders/...), you will need to manually update the paths in the shaders under TextMeshPro Support or TextMeshPro Support (Unity 6).

Usage with Your Custom Shaders

Here, let's make UI/Additive custom shader soft-maskable.
There are two ways to support SoftMask with custom shaders.

• Hybrid (recommended): Add soft-maskable variants to the existing shader. ( e.g. UI/Additive (SoftMaskable))
  Modify the shader as follows:

  // Add the ` (SoftMaskable)` suffix to the shader name.
  Shader "UI/Additive (SoftMaskable)"
  
  // Import "SoftMask.cginc" and add shader features.
  #include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
  #pragma shader_feature _ SOFTMASK_EDITOR
  #pragma shader_feature_local _ SOFTMASKABLE
  
  // "SoftMask" function returns [0-1]. Multiply this by the final output.
  color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);
  

• Separate: Create a new shader with soft-maskable variants. ( e.g. Hidden/UI/Additive (SoftMaskable))
  Use this way for built-in shaders that cannot be edited, like UI/Default.
  Modify the shader as follows:

  // Add the `Hidden/` prefix and ` (SoftMaskable)` suffix to the shader name.
  Shader "Hidden/UI/Additive (SoftMaskable)"
  
  // Import "SoftMask.cginc" and add shader features.
  #include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
  #pragma shader_feature _ SOFTMASK_EDITOR
  #pragma shader_feature_local _ SOFTMASKABLE
  
  // "SoftMask" function returns [0-1]. Multiply this by the final output.
  color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);
  

  

Usage with Canvas ShaderGraph

NOTE: Unity 2023.2/6000.0+ is required.

1. Open the Package Manager window and select the UI Soft Mask package in the package list and click the ShaderGraph Support > Import button.

2. The sample includes UIDefault (SoftMaskable).shadergraph and SoftMask.subshadergraph.
   You can use the sample as references to make your own shader graph compatible with SoftMask.

   1. Add (SoftMaskable) at the end of the shader name.
   2. Add SOFTMASK_EDITOR and SOFTMASKABLE as a Boolean Keyword (Shader Feature).
   3. Add the Sub Graphs > SoftMask node and connect it to the final alpha output.
      

Usage with UIEffect

UIEffect is a package that allows you to intuitively apply rich Unity UI effects.

SoftMaskForUGUI (v3.3.0+) supports UIEffect (v5.6.0+).
When a shader included in the samples is requested, an import dialog will automatically appear.
Click the Import button.

:warning: Limitations

The following are the limitations of SoftMaskForUGUI.

• (Android) RGB ETC1 (+ Split alpha channel) texture format is not supported.
  • Use a format that supports alpha, such as RGBA ETC2.
  • Technically possible, but not supported because ETC2 support rate is over 95%.
  • If needed, feel free to create an issue.
• Alpha hit test is not supported when the texture is in crunch format or non-readable.
• Hidden/UI/SoftMask, Hidden/UI/TerminalMaskingShape and SoftMaskable shader variants used at runtime must be registered in the Project Settings.
• If you are using DynamicResolution or RenderScale (URP), the display may not work correctly.
  • For details, see the issue.

🤝 Contributing

Issues

Issues are incredibly valuable to this project:

• Ideas provide a valuable source of contributions that others can make.
• Problems help identify areas where this project needs improvement.
• Questions indicate where contributors can enhance the user experience.

Pull Requests

Pull requests offer a fantastic way to contribute your ideas to this repository.
Please refer to CONTRIBUTING.md and develop branch.

Support

This is an open-source project developed during my spare time.
If you appreciate it, consider supporting me.
Your support allows me to dedicate more time to development. 😊

License

• MIT

Author

• mob-sakai

See Also

• GitHub page : https://github.com/mob-sakai/SoftMaskForUGUI
• Releases : https://github.com/mob-sakai/SoftMaskForUGUI/releases
• Issue tracker : https://github.com/mob-sakai/SoftMaskForUGUI/issues
• Change log : https://github.com/mob-sakai/SoftMaskForUGUI/blob/main/Packages/src/CHANGELOG.md