Render particle effect in UnityUI(uGUI). Maskable, sortable, and no extra Camera/RenderTexture/Canvas.
This package provides a component to render particle effects for uGUI in Unity 2018.2 or later.
The particle rendering is maskable and sortable, without the need for an extra Camera, RenderTexture, or Canvas.
<< 📝 Description | 🎮 Demo | ⚙ Installation | 🚀 Usage | 🛠 Development Note | 🤝 Contributing >>
This package utilizes the new APIs MeshBake/MashTrailBake
(introduced with Unity 2018.2) to render particles through
CanvasRenderer.
You can render, mask, and sort your ParticleSystems for UI without the necessity of an additional Camera, RenderTexture,
or Canvas.
Enter Play Mode Options > Reload Domain
.This package requires Unity 2018.3 or later.
This package is available on OpenUPM package registry. This is the preferred method of installation, as you can easily receive updates as they're released.
If you have openupm-cli installed, then run the following command in your project's directory:
openupm add com.coffee.ui-particle
Navigate to your project's Packages folder and open the manifest.json
file. 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.6.0",
Or, use UpmGitExtension to install and update the package.
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 the changes.Random
toggle is enabled, it will be grouped randomly.ParticleSystem
.ParticleSystem
.Transform.lossyScale
(=world scale) will be set to (1, 1, 1)
on update. It prevents the
root-Canvas scale from affecting the hierarchy-scaled ParticleSystem
.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.
// Instant ParticleSystem prefab with UIParticle on runtime.
var go = GameObject.Instantiate(prefab);
var uiParticle = go.AddComponent<UIParticle>();
// 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
)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.Shader "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. 😊