balochcodes/celebrationfx

✨ 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 ``

1. Select Up to Next Major Version (1.0.0) and click Add Package.

In Package.swift

Add CelebrationFX to your dependencies:

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

Import the framework:

import SwiftUI
import CelebrationFX

🚀 Usage Examples

1. Trigger Confetti Cannon on Milestone Completion

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

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

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 file for details.

Author

Created by Shahzain Baloch.

Package Metadata

Repository: balochcodes/celebrationfx

Default branch: main

README: README.md