charmbracelet/harmonica

A simple, physics-based animation library 🎼

Harmonica

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

It even works well on the command line.

Usage

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)
    time.Sleep(time.Second/60)
}

For details, see the examples and the docs.

Settings

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 sure 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.

Under-Damping

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.

Over-Damping

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.

Acknowledgements

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

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• The Fediverse
• Discord

License

MIT

---

Part of Charm.

Charm热爱开源 • Charm loves open source

harmonica's Issues

Example with gio based gui

Looks like a perfect match for gio.

https://github.com/gioui/gio-example

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.

remake a telnet starwars movie with harmonica

`go mod tidy` unable to pull Projectile, Point, Vector etc

To reproduce, create a new go module with the contents of https://github.com/charmbracelet/harmonica/blob/master/examples/physics/main.go, run go mod tidy and run go build

I expected a binary to compile, but instead I received:

; go build                                                                                                                                                                                                             
# iamadrawist
./main.go:34:24: undefined: harmonica.Projectile
./main.go:35:23: undefined: harmonica.Point
./main.go:77:23: undefined: harmonica.Point
./main.go:78:23: undefined: harmonica.Vector
./main.go:79:23: undefined: harmonica.TerminalGravity
./main.go:81:25: undefined: harmonica.NewProjectile

I think this is because the harmonica github project's most recently published tagged version is 0.1, which does not contain these files.

issue running an example

when attempted to run example provided at https://github.com/charmbracelet/harmonica/blob/master/examples/spring/opengl/main.go
returns error as below. wondering if am missing to install any package ?

(base) ➜  temp go run main.go
# pkg-config --cflags  -- gl gl
Package gl was not found in the pkg-config search path.
Perhaps you should add the directory containing `gl.pc'
to the PKG_CONFIG_PATH environment variable
No package 'gl' found
Package gl was not found in the pkg-config search path.
Perhaps you should add the directory containing `gl.pc'
to the PKG_CONFIG_PATH environment variable
No package 'gl' found
pkg-config: exit status 1
# github.com/go-gl/glfw/v3.3/glfw
vendor/github.com/go-gl/glfw/v3.3/glfw/c_glfw.go:4:10: fatal error: glfw/src/context.c: No such file or directory
    4 | #include "glfw/src/context.c"
      |          ^~~~~~~~~~~~~~~~~~~~
compilation terminated.