WebGPU Particle Fluid Simulation

English | 简体中文

🔮 Live Demo · 📖 Docs · 📝 Changelog

High-performance particle fluid simulation built with WebGPU compute shaders. The project stays intentionally small: one WebGPU runtime, one VitePress site, and one root CHANGELOG.md.

Quick start

git clone https://github.com/AICL-Lab/particle-fluid-sim.git
cd particle-fluid-sim
npm install
npm run dev

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

Requirements

• Node.js 18+
• Chrome 113+, Edge 113+, or Safari 17+

Controls

Action	Effect
Move mouse	Repel nearby particles
Touch	Same interaction on mobile
Resize window	Recompute canvas size and HiDPI scale

Development commands

Command	Purpose
npm run dev	Start the development server
npm run build	Type-check and build the demo
npm run docs:dev	Start the VitePress docs site
npm run docs:build	Build the docs site
npm run lint	Lint src/**/*.ts
npm run typecheck	Run TypeScript checks
npm run test:coverage	Run tests with coverage
npm run verify	Run the full closeout gate

Project layout

particle-fluid-sim/
├── src/              # WebGPU runtime and tests
│   ├── config/       # Shared simulation constants
│   ├── core/         # WebGPU setup, buffers, renderer, quality, input
│   └── shaders/      # WGSL shader assets
├── docs/             # VitePress docs and architecture notes
├── .github/          # CI, Pages, issue templates, repo metadata
├── CHANGELOG.md      # The single project changelog
└── package.json      # Build, docs, and validation scripts

Documentation map

Document	Purpose
Getting Started	Local setup and core commands
Architecture Notes	CPU/GPU split and render pipeline
API Reference	Runtime-facing modules and types
Performance Guide	Profiling and performance checks
Contributing Guide	Contribution rules and validation
Changelog	Release history and notable changes

Architecture summary

The runtime is organized around a small set of focused modules:

• src/main.ts wires canvas setup, WebGPU initialization, quality selection, input, and the render loop.
• src/core/simulation-resources.ts owns pipelines, buffers, and bind groups.
• src/core/renderer.ts manages frame timing and delegates GPU work to frame-encoder.ts.
• src/shaders/*.wgsl contain the compute, trail, render, and present shader stages.

Contributing

Focused cleanup, correctness fixes, documentation improvements, and presentation polish are welcome. Run npm run verify before opening a high-impact pull request.

License

Released under the MIT License.