GitHub - mob-sakai/UIEffect: UIEffect is an open-source package that allows you to intuitively apply rich UI effects directly from the Inspector or via code. Combine various filters, such as grayscale, blur, and dissolve, to decorate your UI with a unique visual style! (original) (raw)

⚠️ This README is for v5. For v4, please visit here.

📝 Description

"Decorate your UI, simply and powerfully."

UIEffect is a powerful, open-source Unity package that transforms your UI with stunning visual effects.
Apply professional-grade filters like grayscale, blur, and dissolve directly from the Inspector—no coding required!

✨ Perfect for: Game developers, UI designers, and anyone looking to enhance their Unity UI with minimal effort

📌 Key Features
🎮 Demo
⚙ Installation
🔄 Upgrading from v4 to v5
🚀 Usage
🤝 Contributing
License
Author
See Also

📌 Key Features

UIEffect is out-of-the-box!: Easily apply effects by adjusting parameters directly in the inspector.
Rich effect combinations: Decorate your UI with a variety of effects, such as grayscale, blur, and dissolve, by combining multiple filters and parameters.
Efficient shader builds: Only the shader variants in use are built, resulting in shorter build times.
URP/HDRP/VR support: Compatible with URP, HDRP, and VR environments.
Runtime and editor presets: Presets are available both at runtime and in the editor.
TextMeshPro support: Supports TextMeshPro, including <font> and <sprite> tags.
UIEffectReplica Component: Duplicate effects and apply them to multiple UI elements at once.
UIEffectTweener Component: A simple tweener component to play, stop, pause, and resume effects.
AnimationClip support: Allows control of effect animations using AnimationClips.
v4 compatible components (optional): For easy upgrading with minimal changes, compatible v4 components are available optionally.
SoftMaskForUGUI support (optional): Compatible with SoftMaskForUGUI for creating soft masks for UI elements. See for more details here.
ShaderGraph support (optional): Add Canvas (UIEffect) sub target (material) for UIEffect shaders. See for more details here.
Timeline support: Control UIEffect using Timeline with ControlTrack and UIEffect Tracks. See for more details here.

🎮 Demo

Try the WebGL Demo

⚙ Installation

This package requires Unity 2020.3 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.ui-effect

To update the package, use Package Manager UI (Window > Package Manager) or run the following command with @{version}:

openupm add com.coffee.ui-effect@5.9.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/UIEffect.git?path=Packages/src
To update the package, change suffix #{version} to the target version.
- e.g. https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.9.0

Install via UPM (Manually)

Open the Packages/manifest.json file in your project. Then add this package somewhere in the dependencies block:
{
"dependencies": {
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src",
...
}
}
To update the package, change suffix #{version} to the target version.
- e.g. "com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.9.0",

Install as Embedded Package

Download the Source code (zip) file from Releases and extract it.
Move the <extracted_dir>/Packages/src directory into your project's Packages directory.
- You can rename the src directory if needed.
- If you intend to fix bugs or add features, installing it as an embedded package is recommended.
- To update the package, re-download it and replace the existing contents.

Import Additional Resources

Additional resources can be imported to extend functionality.

🔄 Upgrading from v4 to v5
Usage with TextMeshPro
Usage with ShaderGraph

🔄 Upgrading from v4 to v5

If upgrading from UIEffect v4 to v5, note the following breaking changes:

If you are installing via git URL, add ?path=Packages/src. The default branch is changed upm to main.
// v4
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git",
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git#upm",
// v5
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src",
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#main",
Import the v4 Compatible Components sample from the Package Manager window.
All v4 components are obsolete.

v4 UIEffect component is now UIEffectV4 component. Change the reference in the code.
The effectArea property in some components are not supported in v5.
UIShadow, UIGradient components are not supported in v5.
v4 components can be converted to v5 UIEffect component by selecting Convert To UIEffect from the context menu.

🚀 Usage

Getting Started

Install the package.
Add a UIEffect component to a UI element (Image, RawImage, Text, TextMeshProUGUI, etc...) from the Add Component in the inspector or Component > UI > UIEffect menu.
Set Tone Filter to Grayscale and Tone Intensity to 1.0.
Try other effect filters and parameters in the inspector.
From the top menu, you can load/append preset.

[!TIP]
Load overwrites all properties with the preset, while Append only overwrites enabled filters and modes with the preset.
You can easily build effects by combining them with Append.
Enjoy!

Component: UIEffect

The UIEffect component applies visual effects to UI elements, allowing various effects to be achieved by combining multiple filters.

Tip

From the top menu, you can load and save the editor presets or clear settings.
For details, refer to the Runtime/Editor Preset for UIEffect.

Tone Filter

Tone Filter: None, Grayscale, Sepia, Nega, Retro, Posterize
Tone Intensity: 0.0 (no effect) - 1.0 (full effect).

Color Filter

Color Filter: None, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
Color Intensity: 0.0 (no effect) - 1.0 (full effect).
Color Glow: Set the color to glow.

Sampling Filter

Sampling Filter: None, Blur Fast, Blur Medium, Blur Detail, Pixelation, Rgb Shift, Edge Luminescence, Edge Alpha
Sampling Intensity: 0.0 (no effect) - 1.0 (full effect).
Sampling Width: The width of the sampling effect.

Transition Filter

Transition Filter: None, Fade, Cutoff, Dissolve, Shiny, Mask, Melt, Burn, Blaze, Pattern
Transition Rate: 0.0 (no effect) - 1.0 (full effect).
Transition Tex: The texture used for the transition filter.
- Scale, Offset, Speed, Rotation, Keep Aspect Ratio, Reverse: Additional properties for the texture.
- ⚠️ NOTE: Rotation is shared with Transition Filter and Detail Filter.
- ⚠️ NOTE: Keep Aspect Ratio is shared with Transition Filter and Gradation Mode and Detail Filter.
Transition Width: The width where the transition color is applied.
Transition Pattern Range: The range of the pattern.
Transition Pattern Reverse: Reverse the pattern.
Transition Softness: The softness of the boundary for the transition color.
Transition Color Filter: None, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
- Transition Color: The color of the transition.
- Transition Color Glow: Set the transition color to glow.
Transition Auto Play Speed: The speed of the transition animation (using shader side _Time). You can use this property to loop the TransitionRate without tweener or animation.
- ⚠️ NOTE: This uses scaled time (affected by Time.timeScale). If you need unscaled time (useful for pause-resistant effects), use the UIEffectTweener component instead.

Tip

Transition Tex applies transitions using its alpha channel.
If you use Scale, Offset, or Speed, set Wrap Mode = Repeat in the texture import settings.
For details, refer to the textures included in the built-in presets.

Target Mode

Target Mode: None, Hue, Luminance
- Restricts the effect application area based on hue or luminance.
Target Range: The range of target hue or luminance.
Target Softness: The softness of the target boundary.

Blend Type

Blend Type: Alpha Blend, Multiply, Additive, Soft Additive, Multiply Additive, Custom
- Custom blend type can be set using the SrcBlend and DstBlend properties.

Shadow Mode

Shadow Mode: None, Shadow, Shadow3, Outline, Outline8, Mirror
Shadow Distance: Distance of the shadow or outline.
Shadow Iteration: Number of times the shadow or outline is applied.
Shadow Color Filter: None, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
- Shadow Color: The color of the shadow.
- Shadow Color Glow: Set the shadow color to glow.
Shadow Fade: Alpha value of the shadow or outline.
Shadow Blur Intensity (SamplingFilter = Blur*** required): Intensity of the shadow or outline blur.
Mirror Reflection (Mirror only): Distance of the mirrored image.
Mirror Offset (Mirror only): Offset for the mirrored image.
Mirror Scale (Mirror only): Scale of the mirrored image.

Gradation Mode

Gradation Mode: None, Horizontal, HorizontalGradient, Vertical, VerticalGradient, Radial, RadialGradient, Diagonal, DiagonalToRightBottom, DiagonalToLeftBottom, Angle, AngleGradient
Gradation Color Filter: None, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive
Gradation Gradient: The gradient of the gradation. HDR colors are supported.
- Blend and Fixed modes are available.
Gradation Color 1: The first color of the gradation.
Gradation Color 2: The second color of the gradation.
Gradation Intensity: 0.0 (no effect) - 1.0 (full effect).
Gradation Offset: The offset of the gradation range.
Gradation Scale: The scale of the gradation range.
Gradation Rotation (Angle or AngleGradient only): The rotation of the gradation range.
Gradation Wrap Mode: Repaet, Clamp, Mirror, Mirror Once
Gradation Reverse: Reverse the gradient.
Keep Aspect Ratio:
- ⚠️ NOTE: Keep Aspect Ratio is shared with Transition Filter and Gradation Mode and Detail Filter.

Edge Mode

Edge Mode: None, Plain, Shiny
Edge Width: The width of the edge.
Edge Color Filter: None, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
- Edge Color: The color of the edge.
- Edge Color Glow: Set the shadow color to glow.
Edge Shiny Width: The width of the edge shiny.
Edge Shiny Auto Play Speed: The speed of the edge shiny (using shader side _Time).
- ⚠️ NOTE: This uses scaled time (affected by Time.timeScale). If you need unscaled time (useful for pause-resistant effects), use the UIEffectTweener component instead.

Detail Filter

Detail Filter: None, Masking, Multiply, Additive, Subtractive, Replace, MuliplyAdditive
Detail Intensity: 0.0 (no effect) - 1.0 (full effect).
Detail Color: The color of the detail.
Detail Threshold (Masking only): The minimum and maximum alpha values used for masking. The larger the gap between these values, the stronger the softness effect.
Detail Tex: The texture used for the transition filter.
- Scale, Offset, Speed, Rotation, Keep Aspect Ratio: Additional properties for the texture.
- ⚠️ NOTE: Rotation is shared with Transition Filter and Detail Filter.
- ⚠️ NOTE: Keep Aspect Ratio is shared with Transition Filter and Gradation Mode and Detail Filter.

Flip

Flip: Combine the following flags.
- Nothing
- Horizontal
- Vertical
- Effect: Flip with the effect.
- Shadow: Flip with the shadow.

Others

Sampling Scale: The referencing scale during sampling.
- Larger values are suitable for high-resolution textures.
Allow To Modify Mesh Shape: If enabled, the mesh shape can be modified.
Custom Root: Use the custom transform for some effects.

Tip

Transition Filter, Gradation Filter, and Detail Filter usually refer to their own RectTransform when applying effects.
For example, if the mesh shape exceeds the RectTransform boundaries, the effect may not be applied correctly.
By specifying Custom Root, you can refer to the specified transform.

Component: UIEffectTweener

The UIEffectTweener component animates the effect, enabling easy control over effect animations without the need for an AnimationClip.

Culling Mask: Tone, Color, Sampling, Transition, GradiationOffset, GradiationRotation, EdgeShiny, Event
OnChangeRate (Event only): A event that is triggered when the tweening rate changes.
Direction: Forward (0.0 -> 1.0), Reverse (1.0 -> 0.0)
Curve: The curve of the animation.
Separate Reverse Curve: If enabled, Reverse Curve will be used for the reverse direction.
Reverse Curve: The curve of the reverse animation.
Delay: The delay time before starting the animation.
Duration: The duration of the animation.
Interval: The interval time between the animation.
Play On Enable: None, Forward, Reverse, Keep Direction
- Play the animation automatically when the component is enabled.
- If None is selected, the animation will not play automatically. You can play it using the Play, PlayForward or PlayReverse method.
Reset Time On Enable: Reset the tweening time when the component is enabled.
Wrap Mode:
- Once: delay -> duration(0-1) -> onComplete
- Loop: delay -> duration(0-1) -> interval -> ...
- PingPongOnce: delay -> duration(0-1) -> interval -> duration(1-0) -> onComplete
- PingPongLoop: delay -> duration(0-1) -> interval -> duration(1-0) -> interval -> ...
Update Mode: Normal, UnscaledTime, Manual
On Complete: A event that is triggered when the animation is completed.

You can preview the animation using the seek bar and play button.

Component: UIEffectReplica

The UIEffectReplica component applies visual effects to UI elements by replicating the settings of another UIEffect component. This allows the same effect to be applied across multiple UI elements simultaneously.

Target: The target UIEffect component to replicate.

[!TIP] You can specify a preset as well as an instance as the target for UIEffectReplica.
Use Target Transform: Use the target's transform for some effects.
Custom Root: Use the custom transform for some effects.
Sampling Scale: Override the sampling scale.
Allow To Modify Mesh Shape: If enabled, the mesh shape can be modified.

Usage with TextMeshPro

To use UIEffect with TextMeshPro, you need to import additional resources.
When a shader included in the samples is requested, an import dialog will automatically appear.
Click the Import button.

Alternatively, you can manually import the resources by following these steps:

First, you must import TMP Essential Resources before using.
Open the Package Manager window and select the UI Effect package in the package list and click the TextMeshPro Support > Import button.
⚠️ If you are using Unity 2023.2/6000.0+ or TextMeshPro 3.2/4.0+, click the TextMeshPro Support (Unity 6) > Import button instead.
The assets will be imported under Assets/Samples/UI Effect/{version}.
Add the UIEffect component to a TextMeshProUGUI element and adjust the effect settings. The <font> and <sprite> tags are also supported.

Tip

TextMeshPro Support may change with updates to the UIEffect package.
If issues occur, try importing it again.

Tip

If you have moved TMPro_Properties.cginc and TMPro.cginc from their default install path (Assets/TextMesh Pro/Shaders/...), you will need to manually update the paths in the shaders underTextMeshPro Support or TextMeshPro Support (Unity 6).

Usage with SoftMaskForUGUI

SoftMaskForUGUI is a package that allows you to create soft masks for UI elements.

SoftMaskForUGUI (v3.3.0+) supports UIEffect (v5.7.0+).
When a shader included in the samples is requested, an import dialog will automatically appear.
Click the Import button.

Usage with ShaderGraph

⚠️ ShaderGraph support is available only in Unity 2023.2/6.0 or later.

To use UIEffect with ShaderGraph, you need to import additional resources.

Open the Package Manager window and select the UI Effect package in the package list and click the ShaderGraph Support (Unity6, BuiltIn) > Import button.
⚠️ If you are using Universal Render Pipeline (URP), click the ShaderGraph Support (Unity6, URP) > Import button.
The assets will be imported under Assets/Samples/UI Effect/{version}.
Change the sub target (Material) of the existing ShaderGraph file to Canvas (UIEffect).
Alternatively, create a new ShaderGraph from Assets/Create/Shader Graph/BuiltIn/Canvas Shader Graph (UIEffect).

Tip

Use (UIEffect) in the shader name or register as an optional shader in ProjectSettings.

Usage with Timeline

Timeline is a powerful animation tool that can control UIEffect using ControlTrack and UIEffect tracks.

Control Track: One of the built-in tracks. When you assign a GameObject with UIEffect, UIEffect will be enabled during the clip duration.
UIEffect Tracks: Tracks for UIEffect. They control float or Color type properties.
- Supports blending, extrapolation, and tween.

Runtime/Editor Preset for UIEffect

You can create and use presets for UIEffect components.

Click the Load button to apply an editor preset.
Click the Append button to load only non-default settings from the editor preset.
Click the Save As New button to save the current settings as an editor preset.
In the Project Settings, you can register saved editor presets as runtime presets.
Runtime presets can be loaded using the UIEffect.LoadPreset(presetName) method.

Tip

Editor presets are saved in the UIEffectPresets directory. You can also create subdirectories to customize the preset menu.

Usage with Code

You can control the effect settings and animations via code.

var effect = graphic.AddComponent();

// Apply a runtime preset effect.LoadPreset("Dissolve");

// Set the effect parameters effect.transitionWidth = 0.1f; effect.transitionColor = Color.red;

// Add a tweener var tweener = graphic.AddComponent(); tweener.cullingMask = UICullingMask.Tone; tweener.wrapMode = UIWrapMode.PingPongLoop;

// Warm up the shader variant collection. UIEffectProjectSettings.shaderVariantCollection.WarmUp();

Project Settings

You can adjust the project-wide settings for UIEffect. (Edit > Project Settings > UI > UIEffect)

Settings

Runtime Presets: A list of presets that can be loaded at runtime. Load them using UIEffect.LoadPreset(presetName) method.

Important

The legacy prefab-based preset system is deprecated as of v5.8.0.
If your project contains legacy presets, you can convert them to the new system.
- Convert All Legacy Presets: Creates new presets based on the legacy ones.
  If the legacy presets are used as runtime presets, they will be replaced with the new ones.
  You can load the new preset via the UIEffect.LoadPreset method.
- Delete All Legacy Presets: Deletes all legacy presets. If any legacy presets are assigned to UIEffectReplica.target, those targets will also be removed.

Editor

Use HDR Color Picker: If enabled, the HDR color picker will be used in the inspector.

Shader

Optional Shaders (UIEffect): A list of shaders that will be prioritized when a ui-effect shader is requested.
- If the shader is included in the list, that shader will be used.
- If it is not in the list, the following shaders will be used in order:
  * If the shader name contains (UIEffect), that shader will be used.
  * If Hidden/<shader_name> (UIEffect) exists, that shader will be used.
  * As a fallback, UI/Default (UIEffect) will be used.
Registered Variants: A list of shader variants available at runtime. Use "-" button to remove unused variants, reducing build time and file size.
- By default, the used ui-effect shaders will be included in the build. You can remove them if you don't need.
Unregistered Variants: A list of shader variants that are not registered. Use "+" button to add variants.
Error On Unregistered Variant: If enabled, an error will be displayed when an unregistered shader variant is used.
- The shader variant will be automatically added to the Unregistered Variants list.