firework

README

Firework

A terminal Firework animation engine and ASCII art CLI written in Go, built with Charm's Bubble Tea and Lip Gloss TUI libraries.

Demo

Watch the demo on YouTube

Note on GPU-Accelerated Terminals

For the best animation experience, use a GPU-accelerated terminal emulator such as Kitty, Alacritty or similar. While not required, these terminals can provide smoother and more vibrant visuals for the firework animation.

Table of Contents

• Requirements
• Features
• Usage
• Dependencies
• Project Structure
• How it Works
• Contributions
• License

Requirements

• Go 1.26+

Features

• Real-time firework simulation reusing firework-rs cjk charset and glimmering effect.
• Colorful, animated terminal output for modern terminal emulators.
• Performance-oriented particle engine.
• 30 FPS ASCII rendering up to 4K (3829x700 with kitty or iTerm2 on Apple M1/16GB).

Usage

Clone

git clone https://github.com/erik-adelbert/firework.git
cd firework

Run with Makefile

make demo

or

make run

Build the executable:

make build
./bin/firework -h

Install with go install

go install github.com/erik-adelbert/firework/cmd/firework@latest

Test and benchmark

make test
make bench

Run without Makefile

go run ./cmd/firework/main.go

Build a binary:

mkdir -p bin
go build -o bin/firework ./cmd/firework/main.go
./bin/firework -h

Dependencies

• Bubble Tea
• Lip Gloss
• Go terminal support

Project Structure

• cmd/firework/ — CLI entry point (main package)
• fireworks/ — Builtins fireworks
• demos/ — Builtins shows
• internal/ — Core simulation and rendering logic
• tui/ — Charm's TUI application

How it Works

• The model simulates fireworks as a simple physics-based particle system.

Contributions

• Fork the project and open a pull request
• Contribute improvements, new fireworks, or show scripts

License

MIT. See LICENSE.

Author

Erik Adelbert

Note: I don't need to vibe my code. This project is crafted.