WebGPU Particle Fluid Simulation

English | 简体中文

🔮 Live Demo · 📖 Documentation · 📋 Specifications

A high-performance particle fluid simulation built with WebGPU compute shaders. Watch 10,000 particles interact with realistic physics, all running on your GPU.

💡 Try it: Open the Live Demo and move your mouse over the simulation to push particles around!

✨ Highlights

🚀 Quick Start

Get the simulation running in under a minute:

# 1. Clone the repository
git clone https://github.com/LessUp/particle-fluid-sim.git
cd particle-fluid-sim

# 2. Install dependencies
npm install

# 3. Start development server
npm run dev

Then open http://localhost:5173 in a WebGPU-enabled browser.

Requirements

• Node.js 18+ (Download)
• Browser: Chrome 113+, Edge 113+, or Safari 17+ (Check WebGPU Support)

🎮 Controls

📁 Project Structure

Built with OpenSpec for specification-driven development:

particle-fluid-sim/
├── openspec/               # 📋 OpenSpec framework
│   ├── specs/              # Specifications (Single Source of Truth)
│   │   ├── product/        # Product requirements & acceptance criteria
│   │   ├── rfc/            # Technical architecture decisions
│   │   ├── api/            # API contracts & type definitions
│   │   └── testing/        # BDD test specifications
│   ├── changes/            # Active change proposals
│   └── config.yaml         # OpenSpec configuration
├── docs/                   # 📖 Developer & user documentation
│   ├── API.md              # Complete API reference
│   ├── PERFORMANCE.md      # Optimization guide
│   ├── TROUBLESHOOTING.md  # Common issues & solutions
│   ├── architecture/       # System architecture
│   ├── setup/              # Environment and toolchain setup
│   └── maintenance.md      # Closeout workflow and maintenance guide
├── src/                    # 💻 Source code
│   ├── config/             # Simulation constants & configuration
│   ├── core/               # Core modules (WebGPU, physics, rendering)
│   └── shaders/            # WGSL compute & render shaders
├── scripts/                # 🔧 Build & release automation
└── .github/                # 🤖 CI/CD workflows & templates

🏗️ Architecture

CPU-GPU Heterogeneous Computing

┌─────────────────────────────────────────────────────┐
│  CPU (TypeScript)                                    │
│  • WebGPU initialization                            │
│  • Quality detection & scaling                      │
│  • Input handling (mouse/touch)                     │
│  • Frame loop orchestration                         │
└───────────────────┬─────────────────────────────────┘
                    │ writeBuffer / commandEncoder
                    ▼
┌─────────────────────────────────────────────────────┐
│  GPU (WGSL Shaders)                                  │
│                                                       │
│  ┌─────────────┐  ┌──────────┐  ┌──────────────┐    │
│  │  1.Compute  │─▶│ 2.Trail  │─▶│ 3. Render    │    │
│  │  Physics    │  │ Effects  │  │  Particles   │    │
│  └─────────────┘  └──────────┘  └──────┬───────┘    │
│                                         │            │
│                                         ▼            │
│                                ┌──────────────┐     │
│                                │ 4. Present   │     │
│                                │ To Screen    │     │
│                                └──────────────┘     │
└─────────────────────────────────────────────────────┘

Physics Pipeline

Each particle updates every frame with these steps:

1. Apply Gravity → velocity += gravity * deltaTime
2. Mouse Repulsion → Push away if within radius
3. Clamp Velocity → Limit to MAX_SPEED
4. Update Position → position += velocity * deltaTime
5. Boundary Bounce → Elastic collision with damping

Performance Characteristics

⚙️ Configuration

All constants in src/config/sim.ts:

🧪 Testing

Property-based testing with Vitest + fast-check:

# Run all tests
npm test

# Watch mode (TDD)
npm run test:watch

# With coverage report
npm run test:coverage

Test Coverage

• ✅ Particle initialization bounds
• ✅ Physics integration correctness
• ✅ Boundary bounce behavior
• ✅ Color interpolation accuracy
• ✅ Quality heuristic calculations
• ✅ HiDPI coordinate mapping

🛠️ Development

Available Scripts

Contributing

We welcome contributions! Here's how to get started:

1. Read AGENTS.md for Spec-Driven Development workflow
2. Follow the Contributing Guide
3. Update specs before implementing features
4. Test your changes with npm test
5. Submit a Pull Request

Quick start for contributors:

# 1. Fork and clone
git clone https://github.com/LessUp/particle-fluid-sim.git
cd particle-fluid-sim

# 2. Install dependencies
npm install

# 3. Create a feature branch
git checkout -b feature/your-feature-name

# 4. Make changes and run tests
npm test

# 5. Commit and push
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

# 6. Open a Pull Request

📚 Documentation

Specifications (Source of Truth)

Guides & Tutorials

Additional Resources

• Contributing Guide
• Changelog
• Maintenance Guide
• Security Policy

🌐 Browser Support

WebGPU is required. Check compatibility:

Firefox Users: Enable WebGPU by setting dom.webgpu.enabled = true in about:config

🙏 Acknowledgments

Built with modern web technologies:

• WebGPU - Next-generation graphics API
• TypeScript - Type-safe JavaScript
• Vite - Lightning-fast build tool
• Vitest - Blazing fast testing framework
• fast-check - Property-based testing

📄 License

MIT License © 2026 LessUp

See LICENSE for details.

🔗 Links

🔮 Live Demo · 💻 Repository · 🐛 Issues · 💬 Discussions

Made with 💜 and WebGPU