UIEffect v5
[](https://openupm.com/packages/com.coffee.ui-effect/)
[](https://github.com/mob-sakai/UIEffect/releases)
[](https://github.com/mob-sakai/UIEffect/releases)
[](https://github.com/mob-sakai/UIEffect/blob/main/LICENSE.md)
[](http://makeapullrequest.com)
[](https://github.com/mob-sakai/UIEffect/subscription)
[](https://twitter.com/intent/follow?screen_name=mob_sakai)
<< [๐ Description](#-description-) | [๐ Key Features](#-key-features) | [๐ฎ Demo](#-demo) | [โ Installation](#-installation) | [๐ Upgrading from v4 to v5](#-upgrading-from-v4-to-v5) | [๐ Usage](#-usage) | [๐ค Contributing](#-contributing) >>
โ ๏ธ This README is for v5. For v4, please visit [here](https://github.com/mob-sakai/UIEffect/blob/upm/README.md).
## ๐ 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](#-key-features)
- [๐ฎ Demo](#-demo)
- [โ Installation](#-installation)
- [Install via OpenUPM](#install-via-openupm)
- [Install via UPM (with Package Manager UI)](#install-via-upm-with-package-manager-ui)
- [Install via UPM (Manually)](#install-via-upm-manually)
- [Install as Embedded Package](#install-as-embedded-package)
- [Import Additional Resources](#import-additional-resources)
- [๐ Upgrading from v4 to v5](#-upgrading-from-v4-to-v5)
- [๐ Usage](#-usage)
- [Getting Started](#getting-started)
- [Component: UIEffect](#component-uieffect)
- [Tone Filter](#tone-filter)
- [Color Filter](#color-filter)
- [Sampling Filter](#sampling-filter)
- [Transition Filter](#transition-filter)
- [Target Mode](#target-mode)
- [Blend Type](#blend-type)
- [Shadow Mode](#shadow-mode)
- [Gradation Mode](#gradation-mode)
- [Edge Mode](#edge-mode)
- [Detail Filter](#detail-filter)
- [Flip](#flip)
- [Others](#others)
- [Component: UIEffectTweener](#component-uieffecttweener)
- [Component: UIEffectReplica](#component-uieffectreplica)
- [Usage with TextMeshPro](#usage-with-textmeshpro)
- [Usage with SoftMaskForUGUI](#usage-with-softmaskforugui)
- [Usage with ShaderGraph](#usage-with-shadergraph)
- [Usage with Timeline](#usage-with-timeline)
- [Runtime/Editor Preset for UIEffect](#runtimeeditor-preset-for-uieffect)
- [Usage with Code](#usage-with-code)
- [Project Settings](#project-settings)
- [Settings](#settings)
- [Editor](#editor)
- [Shader](#shader)
- [:warning: Limitations](#warning-limitations)
- [๐ค Contributing](#-contributing)
- [Issues](#issues)
- [Pull Requests](#pull-requests)
- [Support](#support)
- [License](#license)
- [Author](#author)
- [See Also](#see-also)
## ๐ฎ Demo 
[Try the WebGL Demo](https://mob-sakai.github.io/UIEffect/)
## โ Installation _This package requires **Unity 2020.3 or later**._ ### Install via OpenUPM - This package is available on [OpenUPM](https://openupm.com/packages/com.coffee.ui-effect/) package registry. - This is the preferred method of installation, as you can easily receive updates as they're released. - If you have [openupm-cli](https://github.com/openupm/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: ```json { "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](https://github.com/mob-sakai/UIEffect/releases) and extract it. 2. Move the `
## ๐ 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`. ```json // 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](#-installation). 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](#runtimeeditor-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-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-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](https://docs.unity3d.com/Packages/com.unity.textmeshpro@3.0/manual/index.html#installation) 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 `` and `
### Usage with SoftMaskForUGUI  [SoftMaskForUGUI](https://github.com/mob-sakai/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  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](#project-settings).
### 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](#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. ```csharp var effect = graphic.AddComponent
### 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/
### :warning: Limitations Here are the limitations of UIEffect: - Shader variants used at runtime must be registered in the [Project Settings](#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](https://github.com/mob-sakai/UIEffect/tree/main/CONTRIBUTING.md) and use [develop branch](https://github.com/mob-sakai/UIEffect/tree/develop) 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. ๐ [](https://github.com/users/mob-sakai/sponsorship) [](https://www.patreon.com/join/2343451?)
## License * MIT ## Author *  [mob-sakai](https://github.com/mob-sakai) [](https://twitter.com/intent/follow?screen_name=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