Render particle effect in UnityUI(uGUI). Maskable, sortable, and no extra Camera/RenderTexture/Canvas.
MIT License
<< 📝 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
.
Mask
or RectMask2D
.Camera
, RenderTexture
, or Canvas
.CanvasGroup
alpha.Enter Play Mode Options > Reload Domain
.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.0
Open 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,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
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 fromPosition 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 inRandom Group
feature.Sprite
mode in the Texture Sheet Animation
moduleMask
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. 😊