Falling Sand Simulator - Chunked Plan/Commit with ImGui Profiler

A chunked, multi-threaded falling-sand simulation using SDL2 for windowing/input and Dear ImGui for an on-screen profiler and minimal UI. The core loop is split into a Plan phase (compute intents) and a Commit phase (apply winners), enabling safe parallelism with minimal locking.

Features

• Chunked world with per-chunk activity tracking -Two-phase update (Plan → Commit) for safe multithreading
• Threaded or sequential simulation toggle
• Adjustable resolution, scale, and chunk size via startup UI
• Particles: sand, water, rock, empty
• Live profiler overlay via Dear ImGui
• Determinism toggle and profiling hooks

Build and run (Windows, MinGW-w64)

This matches the VS Code task used in this repo (MinGW g++ with SDL2 and ImGui).

Compile:

g++ -std=c++17 -O3 -g
-I SDL2/include -I SDL2/include/SDL2 -I imgui -I imgui/backends -L SDL2/lib
src/main.cpp src/sand.cpp src/SandWorld.cpp
imgui/imgui.cpp imgui/imgui_draw.cpp imgui/imgui_tables.cpp imgui/imgui_widgets.cpp
imgui/backends/imgui_impl_sdl2.cpp imgui/backends/imgui_impl_sdlrenderer2.cpp imgui/backends/imgui_impl_opengl3.cpp
-o sand-sim.exe -lmingw32 -lSDL2main -lSDL2 -lopengl32

Run:

./sand-sim.exe

Build with VS Code task

The repository can include a tasks.json entry equivalent to the command above:

{
  "version": "1.0.0",
  "tasks": [
    {
      "label": "build sand sim",
      "type": "shell",
      "command": "g++",
      "args": [
        "-std=c++17",
        "-g",
        "-O3",
        "-I", "SDL2/include",
        "-I", "SDL2/include/SDL2",
        "-I", "imgui",
        "-I", "imgui/backends",
        "-L", "SDL2/lib",
        "src/main.cpp",
        "src/sand.cpp",
        "src/SandWorld.cpp",
        "imgui/imgui.cpp",
        "imgui/imgui_draw.cpp",
        "imgui/imgui_tables.cpp",
        "imgui/imgui_widgets.cpp",
        "imgui/backends/imgui_impl_sdl2.cpp",
        "imgui/backends/imgui_impl_sdlrenderer2.cpp",
        "imgui/backends/imgui_impl_opengl3.cpp",
        "-o", "sand-sim.exe",
        "-lmingw32", "-lSDL2main", "-lSDL2", "-lopengl32"
      ],
      "group": "build",
      "problemMatcher": ["$gcc"]
    },
    {
      "label": "build:release (MinGW g++)",
      "type": "shell",
      "command": "g++",
      "options": { "cwd": "${workspaceFolder}" },
      "args": [
        "-std=c++17", "-DNDEBUG", "-O3", "-s",
        "-static-libstdc++", "-static-libgcc",
        "-I", "SDL2/include",
        "-I", "SDL2/include/SDL2",
        "-I", "imgui",
        "-I", "imgui/backends",
        "-L", "SDL2/lib",
        "src/main.cpp",
        "src/sand.cpp",
        "src/SandWorld.cpp",
        "imgui/imgui.cpp",
        "imgui/imgui_draw.cpp",
        "imgui/imgui_tables.cpp",
        "imgui/imgui_widgets.cpp",
        "imgui/backends/imgui_impl_sdl2.cpp",
        "imgui/backends/imgui_impl_sdlrenderer2.cpp",
        "imgui/backends/imgui_impl_opengl3.cpp",
        "-Xlinker", "-Bstatic",
        "-lwinpthread",
        "-Xlinker", "-Bdynamic",
        "-o", "sand-sim.exe",
        "-lmingw32", "-lSDL2main", "-lSDL2", "-lopengl32"
      ],
      "group": "build",
      "problemMatcher": ["$gcc"]
    }
  ]
}

If your local paths differ, adjust the -I and -L flags. Ensure SDL2.dll is available at runtime.

Optional build notes

Linux (gcc or clang, system SDL2)

sudo apt-get install libsdl2-dev
g++ -std=c++17 -O3 -g -I/usr/include/SDL2 -D_REENTRANT
-I imgui -I imgui/backends
src/main.cpp src/sand.cpp src/SandWorld.cpp
imgui/imgui.cpp imgui/imgui_draw.cpp imgui/imgui_tables.cpp imgui/imgui_widgets.cpp
imgui/backends/imgui_impl_sdl2.cpp imgui/backends/imgui_impl_sdlrenderer2.cpp imgui/backends/imgui_impl_opengl3.cpp
-lSDL2 -lGL -ldl -lpthread -o sand-sim
./sand-sim

macOS (Apple clang, Homebrew SDL2)

brew install sdl2
clang++ -std=c++17 -O3 -g -I /opt/homebrew/include -I imgui -I imgui/backends
src/main.cpp src/sand.cpp src/SandWorld.cpp
imgui/imgui.cpp imgui/imgui_draw.cpp imgui/imgui_tables.cpp imgui/imgui_widgets.cpp
imgui/backends/imgui_impl_sdl2.cpp imgui/backends/imgui_impl_sdlrenderer2.cpp imgui/backends/imgui_impl_opengl3.cpp
-L /opt/homebrew/lib -lSDL2 -framework OpenGL -framework Cocoa -framework IOKit -framework CoreVideo
-o sand-sim
./sand-sim

Controls

• Left mouse: paint particles (default sand)
• Right mouse: erase to empty
• S while painting: sand
• W while painting: water
• R while painting: rock
• ImGui overlay: toggle profiler panels, chunk grid, parameters, buttoms to change brush

Project structure

.
├─ .vscode/
│  ├─ launch.json
│  ├─ settings.json
│  └─ tasks.json
├─ src/
│  ├─ Colour.h
│  ├─ Particle.h
│  ├─ Profiler.h
│  ├─ SandWorld.h
│  ├─ main.cpp
│  ├─ sand.cpp
│  └─ SandWorld.cpp
├─ imgui/
│  ├─ imgui*.cpp
│  └─ backends/
├─ SDL2/
│  ├─ include/
│  └─ lib/
├─ third_party/
│  ├─ SDL2-LICENSE.txt        # zlib
│  └─ imgui-LICENSE.txt       # MIT
├─ README.md
├─ imgui.ini
├─ .gitignore
├─ screenshot.png              # program window capture
└─ SDL2.dll

Citation

• SDL2, Simple DirectMedia Layer, https://www.libsdl.org/
• Dear ImGui, https://github.com/ocornut/imgui

License

This project’s original code: 0BSD © 2025 Oscar Carter-South (see LICENSE.txt).

Third-party components:

• SDL2 : zlib license. See third_party/SDL2-LICENSE.txt.
• Dear ImGui : MIT license. See third_party/imgui-LICENSE.txt.