Home

Awesome

<img alt="logo" height="26" src="https://github.com/mob-sakai/mob-sakai/assets/12690315/05eae124-58aa-414d-9e9f-cc65022e9854"/> SoftMaskForUGUI v2 <!-- omit in toc -->



PRs Welcome

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

📝 Description <!-- omit in toc -->

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

<br><br>

📌 Key Features

<br><br>

🎮 Demo

WebGL Demo

<br><br>

⚙ Installation

This package requires Unity 2019.4 or later.

Install via OpenUPM

Install via UPM (with Package Manager UI)

Install via UPM (Manually)

Install as Embedded Package

  1. Download a source code zip file from Releases and extract it.
  2. Place it in your project's Packages directory.

<br><br>

🔄 Upgrading from v1 to v2

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

  1. API changes: Some APIs are obsolete.
  1. SoftMaskable component: SoftMaskable component is no longer required to be added explicitly. It will be added automatically at runtime as needed.

  2. 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);
    
<br>

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 V1 to V2 to upgrade the assets.

<br><br>

🚀 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!

<br><br>

Comparison of Masking Mode

<br><br>

RectMask2D vs SoftMask

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

<br><br>

Component: SoftMask

<br><br>

Component: SoftMaskable

NOTE: SoftMaskable components are added automatically.
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.

<br><br>

Component: MaskingShape

<br><br>

Component: RectTransformFitter

<br><br>

Project Settings

<br><br>

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);

<br><br>

Usage with TextMeshPro

  1. First, you must import TMP Essential Resources before using.

  2. Open the Package Manager window and select the UI Soft Mask package in the package list and click the TextMeshPro Support > Import button.
    ⚠️ If you are using ugui 2.0 (=Unity 2023.2+/6.0+) or TextMeshPro 3.2+/4.0+, click the TextMeshPro Support (ugui 2.0) > Import button instead.

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

<br><br>

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.

<br><br>

Usage with 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 as a Boolean Keyword (Shader Feature).
    3. Add the Sub Graphs > SoftMask node and connect it to the final alpha output.
  3. To use the soft-maskable ShaderGraph in the editor, the SoftMaskable ShaderGraph Support (Editor) renderer feature is required.
    This feature is specifically for previewing SoftMaskable ShaderGraph in the editor and will be automatically removed during the build process.
    SoftMaskable ShaderGraph Support

⚠️ Currently, the soft-maskable ShaderGraph does not display correctly in the SceneView.

<br><br>

:warning: Limitations

The following are the limitations of SoftMaskForUGUI.

<br><br>

🤝 Contributing

Issues

Issues are incredibly valuable to this project:

Pull Requests

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

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. 😊


<br><br>

License

Author

See Also