DEV Community

HarmonyOS
HarmonyOS

Posted on

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

#harmonyos #particleeffects #wearabledevelopment #pointparticles

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

Written by Sefa Koyuncu

Top comments (0)