Documentation ¶
Overview ¶
Package harmonica is a set of physics-based animation tools for 2D and 3D applications. There's a spring animation simulator for for smooth, realistic motion and a projectile simulator well suited for projectiles and particles.
Example spring usage:
// Run once to initialize. spring := NewSpring(FPS(60), 6.0, 0.2) // Update on every frame. pos := 0.0 velocity := 0.0 targetPos := 100.0 someUpdateLoop(func() { pos, velocity = spring.Update(pos, velocity, targetPos) })
Example projectile usage:
// Run once to initialize. 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}, ) // Update on every frame. someUpdateLoop(func() { pos := projectile.Update() })
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Gravity = Vector{0, -9.81, 0}
Gravity is a utility vector that represents gravity in 2D and 3D contexts, assuming that your coordinate plane looks like in 2D or 3D:
y y ±z │ │ / │ │/ └───── ±x └───── ±x
(i.e. origin is located in the bottom-left corner)
var TerminalGravity = Vector{0, 9.81, 0}
TerminalGravity is a utility vector that represents gravity where the coordinate plane's origin is on the top-right corner
Functions ¶
func FPS ¶
FPS returns a time delta for a given number of frames per second. This value can be used as the time delta when initializing a Spring. Note that game engines often provide the time delta as well, which you should use instead of this function, if possible.
Example:
spring := NewSpring(FPS(60), 5.0, 0.2)
Types ¶
type Point ¶ added in v0.2.0
type Point struct {
X, Y, Z float64
}
Point represents a point containing the X, Y, Z coordinates of the point on a plane.
type Projectile ¶ added in v0.2.0
type Projectile struct {
// contains filtered or unexported fields
}
Projectile is the representation of a projectile that has a position on a plane, an acceleration, and velocity.
func NewProjectile ¶ added in v0.2.0
func NewProjectile(deltaTime float64, initialPosition Point, initialVelocity, initalAcceleration Vector) *Projectile
NewProjectile creates a new projectile. It accepts a frame rate and initial values for position, velocity, and acceleration. It returns a new projectile.
func (*Projectile) Acceleration ¶ added in v0.2.0
func (p *Projectile) Acceleration() Vector
Acceleration returns the acceleration of the projectile.
func (*Projectile) Position ¶ added in v0.2.0
func (p *Projectile) Position() Point
Position returns the position of the projectile.
func (*Projectile) Update ¶ added in v0.2.0
func (p *Projectile) Update() Point
Update updates the position and velocity values for the given projectile. Call this after calling NewProjectile to update values.
func (*Projectile) Velocity ¶ added in v0.2.0
func (p *Projectile) Velocity() Vector
Velocity returns the velocity of the projectile.
type Spring ¶
type Spring struct {
// contains filtered or unexported fields
}
Spring contains a cached set of motion parameters that can be used to efficiently update multiple springs using the same time step, angular frequency and damping ratio.
To use a Spring call New with the time delta (that's animation frame length), frequency, and damping parameters, cache the result, then call Update to update position and velocity values for each spring that neeeds updating.
Example:
// First precompute spring coefficients based on your settings: var x, xVel, y, yVel float64 deltaTime := FPS(60) s := NewSpring(deltaTime, 5.0, 0.2) // Then, in your update loop: x, xVel = s.Update(x, xVel, 10) // update the X position y, yVel = s.Update(y, yVel, 20) // update the Y position
func NewSpring ¶
NewSpring initializes a new Spring, computing the parameters needed to simulate a damped spring over a given period of time.
The delta time is the time step to advance; essentially the framerate.
The angular frequency is the angular frequency of motion, which affects the speed.
The damping ratio is the damping ratio of motion, which determines the oscillation, or lack thereof. There are three categories of damping ratios:
Damping ratio > 1: over-damped. Damping ratio = 1: critlcally-damped. Damping ratio < 1: under-damped.
An over-damped spring will never oscillate, but reaches equilibrium at a slower rate than a critically damped spring.
A critically damped spring will reach equilibrium as fast as possible without oscillating.
An under-damped spring will reach equilibrium the fastest, but also overshoots it and continues to oscillate as its amplitude decays over time.
type Vector ¶ added in v0.2.0
type Vector struct {
X, Y, Z float64
}
Vector represents a vector carrying a magnitude and a direction. We represent the vector as a point from the origin (0, 0) where the magnitude is the euclidean distance from the origin and the direction is the direction to the point from the origin.