A voxel-based fluid simulation engine for computer games
CubbyFlow is based on the Jet framework created by Doyub Kim. It provides matching 2-D and 3-D C++ and Python APIs for fluid simulation. Host code uses C++23; optional CUDA device code uses C++17.
- Basic math and geometry operations and data structures
- Spatial query accelerators
- SPH and PCISPH fluid simulators
- Stable fluids-based smoke simulator
- Level set-based liquid simulator
- PIC, FLIP, and APIC fluid simulators
- Upwind, ENO, and FMM level set solvers
- Jacobi, Gauss-Seidel, SOR, MG, CG, ICCG, and MGPCG linear system solvers
- Spherical, SPH, Zhu & Bridson, and Anisotropic kernel for points-to-surface converter
- Converters between signed distance function and triangular mesh
- C++ and Python API
- Intel TBB, OpenMP, HPX and C++11 multi-threading backends
Every simulator has both 2-D and 3-D implementations.
- CMake 3.31.6 or newer
- A C++23 compiler
- A bootstrapped vcpkg checkout
- Python when building
pyCubbyFlow - A CUDA toolkit only when building the optional CUDA backend
Set VCPKG_ROOT to your vcpkg checkout. CubbyFlow's manifest installs the required libraries during CMake configuration.
git clone https://github.com/utilForever/CubbyFlow.git
cd CubbyFlowFor macOS, Linux, or Windows Subsystem for Linux:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DUSE_CUDA=OFF
cmake --build build --config ReleaseFor Windows:
cmake -S . -B build -A x64 -DUSE_CUDA=OFF cmake --build build --config Release
Run an example:
./build/bin/HybridLiquidSim
On Windows, the executable is build\bin\Release\HybridLiquidSim.exe.
python -m pip install .docker pull cubbyflow/cubbyflow:latest
docker run -it cubbyflow/cubbyflow
# Inside the container:
/app/build/bin/HybridLiquidSimSee Documents/Install.md for platform-specific build, test, and installation instructions.
| Area | Paths |
|---|---|
| Public C++ API | Includes/Core/ |
| Core implementation | Sources/Core/ |
| Optional CUDA | Includes/Core/CUDA/, Sources/Core/CUDA/ |
| Python bindings | Includes/API/Python/, Sources/API/Python/ |
| Tests | Tests/ |
| Examples | Examples/ |
Most behavior starts in the core library and is shared by matching 2-D and 3-D APIs. Python bindings expose the same core types, while CUDA remains optional. See ARCHITECTURE.md for the full design and code-reading guide.
Build and run the focused CPU unit-test target:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DUSE_CUDA=OFF -DBUILD_EXAMPLES=OFF -DBUILD_TESTS=ON
cmake --build build --target UnitTests --config Release
./build/bin/UnitTestsOn Windows, run build\bin\Release\UnitTests.exe. Contributor workflow, dimensional parity, Python/CUDA synchronization, and validation rules are
documented in AGENTS.md.
Generated API reference and additional documentation are available on the project website.
Source code is available under Examples. These images were rendered with Mitsuba; more demos are on the project website.
| PCISPH | Level set | FLIP |
|---|---|---|
 |
 |
 |
| PIC | APIC |
|---|---|
 |
 |
| High viscosity | Low viscosity |
|---|---|
 |
 |
| Linear | Cubic spline |
|---|---|
 |
 |
Contributions are welcome through issues and pull requests. Read AGENTS.md for the repository's coding, testing, and review expectations before making a change.
You can contact me via e-mail (utilForever at gmail.com). I am always happy to answer questions or help with any issues you might have, and please be sure to share any additional work or your creations with me, I love seeing what other people are making.
CubbyFlow is licensed under the MIT License.
Copyright © 2017-2026 Chris Ohk