3.0.0

3.0.0 (2024-12-01)

Bug Fixes

• fix anti-aliasing issues (e68ee7b)

Features

• add 'SOFTMASKABLE' shader feature to improve shader build (eec3212)
• asset upgrade system 'SOFTMASKABLE' shader feature (d36f932)
• MaskingShape components always use stencil mask (6c6ac59), closes #203 #209
• strip shaders using ShaderVariantCollection instead of 'Always Include Shaders' (5f4c435), closes #211
• update asset upgrade system to unregister always included shaders (906bdb6)

BREAKING CHANGES

• SoftMaskable shaders now require the SOFTMASKABLE shader feature.
  Please upgrade assets from Project Settings > UI > Soft Mask or refer to the 'README > Usage with Your Custom Shaders' section to manually update your shaders.

---

🎮 Demo

WebGL Demo

⚙ Installation

This package requires Unity 2019.4 or later.

Install via OpenUPM

openupm add com.softmask-for-ugui
# or, for a specific version
openupm add com.softmask-for-ugui@3.0.0

Install via UPM

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

Import Additional Resources

Additional resources can be imported to extend functionality.

• Usage with TextMeshPro.

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