Particle Fluid Simulation
A spec-driven WebGPU reference project with 10,000+ particles, compute-shader physics, adaptive quality, and a polished browser demo you can inspect and extend.
Features
Built with modern web technologies for maximum performance
GPU Compute Shaders
All physics calculations run in parallel on the GPU using WebGPU compute shaders for maximum performance.
Frame-Rate Independent
Physics uses delta time calculations, ensuring consistent simulation speed at any frame rate.
Adaptive Quality
Automatically detects device capabilities and scales particle count from 2,500 to 10,000 for optimal performance.
Visual Effects
Beautiful motion trails with velocity-based color mapping from cyan to purple based on particle speed.
Interactive Controls
Push particles with mouse or touch input. HiDPI-aware coordinate mapping for Retina displays.
Modern Stack
Built with TypeScript, Vite, WebGPU, and Vitest for a great developer experience.
Quick Start
Get the simulation running in under a minute
Clone the repository
git clone https://github.com/LessUp/particle-fluid-sim.git
cd particle-fluid-simInstall dependencies
npm installRun locally or open the hosted demo
npm run devFor GitHub Pages, use /demo/. For local development, open http://localhost:5173.
Requirements
Docs & Workflow
Curated reference for running, understanding, and finishing the project cleanly
Documentation Index
Entry point for the curated docs set: setup, architecture, troubleshooting, workflow, and API details.
Read more →API Reference
Complete API documentation including configuration, types, core modules, and shader constants.
Read more →Performance Guide
Benchmarks, optimization tips, and profiling techniques for the WebGPU particle simulation.
Read more →Troubleshooting
Common issues and solutions including browser compatibility and performance problems.
Read more →Architecture
High-level architecture overview including CPU-GPU heterogeneous computing and data flow.
Read more →Setup Guide
Environment setup, local LSP, editor recommendations, and hook installation for the TypeScript/WebGPU stack.
Read more →Workflow Guide
Project-specific closeout workflow, OpenSpec usage, hooks, validation gates, and review checkpoints.
Read more →OpenSpec Source of Truth
The project’s requirements, architecture, API, and testing expectations are published as browsable HTML pages.
Product Requirements
Functional requirements, non-functional expectations, and acceptance criteria for the current simulation.
Read more →Architecture RFC
CPU/GPU split, data layout, render passes, and quality heuristics explained at the spec level.
Read more →API Specification
Contracts for configuration, buffers, renderer lifecycle, and WebGPU-facing types.
Read more →Testing Spec
BDD scenarios, coverage expectations, and verification criteria that back the codebase.
Read more →