A simple, efficient spring animation library for smooth, natural motion🎼



Harmonica Image
Latest Release GoDoc Build Status

A simple, efficient spring animation library for smooth, natural motion.

Harmonica OpenGL Demo

It even works well on the command line.

Harmonica TUI Demo


Harmonica is framework-agnostic and works well in 2D and 3D contexts. Simply call NewSpring with your settings to initialize and Update on each frame to animate.

import "github.com/charmbracelet/harmonica"

// A thing we want to animate.
sprite := struct{
    x, xVelocity float64
    y, yVelocity float64

// Where we want to animate it.
const targetX = 50.0
const targetY = 100.0

// Initialize a spring with framerate, angular frequency, and damping values.
spring := harmonica.NewSpring(harmonica.FPS(60), 6.0, 0.5)

// Animate!
for {
    sprite.x, sprite.xVelocity = spring.Update(sprite.x, sprite.xVelocity, targetX)
    sprite.y, sprite.yVelocity = spring.Update(sprite.y, sprite.yVelocity, targetY)

For details, see the examples and the docs.


NewSpring takes three values:

  • Time Delta: the time step to operate on. Game engines typically provide a way to determine the time delta, however if that's not available you can simply set the framerate with the included FPS(int) utility function. Make the framerate you set here matches your actual framerate.
  • Angular Velocity: this translates roughly to the speed. Higher values are faster.
  • Damping Ratio: the springiness of the animation, generally between 0 and 1, though it can go higher. Lower values are springier. For details, see below.

Damping Ratios

The damping ratio affects the motion in one of three different ways depending on how it's set.


A spring is under-damped when its damping ratio is less than 1. An under-damped spring reaches equilibrium the fastest, but overshoots and will continue to oscillate as its amplitude decays over time.

Critical Damping

A spring is critically-damped the damping ratio is exactly 1. A critically damped spring will reach equilibrium as fast as possible without oscillating.


A spring is over-damped the damping ratio is greater than 1. An over-damped spring will never oscillate, but reaches equilibrium at a slower rate than a critically damped spring.


This library is a fairly straightforward port of Ryan Juckett’s excellent damped simple harmonic oscillator originally writen in C++ in 2008 and published in 2012. Ryan’s writeup on the subject is fantastic.



Part of Charm.

The Charm logo

Charm热爱开源 • Charm loves open source

  • Correct usage in README example

    Correct usage in README example

    opened by meowgorithm 1
  • Change waitASec to wait

    Change waitASec to wait

    This is a tiny refactor that doesn't change any functionality.

    While playing around with this library, I saw that waitASec sometimes sleeps for 500ms and 750ms, for me this makes sense to call it wait instead of waitASec and accept a time.Duration instead of an int.

    Not a big deal either way though! Feel free to merge or close this PR.

    Great work on this library! :D

    opened by maaslalani 1
  • Link README image to high-res art

    Link README image to high-res art

    opened by meowgorithm 0
  • Introduce 2D + 3D projectile motion

    Introduce 2D + 3D projectile motion

    This PR introduces 2D and 3D projectile motion to be used with Harmonica. It's fairly simple for now but usable with stuff like https://github.com/maaslalani/confetty

    Example Usage:

    projectile := NewProjectile(FPS(60), Point{6.0, 100.0, 0.0}, Vector{2.0, 0.0, 0.0}, Vector{2.0, -9.81, 0.0})
    someUpdateLoop(func() {
      pos := projectile.Update()

    NOTE, this is still missing:

    1. Projectile mass
    2. Forces (projectile.AddForce(Force{...})...))
    3. Collisions (maybe?)
    opened by maaslalani 0
  • Example with gio based gui

    Example with gio based gui

    Looks like a perfect match for gio.


    gio is a golang gui and from a brief look at your code it looks like a very good match for GIO,

    gio gives the opportunity to update gui elements on each frame tick for example.

    opened by gedw99 0
We build tools to make the command line glamorous
gensvg generates SVG to an io.Writer

gensvg: A Go library for SVG generation The library generates SVG as defined by the Scalable Vector Graphics 1.1 Specification

Anthony Starks 16 Apr 15, 2021
Go Language Library for SVG generation

SVGo: A Go library for SVG generation The library generates SVG as defined by the Scalable Vector Graphics 1.1 Specification (http://www.w3.org/TR/SVG

Anthony Starks 1.7k Sep 26, 2021
Build apps for pixel-based displays.

Pixlet Pixlet is an app runtime and UX toolkit for highly-constrained displays. We use Pixlet to develop applets for Tidbyt, which has a 64x32 RGB LED

Tidbyt 110 Sep 21, 2021
A fast, correct image dithering library in Go.

dither is a library for dithering images in Go. It has many dithering algorithms built-in, and allows you to specify your own. Correctness is a

makeworld 219 Sep 22, 2021
Reproducing images with geometric primitives.

Primitive Pictures Reproducing images with geometric primitives. How it Works A target image is provided as input. The algorithm tries to find the sin

Michael Fogleman 11.5k Sep 17, 2021
A library for playing with colors in go (golang).

go-colorful A library for playing with colors in Go. Supports Go 1.13 onwards. Why? I love games. I make games. I love detail and I get lost in detail

Lucas Beyer 886 Sep 7, 2021
The android-go project provides a platform for writing native Android apps in Go programming language.

android-go The android-go project aims to provide a platform (namely an SDK) for writing native Android apps in Go programming language. All things he

Max Kupriianov 941 Sep 14, 2021
:eyeglasses: Go library for [d]encoding glTF 2.0 files

gltf A Go module for efficient and robust serialization/deserialization of glTF 2.0, a royalty-free specification for the efficient transmission and l

Quim Muntal 118 Sep 24, 2021
Cairo in Go: vector to SVG, PDF, EPS, raster, HTML Canvas, etc.

Canvas is a common vector drawing target that can output SVG, PDF, EPS, raster images (PNG, JPG, GIF, ...), HTML Canvas through WASM, and OpenGL. It h

Taco de Wolff 801 Sep 18, 2021
Imaging is a simple image processing package for Go

Imaging Package imaging provides basic image processing functions (resize, rotate, crop, brightness/contrast adjustments, etc.). All the image process

Grigory Dryapak 3.9k Sep 25, 2021
Real-time Geospatial and Geofencing

Tile38 is an open source (MIT licensed), in-memory geolocation data store, spatial index, and realtime geofence. It supports a variety of object types

Josh Baker 7.7k Sep 15, 2021
S2 geometry library in Go

Overview S2 is a library for spherical geometry that aims to have the same robustness, flexibility, and performance as the best planar geometry librar

Go 1.3k Sep 20, 2021
a tool to output images as RGB ANSI graphics on the terminal

imgcat Tool to output images in the terminal. Built with bubbletea install homebrew brew install trashhalo/homebrew-brews/imgcat prebuilt packages Pr

Stephen Solka 443 Sep 9, 2021
Create a cool glass-like pattern using Voronoi cells

voronoi-glass Have you ever looked through a shower door made of intentionally uneven glass? Everything looks distorted, but maybe also beautiful. Now

Alex Nichol 7 Jun 1, 2021
Direct3D9 wrapper for Go.

d3d9 This library is a pure Go wrapper for Microsoft's Direct3D9 API. Games Here you can see the library in action, it was used for two 48 hour game j

null 127 Sep 5, 2021
Find out where you fall on the Open-Source Character Alignment Chart

gitaligned Find out where you fall on the Open-Source Character Alignment Chart Binaries available in releases. If you prefer to install from source,

Patricio Whittingslow 73 Sep 15, 2021
Efficient moving window for high-speed data processing.

Moving Window Data Structure Copyright (c) 2012. Jake Brukhman. ([email protected]). All rights reserved. See the LICENSE file for BSD-style license. I

Jake Brukhman 31 Jun 30, 2021
Dendrite is a second-generation Matrix homeserver written in Go!

Dendrite Dendrite is a second-generation Matrix homeserver written in Go. It intends to provide an efficient, reliable and scalable alternative to Syn

matrix.org 2.5k Sep 22, 2021
Fast, simple, scalable, Docker-ready HTTP microservice for high-level image processing

imaginary Fast HTTP microservice written in Go for high-level image processing backed by bimg and libvips. imaginary can be used as private or public

Tom 3.8k Sep 17, 2021