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

⚡ GPU-Accelerated Physics All physics calculations run on the GPU via WebGPU compute shaders. Gravity, repulsion, velocity clamping, and boundary bounce happen in parallel for 10,000 particles.	📊 Frame-Rate Independent Physics uses delta time calculations, so the simulation runs at the same speed whether you're getting 30 FPS or 144 FPS.
🎯 Adaptive Quality Automatically detects your device capabilities and adjusts particle count from 2,500 to 10,000 for optimal performance.	🎨 Persistent Trails Beautiful motion trails via dedicated offscreen texture with velocity-based color mapping (cyan for slow, purple for fast).

🚀 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

Action	Effect
Move Mouse	Push particles away from cursor
Touch (Mobile)	Same as mouse interaction
Resize Window	Automatically adjusts HiDPI scaling

📁 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

Metric	Value	Notes
Particles	2,500 - 10,000	Adaptive based on device
Particle Size	16 bytes	4 × float32 (x, y, vx, vy)
Compute Workgroup	64 threads	Optimized for GPU architecture
Frame Budget	< 16ms	Targets 60 FPS

⚙️ Configuration

All constants in src/config/sim.ts:

Parameter	Default	Description
PARTICLE_COUNT	10,000	Base particle count (scaled by quality)
GRAVITY	{x: 0, y: 600}	Gravity acceleration (px/s²)
MAX_SPEED	800	Velocity ceiling (px/s)
REPULSION_RADIUS	200	Mouse influence radius (px)
REPULSION_STRENGTH	3,000	Mouse repulsion force (px/s)
DAMPING	0.9	Bounce energy retention (90%)
TRAIL_FADE_ALPHA	0.05	Trail persistence per frame

🧪 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

Command	Description
npm run dev	Start development server with HMR
npm run build	TypeScript check + production build
npm run preview	Preview production build locally
npm run lint	Run ESLint
npm run typecheck	Run TypeScript type checking
npm run format	Format code with Prettier

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)

Document	Description
📋 Product Requirements	Functional & non-functional requirements
📐 RFC 0001: Core Architecture	System architecture & design decisions
📝 RFC 0002: Implementation Tasks	Implementation task tracking
🧪 Testing Specification	BDD test specifications

Guides & Tutorials

Document	Description
📖 API Reference	Complete API documentation
⚡ Performance Guide	Benchmarks and optimization
🔧 Troubleshooting	Common issues and solutions
📚 Docs Index	Curated map of the durable documentation set
🏗️ Architecture	System architecture overview
🚀 Setup Guide	Environment setup, LSP, and local tooling
🛠️ Workflow Guide	OpenSpec-first closeout workflow and review gates

Additional Resources

• Contributing Guide
• Changelog
• Maintenance Guide
• Security Policy

🌐 Browser Support

WebGPU is required. Check compatibility:

Browser	Version	Status
Chrome	113+	✅ Recommended
Edge	113+	✅ Recommended
Safari	17+	✅ macOS 14+
Firefox	Nightly	⚠️ Enable flag
Opera	99+	✅ Chromium-based

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