mob-sakai/UIEffect

UIEffect v5

<< 📝 Description | 📌 Key Features | 🎮 Demo | ⚙ Installation | 🔄 Upgrading from v4 to v5 | 🚀 Usage | 🤝 Contributing >>

⚠️ 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
  • Install via OpenUPM
  • Install via UPM (with Package Manager UI)
  • Install via UPM (Manually)
  • Install as Embedded Package
  • Import Additional Resources
• 🔄 Upgrading from v4 to v5
• 🚀 Usage
  • Getting Started
  • Component: UIEffect
    • Tone Filter
    • Color Filter
    • Sampling Filter
    • Transition Filter
    • Target Mode
    • Blend Type
    • Shadow Mode
    • Gradation Mode
    • Edge Mode
    • Detail Filter
    • Flip
    • Others
  • Component: UIEffectTweener
  • Component: UIEffectReplica
  • Usage with TextMeshPro
  • Usage with SoftMaskForUGUI
  • Usage with ShaderGraph
  • Usage with Timeline
  • Usage with Custom Shader
  • Runtime/Editor Preset for UIEffect
  • Usage with Code
  • Project Settings
    • Settings
    • Editor
    • Shader
  • :warning: Limitations
• 🤝 Contributing
  • Issues
  • Pull Requests
  • Support
• 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 [email protected]
  

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

1. Download the Source code (zip) file from Releases and extract it.
2. 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:

1. 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",
   

2. Import the v4 Compatible Components sample from the Package Manager window.

3. 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

1. Install the package.

2. 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.
   

3. Set Tone Filter to Grayscale and Tone Intensity to 1.0.
   

4. Try other effect filters and parameters in the inspector.
   

5. 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.

5. 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:

1. First, you must import TMP Essential Resources before using.
   

2. 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.

3. The assets will be imported under Assets/Samples/UI Effect/{version}.

4. 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 under TextMeshPro 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.

1. 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.

2. The assets will be imported under Assets/Samples/UI Effect/{version}.

3. 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.

Usage with Custom Shader

To make your custom shader support UIEffect, it must satisfy the following requirements. Refer to the sections enclosed by ==== UIEFFECT START === and ==== UIEFFECT END ==== in the built-in Hidden/UI/Default (UIEffect) shader included in the package.

https://github.com/mob-sakai/UIEffect/blob/main/Packages/src/Shaders/UIEffect.shader

• Blend: Blend [_SrcBlend] [_DstBlend]
• Shader variants: #pragma shader_feature_local_fragment ***
• Vertex shader input structure: float4 uvMask : TEXCOORD***;
• Vertex shader: OUT.uvMask = v.uvMask; and OUT.worldPosition = v.vertex;
• Pixel shader input structure: float4 uvMask : TEXCOORD***; and float4 worldPosition : TEXCOORD***;
• UIEffect micro pixel shader: a function that returns the color of the specified pixel and has the signature half4 uieffect_frag(v2f IN, float2 uv).
• Pixel shader input structure name definition: #define UIEFFECT_FRAG_STRUCT v2f
• Include the UIEffect library: #include "Packages/com.coffee.ui-effect/Shaders/UIEffect.cginc"
• Pixel shader: half4 c = uieffect(IN.texcoord, IN.uvMask, IN.worldPosition, IN);

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<UIEffect>();

// 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<UIEffectTweener>();
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.

[!IMPORTANT]

• The setting file is usually saved in Assets/ProjectSettings/UIEffectProjectSettings.asset. Include this file in your version control system.
• The setting file is automatically added as a preloaded asset in ProjectSettings/ProjectSettings.asset.

Advanced

• Pre Load Settings In Build: When enabled, this settings asset will be added to PlayerSettings.preloadedAssets in build.
• When disable, you should load this settings via Resources, AssetBundles or Addressables to use UIEffect.
• You can overwrite the settings by re-enabling UIEffectProjectSettings. This allows you to hot update shader variants and presets.

private static IEnumerator HotUpdateCoroutine()
{
    const string k_SettingsAddress = "Assets/ProjectSettings/UIEffectProjectSettings.asset";
    yield return Addressables.LoadAssetAsync<UIEffectProjectSettings>(k_SettingsAddress);
    while (UIEffectProjectSettings.shaderVariantCollection.WarmUpProgressively(5) == false) yield return null;
}

:warning: Limitations

Here are the limitations of UIEffect:

• Shader variants used at runtime must be registered in the Project Settings.
• When using UIEffect with TextMeshProUGUI, SamplingFilter.BlurMedium and SamplingFilter.BlurDetail are not supported due to performance considerations.
  • These will automatically fall back to SamplingFilter.BlurFast.
• UIEffect supports default UI components (Image, RawImage, Text) and TextMeshProUGUI.
  • If you want to use UIEffect with other components, create a issue or pull request.

🤝 Contributing

Issues

Issues are incredibly valuable to this project:

• Ideas provide a valuable source of contributions that others can make.
• Problems help identify areas where this project needs improvement.
• Questions indicate where contributors can enhance the user experience.

Pull Requests

Pull requests offer a fantastic way to contribute your ideas to this repository.
Please refer to CONTRIBUTING.md and use develop branch for development.

Support

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. 😊

License

• MIT

Author

• mob-sakai

See Also

• GitHub page : https://github.com/mob-sakai/UIEffect
• Releases : https://github.com/mob-sakai/UIEffect/releases
• Issue tracker : https://github.com/mob-sakai/UIEffect/issues
• Change log : https://github.com/mob-sakai/UIEffect/blob/main/Packages/src/CHANGELOG.md