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.9.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.9.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.Random toggle is enabled, it will be grouped randomly.
NOTE: Press the Refresh button to reconstruct the rendering order based on children ParticleSystem's sorting order
and z-position.
GameObject/UI/ParticleSystem to create UIParticle with a ParticleSystem.
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)Edit > Project Settings to open the Project Settings window and then select UI > UI Particle category.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 |
If ParticleSystem alone displays particles correctly but UIParticle does not, please check the following points:
UIParticle does not support all built-in shaders except for UI/Default.UI/Additive or UI/Default.UIParticle is maskable.Mask or RectMask2D component properly.UI/Additive or UI/Default)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.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.ParticleSystem.renderer.Min/MaxParticleSize.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. 😊