Compose Ambiance 🌿✨

Compose Ambiance is a lightweight, physics-based particle system library built exclusively for Android Jetpack Compose.

It allows you to easily add atmospheric effects like rain, snow, confetti, fireflies, or bubbles to your UI to enhance the user experience and "mood" of your application.

Snow	Heavy Rain	Drizzle (Windy)
Confetti	Bubbles	Fireflies

✨ Features

• Pure Compose: Built 100% with Kotlin and Jetpack Compose.
• Physics-based Engine: Simulates gravity, wind, air resistance, and sine-wave swaying.
• 3D Simulation: Supports 3D flipping effects for confetti and falling leaves using axis scaling.
• Highly Customizable: Configure speed, size, colors, characters, and movement logic via ParticleSpec.
• Ready-to-use Presets:
  • ❄️ Snow: Gentle, swaying snowflakes.
  • 🌧️ Rain: Heavy storm or light drizzle with wind support.
  • 🎉 Confetti: Colorful, spinning, 3D-flipping paper pieces.
  • 🫧 Bubbles: Rising, stroke-outlined bubbles.
  • ✨ Fireflies: Glowing, hovering, blinking lights for night scenes.
  • 🍂 Autumn Leaves: Falling leaves with tumbling physics.

📦 Installation

This library is hosted on JitPack.

Step 1. Add the JitPack repository to your root settings.gradle.kts:

dependencyResolutionManagement {  
    repositories {  
        google()  
        mavenCentral()  
        maven(url = uri("https://jitpack.io")) // <--- Add this  
    }  
}

Step 2. Add the dependency to your module's build.gradle.kts:

dependencies {  
    // Replace '2026.1.19' with the latest version from the JitPack badge above  
    implementation("com.github.toantd2000:compose-ambiance:2026.1.19")  
}

🚀 Usage

1. Using Presets (Quick Start)

The easiest way to use the library is to wrap your content in a Box and add the ParticleEffect with a preset.

import com.toantd2000.composeambiance.ParticleEffect  
import com.toantd2000.composeambiance.ParticlePresets

Box(modifier = Modifier.fillMaxSize()) {  
    // Your Background/Content  
    Text("Happy New Year!", modifier = Modifier.align(Alignment.Center))

    // Add Confetti Effect overlay  
    ParticleEffect(  
        spec = ParticlePresets.confetti(),  
        modifier = Modifier.fillMaxSize()  
    )  
}

2. Customizing Presets

You can take a preset and modify specific properties using .copy().

// Example: Creating a "Golden Rain" effect
ParticleEffect(  
    spec = ParticlePresets.rain().copy(  
        colors = listOf(Color(0xFFFFD700), Color(0xFFFFC107)), // Gold colors  
        particlesCount = 500, // More density  
        wind = 15f,           // Strong wind blowing right  
        minSpeed = 30f        // Falling very fast  
    ),  
    modifier = Modifier.fillMaxSize()  
)

3. Creating Custom Effects

Define your own ParticleSpec for unique effects (e.g., falling money 💸).

val moneySpec = ParticleSpec(  
    particlesCount = 50,  
    characters = listOf("$", "€", "£"),  
    colors = listOf(Color.Green),  
    minSpeed = 3f,  
    maxSpeed = 6f,  
    rotationSpeed = 2f, // Spin the coins  
    swayStrength = 1f   // Gentle sway  
)
ParticleEffect(spec = moneySpec)

4. Legacy View System Support (XML)

You can use this library in existing XML layouts using ComposeView.

<androidx.compose.ui.platform.ComposeView  
    android:id="@+id/compose_view"  
    android:layout_width="match_parent"  
    android:layout_height="match_parent"/>


findViewById<ComposeView>(R.id.compose_view).setContent {  
    ParticleEffect(spec = ParticlePresets.snow())  
}

🧩 Configuration (ParticleSpec)

Property	Type	Description
particlesCount	Int	Total number of particles on screen.
characters	List<String>	List of strings to render (e.g., "●", "❄").
colors	List<Color>	List of colors to randomly assign to particles.
minSpeed / maxSpeed	Float	Vertical speed (px/frame). Negative values make particles fly upward (e.g., Bubbles).
gravity	Float	Adds downward acceleration (0.0 - 1.0). Useful for realistic falling objects.
wind	Float	Constant horizontal force. Positive = Right, Negative = Left.
swayStrength	Float	Amplitude of the sine-wave oscillation (Drifting effect).
rotationSpeed	Float	Speed of 2D rotation and 3D flip simulation. Set to 0f to disable.
isStroke	Boolean	If true, draws outlines (Paint.Style.STROKE). Use for Bubbles.
alphaVariance	Boolean	If true, randomizes opacity for a depth/shimmering effect.

🤝 Acknowledgements & Credits

This project is maintained by Trần Đức Toàn.

🤖 AI Collaboration:
Special thanks to Google Gemini for serving as an AI technical partner during the development of this library. Gemini provided support in:

• Designing the ParticleSystem architecture.
• Optimizing physics algorithms (3D flipping, aerodynamic sway).
• Refactoring code for a clean, publishable library structure.

📄 License

Copyright 2026 Trần Đức Toàn

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.