https://github.com/charmbracelet/harmonica

A simple, physics-based animation library 🎼
https://github.com/charmbracelet/harmonica

animation game-development go golang hacktoberfest physics

Last synced: 5 days ago
JSON representation

A simple, physics-based animation library 🎼

• Host: GitHub
• URL: https://github.com/charmbracelet/harmonica
• Owner: charmbracelet
• License: mit
• Created: 2021-07-08T22:08:06.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-08-06T14:30:27.000Z (5 months ago)
• Last Synced: 2024-12-10T06:04:23.168Z (13 days ago)
• Topics: animation, game-development, go, golang, hacktoberfest, physics
• Language: Go
• Homepage:
• Size: 143 KB
• Stars: 1,079
• Watchers: 10
• Forks: 23
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

        
Harmonica

=========



    


    

    

    



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



It even works well on the command line.



[examples]: https://github.com/charmbracelet/harmonica/tree/master/examples

[docs]: https://pkg.go.dev/github.com/charmbracelet/harmonica?tab=doc

## Usage

Harmonica is framework-agnostic and works well in 2D and 3D contexts. Simply

call [`NewSpring`][newspring] with your settings to initialize and

[`Update`][update] on each frame to animate.

```go

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][examples] and the [docs][docs].

[newspring]: https://pkg.go.dev/github.com/charmbracelet/harmonica#NewSpring

[update]: https://pkg.go.dev/github.com/charmbracelet/harmonica#Update

## Settings

[`NewSpring`][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][juckett]’s

excellent damped simple harmonic oscillator originally written in C++ in 2008

and published in 2012. [Ryan’s writeup][writeup] on the subject is fantastic.

[juckett]: https://www.ryanjuckett.com/

[writeup]: https://www.ryanjuckett.com/damped-springs/

## Feedback

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

* [Twitter](https://twitter.com/charmcli)

* [The Fediverse](https://mastodon.social/@charmcli)

* [Discord](https://charm.sh/chat)

## License

[MIT](https://github.com/charmbracelet/harmonica/raw/master/LICENSE)

***

Part of [Charm](https://charm.sh).



Charm热爱开源 • Charm loves open source