• Stars
    star
    1,020
  • Rank 45,113 (Top 0.9 %)
  • Language
    Go
  • License
    MIT License
  • Created over 3 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A simple, physics-based animation library 🎼

Harmonica

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

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!

License

MIT


Part of Charm.

The Charm logo

Charmηƒ­ηˆ±εΌ€ζΊ β€’ Charm loves open source

More Repositories

1

bubbletea

A powerful little TUI framework πŸ—
Go
26,561
star
2

gum

A tool for glamorous shell scripts πŸŽ€
Go
17,705
star
3

glow

Render markdown on the CLI, with pizzazz! πŸ’…πŸ»
Go
15,692
star
4

vhs

Your CLI home video recorder πŸ“Ό
Go
14,678
star
5

lipgloss

Style definitions for nice terminal layouts πŸ‘„
Go
7,832
star
6

bubbles

TUI components for Bubble Tea 🫧
Go
5,325
star
7

soft-serve

The mighty, self-hostable Git server for the command line🍦
Go
5,174
star
8

huh

Build terminal forms and prompts πŸ€·πŸ»β€β™€οΈ
Go
3,994
star
9

wish

Make SSH apps, just like that! πŸ’«
Go
3,428
star
10

freeze

Generate images of code and terminal output πŸ“Έ
Go
3,091
star
11

mods

AI on the command line
Go
2,830
star
12

pop

Send emails from your terminal πŸ“¬
Go
2,382
star
13

glamour

Stylesheet-based markdown rendering for your CLI apps πŸ’‡πŸ»β€β™€οΈ
Go
2,369
star
14

charm

The Charm Tool and Library 🌟
Go
2,351
star
15

log

A minimal, colorful Go logging library πŸͺ΅
Go
2,284
star
16

skate

A personal key value store πŸ›Ό
Go
1,326
star
17

wishlist

The SSH directory ✨
Go
1,074
star
18

melt

Backup and restore Ed25519 SSH keys with seed words 🫠
Go
579
star
19

kancli

A tutorial for building a command line kanban board in Go
Go
172
star
20

vhs-action

Keep your GIFs up to date with VHS + GitHub actions πŸ“½οΈ
TypeScript
163
star
21

bubbletea-app-template

A template repository to create Bubbletea apps.
Go
131
star
22

x

Charm experimental packages
Go
125
star
23

keygen

An SSH key pair generator πŸ—οΈ
Go
109
star
24

taskcli

A tutorial for building a Taskwarrior-inspired task tracker in Go using glamorous CLI libraries
Go
97
star
25

inspo

Share and explore projects you can build with Charm libraries
93
star
26

wizard-tutorial

A basic wizard made with Bubble Tea and Lip Gloss. Follow along with the tutorial video for this project:
Go
81
star
27

tree-sitter-vhs

Syntax highlighting for VHS with tree-sitter 🌳
JavaScript
79
star
28

confettysh

confetti over ssh
Go
56
star
29

git-lfs-transfer

Server-side implementation of the Git LFS pure-SSH protocol
Go
50
star
30

catwalk

Open source 3D models from Charm 🧸
50
star
31

soft-serve-action

Synchronize GitHub repositories to your Soft Serve instance 🍦
47
star
32

promwish

Prometheus middleware for Wish
Go
41
star
33

meta

Charm's meta configuration files πŸ«₯
25
star
34

hotdiva2000

A human-readable random string generator πŸ‘‘
Go
25
star
35

homebrew-tap

Our homebrew tap 🍺
Ruby
23
star
36

scoop-bucket

Charmbracelet Scoop Bucket
15
star
37

nur

Nix
14
star
38

.github

Default community health files
2
star