README.md
<< ๐ Description | ๐ Key Features | ๐ฎ Demo | โ Installation | ๐ Upgrading from v4 to v5 | ๐ Usage | ๐ค Contributing >>
โ ๏ธ This README is for v5. For v4, please visit here.
"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
<font> and <sprite> tags.AnimationClips.Canvas (UIEffect) sub target (material) for UIEffect shaders. See for more details here.ControlTrack and UIEffect Tracks. See for more details here.
This package requires Unity 2020.3 or later.
openupm add com.coffee.ui-effect
Window > Package Manager) or run the following command with @{version}:
openupm add [email protected]
Window > Package Manager to open Package Manager UI.+ > Add package from git URL... and input the repository URL: https://github.com/mob-sakai/UIEffect.git?path=Packages/src#{version} to the target version.
https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.9.0Open 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.
"com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.9.0",Source code (zip) file from Releases and
extract it.<extracted_dir>/Packages/src directory into your project's Packages directory.src directory if needed.Additional resources can be imported to extend functionality.
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.
UIEffect component is now UIEffectV4 component. Change the reference in the code.effectArea property in some components are not supported in v5.UIShadow, UIGradient components are not supported in v5.UIEffect component by selecting Convert To UIEffect from the context menu.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]
Loadoverwrites all properties with the preset, whileAppendonly overwrites enabled filters and modes with the preset.
You can easily build effects by combining them withAppend.
Enjoy!
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.
None, Grayscale, Sepia, Nega, Retro, PosterizeNone, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, ContrastNone, Blur Fast, Blur Medium, Blur Detail, Pixelation, Rgb Shift, Edge Luminescence, Edge AlphaNone, Fade, Cutoff, Dissolve, Shiny, Mask, Melt, Burn, Blaze, PatternRotation is shared with Transition Filter and Detail Filter.Keep Aspect Ratio is shared with Transition Filter and Gradation Mode and Detail Filter.None, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
_Time). You can use this property to loop the TransitionRate without tweener or animation.
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 useScale,Offset, orSpeed, setWrap Mode = Repeatin the texture import settings.
For details, refer to the textures included in the built-in presets.
None, Hue, LuminanceAlpha Blend, Multiply, Additive, Soft Additive, Multiply Additive, CustomCustom blend type can be set using the SrcBlend and DstBlend properties.None, Shadow, Shadow3, Outline, Outline8, MirrorNone, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
SamplingFilter = Blur*** required): Intensity of the shadow or outline blur.Mirror only): Distance of the mirrored image.Mirror only): Offset for the mirrored image.Mirror only): Scale of the mirrored image.None, Horizontal, HorizontalGradient, Vertical, VerticalGradient, Radial, RadialGradient, Diagonal, DiagonalToRightBottom, DiagonalToLeftBottom, Angle, AngleGradientNone, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply AdditiveBlend and Fixed modes are available.Angle or AngleGradient only): The rotation of the gradation range.Repaet, Clamp, Mirror, Mirror OnceKeep Aspect Ratio is shared with Transition Filter and Gradation Mode and Detail Filter.None, Plain, ShinyNone, Multiply, Additive, Subtractive, Replace, Multiply Luminance, Multiply Additive, Hsv Modifier, Contrast
_Time).
Time.timeScale). If you need unscaled time (useful for pause-resistant effects), use the UIEffectTweener component instead.None, Masking, Multiply, Additive, Subtractive, Replace, MuliplyAdditiveMasking only): The minimum and maximum alpha values used for masking. The larger the gap
between these values, the stronger the softness effect.Rotation is shared with Transition Filter and Detail Filter.Keep Aspect Ratio is shared with Transition Filter and Gradation Mode and Detail Filter.NothingHorizontalVerticalEffect: Flip with the effect.Shadow: Flip with the shadow.[!TIP]
Transition Filter,Gradation Filter, andDetail Filterusually refer to their ownRectTransformwhen applying effects.
For example, if the mesh shape exceeds theRectTransformboundaries, the effect may not be applied correctly.
By specifyingCustom Root, you can refer to the specified transform.
The UIEffectTweener component animates the effect, enabling easy control over effect animations without the need for an AnimationClip.
Tone, Color, Sampling, Transition, GradiationOffset, GradiationRotation, EdgeShiny, EventEvent only): A event that is triggered when the tweening rate changes.Forward (0.0 -> 1.0), Reverse (1.0 -> 0.0)Reverse Curve will be used for the reverse direction.None, Forward, Reverse, Keep Direction
None is selected, the animation will not play automatically. You can play it using the Play, PlayForward or PlayReverse method.Once: delay -> duration(0-1) -> onCompleteLoop: delay -> duration(0-1) -> interval -> ...PingPongOnce: delay -> duration(0-1) -> interval -> duration(1-0) -> onCompletePingPongLoop: delay -> duration(0-1) -> interval -> duration(1-0) -> interval -> ...Normal, UnscaledTime, ManualYou can preview the animation using the seek bar and play button.
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.
UIEffect component to replicate.
[!TIP] You can specify a preset as well as an instance as the target for
UIEffectReplica.
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 Supportmay change with updates to the UIEffect package.
If issues occur, try importing it again.
[!TIP] If you have moved
TMPro_Properties.cgincandTMPro.cgincfrom their default install path (Assets/TextMesh Pro/Shaders/...), you will need to manually update the paths in the shaders underTextMeshPro SupportorTextMeshPro Support (Unity 6).
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.
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.
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.
You can create and use presets for UIEffect components.
Load button to apply an editor preset.Append button to load only non-default settings from the editor preset.Save As New button to save the current settings as an editor preset.UIEffect.LoadPreset(presetName) method.[!TIP] Editor presets are saved in the
UIEffectPresetsdirectory. You can also create subdirectories to customize the preset menu.
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();
You can adjust the project-wide settings for UIEffect. (Edit > Project Settings > UI > UIEffect)
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 theUIEffect.LoadPresetmethod.- Delete All Legacy Presets: Deletes all legacy presets. If any legacy presets are assigned to
UIEffectReplica.target, those targets will also be removed.
(UIEffect), that shader will be used.Hidden/<shader_name> (UIEffect) exists, that shader will be used.UI/Default (UIEffect) will be used.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.
Here are the limitations of UIEffect:
SamplingFilter.BlurMedium and SamplingFilter.BlurDetail are not supported due to performance considerations.
SamplingFilter.BlurFast.Image, RawImage, Text) and TextMeshProUGUI.
Issues are incredibly valuable to this project:
Pull requests offer a fantastic way to contribute your ideas to this repository.
Please refer to CONTRIBUTING.md
and use develop branch for development.
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. ๐