Harmonica

The damping ratio determines how the spring behaves as it approaches its target (equilibrium):

• Under-Damping (Ratio < 1): Reaches equilibrium the fastest but overshoots the target and oscillates with decaying amplitude.
• Critical Damping (Ratio == 1): Reaches equilibrium as fast as possible without any oscillation.
• Over-Damping (Ratio > 1): Does not oscillate, but reaches equilibrium more slowly than a critically damped spring.

The dampingRatio parameter in NewSpring determines how the spring behaves as it approaches its target position:

A Spring simulates a damped harmonic oscillator, useful for creating smooth, springy animations. To use it efficiently, you should initialize a Spring once with your desired physics parameters and then call Update on every frame of your animation loop.

Workflow

1. Initialize: Call NewSpring with your deltaTime (the time elapsed between frames), angularFrequency (speed of motion), and dampingRatio (oscillation behavior).
2. Update: In your animation loop, call Update passing the current position, current velocity, and the targetPosition (equilibrium) you want the spring to reach.

// 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)
})

To simulate projectile motion, use NewProjectile to initialize the state with a frame rate (delta time), starting position, initial velocity, and acceleration. On every frame of your simulation loop, call Update() to advance the physics state. Update() returns the new Point position of the projectile.

// Run once to initialize.
projectile := NewProjectile(
    FPS(60), // Note: Ensure your FPS helper matches the float64 deltaTime requirement
    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()
})

The NewSpring function initializes a spring simulation with three primary parameters:

1. Time Delta: The time step for each operation. If your environment doesn't provide a delta time, use the harmonica.FPS(int) utility to set a fixed framerate. Ensure this matches your actual loop frequency.
2. Angular Velocity: Controls the speed of the animation. Higher values result in faster motion.
3. Damping Ratio: Controls the 'springiness' or oscillation of the motion. Generally a value between 0 and 1, but can be higher.

The NewProjectile function initializes a Projectile instance. It requires a float64 representing the time step (delta time) between updates, an initial Point for position, and Vector types for velocity and acceleration.

func NewProjectile(deltaTime float64, initialPosition Point, initialVelocity, initalAcceleration Vector) *Projectile

To simulate projectiles or particles, initialize a simulator with NewProjectile. This requires the frame rate (via FPS), an initial starting Point, an initial velocity Vector, and a gravity Vector. On every frame, call Update() to retrieve the new position of the projectile.

// 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()
})

Initializes a new Spring by computing cached coefficients for efficient updates. This allows you to use the same physics settings across multiple different springs in an update loop.

Parameters:

• deltaTime (float64): The time step to advance (e.g., the length of one animation frame).
• angularFrequency (float64): The angular frequency of motion; higher values increase the speed of the spring.
• dampingRatio (float64): Determines the oscillation behavior (see Damping Ratios).

The FPS(n int) function returns the time delta (in seconds) for a given number of frames per second. This is a convenient way to provide a deltaTime to NewSpring if you are targeting a specific framerate.

Note: If your game engine or animation loop provides a real-time delta (the actual time elapsed since the last frame), use that instead of FPS() for more accurate physics.

You can inspect the current state of a Projectile using the following methods:

• Position(): Returns the current Point coordinates.
• Velocity(): Returns the current Vector velocity.
• Acceleration(): Returns the current Vector acceleration.

func (p *Projectile) Position() Point
func (p *Projectile) Velocity() Vector
func (p *Projectile) Acceleration() Vector

Harmonica uses Point and Vector types to represent 3D coordinates and directions.

• Point: Represents a specific location in 3D space using X, Y, and Z (all float64).
• Vector: Represents a magnitude and direction using X, Y, and Z (all float64).

type Point struct {
	X, Y, Z float64
}

type Vector struct {
	X, Y, Z float64
}