# SoftMaskForUGUI: soft-edged masks for Unity uGUI, and when RectMask2D is enough

> SoftMaskForUGUI is an MIT-licensed Unity package that replaces hard-edged uGUI masking with a soft mask buffer, adjustable visible regions, MaskingShape, and ray-cast filtering. It runs on Unity 2019.4 and later, installs from OpenUPM or UPM, and has a documented limit of four nested soft masks.

**mob-sakai/SoftMaskForUGUI** — Enhance Unity UI (uGUI) with advanced soft-masking features to create more visually appealing effects!

- Repository: https://github.com/mob-sakai/SoftMaskForUGUI
- Website: https://github.com/mob-sakai/SoftMaskForUGUI
- Stars: 2,835 · Forks: 327
- Language: ShaderLab
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/mob-sakai-softmaskforugui

## What SoftMaskForUGUI replaces, and who needs it

Unity's built-in uGUI masking is binary. A Mask component uses stencil testing, so a pixel is either inside the mask or outside it; RectMask2D clips to a rectangle. There is no gradient at the edge and no way to shape the visible region with anything other than the mask graphic's alpha. SoftMaskForUGUI targets that gap. It is for Unity UI developers who need a soft or shaped boundary: a circular avatar fade, a scroll view whose content dissolves at the edge, an iris-out transition, or a tutorial that highlights one region and darkens the rest. The README lists the supported shapes as Text, Image and RawImage, so the mask graphic can be a sprite, a sprite atlas entry, or a text glyph. The package is also aimed at VR projects (it advertises stereo support) and at projects using TextMeshPro or Spine, both of which need extra shader imports. If your mask is a plain rectangle with no gradient, this package is the wrong tool and RectMask2D is the right one.

## The soft mask buffer and how the pipeline uses it

The mechanism is a render pass, not stencil testing. SoftMask renders its masking graphic into a separate buffer, and the masked UI samples that buffer to decide how much of each pixel survives. The README calls this the soft mask buffer and exposes its size in the inspector as a quality-versus-performance dial: a larger buffer gives smoother edges and costs more. The buffer is not redrawn every frame. According to the key features list, it is updated only when needed, which is the package's main answer to the cost of an extra pass. Masking graphics can be multiple sprites or a SpriteAtlas. On the receiving side, a SoftMaskable component is added automatically at runtime as needed, so you do not hand-place it on every child. MaskingShape is the other half of the model: it adds or removes a region from the mask, and the README shows inverse masking built from it, for effects such as iris out. Nesting is supported up to four levels, and the same components work in overlay, camera space and world space.

## Installing SoftMaskForUGUI from OpenUPM or UPM

The README gives four installation routes: OpenUPM, the Package Manager UI, a manual UPM entry, and an embedded package. The OpenUPM route uses the package name com.coffee.softmask-for-ugui and requires the OpenUPM scoped registry, which is the usual openupm-cli command:

```bash
openupm add com.coffee.softmask-for-ugui
```

After the command finishes, the package appears in the Unity Package Manager window under the OpenUPM scope. The manual UPM route instead edits Packages/manifest.json directly, adding a scoped registry for the OpenUPM URL and a dependency on the same package name. If you prefer the Package Manager UI, the README documents adding the registry there and then installing the package by name. Whichever route you take, the README has a separate step for importing additional resources, which is what pulls in the TextMeshPro and Spine shaders; without it, those components keep using their own shaders and will not be masked. There is also an upgrade path: the README includes a section on upgrading all assets for v3, which is relevant if you are moving an existing project from the v2 line.

## A first mask in the editor, then the same thing in script

The fastest start is the context menu. The README states that SoftMask is fully compatible with the existing Mask component and that you can convert an existing Mask to SoftMask from the context menu, so an existing UI hierarchy does not need to be rebuilt. In the inspector you then set the masking graphic (Image, RawImage or Text), tune the visible part, and choose the buffer size. For the anti-aliased case, the README describes an Anti-Aliasing Masking Mode for when you do not need semi-transparent masks; it is documented as the more performant option, so it is worth trying before raising the buffer size. The README also has a scripted usage section for building masks from code, and a section on using the package with custom shaders, which requires converting those shaders to soft-maskable variants. A concrete constraint to plan for: the package ships a soft-maskable UI shader for UI/Default, but any shader outside that family needs its own conversion. The README points to a soft-maskable shader guide for the modification.

## Where SoftMaskForUGUI stops being the right answer

The documented ceiling is four nested soft masks. That is a real design constraint, not a footnote: deep UI hierarchies that stack masks will hit it, and the workaround is flattening the hierarchy or moving some masking into pre-baked art. Second, the buffer is a render target with a size you choose, and the README frames that size as a quality-versus-performance trade-off. On a low-end mobile target, a buffer large enough to look smooth at high resolution may cost more than the effect is worth, and the anti-aliasing mode is the documented escape hatch only if you can live without semi-transparent masks. Third, shader coverage is not automatic. TextMeshProUGUI needs additional shaders imported, Spine needs the same, and custom shaders need conversion. A project with a large custom shader library should treat that as migration work. Finally, if the mask is a rectangle with hard edges, RectMask2D does the job without an extra buffer at all.

## RectMask2D, the built-in Mask, and where each one fits

The README itself carries a RectMask2D versus SoftMask comparison, which is the honest place to start. RectMask2D clips to the rect of its RectTransform. It cannot follow a circle, cannot fade an edge, and cannot be shaped by a sprite. The built-in Mask component can follow a graphic's alpha, but its stencil test is binary, so the edge is hard and semi-transparent mask pixels do not produce a gradient. SoftMaskForUGUI trades a render pass and buffer memory for a sampled gradient, and adds MaskingShape for adding or removing regions, inverse masking, and ray-cast filtering so that clicks only register on the visible part. That last feature is the one with no equivalent in the built-in components, and the README names the tutorial-highlight case as its purpose. A project that needs shaped clicks and soft edges has no built-in alternative; a project that needs neither should not pay for the buffer.

## Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-08-27, the same day as the 3.6.5 release. The two releases before it, 3.6.4 and 3.6.3, landed on 2026-08-07 and 2026-07-22, so the 3.6.x line has seen regular patch releases over that period. The README documents an upgrade path for v3 assets, which tells you the v2 to v3 transition was a breaking change with a migration step, and that is the upgrade cost to budget for if you are on an older version. Because the package installs through UPM or OpenUPM, version pinning is handled by Unity's package system rather than by copying files, with the embedded-package route available if you need to modify the source in place. The licence is MIT, which is permissive and compatible with commercial Unity projects; the repository ships LICENSE.md and LICENSE.txt. This is a description of the licence identifier, not legal advice. One practical consequence of MIT plus a UPM distribution: you can fork and vendor the package if you need a fix faster than upstream, but you then own the merge cost on every release.

## Conclusion

Adopt SoftMaskForUGUI when you need gradient or shaped masking in uGUI: nested masks, sprite atlases, ScrollRect, world-space canvases, or TextMeshPro text, and you accept a render pass and buffer-size tuning. Stay with RectMask2D when your mask is a plain rectangle, since it costs no extra render pass. Before committing, verify three things in your own project: that the soft mask buffer size you pick holds up at your target resolution, that your custom shaders have been converted to soft-maskable ones, and that TextMeshPro and uGUI 2.0 shaders have been imported if you use them.

## FAQ

### How do I install SoftMaskForUGUI in Unity?

The README gives four routes: OpenUPM, the Package Manager UI, a manual UPM entry in Packages/manifest.json, and installing it as an embedded package. The OpenUPM route adds the package com.coffee.softmask-for-ugui from the OpenUPM scoped registry.

### How many soft masks can SoftMaskForUGUI nest?

The README states that SoftMask supports up to 4 nested soft masks. Beyond that, the documented nesting limit is reached and the hierarchy needs restructuring.

### Does SoftMaskForUGUI work with TextMeshPro?

Yes, but TextMeshProUGUI support requires importing additional shaders, as does Spine support. The README also notes support for TextMeshPro v3.2/4.0 (pre-release) and uGUI 2.0 on Unity 2023.2+ and 6.0+.

### How do I use UI Masks in Unity?

SoftMaskForUGUI is compatible with the existing Mask component and the README says you can convert an existing Mask to SoftMask from the context menu. From there you set the masking graphic to an Image, RawImage or Text and adjust the visible part.

### Is SoftMaskForUGUI a replacement for RectMask2D?

Not always. The README includes a RectMask2D versus SoftMask comparison; SoftMask adds a soft mask buffer and shaped masking, while RectMask2D clips to a rectangle. For a plain rectangular clip, RectMask2D avoids the extra buffer.

## Sources

- [License: MIT](https://github.com/mob-sakai/SoftMaskForUGUI/blob/main/LICENSE)
- [mob-sakai/SoftMaskForUGUI on GitHub](https://github.com/mob-sakai/SoftMaskForUGUI)
- [Project website](https://github.com/mob-sakai/SoftMaskForUGUI)
- [README](https://github.com/mob-sakai/SoftMaskForUGUI/blob/main/README.md)
- [Releases](https://github.com/mob-sakai/SoftMaskForUGUI/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mob-sakai-softmaskforugui