---
title: balochcodes/celebrationfx
framework: Swift Package Catalog
role: article
path: packages/balochcodes/celebrationfx
---

# balochcodes/celebrationfx

A high-performance, GPU-accelerated particle celebration engine for **SwiftUI** powered by 60/120fps Canvas physics.

## ✨ Features

- 🚀 **60/120fps GPU Rendering:** Built on SwiftUI's native `Canvas` and `TimelineView` for buttery-smooth Metal-backed particle drawing. - 💨 **Realistic Particle Physics:** Velocity vectors, downward gravity acceleration, atmospheric drag, angular rotation, and 3D horizontal tumbling. - 🎨 **Rich Built-in Presets:**   - 🎉 `.confetti()`: Classic upwards fanned confetti cannon blast.   - 🪙 `.coinExplosion()`: Golden coins with 3D shine rims for level-up & rewards.   - 🎆 `.fireworks()`: 360-degree radial explosive firework burst.   - 💖 `.heartFountain()`: Floating, romantic heart bubbles fanning skywards.   - ⭐ `.starBurst()`: Sparkling golden star explosion. - 🔘 **Instant `CelebrationButton`:** Self-contained button that triggers celebration bursts directly from tapped touch coordinates. - ⚡ **Zero External Dependencies:** 100% native SwiftUI and Combine.

---

## 📦 Installation

### In Xcode (Recommended) 1. Open your project in Xcode and go to **File** ➔ **Add Package Dependencies...** 2. In the search box, paste:    ```text    https://github.com/BalochCodes/CelebrationFX.git    ``` 3. Select **Up to Next Major Version** (`1.0.0`) and click **Add Package**.

### In `Package.swift` Add `CelebrationFX` to your `dependencies`:

```swift dependencies: [     .package(url: "https://github.com/BalochCodes/CelebrationFX.git", from: "1.0.0") ] ```

Import the framework:

```swift import SwiftUI import CelebrationFX ```

---

## 🚀 Usage Examples

### 1. Trigger Confetti Cannon on Milestone Completion

```swift import SwiftUI import CelebrationFX

struct MilestoneView: View {     @StateObject private var celebrationController = CelebrationController()

var body: some View {         ZStack {             VStack(spacing: 24) {                 Text("Level 10 Completed!")                     .font(.largeTitle.bold())

Button("Claim Reward") {                     celebrationController.burst(                         config: .confetti(count: 80),                         at: CGPoint(x: 200, y: 500)                     )                 }                 .buttonStyle(.borderedProminent)                 .tint(.purple)             }

// Particle overlay on top of screen             CelebrationFXView(controller: celebrationController)         }     } } ```

---

### 2. Gamified Coin Explosion on Checkout

```swift struct CheckoutSuccessView: View {     @StateObject private var celebration = CelebrationController()

var body: some View {         Button("Place Order ($89.00)") {             // Trigger golden coin shower             celebration.burst(                 config: .coinExplosion(count: 50),                 at: CGPoint(x: 200, y: 400)             )         }         .celebrationOverlay(controller: celebration)     } } ```

---

### 3. Tap-Triggered `CelebrationButton`

```swift CelebrationButton(     config: .starBurst(),     controller: celebrationController,     action: {         print("Tapped button!")     } ) {     HStack {         Image(systemName: "sparkles")         Text("Burst Stars")     }     .padding()     .background(Color.yellow)     .cornerRadius(16) } ```

---

## 🛠️ API Reference

### `CelebrationController`

| Method | Parameters | Description | | :--- | :--- | :--- | | `burst()` | `config: CelebrationConfig`, `at: CGPoint` | Spawns a new particle explosion at the given origin. | | `clear()` | — | Immediately dismisses and wipes all active particles. | | `update()` | `dt: CGFloat` | Advances particle physics simulation by delta time. |

### `CelebrationConfig` Presets

| Preset | Key Characteristics | | :--- | :--- | | `.confetti(count:)` | Vibrant rectangular confetti strips with upward blast & fanning. | | `.coinExplosion(count:)` | Metallic gold coins with high mass, gravity, and 3D tumbling. | | `.fireworks(count:)` | 360-degree radial expanding blast with low gravity. | | `.heartFountain(count:)` | Romantic floating pink & red hearts with gentle low-gravity drift. | | `.starBurst(count:)` | Golden sparkling stars fanning across the screen. |

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Author Created by [Shahzain Baloch](https://github.com/ShahzainBaloch).

## Package Metadata

Repository: balochcodes/celebrationfx

Default branch: main

README: README.md