The AMS UI Soft Mask package offers a definitive soft mask solution designed to enhance your project with the Unity UI system. Unlock the potential for gradient-based masks applying smooth and subtle masks to UI elements, adding a sophisticated touch to your projects. Enjoy precise control over revealing or concealing elements, whether it’s individual components or entire UI groups, enabling the creation of captivating transitions that effortlessly engage users.
Key Features:
- Easy Setup: Add smooth and elegant masks to your UI elements for a superior visual finish;
- Fall off & Opacity Control: Apply masks to individual elements or entire groups of UI, giving you full control over tiny visual aspects;
- Custom Shader Support: Enjoy support for custom shaders created using Shader Graph, Amplify Shader Editor, or hand-coded shaders, allowing you to extend the visual capabilities of your UI elements even further;
- Designed for Scriptable Render Pipeline: Works with BRP/SRP/HDRP/Custom RP
- All Target Platforms: Works with all build platforms;
- Seamless Integration: Easily integrate AMS UI Soft Mask into your Unity project, leveraging its functionalities effortlessly.
Getting AMS UI Soft Mask:
Useful Links:
Documentation
Support
1. Installation
- Import ‘AMS UI Soft Mask’ through “Package Manager/My Assets”; or if you have a downloaded package import it as a custom package through “Assets/Import Package/Custom Package..”.
- It’s required to have Unity’s TextMeshPro package imported into your project;
- For TextMeshPro shaders support please import the package present in the plugin folder at path: “Resources/Packages/TMP_SoftMaskSupport.unitypackage”.
Note: For different Unity versions it might be better to add TMP support manually. Please follow 3.3 Hand-coded Shader for that.
Important Note:
To ensure AMS UI Soft Mask shaders are included in builds make sure to add them to the ‘Always Included Shaders’ list at the menu “Project Settings > Graphics > Always Included Shaders”. For your convenience, we’ve added a menu item at “Window/AMS/UISoftMask/Force Include Shaders (Project Settings)”.
2. Using AMS UI Soft Mask
- Add a new “UI Soft Mask” component into your parent UI object;
- Hook your sprite mask into the “Mask” property;
- Control mask fall off by changing “Fall off” property;
- Control opacity by changing the “Opacity” property;
2.1 Properties
PROPERTY | DETAILS |
---|---|
Mask | The sprite texture that represents the mask to display. (Must be a Sprite type). |
Mask Size | The texture size. Keep low to save memory allocation. |
Mask UV | The mask UV’s type. Choose between Simple and Sliced (9-slice masks). |
Fall Off | Smooth step mask falloff control. |
Opacity | Overall opacity control. |
Override Mask Material | Use this to override the temporary UISoftMask material with a material asset from your project. Note: It requires a unique material per mask, and the shader must be compatible with UISoftMask. |
Note:
If any maskable UI element present in the hierarchy uses a material with a custom shader it is required to add ‘UI Soft Mask’ support into that shader. Please check the section 3. Custom Shader Support for more details.
Tip:
Use the “Override Mask Material” property to override the UISoftMask material in favor of using a target material. Note: It requires a unique material per mask and the shader must be compatible with AMS UI Soft Mask.
3. Custom Shader Support
AMS UI Soft Mask has support for custom shaders. In this section, you can find all the details about adding a soft mask to your UI custom shader.
3.1 Shader Graph
3.2 Amplify Shader Editor
3.3 Hand-coded Shader
3.1 Shader Graph
Into Shader Graph Editor search by “UISoftMask” to use the soft mask SubGraph like below:
Notes:
- When using Shader Graph for UI shaders you might notice some unusual behaviour. At least when we release this tool Shader Graph doesn’t support UI shaders. So, we strongly recommend using a different shader editor or hand-coding shaders.
- Please note that Shader Graph requires manually adding “_SoftMask (Texture2D)” property;
3.2 Amplify Shader Editor
Into Amplify Shader Editor search by “UI Soft Mask” to use the soft mask Amplify Shader Function like below:
3.3 Hand-coded Shader
If you are using hand-coded shaders for the UI, please add the following lines of code to your shader in their respective locations.
Shader "Example/UISoftMask"
{
Properties
{
//...
//1. SHADER PROPERTIES
// Add this line into ShaderLab Properties Block
[PerRendererData]_SoftMask("_SoftMask", 2D) = "white" {}
//...
}
SubShader
{
Pass
{
CGPROGRAM
//...
//2. INCLUDE & PROPERTIES
// Add both lines before your 'Vertex Output' struct.
// Note: Make sure to change include path if you are using a different location for 'AMS UI Soft Mask' package
#include_with_pragmas "Assets/AMS/UISoftMask/Shader/Utils/UISoftMask.hlsl"
uniform sampler2D _SoftMask;
//...
struct Varyings{
//...
//3. VERTEX OUTPUT STRUCT
// Add this line into 'Vertex Output' struct.
float2 softMaskUV : TEXCOORDX; // 'X' being the TexCoord Index available on struct
//...
}
Varyings vert (Attributes IN)
{
//...
//4. VERTEX FUNCTION
// Add both lines into Vertex function
// Note: 'IN.vertex' being the corresponding 'Vertex Data : POSITION' and 'OUT' being the 'Vertex Output' in vertex function
float4 wPos = mul(unity_ObjectToWorld, IN.vertex);
OUT.softMaskUV.xy = RectUV(wPos);
//...
}
half4 frag(Varyings IN) : SV_Target
{
//...
//5. FRAGMENT FUNCTION
// Add this line into Fragment function just before UNITY_UI_ALPHACLIP instruction
// Note: 'IN' being the corresponding 'Vertex Output' and 'color' the candidate fragment output
color.a = UISoftMask(IN.softMaskUV, _SoftMask, color.a);
//...
}
ENDCG
}
}
}
4. Changelog
- 1.0.13
- Fixed callback when RectTranform.sizeDelta changes.
- Minor fixes.
- 1.0.12
- Canvas overlay mode: fixed matrix transformation to prevent scaling issues.
- Shader improvements: added trim UV factor to prevent mask outbound.
- 1.0.11
- Editor improvement: Fix for missing mask when undo/redo;
- Fixed callback when scale changes;
- 1.0.10
- Editor improvement: prevent warning on play start after editing a prefab;
- 1.0.9
- Added coexisting for Gamma and Linear color spaces;
- Removed keywords to avoid stripping soft mask shader variant;
- Minor fixes.
- 1.0.8
- Fixed enable/disable state behavior;
- Minor improvements;
- 1.0.7
- Added TMP font material shader change validation;
- TMP package updated: Introduced support to main SDF and mobile minor fixes;
- 1.0.6
- Improved atlas masking behavior;
- Fixed mask rotation;
- 1.0.5
- Shader improvements;
- Introduced Mask UV for 9-slicing mask support;
- Fixed resetting TextMesh objects during OnDisable;
- General fixes;
- 1.0.4
- Shader: Added support to linear color space and fixed keyword to prevent malfunctioning with Unity 6;
- Added support for atlas-packed masks;
- Improved functionality to allow different canvas modes simultaneously;
- Enhanced override mask material;
- Removed hidden rule for the default shader;
- Built-In RP: Added a workaround menu toggle for editing in SceneView;
- General fixes;
- 1.0.3
- Added support for mask rotation;
- Improvements to allow maskable object state for runtime purposes;
- Shader improvements and general fixes;
- 1.0.2
- Mask: changed to sprite type in favor of preventing user-duplicated assets;
- Shader: fixed mask distortion outside bounds;
- Performance and general fixes;
- 1.0.1
- WorldCanvas mode improvements;
- Shader: fixed instruction to allow transparent-white masks
- Added MenuItem to force include shaders in build;
- General fixes;
- 1.0
- First release;
Need Support? (Customer-only)
For support or general inquiries please use the form below.