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 -->
<< 📝 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!
- 📌 Key Features
- 🎮 Demo
- ⚙ Installation
- 🔄 Upgrading from v1 to v2
- 🚀 Usage
- 🤝 Contributing
- License
- Author
- See Also
<br><br>
📌 Key Features
- Compatibility with Mask: SoftMask is fully compatible with the existing
Mask
component. You can convert an existingMask
toSoftMask
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 andSpriteAtlas
. - Nested Soft Masks:
SoftMask
supports up to 4 nested soft masks.
- ScrollRect Support:
SoftMask
supportsScrollRect
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.
- Automatic Shader Include and Stripping: SoftMaskable shaders are automatically included at build time, and unused shader variants are removed.
<br><br>
🎮 Demo
<br><br>
⚙ 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@2.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
- To update the package, change suffix
#{version}
to the target version.- e.g.
https://github.com/mob-sakai/SoftMaskForUGUI.git#2.0.0
- e.g.
Install via UPM (Manually)
-
Open the
Packages/manifest.json
file in your project. Then add this package somewhere in thedependencies
block:{ "dependencies": { "com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git", ... } }
-
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#2.0.0",
- e.g.
Install as Embedded Package
- Download a source code zip file from Releases and extract it.
- Place it in your project's
Packages
directory.
- If you want to fix bugs or add features, install it as an embedded package.
- To update the package, you need to re-download it and replace the contents.
<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:
- API changes: Some APIs are obsolete.
SoftMask.alpha
: UseGraphic.color.a
instead.SoftMask.softness
: UseSoftMask.softnessRange
instead.SoftMask.partOfParent
: UseMaskingShape
component instead.SoftMask.ignoreParent
: Removed.SoftMask.ignoreSelfGraphic
: Removed.SoftMask.ignoreSelfStencil
: Removed.SoftMaskable.useStencil
: Removed.SoftMaskable.raycastFilter
: UseSoftMask.alphaHitTest
instead.SoftMaskable.maskInteraction
: If you want to use as inverse mask, useMaskingShape
component andMaskingMethod=Subtract
.
-
SoftMaskable
component:SoftMaskable
component is no longer required to be added explicitly. It will be added automatically at runtime as needed. -
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);
To apply these changes automatically, please follow the steps below:
-
Click
Edit > Project Settings
to open the Project Settings window and selectUI > SoftMask
category. -
Click
Upgrade All Assets V1 to V2
to upgrade the assets.
- ⚠️ If you select
Dry Run
, you can check the changes before upgrading.
<br><br>
🚀 Usage
Getting Started
-
Add a
SoftMask
component instead ofMask
component.
Or, convert an existingMask
component toSoftMask
component from the context menu (Convert To SoftMask
).
-
Adjust the soft mask parameters in the inspector.
-
(Optional) By placing the
MaskingShape
component underSoftMask
, you can add or remove the masking region.
-
Enjoy!
<br><br>
Comparison of Masking Mode
- Soft Masking: Smooth mask with semi-transparency.
Requires memory forRenderTexture
and soft-maskable shader. - Anti-Aliasing: Less jagged stencil mask.
It does not requireRenderTexture
or soft-maskable shader, and works faster. - Normal: Same as
Mask
component's stencil mask.
<br><br>
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
<br><br>
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:
- Show the graphic that is associated with the Mask render area.
- Alpha Hit Test:
- The transparent part of the mask cannot be clicked.
- This can be achieved by enabling Read/Write enabled in the Texture Import Settings for the texture.
- ⚠️ 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 (editor, SoftMasking only):
- Preview the soft mask buffer in the inspector.
<br><br>
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.
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
MaskingShape
component allows you to add or remove the masking region.- Placing
MaskingShape
component (with anyGraphic
) underSoftMask
component.
- You can use it not only with
SoftMask
component but also withMask
component. - If the
MaskingMode
isAntiAliasing
orNormal
, or if you are using theMask
component, theMaskingShape
component must be placed above the maskedGraphic
in the hierarchy. This is a limitation based on the stencil mask. - The available features depend on the
Masking Mode
.
<br><br>
Component: RectTransformFitter
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.
<br><br>
Project Settings
- Click
Edit > Project Settings
to open the Project Settings window and then selectUI > SoftMask
category. - To use the softmaskable shaders at runtime, you need to register the shaders as
Always Included Shaders
.- By default, the soft-maskable shaders will be included in the build, but you can remove it if you don't need it.
<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
-
First, you must import TMP Essential Resources before using.
-
Open the
Package Manager
window and select theUI Soft Mask
package in the package list and click theTextMeshPro Support > Import
button.
⚠️ If you are usingugui 2.0 (=Unity 2023.2+/6.0+)
orTextMeshPro 3.2+/4.0+
, click theTextMeshPro Support (ugui 2.0) > Import
button instead.
-
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.
-
Hybrid (recommended): Add soft-maskable variants to the existing shader.
Modify the shader as follows:// Add the ` (SoftMaskable)` suffix to the shader name. Shader "UI/Additive (SoftMaskable)" // Import "UISoftMask.cginc" and add shader variants for editor. #include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc" #pragma multi_compile_local _ SOFTMASK_EDITOR // soft-maskable for editor // "SoftMask" function returns [0-1]. Multiply this by the final output. color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);
- Result: UI/Additive (SoftMaskable)
-
Separate: Create a new shader with soft-maskable variants.
Use this way for built-in shaders that cannot be edited, likeUI/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 variants for editor. #include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc" #pragma multi_compile_local _ SOFTMASK_EDITOR // "SoftMask" function returns [0-1]. Multiply this by the final output. color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);
<br><br>
Usage with ShaderGraph
NOTE: Unity 2023.2/6000.0+ is required.
-
Open the
Package Manager
window and select theUI Soft Mask
package in the package list and click theShaderGraph Support > Import
button. -
The sample includes
UIDefault (SoftMaskable).shadergraph
andSoftMask.subshadergraph
.
You can use the sample as references to make your own shader graph compatible withSoftMask
.- Add
(SoftMaskable)
at the end of the shader name. - Add
SOFTMASK_EDITOR
as aBoolean Keyword (Shader Feature)
. - Add the
Sub Graphs > SoftMask
node and connect it to the final alpha output.
- Add
-
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.
⚠️ Currently, the soft-maskable ShaderGraph does not display correctly in the SceneView.
<br><br>
: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.
- Use a format that supports alpha, such as
- Alpha hit test is not supported when the texture is in crunch format or non-readable.
<br><br>
🤝 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. 😊
<br><br>
License
- MIT
Author
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/CHANGELOG.md