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.

Key Features

• 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.

Quick Start

Prerequisites

• 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.

1. Clone

git clone https://github.com/utilForever/CubbyFlow.git
cd CubbyFlow

2. Build the C++ API

For macOS, Linux, or Windows Subsystem for Linux:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DUSE_CUDA=OFF
cmake --build build --config Release

For 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.

3. Install the Python API

python -m pip install .

Docker Image

docker pull cubbyflow/cubbyflow:latest
docker run -it cubbyflow/cubbyflow
# Inside the container:
/app/build/bin/HybridLiquidSim

See Documents/Install.md for platform-specific build, test, and installation instructions.

Architecture at a Glance

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.

Development

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/UnitTests

On Windows, run build\bin\Release\UnitTests.exe. Contributor workflow, dimensional parity, Python/CUDA synchronization, and validation rules are documented in AGENTS.md.

Documentation

Generated API reference and additional documentation are available on the project website.

Examples

Source code is available under Examples. These images were rendered with Mitsuba; more demos are on the project website.

Dam-Break Solvers

PCISPH	Level set	FLIP

PIC	APIC

Level-Set Viscosity

High viscosity	Low viscosity

Smoke Advection

Linear	Cubic spline

Presentations

• NDC 2018

Articles

• NDC 2018
  • [NDC2018] 유체역학 엔진이 직면한 문제와 미래
  • [NDC18] 게임에 쓸 수 있는 유체역학 엔진, 어렵지만 꿈은 아니다

How To Contribute

Contributions are welcome through issues and pull requests. Read AGENTS.md for the repository's coding, testing, and review expectations before making a change.

Contact

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.

License

CubbyFlow is licensed under the MIT License.

Copyright © 2017-2026 Chris Ohk