Troubleshooting ArkUI Particle Effects: Visibility, Motion, and Performance for Wearable

Read the original article：Troubleshooting ArkUI Particle Effects: Visibility, Motion, and Performance for Wearable

Context

Teams implementing particle-based effects (snow, confetti, fireworks, sparkles) report that particles aren’t visible, colors don’t change, or performance drops—especially on wearables—after enabling IMAGE particles, setting very high emitRate, or using infinite counts/lifetimes.

Description

Common pitfalls when configuring Particle:

• Color not applying to image particles.
• Particles spawn off-screen (emitter position/size mismatch).
• Particles don’t move (velocity/acceleration left at defaults).
• Battery/performance issues (very high emitRate, count = -1, lifetime = -1).
• Using disturbanceFields or emitter() runtime updates on API levels that don’t support them.

Solution / Approach

1. Pick the right particle type
   • POINT: cheapest; supports color changes.
   • IMAGE: heavier; colors cannot be set (by design). Use small images; avoid SVG (not supported).
2. Place the emitter correctly
   • Set emitter.shape (RECTANGLE/CIRCLE/ELLIPSE), position: [x, y], and size: [w, h].
   • For snowfall: emitter at top (position: [0, 0], size: ['100%', someHeight]).
3. Make particles move
   • Configure velocity: speed: [min,max], angle: [min,max]（0° = right, 90° = down, positive = clockwise）.
   • Optional acceleration to simulate gravity: increase speed over time or fix angle to 90°.
   • Note: Velocity/Acceleration options require API ≥ 18.
4. Animate properties
   • opacity/scale/spin via ParticleUpdater:
     • NONE (static), RANDOM (per-second random delta), CURVE (time-ranged keyframes).
   • For wearables, prefer RANDOM with small ranges over heavy CURVE chains.
5. Control lifetime & rate
   • emitter.particle.count: avoid -1 (infinite) unless essential.
   • emitter.particle.lifetime and lifetimeRange: keep modest (e.g., 1500–4000 ms).
   • emitRate: default 5; heavy effects can use hundreds, but avoid > 5000 (perf risk).
6. Runtime tuning (API ≥ 12)
   • Use .emitter([{ index, emitRate, position, size }]) to adjust without recreating the component.
   • Use disturbanceFields([{ strength, shape, size, position, feather, noise* }]) sparingly—start with small strength and modest size.
7. Version guardrails
   • Base Particle: API ≥ 10.
   • .emitter() and disturbanceFields: API ≥ 12.
   • VelocityOptions / AccelerationOptions: API ≥ 18.
   • Fallback gracefully on lower API levels (e.g., static or slower-moving particles).
8. Performance checklist (esp. Wearable)
   • Prefer POINT over IMAGE where possible.
   • Use small textures, reduce emitRate, avoid count = -1 and lifetime = -1.
   • Keep spin and complex CURVE segments minimal.
   • Limit number of concurrent emitters.
   • Remember: particle animation auto-pauses on screen off / background and resumes on return.

Key Takeaways

• Colors don’t apply to IMAGE particles (by design).
• Set velocity/angle (and optionally acceleration) to make particles move (API ≥ 18).
• Keep emitRate and lifetime conservative; infinite values harm performance.
• Use .emitter() and disturbanceFields only on API ≥ 12 and in moderation.
• Prefer POINT particles on wearables for battery & FPS.

Reference Link

• Particle Animation

Written by Sefa Koyuncu