Fluid Bottle

ESP-IDF based fluid-bottle demo. It reads gravity from the IMU, runs a small FLIP/PIC-style 2D particle simulation, and renders the liquid occupancy grid to the LCD.

Features

• IMU-driven gravity and shake impulse response.
• Lightweight MAC-grid pressure projection with particle advection.
• Dirty-cell LCD rendering to reduce redraw cost.
• Render occupancy stabilization so the liquid keeps visible volume while moving.

Project Layout

.
├── CMakeLists.txt
├── LICENSE
├── README.md
└── main
    ├── main.c                  # app loop: LCD, IMU, simulation update
    ├── fluid_lcd.*            # LCD adapter
    ├── fluid_imu.*            # IMU adapter
    ├── fluid_sim.c             # simulation frame pipeline
    ├── fluid_sim.h             # public simulation API
    ├── fluid_sim_config.h      # simulation/render tuning constants
    ├── fluid_sim_types.h       # internal particle and state types
    ├── fluid_geometry.c        # reusable geometry, grid and occupancy helpers
    └── fluid_geometry.h

Build

Requires ESP-IDF and the dependencies declared in main/idf_component.yml.

idf.py set-target esp32s3
idf.py build
idf.py flash monitor

Tuning

Most gameplay/visual tuning lives in main/fluid_sim_config.h:

• FLUID_FILL_RATIO controls the liquid volume.
• FLUID_FORCE_GAIN, FLUID_JOLT_GAIN, and FLUID_SLOSH_ROLL_GAIN control motion response.
• FLUID_RENDER_MAX_CHANGES and FLUID_RENDER_MIN_VISIBLE control render stability.
• FLUID_CELL and FLUID_GAP control LCD grid density and spacing.

License

This project is released under the PolyForm Noncommercial License 1.0.0. Noncommercial use, modification, and redistribution are allowed. Commercial use is not allowed unless you get a separate commercial license from the copyright holder.