UIEffect Documentation

To install manually, add the package to your Packages/manifest.json file within the dependencies block:

{
  "dependencies": {
    "com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src",
    ...
  }
}

To update to a specific version, append #version to the URL: "com.coffee.ui-effect": "https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.9.0"

To quickly apply visual effects to a UI element:

1. Install the package via OpenUPM, UPM, or as an embedded package.
2. Add the UIEffect component to a UI element (e.g., Image, RawImage, Text, TextMeshProUGUI) using the Add Component menu in the Inspector or Component > UI > UIEffect menu.
3. Configure filters: Set Tone Filter to Grayscale and Tone Intensity to 1.0 to see an immediate effect.
4. Use Presets: From the top menu, you can use Load to overwrite all properties with a preset, or Append to only overwrite enabled filters and modes (useful for combining effects).

If you want to modify the source code or fix bugs, install it as an embedded package:

1. Download the Source code (zip) from the Releases page and extract it.
2. Move the <extracted_dir>/Packages/src directory into your Unity project's Packages directory.
3. You may rename the src directory if desired.

When upgrading from v4 to v5, observe these breaking changes:

1. Git URL Change: If using a git URL, you must add ?path=Packages/src. The default branch has changed from upm to main.

   • v4: https://github.com/mob-sakai/UIEffect.git or ...#upm
   • v5: https://github.com/mob-sakai/UIEffect.git?path=Packages/src or ...#main

2. Component Obsolescence:

   • The v4 UIEffect component is now named UIEffectV4. Update your code references accordingly.
   • UIShadow and UIGradient components are no longer supported in v5.
   • The effectArea property in some components is not supported in v5.

3. Conversion: You can convert existing v4 components to v5 UIEffect components by selecting Convert To UIEffect from the Unity context menu.

To use UIEffect with TextMeshPro, you must import additional resources:

1. Ensure TMP Essential Resources are imported.
2. Open Package Manager, select UI Effect, and click TextMeshPro Support > Import (or TextMeshPro Support (Unity 6) > Import for Unity 2023.2/6000.0+).
3. Assets will be located in Assets/Samples/UI Effect/{version}.
4. Add the UIEffect component to a TextMeshProUGUI element. The component supports <font> and <sprite> tags.

Note: If you have moved TMPro_Properties.cginc or TMPro.cginc from their default paths, you must manually update the paths in the UIEffect shaders.

The preferred method for installing UIEffect is via the OpenUPM registry, which allows for easy updates. If you have the openupm-cli installed, run the following command in your project directory:

openupm add com.coffee.ui-effect

To update to a specific version, use the @version syntax:

openupm add com.coffee.ui-effect@5.9.0

You can install UIEffect using the Unity Package Manager UI:

1. Open Window > Package Manager.
2. Click the + button and select Add package from git URL....
3. Enter the following URL: https://github.com/mob-sakai/UIEffect.git?path=Packages/src

To target a specific version, append #version to the end of the URL: https://github.com/mob-sakai/UIEffect.git?path=Packages/src#5.9.0

ShaderGraph support requires Unity 2023.2/6.0 or later.

1. In Package Manager, select UI Effect and click ShaderGraph Support (Unity6, BuiltIn) > Import (or ShaderGraph Support (Unity6, URP) > Import for URP).
2. Assets will be located in Assets/Samples/UI Effect/{version}.
3. Change the sub target (Material) of your existing ShaderGraph to Canvas (UIEffect), or create a new one from Assets/Create/Shader Graph/BuiltIn/Canvas Shader Graph (UIEffect).

Tip: Use (UIEffect) in the shader name to help the system identify it.

You can manipulate effects and animations programmatically:

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

The UIEffectTweener component animates UIEffect properties without requiring an AnimationClip.

Key Settings:

• Culling Mask: Select which filters to animate (Tone, Color, Sampling, Transition, GradiationOffset, GradiationRotation, EdgeShiny, Event).
• Direction: Forward (0.0 -> 1.0) or Reverse (1.0 -> 0.0).
• Wrap Mode: Once, Loop, PingPongOnce, or PingPongLoop.
• Update Mode: Normal, UnscaledTime (useful for pause-resistant effects), or Manual.
• Play On Enable: Automatically play on enable (None, Forward, Reverse, Keep Direction).

Note: Transition Filter and Edge Mode use shader-side _Time for auto-play, which is affected by Time.timeScale. For unscaled time, use UIEffectTweener.