Skip to content
/ SoftMaskForUGUI Public

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

github.com/mob-sakai/softmaskforugui
2.1k stars 270 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

mob-sakai/SoftMaskForUGUI

BranchesTags

Repository files navigation

logo SoftMaskForUGUI v3



PRs Welcome

<< 📝 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

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



🎮 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 com.coffee.softmask-for-ugui@3.0.0

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



🔄 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 Mask component's stencil mask.



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.
    • 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 Mask component's stencil mask.
  • 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.

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.

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

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

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)

  • Soft Mask Enabled: Enable soft masking.
  • 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.
  • 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 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.
  • Upgrade All Assets For V3: 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

  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 Unity 2023.2/6000.0+ or TextMeshPro 3.2/4.0+, click the TextMeshPro Support (Unity 6) > Import button instead.

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



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 "UISoftMask.cginc" and add shader features.
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
#pragma shader_feature_local _ 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 "UISoftMask.cginc" and add shader features.
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
#pragma shader_feature_local _ 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.

  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.



⚠️ 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.



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




License

  • MIT

Author

See Also

About

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

github.com/mob-sakai/SoftMaskForUGUI

Topics

components ui unity unity3d smoothing ugui mask unity-plugin uguicomponent

Resources

Readme
Activity

Stars

2.1k stars

Watchers

54 watching

Forks

270 forks
Report repository

Releases 30

3.0.0 Latest
Dec 1, 2024
+ 29 releases

Sponsor this project

  •  
Learn more about GitHub Sponsors

Contributors 8

Languages