README.md
<< 📝 Description | 📌 Key Features | 🎮 Demo | ⚙ Installation | 🚀 Usage | 🛠 Development Note | 🤝 Contributing >>
This package uses the new APIs MeshBake/MeshTrailBake (introduced in Unity 2018.2) to render particles through CanvasRenderer.
You can render, mask, and sort your ParticleSystems for UI without the need for an additional Camera, RenderTexture, or Canvas.
Easy to use: The package is ready to use out of the box.
Sortable: Sort particle effects and other UI elements by sibling index.
Maskable: Supports Mask or RectMask2D.
No extra components required: No need for an additional Camera, RenderTexture, or Canvas.
Trail module support: Fully supports the Trail module.
CanvasGroup alpha support: Integrates with CanvasGroup alpha.
No allocations: Efficiently renders particles without allocations.
Any canvas render mode support: Works with overlay, camera space, and world space.
Any Render pipeline support: Compatible with Universal Render Pipeline (URP) and High Definition Render Pipeline (HDRP).
Disabling domain reload support: Supports disabling Enter Play Mode Options > Reload Domain.
Animatable material properties: Supports changing material properties with AnimationClip (AnimatableProperty).
Multiple materials: Supports 8+ materials.
Correct positioning: Adjusts world space particle positions correctly when changing window size for standalone platforms (Windows, MacOSX, and Linux).
Adaptive scaling: Provides adaptive scaling for UI (AutoScalingMode).
Performance optimization: Mesh sharing group to improve performance.
Particle attractor: Includes a particle attractor component.
Emission position mode: Supports relative/absolute particle emission position modes.
Custom view size: Fixes min/max particle size mismatch.
This package requires Unity 2018.3 or later.
openupm add com.coffee.ui-particle
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/ParticleEffectForUGUI.git#{version} to the target version.
https://github.com/mob-sakai/ParticleEffectForUGUI.git#4.13.0Open the Packages/manifest.json file in your project. Then add this package somewhere in the dependencies block:
{
"dependencies": {
"com.coffee.ui-particle": "https://github.com/mob-sakai/ParticleEffectForUGUI.git",
...
}
}
To update the package, change suffix #{version} to the target version.
"com.coffee.ui-particle": "https://github.com/mob-sakai/ParticleEffectForUGUI.git#4.13.0",Packages directory.UIParticle controls the ParticleSystems that are attached to its own game objects and child game objects.
3D toggle is enabled, 3D scale (x, y, z) is supported._MainTex_ST, _Color) in AnimationClip,
use this to mark as animatable.[!TIPS] (Unity 2021.1 or later) Custom Animatable Properties
From theAdd Custom...menu inAnimatable Properties, you can add fields located outside thePropertiesblock in the shader asAnimatable Properties.
This allowsMatrix,Matrix Array,Float Array, andVector Arrayvalues modified by theParticleSystemRenderer.SetPropertyBlockmethod to be automatically reflected in UIParticle.
Random toggle is enabled, it will be grouped randomly.
[!TIPS] Press the
Refreshbutton to reconstruct the rendering order based on children ParticleSystem's sorting order and z-position.
[!TIPS] When a
GameObjectwith this component is selected in the editor, a temporaryParticleSystemis added if needed so you can preview the effect in the Scene view. The generatedParticleSystemis marked withHideFlags.DontSave, so it is neither saved nor included in builds.
GameObject/UI/ParticleSystem to create UIParticle with a ParticleSystem.
[!Tips] Adding a
UIParticleto the parent is the recommended setup rather than attaching it directly to theParticleSystem. When usingParticleSystem.emission.rateOverDistance, it is recommended to move the transform ofUIParticlerather than theParticleSystem.
GameObject/UI/ParticleSystem (Empty) to create UIParticle.
Mask or RectMask2D ComponentIf you want to mask particles, set a stencil-supported shader (such as UI/UIAdditive) to the material for
ParticleSystem.
If you use some custom shaders, see
the How to Make a Custom Shader to Support Mask/RectMask2D Component
section.
// Instantiate ParticleSystem prefab with UIParticle on runtime.
var go = GameObject.Instantiate(prefab);
var uiParticle = go.AddComponent<UIParticle>();
uiParticle.scale = 100;
// Control by ParticleSystem.
particleSystem.Play();
particleSystem.Emit(10);
// Control by UIParticle.
uiParticle.Play();
uiParticle.Stop();
UIParticleAttractor attracts particles generated by the specified ParticleSystem.
OnAttracted
will be called.OnAttracted may not be called.Linear, Smooth, Sphere)ParticleSystemPreviewer is used to preview a ParticleSystem in the editor.
GameObject with this component is selected in the editor, a temporary ParticleSystem is added if needed so you can preview the effect in the Scene view.ParticleSystem is marked with HideFlags.DontSave, so it is neither saved nor included in builds.You can adjust the project-wide settings for UI Particle. (Edit > Project Settings > UI > UI Particle)
Hide Generated Component: Automatically hide the generated UIParticleRenderer component and UIParticle BakingCamera.
Preview On Select: When selecting UIParticle, a temporary ParticleSystem is generated for preview.
Baking mesh approach (=UIParticle)
Do nothing (=Plain ParticleSystem)
Convert particle to UIVertex (=UIParticleSystem)
Use Canvas to sort (Sorting By Canvas )
Use RenderTexture
| Approach | FPS on Editor | FPS on iPhone6 | FPS on Xperia XZ |
|---|---|---|---|
| Particle System | 43 | 57 | 22 |
| UIParticleSystem | 4 | 3 | 0 (unmeasurable) |
| Sorting By Canvas | 43 | 44 | 18 |
| UIParticle | 17 | 12 | 4 |
| UIParticle with MeshSharing | 44 | 45 | 30 |
See this issue.
If ParticleSystem alone displays particles correctly but UIParticle does not, please check the following points:
UI/Additive or UI/Default.UIParticle is maskable.UI/Additive or UI/Default)Mask or RectMask2D component properly.Scale value.Auto Scaling option.Emission module and Max Particles of ParticleSystem properly.Position Mode = Relative, particles are emitted from the scaled position of the ParticleSystem, not from
the screen point of the ParticleSystem.ParticleSystem in the proper position or try Position Mode = Absolute.UIParticle to the same object as ParticleSystem
Transform.localScale will be overridden by the Auto Scaling option.ParticleSystem under UIParticle.Transform.localScale contains 0, rendering will be skipped.Shape module, please check whether the scale includes 0.ParticleSystem.renderer.Min/MaxParticleSize.Trails.RibbonCount is greater than 1, the following error occurs frequently.
Failed setting triangles. Some indices are referencing out of bounds vertices. IndexCount: 660, VertexCount: 222UIParticle to the parent is the recommended setup rather than attaching it directly to the ParticleSystem.
ParticleSystem.emission.rateOverDistance, it is recommended to move the transform of UIParticle rather than the ParticleSystem.Default View Size For Baking setting under ProjectSettings > UI > UI Particle to a value such as 100 or 1000.The use of UI shaders is recommended.
UI/Additive shader instead.UI/Default shader instead.UIParticle does not support all built-in shaders except for UI/Default.
If their use is detected, an error is displayed in the inspector.
Use UI shaders instead.
UIParticleRenderer renders the particles based on UIVertex.
Therefore, only the xy components are available for each UV in the shader. (zw components will be discarded).
So unfortunately, UIParticles will not work well with some shaders.
When using custom vertex streams, you can fill zw components with "unnecessary" data.
Refer to this issue for more information.
UIParticle has some overheads, and the batching depends on uGUI.
When improving performance, keep the following in mind:
Mesh Sharing feature in
the UIParticle Component.
Random Group feature.Sprite mode in the Texture Sheet Animation module
in the ParticleSystem.Mask and RectMask2D ComponentShader "Your/Custom/Shader"
{
Properties
{
// ...
// #### required for Mask ####
_StencilComp ("Stencil Comparison", Float) = 8
_Stencil ("Stencil ID", Float) = 0
_StencilOp ("Stencil Operation", Float) = 0
_StencilWriteMask ("Stencil Write Mask", Float) = 255
_StencilReadMask ("Stencil Read Mask", Float) = 255
_ColorMask ("Color Mask", Float) = 15
[Toggle(UNITY_UI_ALPHACLIP)] _UseUIAlphaClip ("Use Alpha Clip", Float) = 0
}
SubShader
{
Tags
{
// ...
}
// #### required for Mask ####
Stencil
{
Ref [_Stencil]
Comp [_StencilComp]
Pass [_StencilOp]
ReadMask [_StencilReadMask]
WriteMask [_StencilWriteMask]
}
ColorMask [_ColorMask]
// ...
Pass
{
// ...
// #### required for RectMask2D ####
#include "UnityUI.cginc"
#pragma multi_compile __ UNITY_UI_CLIP_RECT
float4 _ClipRect;
// #### required for Mask ####
#pragma multi_compile __ UNITY_UI_ALPHACLIP
struct appdata_t
{
// ...
};
struct v2f
{
// ...
// #### required for RectMask2D ####
float4 worldPosition : TEXCOORD1;
};
v2f vert(appdata_t v)
{
v2f OUT;
// ...
// #### required for RectMask2D ####
OUT.worldPosition = v.vertex;
return OUT;
}
fixed4 frag(v2f IN) : SV_Target
{
// ...
// #### required for RectMask2D ####
#ifdef UNITY_UI_CLIP_RECT
color.a *= UnityGet2DClipping(IN.worldPosition.xy, _ClipRect);
#endif
// #### required for Mask ####
#ifdef UNITY_UI_ALPHACLIP
clip (color.a - 0.001);
#endif
return color;
}
ENDCG
}
}
}
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 develop branch for guidelines.
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. 😊