<< ๐ Description | ๐ Key Features | ๐ฎ Demo | โ Installation | ๐ Usage | ๐ค Contributing >>
Enhance Unity UI (uGUI) with advanced soft-masking features to create more visually appealing effects!
Mask
component.
You can convert an existing Mask
to SoftMask
from the context menu.Text
, Image
, RawImage
can be used as a masking graphic.SoftMask
supports multiple sprites and SpriteAtlas
.SoftMask
supports up to 4 nested soft masks.SoftMask
supports ScrollRect
component.SoftMask
supports overlay, camera space, and world space.UI/Dafault
.SoftMaskable
component will be added automatically at runtime as needed.MaskingShape
component.MaskingShape
component to inverse masking. You can implement effects such as iris out.TextMeshProUGUI
by importing additional shaders.This package requires Unity 2019.4 or later.
openupm add com.coffee.softmask-for-ugui
Window > Package Manager
) or run the following command with @{version}
:
openupm add com.coffee.softmask-for-ugui@2.0.0
Window > Package Manager
to open Package Manager UI.+ > Add package from git URL...
and input the repository URL: https://github.com/mob-sakai/SoftMaskForUGUI.git
#{version}
to the target version.
https://github.com/mob-sakai/SoftMaskForUGUI.git#2.0.0
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",
...
}
}
To update the package, change suffix #{version}
to the target version.
"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git#2.0.0",
Packages
directory.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.softness
: Use SoftMask.softnessRange
instead.SoftMask.partOfParent
: Use MaskingShape
component instead.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 select UI > SoftMask
category.
Click on "Upgrade All Assets V1 to V2" to modify the assets.
Add a SoftMask
component instead of Mask
component.
Or, convert an existing Mask
component to SoftMask
component from the context menu (Convert To SoftMask
).
Adjust the soft mask parameters in the inspector.
(Optional) By placing the MaskingShape
component under SoftMask
, you can add or remove the masking region.
Enjoy!
RenderTexture
and soft-maskable shader.RenderTexture
or soft-maskable shader, and works faster.Mask
component's stencil mask.RectMask2D
is a built-in component that supports soft masking.
SoftMask
provides more advanced soft masking.
SoftMasking
: RenderTexture
and soft-maskable shader.AntiAliasing
:RenderTexture
or soft-maskable shader, and works faster.Normal
: Same as Mask component's stencil mask.MaskingShape
component allows you to add or remove the masking region.MaskingShape
component (with any Graphic
) under SoftMask
component.SoftMask
component but also with Mask
component.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.Masking Mode
.RectTransformFitter
component follows the target RectTransform.RectTransformFitter.targetProperties
.MaskingShape
component, you can implement an effect that displays only the buttons during the tutorial.Edit > Project Settings
to open the Project Settings window and then select UI > SoftMask
category.var softMask = gameObject.GetComponent<SoftMask>();
softMask.maskingMode = SoftMask.MaskingMode.SoftMasking;
softMask.downSamplingRate = SoftMask.DownSamplingRate.x2;
softMask.softnessRange = new MinMax01(0.5f, 0.75f);
First, you must import TMP Essential Resources before using.
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.
The assets will be imported under Assets/Samples/UI Soft Mask/{version}
.
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);
Separate: Create a new shader with soft-maskable variants.
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 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);
The following are the limitations of SoftMaskForUGUI.
RGB ETC1 (+ Split alpha channel)
texture format is not supported.
RGBA ETC2
.Issues are incredibly valuable to this project:
Pull requests offer a fantastic way to contribute your ideas to this repository.
Please refer to CONTRIBUTING.md
and develop branch for guidelines.
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. ๐