Getting Started • How To Use • Features • Samples • Dependencies
A lightweight particle effect for Android
Add the jitpack
maven { url 'https://jitpack.io' }Add the dependency
dependencies {
// XML
implementation 'com.github.iamoscarliang.particleview:xml:<version>'
// Compose
implementation 'com.github.iamoscarliang.particleview:compose:<version>'
}XML
<com.oscarliang.particleview.xml.ParticleView
android:id="@+id/particle_view"
android:layout_width="match_parent"
android:layout_height="match_parent" />particleView.start(
configs = listOf(
ParticleConfig(
images = listOf(
Image(
imageId = R.drawable.particle,
size = 30
)
),
startX = FloatOffset(0.0f, 1.0f),
startY = FloatOffset(0.0f, 1.0f),
angle = IntOffset(-30, 30),
speed = FloatOffset(300.0f, 600.0f),
particlePerSecond = 20,
)
),
duration = 5000
)Compose
ParticleView(
modifier = Modifier.fillMaxSize(),
configs = listOf(
ParticleConfig(
images = listOf(
Image(
imageId = R.drawable.particle,
size = 30
)
),
startX = FloatOffset(0.0f, 1.0f),
startY = FloatOffset(0.0f, 1.0f),
angle = IntOffset(-30, 30),
speed = FloatOffset(300.0f, 600.0f),
particlePerSecond = 20,
)
),
duration = 5000
)images- the image of the particlestartX- the start x position of the particle. Range from [0.0f, 1.0f] relative to the view's widthstartY- the start y position of the particle. Range from [0.0f, 1.0f] relative to the view's heightspeed- the speed of the particle moving in (px / per second)accelX- the x acceleration added to the speed per secondaccelY- the y acceleration added to the speed per secondangle- the direction of the particle's speed. Range from [0, 360]. Top - 180, Right - 90, Bottom - 0, Left - 270rotation- the start rotation of the particle. Range from [0, 360]rotationSpeed- the rotation speed of the particle rotating in (degree / per second)particleDuration- the duration of the individual particleparticleFadeOutDuration- the duration of the fade out effect of particleparticlePerSecond- the amount of particle being emitted per secondduration- the duration of the animationisPause- pause or resume the animationisCancel- cancel the animationonParticlesEnd- callback being executed when end of animation or cancellation
Recycling mechanism has been added since v1.2 to improve performance. ParticleView use a pre-created object pool to store unused particles, when a particle finishing emitting, it will be added back to the pool and being reused next time. The mechanism can decrease the creation of particles, improving rendering efficiency, and preventing memory leak.
Playback control (since v1.4) can be easily integrated with Android's lifecycle.
XML
override fun onPause() {
super.onPause()
particleView.pause()
}
override fun onResume() {
super.onResume()
particleView.resume()
}Compose
var isPause by rememberSaveable { mutableStateOf(false) }
LifecycleEventEffect(Lifecycle.Event.ON_PAUSE) {
isPause = true
}
LifecycleEventEffect(Lifecycle.Event.ON_RESUME) {
isPause = false
}
ParticleView(
isPause = isPause
//...
)Config change handling has been introduced at v1.4 (Currently Compose support only) to prevent state loss when UI recreation. ParticleView use kotlin-parcelize to serialize data for state saving and restoring. For large complex objects like bitmap, ParticleView use Glide to cache image resource.
