Animations with Harmonica

Harmonica is a port of charmbracelet/harmonica, a spring-physics library that produces natural-feeling animations. Instead of linear tweens, it simulates a damped spring that overshoots and settles, giving motion a physical weight. The Java package is com.williamcallahan.tui4j.compat.harmonica.

How it works

A Spring computes new position and velocity values each frame from the current state and a target equilibrium. Call update() once per frame and write the resulting position to your view:

frame N   →  spring.update(pos, vel, target)  →  [newPos, newVel]
frame N+1 →  spring.update(newPos, newVel, target) → ...

The spring converges on target at a rate determined by three parameters: FPS, frequency, and damping.

Creating a spring

import com.williamcallahan.tui4j.compat.harmonica.Spring;

// 60 fps, angular frequency 7.5, damping ratio 0.15 (under-damped = bouncy)
Spring spring = Spring.newSpring(Spring.fps(60), 7.5, 0.15);

Spring.newSpring(double deltaTime, double angularFrequency, double dampingRatio)

Parameter	Description
`deltaTime`	Time step in seconds per frame. Use `Spring.fps(n)` to compute `1.0 / n`.
`angularFrequency`	How fast the spring oscillates. Higher values = snappier motion.
`dampingRatio`	Controls overshoot. `< 1.0` = under-damped (bouncy), `= 1.0` = critically damped (no overshoot), `> 1.0` = over-damped (sluggish).

Advancing the simulation

Call update(pos, vel, equilibriumPos) once per animation frame:

double[] result = spring.update(currentX, xVelocity, targetX);
double newX        = result[0];
double newVelocity = result[1];

The method returns a two-element double[] array: [newPosition, newVelocity]. Store both values and feed them back into the next update() call.

Complete example: animated ellipse following the mouse

The cell-buffer example uses two independent springs — one for the X axis and one for the Y axis — to smoothly chase the mouse cursor:

import com.williamcallahan.tui4j.compat.bubbletea.*;
import com.williamcallahan.tui4j.compat.harmonica.Spring;
import java.time.Duration;

public class AnimatedEllipseModel implements Model {

    private static final double FPS       = 60.0;
    private static final double FREQUENCY = 7.5;
    private static final double DAMPING   = 0.15;

    private final Spring spring;
    private double targetX, targetY;
    private double x, y;
    private double xVelocity, yVelocity;

    public AnimatedEllipseModel() {
        // One spring instance, used for both axes
        this.spring = Spring.newSpring(Spring.fps((int) FPS), FREQUENCY, DAMPING);
    }

    @Override
    public Command init() {
        // Schedule the first frame tick
        return Command.tick(
            Duration.ofNanos((long) (1_000_000_000.0 / FPS)),
            time -> new FrameMessage()
        );
    }

    @Override
    public UpdateResult<? extends Model> update(Message msg) {
        if (msg instanceof MouseMessage mouse) {
            // Move the target to wherever the cursor is
            targetX = mouse.column();
            targetY = mouse.row();
            return UpdateResult.from(this);
        }

        if (msg instanceof FrameMessage) {
            // Advance the spring one step on each axis
            double[] xResult = spring.update(x, xVelocity, targetX);
            x         = xResult[0];
            xVelocity = xResult[1];

            double[] yResult = spring.update(y, yVelocity, targetY);
            y         = yResult[0];
            yVelocity = yResult[1];

            // Schedule the next frame
            return UpdateResult.from(this, Command.tick(
                Duration.ofNanos((long) (1_000_000_000.0 / FPS)),
                time -> new FrameMessage()
            ));
        }

        if (msg instanceof KeyPressMessage key) {
            if ("q".equals(key.key()) || "ctrl+c".equals(key.key())) {
                return UpdateResult.from(this, QuitMessage::new);
            }
        }

        return UpdateResult.from(this);
    }

    @Override
    public String view() {
        // Use x and y to position whatever you're animating
        return "Position: (%.1f, %.1f)".formatted(x, y);
    }

    public static void main(String[] args) {
        new Program(new AnimatedEllipseModel())
                .withAltScreen()
                .withMouseCellMotion()
                .run();
    }

    private record FrameMessage() implements Message {}
}

Animating a progress bar

Use a single spring to animate a bar toward a target width:

private static final double FPS       = 30.0;
private static final double FREQUENCY = 5.0;
private static final double DAMPING   = 0.8;   // near-critical: settles fast, minimal bounce

private final Spring spring = Spring.newSpring(Spring.fps((int) FPS), FREQUENCY, DAMPING);
private double barPos      = 0.0;
private double barVelocity = 0.0;
private double barTarget   = 60.0;   // target width in columns

// In update(), on each FrameMessage:
double[] result = spring.update(barPos, barVelocity, barTarget);
barPos      = result[0];
barVelocity = result[1];

// In view():
int filled = (int) Math.round(barPos);
String bar = "=".repeat(Math.max(0, filled))
           + " ".repeat(Math.max(0, 80 - filled));
return "[" + bar + "]";

Tuning the parameters

Goal	Damping	Frequency
Fast snap with no bounce	`0.9–1.0`	`10–15`
Playful bounce	`0.1–0.3`	`5–8`
Slow, smooth drift	`0.5–0.7`	`2–4`
Instant (spring disabled)	any	`0`

When angularFrequency is zero, newSpring returns a no-op spring that always returns the current position unchanged — useful for disabling animation without changing your update logic.

Harmonica springs are stateless value objects. The state (position and velocity) lives in your model, not in the Spring instance. You can safely share a single Spring across multiple animated values as long as each value has its own position and velocity fields.

Projectile motion

Projectile simulates ballistic motion under acceleration. It is useful for effects like particles or bouncing elements:

import com.williamcallahan.tui4j.compat.harmonica.*;

// Launch upward at 10 units/s under terminal gravity (y increases downward)
Projectile p = Projectile.newProjectile(
    Spring.fps(60),
    new Point(40, 0, 0),                    // start position
    new Vector(0, -10, 0),                  // initial velocity (upward)
    Projectile.TERMINAL_GRAVITY             // acceleration (0, 9.81, 0)
);

// In update(), each frame:
Point position = p.update();
// position.x(), position.y(), position.z() give the current coordinates

Mouse input

Combine mouse tracking with spring animation

External commands

Launch editors and shells from your TUI

Get Started

Core Concepts

Components

Guides

Compatibility

Animations with Harmonica

How it works

Creating a spring

Advancing the simulation

Complete example: animated ellipse following the mouse

Animating a progress bar

Tuning the parameters

Projectile motion

Mouse input

External commands

​How it works

​Creating a spring

​Advancing the simulation

​Complete example: animated ellipse following the mouse

​Animating a progress bar

​Tuning the parameters

​Projectile motion

Mouse input

External commands

How it works

Creating a spring

Advancing the simulation

Complete example: animated ellipse following the mouse

Animating a progress bar

Tuning the parameters

Projectile motion