Features
- Smooth metaball animation rendered directly in the terminal
- Half-block rendering (
▀,▄,█) for double vertical resolution - Named terminal colors and
RRGGBB/#RRGGBBtruecolor input - Two-color gradient rendering with named or hex endpoints
- Optional gravity, heating, and buoyancy movement
- Contained mode that keeps every blob inside the visible terminal area
- Configurable speed, radius, rim size, and metaball count
- Custom ASCII glyphs and animated party color modes
- Live keyboard controls with transient top-right status messages
- Automatic terminal resize handling
- Alternate-screen rendering with reliable terminal state restoration
Installation
From crates.io
After the package is published:
With Nix (Flake)
Use nix run to try lavatr without installing it, or add it permanently to your Nix profile.
From source
This installs a single executable named lavatr.
Build without installing
The executable is written to target/release/lavatr.
Quick start
# Default lava lamp
# Named colors with an inner rim
# Truecolor gradient with gravity
# Named-to-hex gradient
# Party colors and custom characters
General syntax:
lavatr [OPTIONS]
CLI options
| Option | Description |
|---|---|
| -g, --gradient | Enable truecolor gradient rendering; both endpoints accept named and hex colors |
| -G, --gravity | Enable gravity, heating, and buoyancy movement |
| -c, --color <COLOR> | Set the lava color using a name, RRGGBB, or #RRGGBB |
| -k, --rim-color <COLOR> | Set the rim color, or the second endpoint in gradient mode |
| -s, --speed <1..10> | Set animation speed; default 5 |
| -r, --radius <1..10> | Set metaball radius; default 5 |
| -R, --rim <1..5> | Enable and size the inner rim |
| -b, --balls <5..20> | Set the number of metaballs; default 10 |
| -F, --chars <CHARS> | Draw with custom ASCII glyphs |
| -C, --contained | Keep blobs inside the visible terminal bounds |
| -p, --party <MODE> | Select off, 1, 2, 3, p1, p2, or p3 |
| -h, --help | Print help |
| -V, --version | Print version information |
Named colors are red, blue, yellow, green, cyan, magenta, white, and black.
Runtime controls
| Key | Action |
|---|---|
| ~ | Toggle the centered keyboard shortcuts popup |
| + or = / - or _ | Increase / decrease animation speed |
| i / d | Increase / decrease metaball radius |
| I / D | Increase / decrease inner rim size |
| m or M / l or L | Increase / decrease metaball count |
| c / k | Cycle lava / rim color in normal color mode |
| p or P | Cycle party modes |
| q, Q, Ctrl+C | Quit |
Setting changes are displayed in the top-right corner for one second.
Shell notes
PowerShell treats # as the start of a comment, so hash-prefixed colors must be quoted:
lavatr --color "#8ba4b0"
The hash is optional, so this is equivalent:
lavatr --color 8ba4b0
Development