showcase

README

Particle Symphony 🎵✨

An interactive particle simulation showcasing the power and elegance of andygeiss/ecs – a lightweight, high-performance Entity Component System framework for Go.

🎯 This project exists to demonstrate how simple yet powerful ECS architecture can be. Watch thousands of particles dance, interact, and create emergent beauty – all powered by clean, modular ECS patterns.

🌐 Live Demo

🎆 Try it in your Browser →

No installation required! The web version runs entirely in WebAssembly.

⚡ Powered By

Technology	Purpose
andygeiss/ecs	🏆 The star of the show! Lightweight ECS framework with bitmask-based entity filtering
raylib-go	Native desktop rendering (high performance)
Ebitengine	WebAssembly rendering (cross-platform)
Go	Because simplicity and performance matter

🚀 Quick Start

Native Version (raylib)

For the best performance, run the native version:

# Clone the repository
git clone https://github.com/deltatree/showcase.git
cd showcase

# Build and run
go build -o particle-symphony . && ./particle-symphony

WebAssembly Version (Ebitengine)

Build the WASM version locally:

./build-wasm.sh
cd web && python3 -m http.server 8080
# Open http://localhost:8080

🎮 Controls

Key	Action
1	Galaxy Preset
2	Firework Preset
3	Swarm Preset
4	Fountain Preset
5	Chaos Preset
LMB	Attract Particles
RMB	Repel Particles
2× Click	Lock Attract/Repel
F3	Toggle Debug Overlay
ESC	Exit (Native only)

✨ Features

• Entity Component System - Clean, modular architecture
• Multiple Presets - Fountain, Firework, Galaxy, Swarm, and Chaos effects
• Real-time Physics - Gravity, damping, and velocity simulation
• Color Transitions - Smooth gradient color animations
• Lifetime Management - Particle birth, aging, and death cycles

🏗️ Architecture

The project follows a pure ECS architecture using andygeiss/ecs:

• Components - Pure data containers (Position, Velocity, Color, Mass, etc.)
• Systems - Logic processors (Physics, Render, Emitter, Gravity, etc.)
• Entities - Unique identifiers linking components together
• Bitmask Filtering - Blazingly fast entity queries using component masks

Why andygeiss/ecs?

✅ Zero Dependencies - Pure Go, no external requirements
✅ Bitmask-based Filtering - O(1) component lookups
✅ Clean API - Simple, intuitive, Go-idiomatic
✅ Battle-tested - Used in production game projects
✅ Minimal Footprint - Small codebase, easy to understand

// Example: How simple ECS can be!
particles := em.FilterByMask(MaskPosition | MaskVelocity | MaskColor)
for _, entity := range particles {
    pos := entity.Get(MaskPosition).(*Position)
    vel := entity.Get(MaskVelocity).(*Velocity)
    pos.X += vel.X * deltaTime
    pos.Y += vel.Y * deltaTime
}

📁 Project Structure

├── components/     # ECS component definitions
├── systems/        # ECS system implementations
├── presets/        # Particle effect presets
├── internal/       # Internal packages (config)
├── web/            # Web showcase page
├── cmd/wasm/       # WebAssembly version (Ebitengine)
└── docs/           # Project documentation

🙏 Credits & Acknowledgments

This project wouldn't exist without these amazing open-source projects:

• andygeiss/ecs by @andygeiss - The ECS framework that makes this all possible. Seriously, go check it out! ⭐
• raylib-go - Go bindings for the fantastic raylib game library
• Ebitengine by @hajimehoshi - Making Go games run everywhere, including the browser!

📝 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Built with ❤️ and mass quantities of ☕

If you found this useful, consider starring the repo and checking out andygeiss/ecs!

Documentation

Overview

Particle Symphony - Native Desktop Application

This is the main entry point for the native desktop version of Particle Symphony. It uses raylib-go for rendering and provides interactive particle effects driven by the andygeiss/ecs Entity-Component-System framework.

Controls:

• Mouse: Move to guide particles
• Left Click: Attract particles
• Right Click: Repel particles
• Double-Click: Lock attract/repel mode
• 1-5: Switch between presets
• F3: Toggle debug overlay

Run: go run main.go