lavatr 1.1.0

Animated terminal lava lamp with configurable metaball physics
Documentation

Features

  • Smooth metaball animation rendered directly in the terminal
  • Half-block rendering (▀, ▄, █) for double vertical resolution
  • Named terminal colors and RRGGBB / #RRGGBB truecolor 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:

cargo install lavatr

With Nix (Flake)

nix run github:WhoSowSee/lavatr
nix profile install github:WhoSowSee/lavatr

Use nix run to try lavatr without installing it, or add it permanently to your Nix profile.

From source

git clone https://github.com/WhoSowSee/lavatr.git
cd lavatr
cargo install --path .

This installs a single executable named lavatr.

Build without installing

cargo build --release

The executable is written to target/release/lavatr.

Quick start

# Default lava lamp
lavatr

# Named colors with an inner rim
lavatr -c cyan -k magenta -R 2

# Truecolor gradient with gravity
lavatr -g -c 00FF00 -k FF0000 -G -b 8 -r 8

# Named-to-hex gradient
lavatr -g -c red -k 0000FF

# Party colors and custom characters
lavatr -p p3 -F '@#'

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

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo build --release