LavaCLI

A beautiful, interactive terminal lava lamp simulator with metaball physics, Perlin noise flow, half-block rendering, a fullscreen koi pond, and a theme-cycling spinning ASCII donut. Published on PyPI as pylavalamp.

          ╭─╮
        ╭─┘ └─╮
        │      │
        │ ▄██▄ │
       ╱ █████  ╲
      │  ▀████▀  │
      │   ▀▀▀▀   │
      │           │
     ╱    ▄▄▄     ╲
     │   █████     │
    ╱   ██████▄     ╲
    │   ████████    │
    │   ▀██████▀    │
   ╱     ▀▀▀▀▀      ╲
   │                  │
   │      ▄▄▄▄▄      │
  ╱      ███████      ╲
  │     █████████      │
  │     █████████      │
  │      ▀█████▀       │
  ████████████████████
   ████████████████
     ████████████
       ████████
     ████████████
   ████████████████
  ████████████████████
  ══════════════════════

Features

• 14 Lamp Styles - Classic, Slim, Globe, Lava, Diamond, Cylinder, Pear, Rocket (Mathmos Telstar), Freestyle (fullscreen lava), Koi Pond (fullscreen animated fish), Fireplace (fullscreen embers), Campfire (fullscreen embers + pine forest scene), Donut (fullscreen spinning ASCII donut), and Christmas (fullscreen indoor fireplace with brick surround, mantel, and stockings)
• 17 Color Themes - Yellow Red, Blue White, Clear Orange, Purple Haze, Neon Green, Blue Purple, Clear Red, Sunset, Psychedelic, Monochrome, Koi Pond, Aurora, Campfire, Cyberpunk, Matrix, Oceanic, and Christmas - inspired by classic 1992-2004 Lava Library color codes and modern neon aesthetics
• Bi-color Lava - Mix two themes in a single lamp (like the 90s red/blue Mathmos bi-color lamps) via --bicolor THEME_B or the menu's TINT field. Half the blobs carry each palette and merge naturally at their boundaries
• Motion Trails - Press T during animation to toggle slow-shutter trails; each blob paints a soft fading comet-tail behind it. Works on all lamp and fullscreen styles
• 6 Flow Types - Classic, Chaotic, Zen, Bouncy, Swirl, and Liquid (Perlin noise organic flow)
• Koi Pond Mode - Fullscreen animated koi pond with 6-10 sage-green lily pads scattered across the water and colorized fish (6 real koi varieties: Kohaku, Sanke, Showa, Tancho, Ogon, Asagi) using 14-segment skeletal physics, pectoral fins, and fanning tail fins
• Campfire Mode - Dedicated fullscreen campfire with rising ember physics and a layered pine forest silhouette background: three depth layers of conifers, rolling snowy ground with warm firelight glow, and a starry night sky
• Christmas Fireplace Mode - Fullscreen indoor Christmas fireplace: red brick surround with lintel, wooden mantel shelf, two Christmas stockings with white cuffs, a procedural dancing hearth flame (black backdrop tapering from white-hot center to dark red edges, with time-based flicker), metaball embers rising on top for depth, stone hearth, and a warm dark room with hardwood floor
• Donut Mode - Fullscreen spinning ASCII donut (Andy Sloane's donut.c geometry) rendered entirely in theme colors. 5 shade modes via B/V — Smooth, Glow, Bold, Dim, and Iced (pink icing on upward-facing surfaces with golden dough)
• 1-6 Lamps - Display multiple lava lamps side by side
• 5 Sizes - 11.5", 14.5", 16.3", 17", and 27" Grande (default)
• Freestyle Mode - Fullscreen lava with no lamp frame, filling the entire terminal
• Groovy Animated Menu - Lava background, rotating taglines, live lamp preview panel (every selection renders a real miniature lamp or koi pond next to the menu), inline theme palette swatch, position counters, R for randomize, 1–6 to jump between fields
• Direct-launch CLI flags - lavacli --style koipond --theme koi_pond --duration 600 skips the menu entirely — perfect for tmux startup scripts and terminal screensavers
• Rim/Edge Glow - Dual-threshold rendering gives lava blobs a glowing halo edge
• Resizable - Lamps adapt when you resize the terminal, including ball radius scaling so blobs maintain proper proportions at any size
• Half-Block Rendering - Uses Unicode ▀▄█ characters for 2x vertical resolution
• Metaball Physics - Real metaball field simulation for authentic blob merging/splitting
• Perlin Noise Flow - Pure-Python 3D Perlin noise with fractal Brownian motion for smooth organic liquid animation
• Heat/Buoyancy Cycle - Blobs heat at the bottom, rise, cool at the top, and sink back down
• Dark Metallic Base - Hourglass-shaped base with 3-tone shading, matching classic black lava lamp bases
• Rocket Style - Mathmos Telstar-inspired rocket ship with cylindrical chrome glass column, sharp pointed nose cone, three swept-back fins, and a vertical chrome highlight stripe for polished metal feel
• Interactive Controls - Change speed, pause, cycle colors, add/remove blobs, return to menu, toggle HUD

Install

The PyPI package is named pylavalamp (the bare lavacli name was already taken on PyPI), but the installed command is still lavacli.

pipx install pylavalamp

That's it — lavacli is now available as a command from anywhere in your terminal.

To install from a local clone instead:

git clone https://github.com/ElysiumDisc/lavacli.git
pipx install ./lavacli

For development (editable mode, source changes take effect immediately):

pipx install -e ./lavacli

Uninstall

pipx uninstall pylavalamp

Quick Start

lavacli

Or run directly without installing:

python3 -m lavacli

CLI Flags (skip the menu)

Pass any lamp-config flag and the menu is skipped — LavaCLI drops straight into the animation. Omitted fields get sensible defaults. Great for tmux startup scripts, shell aliases, and terminal screensavers.

# Fullscreen koi pond with the matching theme
lavacli --style koipond --theme koi_pond

# Three swirling rocket lamps on the Purple Haze theme
lavacli --style rocket --flow swirl --theme purple_haze --count 3

# Surprise me, but keep it freestyle, for 10 minutes then exit
lavacli --random --style freestyle --duration 600

# Just randomize everything
lavacli --random

# Cozy campfire scene (pine forest + rising embers)
lavacli --style campfire

# Cozy fireplace with Aurora-night-sky embers
lavacli --style fireplace --theme aurora

# Christmas indoor fireplace
lavacli --style xmas

# Classic bi-color lamp: yellow/red mixed with blue/white
lavacli --theme yellow_red --bicolor blue_white

# Big spinning donut
lavacli --style donut

Run lavacli --help for the full list.

Controls

Menu

During Animation

Styles

Themes

Inspired by the classic 1992-2004 Lava Library color codes with dark bases:

Flow Types

Koi Pond

Select Koi Pond from the STYLE menu for a fullscreen animated koi pond. Fish are rendered with the same half-block technique as the lava lamp, but use skeletal segment-based physics inspired by cpond.

Each fish has 14 connected body segments with constraint-based movement, sinusoidal swimming undulation, pectoral fins, and a fanning tail fin. The pond surface is decorated with 6-10 sage-green elliptical lily pads (each with a characteristic V-notch and 3-tone shading) — fish swim freely over and around them, just like a real koi pond. Fish are colorized using 6 real koi varieties:

The pond is biased toward Kohaku and Sanke (white-with-orange) so the default scene reads as a classic watercolor koi pond. Pick the Koi Pond theme for the closest match to that aesthetic — teal water + sage lily pads + warm koi colors. Lily pads stay sage-green regardless of which theme you cycle to. Use B/V to add/remove fish, and C to cycle themes.

Sizes

Modeled after real lava lamp dimensions:

Requirements

• Python 3.8+
• A terminal with:
  • Unicode support (for half-block characters ▀▄█)
  • 256-color support (for full color themes; falls back to 8 colors)
  • Minimum 46x20 characters (larger recommended for Grande size)

No external dependencies - uses only Python standard library (curses).

How It Works

Metaball Physics

Each lava blob is a "metaball" - a point with a radius that generates an implicit field:

field(x,y) = sum( radius^2 / distance^2 ) for each ball

When the field exceeds a threshold, that pixel is "inside" the lava. Nearby blobs naturally merge into smooth shapes. A secondary rim threshold creates a glowing edge around each blob for visual depth. The engine uses a dual-field pass that computes both the top and bottom half-block field values in a single iteration, sharing redundant square-distance calculations. A distance-based cutoff skips contributions from blobs further than 20 units away, ensuring high performance even on large terminals with many balls.

Perlin Noise Flow

The "Liquid" flow type uses 3D Perlin noise with fractal Brownian motion (3 octaves) instead of metaball physics. Time advances continuously through the noise field, creating smooth organic flowing patterns. No ball physics needed - just fbm3(x * scale, y * scale, time). noise3() inlines its fade/lerp/gradient helpers, and each row samples noise on every other column and interpolates between them, which keeps fullscreen Liquid within the frame budget.

Heat/Buoyancy Cycle

Balls track a temperature value. Near the bottom they heat up and gain buoyancy. As they rise to the top they cool down and gravity pulls them back. This creates the mesmerizing rise-and-fall cycle of a real lava lamp.

Half-Block Rendering

Each terminal cell is split into two vertical halves using Unicode half-block characters (▀▄█), doubling the effective vertical resolution for smooth blob edges.

Solid Base/Cap

The metallic base and cap are rendered as filled shapes using half-block characters with 3-tone highlight/mid/shadow shading. The base uses a classic hourglass profile. The rocket style uses a sharp pointed nose cone, a serrated three-fin base profile, and an extra horizontal chrome highlight stripe down the center column for polished metal curvature.

Fireplace & Campfire

The Fireplace and Campfire styles reuse the metaball engine but flip gravity: a dense cloud of small "embers" spawns at the bottom and drifts upward. Each ember's temperature decays as a function of its height and its horizontal distance from the center, forming a natural triangular flame shape. The metaball field computation applies asymmetric teardrop shaping (squashed bottom, long tail) and sine-wave "licking" motion for both styles. The base of the fire features a high-fidelity procedural 3D log structure—complete with 3D-shaded bark, concentric rings on log ends, glowing cracks, and a bed of hot ash. A sustained procedural flame core sways and tapers upwards from the logs, providing a solid body of fire. The Campfire style adds a lush pine tree silhouette background with layered conifers, rolling hills, and stars procedurally rendered behind the fire structure.

Bi-color Lava

Each ball carries a palette_id (0 or 1); --bicolor THEME_B assigns palettes round-robin so the two halves stay balanced. At every rendered pixel the engine sums per-palette metaball contributions separately and picks the dominant palette for coloring, so merged blobs blend along a natural boundary. Cross-palette color pairs are allocated lazily on first use via ColorHelper.set_secondary_theme — only the (fg, bg) combos that actually appear on screen consume curses pair slots, which keeps the approach within the 255 pairs curses can address through attributes (the lazy range is recycled if it ever fills). Liquid (Perlin-noise) flow has no per-ball identity, so its bi-color regions are carved out by a smooth time-varying spatial mask (sin(t + px·k + py·k)) that drifts the A/B boundary across the lamp instead — both palettes still appear, just along noise-field contours rather than around individual blobs.

Motion Trails

When T is pressed, each lamp allocates a per-cell trail buffer sized to the body. Every frame, cells that currently hold lava refresh to full trail life; cells that went back to liquid but still have life remaining are redrawn with a progressively dimmer level (lava 3 → 2 → 1 → rim) over ~14 frames before disappearing. Trail decay is funneled through a single _apply_trail helper shared by the body and freestyle render paths, so the two paths cannot drift. The buffer preserves the -1 "outside glass" sentinel end-to-end, so the trail never bleeds liquid color past the glass curve at the body's edge. The trail buffer lives on the Lamp instance, so resize or reset cleanly invalidates it.

Donut

The donut is a port of Andy Sloane's classic donut.c: a torus of inner radius 1 and outer radius 2 is rotated about two axes, perspective-projected, lit by a diagonal Lambertian light, and rasterized into a z-buffer. At initialization, Donut.__init__ pre-computes sin/cos lookup tables for the fixed theta (90 entries) and phi (158 entries) step sizes, replacing ~28,000 math.sin/math.cos calls per frame with fast array lookups. Instead of donut.c's 12-character luminance ramp, each lit surface point picks its palette from the active theme, then the Lambertian intensity selects the shade within that palette. B/V cycles through 5 shade modes (Smooth, Glow, Bold, Dim, Iced). Width and height scale independently so the donut fills wide terminals too — on an 80×24 screen the silhouette diameter spans ~60 columns.

Koi Pond

The koi pond is a separate render path from the lava lamp. Each fish is a 14-segment chain with constraint-based segment physics — the head moves toward a random target with a sinusoidal lateral wobble, and the rest of the body trails behind via distance constraints. Lily pads are scattered with Poisson-ish rejection sampling and pre-rendered into a static background buffer on initialization; the main loop performs a fast row-copy of this buffer before rasterizing fish, eliminating redundant geometry calculations for the static pond elements. The whole scene uses the same half-block buffer rendering as the lava lamp.

License

MIT