repository·main·Indexed 25 days ago
https://github.com/mob-sakai/softmaskforuguiA Unity package (com.coffee.softmask-for-ugui) providing a smooth masking component for uGUI elements. It enables rounded edges, semi-transparent edges, nested masks, and various masking shapes via the SoftMask, SoftMaskable, and MaskingShape components. Supports three masking modes: SoftMasking, AntiAliasing, and Normal. Includes integration for TextMeshPro and Spine, as well as tools for creating custom soft-maskable shaders.
Choose between the built-in RectMask2D and SoftMask based on your requirements:
| Feature | RectMask2D | SoftMask |
|---|---|---|
| Type | uGUI built-in | Advanced soft masking |
| Performance | Very fast | Requires RenderTexture/Shader |
| Shapes | Rectangular only | Any graphic shape |
| Nesting | 1 level only | Up to 4 levels |
| Rotation | Limited | Fully supported |
You can install the package directly through the Unity Package Manager:
Window > Package Manager.+ button and select Add package from git URL....https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/srcTo target a specific version, append #version to the end of the URL (e.g., #3.2.0).
https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/srcTo use SoftMaskForUGUI in your project:
SoftMask component to a GameObject instead of the standard Unity Mask component. You can also convert an existing Mask component to SoftMask via the context menu using Convert To SoftMask.MaskingShape: Place a MaskingShape component under the SoftMask component to add or remove specific masking regions.If you want to modify the source code or keep the package within your project folder:
Source code (zip) from the Releases page and extract it.<extracted_dir>/Packages/src directory into your Unity project's Packages directory.src directory if desired.To use SoftMask with TextMeshPro or Spine, you must import specific support assets:
UI Soft Mask package.TextMeshPro SupportTextMeshPro Support (Unity 6)Spine SupportAssets/Samples/UI Soft Mask/{version}.Note: If you have moved TMPro_Properties.cginc or TMPro.cginc from their default Unity paths, you must manually update the paths in the imported shaders.
To hot-update shader variants and presets in a build, enable Pre Load Settings In Build in the Project Settings. This adds the settings asset to PlayerSettings.preloadedAssets.
If disabled, you must load the settings via Resources, AssetBundles, or Addressables. You can use the following pattern to load and warm up variants:
private static IEnumerator HotUpdateCoroutine()
{
const string k_SettingsAddress = "Assets/ProjectSettings/UISoftMaskProjectSettings.asset";
yield return Addressables.LoadAssetAsync<UISoftMaskProjectSettings>(k_SettingsAddress);
while (UISoftMaskProjectSettings.shaderVariantCollection.WarmUpProgressively(5) == false) yield return null;
}You can make custom shaders compatible with SoftMask using two methods:
Add soft-maskable variants to your existing shader.
(SoftMaskable) suffix to the shader name.Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc.#pragma shader_feature _ SOFTMASK_EDITOR and #pragma shader_feature_local _ SOFTMASKABLE.SoftMask function.// Add the ` (SoftMaskable)` suffix to the shader name.
Shader "UI/Additive (SoftMaskable)"
// Import "SoftMask.cginc" and add shader features.
#include "Packages/com.coffee.softmask-for-ugui/Shaders/SoftMask.cginc"
#pragma shader_feature _ 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);Create a new shader specifically for soft masking. This is useful for built-in shaders that cannot be edited.
Hidden/ prefix and the (SoftMaskable) suffix to the shader name.Add the package dependency directly to your project's Packages/manifest.json file within the dependencies block.
{
"dependencies": {
"com.coffee.softmask-for-ugui": "https://github.com/mob-sakai/SoftMaskForUGUI.git?path=Packages/src",
...
}
}If you are upgrading from SoftMaskForUGUI v1.x or v2.x to v3, several breaking changes apply to APIs, shaders, and installation methods.
SoftMask.alpha $\rightarrow$ Use Graphic.color.a.SoftMask.softness $\rightarrow$ Use SoftMask.softnessRange.SoftMask.partOfParent $\rightarrow$ Use MaskingShape component.SoftMask.ignoreParent, SoftMask.ignoreSelfGraphic, and SoftMask.ignoreSelfStencil are removed.SoftMaskable.useStencil is removed.SoftMaskable.raycastFilter $\rightarrow$ Use SoftMask.alphaHitTest.SoftMaskable.maskInteraction $\rightarrow$ For inverse masks, use MaskingShape component with MaskingMethod=Subtract.SoftMaskable component: No longer needs to be added explicitly; it is added automatically at runtime.SoftMask() shader function: Now requires an additional argument.color.a *= SoftMask(IN.vertex, IN.worldPosition);color.a *= SoftMask(IN.vertex, IN.worldPosition, color.a);SOFTMASKABLE shader feature: Now required in shaders via #pragma shader_feature_local _ SOFTMASKABLE.?path=Packages/src to the URL.Hidden/UI/SoftMask, Hidden/UI/TerminalMaskingShape, and SoftMaskable shader variants must be registered in Project Settings > UI > SoftMask. If masks do not display correctly in the player, open/play the relevant scenes or prefabs in the editor to trigger automatic registration.You can automate these changes using the built-in upgrade tool:
Edit > Project Settings.UI > SoftMask category.Upgrade All Assets For V3.Dry Run to preview changes before applying them.The preferred installation method is via the OpenUPM registry, which allows for easy updates. If you have the openupm-cli installed, run the following command in your project's directory to add the package.
To update the package to a specific version, use the @version syntax.
openupm add com.coffee.softmask-for-ugui
# To update to a specific version
openupm add com.coffee.softmask-for-ugui@3.2.0Access settings via Edit > Project Settings > UI > Soft Mask. The settings file is typically saved at Assets/ProjectSettings/UISoftMaskProjectSettings.asset and should be included in version control.
Core Settings:
SoftMasking mode. If disabled, SoftMasking behaves as Normal.Low, Medium, or High. Adjusts how frequently the soft mask buffer updates during transformations.Automatic: Adds SoftMaskable components automatically.Manual: Requires explicit addition of SoftMaskable components.Shader Settings:
Error On Unregistered Variant is enabled, unregistered variants are automatically added to the list.You can manipulate SoftMask properties programmatically:
var softMask = gameObject.GetComponent<SoftMask>();
softMask.maskingMode = SoftMask.MaskingMode.SoftMasking;
softMask.downSamplingRate = SoftMask.DownSamplingRate.x2;
softMask.softnessRange = new MinMax01(0.5f, 0.75f);