1# Particle Animation
2
3[Particle animation](../reference/apis-arkui/arkui-ts/ts-particle-animation.md) is an animation composed of a multitude of particles randomly generated within a certain range. The particles can be points or images. By animating different aspects of the particles, such as color, opacity, scale, velocity, acceleration, and spin angle, you can create engaging and dynamic aesthetics. For example, you can create an impressive snowfall animation by animating the particles – snowflakes.
4
5The component used for producing particle animations is **Particle**.
6
7Below is the sample code and effect:
8```ts
9@Entry
10@Component
11struct ParticleExample {
12  build() {
13    Stack() {
14      Text()
15        .width(300).height(300).backgroundColor(Color.Black)
16      Particle({ particles: [
17        {
18          emitter: {
19            particle: {
20              type: ParticleType.POINT, // Particle type.
21              config: {
22                radius: 5 // Point radius.
23              },
24              count: 100, // Total number of particles.
25            },
26          },
27        },
28      ]
29      }).width(250).height(250)
30    }.width("100%").height("100%").align(Alignment.Center)
31  }
32}
33```
34
35![particle-base](figures/particle-base.gif)
36
37
38## Particle Emitter
39
40A particle emitter in particle animation is a component used to generate and control particles. It is primarily used to define the initial properties of particles (such as type, position, and color), control the rate of particle emission, and manage the lifecycle of the particles.
41
42The position of the emitter can be dynamically updated. You can adjust the position, emission rate, and size of the emission window for the emitter using the [emitter](../reference/apis-arkui/arkui-ts/ts-particle-animation.md#emitter12) API.
43
44```ts
45// ...
46@State emitterProperties: Array<EmitterProperty> = [
47  {
48    index: 0,
49    emitRate: 100,
50    position: { x: 60, y: 80 },
51    size: { width: 200, height: 200 }
52  }
53]
54
55Particle(...).width(300).height(300).emitter(this.emitterProperties) // Dynamically adjust the position of the particle emitter.
56// ...
57```
58
59![particle-emitter](figures/particle-emitter.gif)
60
61
62## Color
63
64Set the type of random value distribution for the initial color of particles. using [DistributionType](../reference/apis-arkui/arkui-ts/ts-particle-animation.md#distributiontype12). You can choose between uniform distribution or Gaussian (normal) distribution.
65
66```ts
67// ...
68color: {
69  range: [Color.White, Color.Yellow], // Initial color range.
70  distributionType: DistributionType.GAUSSIAN // Random value distribution type of the initial color.
71},
72// ...
73```
74
75![particle-color](figures/particle-color.gif)
76
77
78## Lifecycle
79
80The lifecycle of a particle, from creation to expiration, is used to specify how long a particle exists.
81
82Set the particle lifecycle using **lifetime** and **lifetimeRange**.
83
84```ts
85// ...
86emitter: {
87  particle: {
88    // ...
89    lifetime: 300, // Particle lifetime, in ms.
90    lifetimeRange: 100 // Range of particle lifetime values, in ms.
91  },
92  emitRate: 10, // Number of particles emitted per second.
93  position: [0, 0],
94  shape: ParticleEmitterShape.RECTANGLE // Emitter shape.
95},
96color: {
97  range: [Color.White, Color.Yellow], // Initial color range.
98},
99// ...
100```
101
102![particle-lifetime](figures/particle-lifetime.gif)
103
104
105## Disturbance Field
106
107A disturbance field is a mechanism used to influence the motion of particles. By applying specific forces within the spatial area where particles exist, it alters their trajectories and behaviors, creating more complex and natural animation effects.
108
109Configure disturbance fields using the [disturbanceFields](../reference/apis-arkui/arkui-ts/ts-particle-animation.md#disturbancefields12) API.
110
111```ts
112// ...
113Particle({ particles: [
114  {
115    emitter: // ...
116    color: // ...
117    scale: {
118      range: [0.0, 0.0],
119      updater: {
120        type: ParticleUpdater.CURVE,
121        config: [
122          {
123            from: 0.0,
124            to: 0.5,
125            startMillis: 0,
126            endMillis: 3000,
127            curve: Curve.EaseIn
128          }
129        ]
130      }
131    },
132    acceleration: { // Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction.
133      speed: {
134        range: [3, 9],
135        updater: {
136          type: ParticleUpdater.RANDOM,
137          config: [1, 20]
138        }
139      },
140      angle: {
141        range: [90, 90]
142      }
143    }
144
145  }
146]
147}).width(300).height(300).disturbanceFields([{
148  strength: 10,
149  shape: DisturbanceFieldShape.RECT,
150  size: { width: 100, height: 100 },
151  position: { x: 100, y: 100 },
152  feather: 15,
153  noiseScale: 10,
154  noiseFrequency: 15,
155  noiseAmplitude: 5
156}])
157// ...
158```
159
160![particle-disturbance](figures/particle-disturbance.gif)
161