repository·main·Indexed 24 days ago
https://github.com/mob-sakai/particleeffectforuguiA Unity package (com.coffee.ui-particle) that allows rendering Particle Systems within the uGUI framework using MeshBake/MeshTrailBake APIs. It enables maskable and sortable particle effects through CanvasRenderer without requiring extra cameras or RenderTextures. Features include the UIParticle component for rendering control, UIParticleAttractor for particle attraction, and support for UI-specific shaders to ensure compatibility with Mask and RectMask2D.
To improve performance when using UIParticle, consider the following:
Mesh Sharing feature in the UIParticle component. To avoid perfectly uniform output, use the Random Group feature.Sprite mode in the Texture Sheet Animation module of the ParticleSystem to achieve this.To ensure compatibility with UIParticle, use UI-specific shaders. Built-in Unity shaders are generally not supported and will cause errors in the inspector.
Recommended shaders:
UI/Additive.UI/Default.Note for Unity 2018/2019: Only the xy components of UVs are available in the shader; zw components will be discarded. If using custom vertex streams, be aware of this limitation.
To use an existing ParticleSystem prefab with UIParticle, follow these steps:
GameObject/UI/ParticleSystem (Empty).ParticleSystem prefab onto the UIParticle component.Recommended Setup:
UIParticle to a parent object rather than attaching it directly to the ParticleSystem.ParticleSystem.emission.rateOverDistance, move the transform of the UIParticle object instead of the ParticleSystem object.If you are writing a custom shader that needs to work with uGUI Mask and RectMask2D components, your shader must include specific properties and logic for Stencil operations and Clipping.
Required Properties for Mask:
_StencilComp (Stencil Comparison)_Stencil (Stencil ID)_StencilOp (Stencil Operation)_StencilWriteMask (Stencil Write Mask)_StencilReadMask (Stencil Read Mask)_ColorMask (Color Mask)[Toggle(UNITY_UI_ALPHACLIP)] _UseUIAlphaClip (Alpha Clip Toggle)Required Logic for RectMask2D:
UnityUI.cginc.#pragma multi_compile __ UNITY_UI_CLIP_RECT.UnityGet2DClipping(worldPosition.xy, _ClipRect) in the fragment shader to apply clipping.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
}
}
}The preferred installation method is via the OpenUPM registry, which allows for easy updates. If you have the openupm-cli installed, run the following command in your project's directory to add the package. To update to a specific version, use the @version syntax.
openupm add com.coffee.ui-particle
# To update to a specific version
openupm add com.coffee.ui-particle@4.13.0Add the package dependency directly to your project's Packages/manifest.json file within the dependencies block. To specify a version, use the #version suffix.
{
"dependencies": {
"com.coffee.ui-particle": "https://github.com/mob-sakai/ParticleEffectForUGUI.git",
...
}
}
# To update to a specific version:
"com.coffee.ui-particle": "https://github.com/mob-sakai/ParticleEffectForUGUI.git#4.13.0"If you need to modify the source code or fix bugs, install it as an embedded package:
Packages directory.Note: To update an embedded package, you must manually re-download and replace the contents.
Mask or RectMask2D) for particles, you must use a stencil-supported shader on the ParticleSystem material, such as UI/UIAdditive.You can install the package directly through the Unity Editor:
Window > Package Manager.+ button and select Add package from git URL....https://github.com/mob-sakai/ParticleEffectForUGUI.git.To target a specific version, append # followed by the version number to the end of the URL (e.g., https://github.com/mob-sakai/ParticleEffectForUGUI.git#4.13.0).
https://github.com/mob-sakai/ParticleEffectForUGUI.gitAdjust global settings via Edit > Project Settings > UI > UI Particle.
UIParticleRenderer and UIParticle BakingCamera.ParticleSystem for preview when a UIParticle is selected in the editor.If your ParticleSystem displays correctly but UIParticle does not, check these common causes:
UI/Additive or UI/Default shaders. Built-in shaders (except UI/Default) are not supported and will trigger an inspector error.UIParticle is maskable, but you must use a maskable/clipable shader (like UI/Additive or UI/Default) and ensure Mask or RectMask2D components are set up correctly.Scale value or enable the Auto Scaling option. Note that if Transform.localScale contains 0, rendering is skipped.Emission module and Max Particles in the ParticleSystem to stay within this limit.Position Mode = Relative, try using Position Mode = Absolute or reposition the ParticleSystem.ParticleSystem as a child of the UIParticle object rather than attaching UIParticle directly to the same object as the ParticleSystem.Trails.RibbonCount is greater than 1, you may encounter vertex index out of bounds errors.Default View Size For Baking in ProjectSettings > UI > UI Particle to a larger value like 100 or 1000.You can instantiate and control UIParticle components at runtime using C#.
// Instantiate ParticleSystem prefab with UIParticle at 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();