### Complete Configuration Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating the configuration of both spring and projectile, and their use in an animation loop.

```ruby
require "harmonica"

# Configure spring for smooth scroll animation
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 5.0,
  damping_ratio: 0.8
)

# Configure projectile for particle effect
particle = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(100, 50, 0),
  velocity: Harmonica::Vector.new(5, 10, 0),
  acceleration: Harmonica::GRAVITY
)

# Use in animation loop
scroll_position = 0.0
scroll_velocity = 0.0
target_scroll = 500.0

loop do
  # Update spring
  scroll_position, scroll_velocity = spring.update(
    scroll_position,
    scroll_velocity,
    target_scroll
  )
  
  # Update particle
  particle_position = particle.update
  
  # Render or process results
  break if scroll_position >= target_scroll && particle_position.y <= 0
end
```

--------------------------------

### Install dependencies

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Install project dependencies using Bundler.

```bash
bundle install
```

--------------------------------

### Initial Position Configuration Examples

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Examples of creating initial position points using Harmonica::Point.new(x, y, z).

```ruby
# Ground level, origin
start = Harmonica::Point.new(0, 0, 0)

# Elevated starting position
elevated = Harmonica::Point.new(50, 100, 0)

# 3D position
in_space = Harmonica::Point.new(10, 20, 30)
```

--------------------------------

### Delta Time Configuration Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Example showing delta time configuration using Harmonica.fps() or manual calculation.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),  # Recommended
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 0, 0),
  acceleration: Harmonica::GRAVITY
)
```

--------------------------------

### Acceleration Configuration Examples

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Examples of creating constant acceleration vectors using Harmonica::Vector.new(x, y, z).

```ruby
# Standard Earth gravity (downward)
gravity = Harmonica::GRAVITY  # => Vector(0, -9.81, 0)

# Terminal gravity (downward in terminal coords)
terminal = Harmonica::TERMINAL_GRAVITY  # => Vector(0, 9.81, 0)

# No acceleration
zero = Harmonica::Vector.new(0, 0, 0)

# Custom multi-directional acceleration
custom = Harmonica::Vector.new(1, -9.81, 0.5)
```

--------------------------------

### Point Constructor Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Demonstrates creating new Point instances with default, explicit, and mixed-type coordinates, including an example for a projectile's starting position.

```ruby
require "harmonica"

# Create point at origin
point1 = Harmonica::Point.new()  # => Point(0.0, 0.0, 0.0)

# Create point with explicit coordinates
point2 = Harmonica::Point.new(10, 20, 30)
# => Point(10.0, 20.0, 30.0)

# Mix integer and float inputs
point3 = Harmonica::Point.new(5, 10.5, 15)
# => Point(5.0, 10.5, 15.0)

# Create point for projectile starting position
start = Harmonica::Point.new(0, 100, 0)
```

--------------------------------

### Initial Velocity Configuration Examples

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Examples of creating initial velocity vectors using Harmonica::Vector.new(x, y, z).

```ruby
# Horizontal movement only
horizontal = Harmonica::Vector.new(10, 0, 0)

# Diagonal launch
diagonal = Harmonica::Vector.new(10, 20, 0)

# 3D velocity
threed = Harmonica::Vector.new(5, 10, 5)

# Stationary
stationary = Harmonica::Vector.new(0, 0, 0)
```

--------------------------------

### Spring Example with Bubbletea

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

An example of using the Spring component within a Bubbletea application model for scroll position management.

```ruby
class ScrollModel
  def initialize
    @scroll_position = 0.0
    @scroll_velocity = 0.0
    @target_scroll = 0.0

    @spring = Harmonica::Spring.new(
      delta_time: Harmonica.fps(60),
      angular_frequency: 5.0,
      damping_ratio: 0.8
    )
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      @target_scroll += 10 if message.to_s == "down"
      @target_scroll -= 10 if message.to_s == "up"
    end

    @scroll_position, @scroll_velocity = @spring.update(
      @scroll_position,
      @scroll_velocity,
      @target_scroll
    )

    [self, nil]
  end
end
```

--------------------------------

### Constructor Examples

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Examples demonstrating how to create new Vector instances with different component values and types.

```ruby
require "harmonica"

# Create zero vector
zero = Harmonica::Vector.new()  # => Vector(0.0, 0.0, 0.0)

# Create velocity vector
velocity = Harmonica::Vector.new(10, 5, 0)
# => Vector(10.0, 5.0, 0.0)

# Create acceleration vector
acceleration = Harmonica::Vector.new(0, -9.81, 0)
# => Vector(0.0, -9.81, 0.0)

# Create from mixed types
mixed = Harmonica::Vector.new(1, 2.5, 3)
# => Vector(1.0, 2.5, 3.0)
```

--------------------------------

### Install Gem

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Add the harmonica gem to your Gemfile or install it directly.

```ruby
gem "harmonica"
```

```bash
gem install harmonica
```

--------------------------------

### + Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Example demonstrating vector addition, including accumulating velocity.

```ruby
v1 = Harmonica::Vector.new(1, 2, 3)
v2 = Harmonica::Vector.new(4, 5, 6)

result = v1 + v2
puts result  # => Vector(5.0, 7.0, 9.0)

# Velocity accumulation
velocity = Harmonica::Vector.new(10, 0, 0)
acceleration_step = Harmonica::Vector.new(0, -0.1635, 0)
velocity = velocity + acceleration_step
```

--------------------------------

### Complete Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Animate a value from 0 to 100 with spring physics.

```ruby
require "harmonica"

spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.3  # bouncy
)

position = 0.0
velocity = 0.0
target = 100.0

60.times do |frame|
  position, velocity = spring.update(position, velocity, target)

  bar_length = (position / 2).to_i
  bar = "#" * bar_length

  puts "\r#{bar.ljust(50)} #{position.round(1)}"
  sleep(1.0 / 60)
end
```

--------------------------------

### Complete Example: Working with Point in a physics simulation

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

An end-to-end example demonstrating the creation, updating, and conversion of a Point object within a simulated physics context.

```ruby
require "harmonica"

# Create initial position
position = Harmonica::Point.new(0, 100, 0)

puts "Initial position: #{position}"

# Update position (simulate movement)
position.x += 10
position.y -= 9.81

puts "Updated position: #{position}"

# Convert to array for processing
coords = position.to_a
puts "Coordinates as array: #{coords.inspect}"
```

--------------------------------

### Point z Coordinate Accessor Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Demonstrates how to get and set the Z coordinate of a Point object.

```ruby
point = Harmonica::Point.new(10, 20, 30)

# Read
puts point.z  # => 30.0

# Write
point.z = 35.5
puts point.z  # => 35.5
```

--------------------------------

### Balanced Spring (Critically-damped)

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Example configuration for a balanced spring with a damping ratio equal to 1.0, providing the fastest settle without oscillation.

```ruby
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 5.0,
  damping_ratio: 1.0  # = 1.0: fastest without oscillation
)
```

--------------------------------

### inspect() Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Example showing the inspectable string representation of a Vector instance.

```ruby
vector = Harmonica::Vector.new(1, 2, 3)

puts vector.inspect  # => "Vector(1.0, 2.0, 3.0)"
```

--------------------------------

### to_a() Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Example showing how to convert a Vector to an array of its components and destructure it.

```ruby
vector = Harmonica::Vector.new(3, 4, 5)

array = vector.to_a
puts array.inspect  # => [3.0, 4.0, 5.0]

# Destructuring
x, y, z = vector.to_a
puts "Vector components: #{x}, #{y}, #{z}"
```

--------------------------------

### Spring Animation Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/spring.md

An example demonstrating how to animate a value from 0 to 100 using spring physics with the Harmonica::Spring class.

```ruby
require "harmonica"

spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.3  # bouncy
)

position = 0.0
velocity = 0.0
target = 100.0

60.times do |frame|
  position, velocity = spring.update(position, velocity, target)
  
  # Visual progress bar
  bar_length = (position / 2).to_i
  bar = "#" * bar_length
  
  puts "\r#{bar.ljust(50)} #{position.round(1)}"
  sleep(1.0 / 60)
end
```

--------------------------------

### Spring Constructor Examples

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/spring.md

Demonstrates how to create new Spring instances with different damping ratios for bouncy, balanced, and smooth animations.

```ruby
require "harmonica"

# Bouncy spring (under-damped)
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.3
)

# Balanced spring (critically-damped)
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 5.0,
  damping_ratio: 1.0
)

# Smooth spring (over-damped)
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 4.0,
  damping_ratio: 1.5
)
```

--------------------------------

### Bouncy Spring (Under-damped)

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Example configuration for a bouncy spring with a damping ratio less than 1.0, suitable for energetic UI elements.

```ruby
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.3  # < 1.0: oscillates before settling
)
```

--------------------------------

### Fast Response Spring

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Example configuration for a spring with a high angular frequency, designed for responsive interactions requiring snappy feedback.

```ruby
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 10.0,
  damping_ratio: 0.7
)
```

--------------------------------

### Smooth Spring (Over-damped)

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Example configuration for a smooth spring with a damping ratio greater than 1.0, resulting in slow, smooth motion without overshoot.

```ruby
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 4.0,
  damping_ratio: 1.5  # > 1.0: slow, smooth approach
)
```

--------------------------------

### Complete Projectile Simulation Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

A full example demonstrating how to simulate projectile motion with gravity using the Harmonica::Projectile class.

```ruby
require "harmonica"

projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 20, 0),
  acceleration: Harmonica::GRAVITY
)

puts "Simulating projectile motion..."

loop do
  position = projectile.update
  velocity = projectile.velocity
  
  printf "t: %.2fs, x: %6.2f, y: %6.2f, vx: %6.2f, vy: %6.2f\n",
    projectile.delta_time * 1.0,  # simplified time tracking
    position.x,
    position.y,
    velocity.x,
    velocity.y
  
  break if position.y <= 0
end

puts "Projectile hit the ground at y=0"
```

--------------------------------

### Point == Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Provides examples of comparing Point objects for equality, including cases with identical and different coordinates, and comparing with non-Point objects.

```ruby
point1 = Harmonica::Point.new(10, 20, 30)
point2 = Harmonica::Point.new(10, 20, 30)
point3 = Harmonica::Point.new(10, 20, 31)

puts point1 == point2  # => true
puts point1 == point3  # => false
puts point1 == "Point"  # => false
```

--------------------------------

### Projectile Motion

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/README.md

Example demonstrating how to simulate projectile motion.

```ruby
require "harmonica"

projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 20, 0),
  acceleration: Harmonica::GRAVITY
)

loop do
  position = projectile.update
  puts "Position: #{position}"
  break if position.y <= 0
end
```

--------------------------------

### Spring Animation

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/README.md

Example demonstrating how to use the Spring class for animation.

```ruby
require "harmonica"

spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.5
)

position = 0.0
velocity = 0.0
target = 100.0

loop do
  position, velocity = spring.update(position, velocity, target)
  break if (position - target).abs < 0.01
end
```

--------------------------------

### == Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Examples illustrating the equality comparison between Vector instances and other types.

```ruby
v1 = Harmonica::Vector.new(1, 2, 3)
v2 = Harmonica::Vector.new(1, 2, 3)
v3 = Harmonica::Vector.new(1, 2, 4)

puts v1 == v2  # => true
puts v1 == v3  # => false
puts v1 == "Vector"  # => false
```

--------------------------------

### to_s() Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Example demonstrating the string representation of a Vector instance using to_s().

```ruby
vector = Harmonica::Vector.new(1.5, 2.25, 3)

puts vector.to_s  # => "Vector(1.5, 2.25, 3.0)"
puts vector       # => Vector(1.5, 2.25, 3.0)
```

--------------------------------

### Custom Delta Time Calculation

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Example of calculating delta_time manually for a custom frame rate (75 FPS) and using it to configure a spring.

```ruby
# 75 FPS
delta = 1.0 / 75  # => 0.0133...

spring = Harmonica::Spring.new(
  delta_time: 1.0 / 75,
  angular_frequency: 6.0,
  damping_ratio: 0.5
)
```

--------------------------------

### Spring Position Position Coefficient Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/spring.md

Example of accessing the read-only `position_position_coefficient` attribute.

```ruby
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.5
)

coeff = spring.position_position_coefficient
# Use for debugging or custom calculations
```

--------------------------------

### Projectile Custom Acceleration - No Gravity

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Example of configuring Projectile with no acceleration, simulating motion in space.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 0, 0),
  velocity: Harmonica::Vector.new(5, 5, 0),
  acceleration: Harmonica::Vector.new(0, 0, 0)
)
```

--------------------------------

### Point to_a() Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Shows how to convert a Point object into an array of its coordinates and how to destructure the array.

```ruby
point = Harmonica::Point.new(10, 20, 30)

array = point.to_a
puts array.inspect  # => [10.0, 20.0, 30.0]

# Destructuring
x, y, z = point.to_a
puts "x=#{x}, y=#{y}, z=#{z}"  # => x=10.0, y=20.0, z=30.0
```

--------------------------------

### Projectile Custom Acceleration - Strong Gravity

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Example of configuring Projectile with strong downward acceleration.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(0, 0, 0),
  acceleration: Harmonica::Vector.new(0, -20, 0)
)
```

--------------------------------

### Projectile Constructor Examples

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Demonstrates creating Projectile instances with different initial conditions, including standard gravity, zero-gravity, and custom acceleration.

```ruby
require "harmonica"

# Projectile with standard gravity
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 20, 0),
  acceleration: Harmonica::GRAVITY
)

# Projectile in zero-gravity (space)
projectile_space = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 0, 0),
  velocity: Harmonica::Vector.new(5, 5, 5),
  acceleration: Harmonica::Vector.new(0, 0, 0)
)

# Projectile with custom acceleration
projectile_custom = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 50, 0),
  velocity: Harmonica::Vector.new(1, 1, 0),
  acceleration: Harmonica::Vector.new(0, -20, 0)  # Strong gravity
)
```

--------------------------------

### Instance Property 'x' Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Demonstrates reading and writing the 'x' component of a Vector instance.

```ruby
vector = Harmonica::Vector.new(3, 4, 0)

# Read
puts vector.x  # => 3.0

# Write
vector.x = 5
puts vector.x  # => 5.0
```

--------------------------------

### Complete Vector Example in Physics Simulation

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

An example demonstrating the use of Vector in a simple physics simulation, including applying gravity and scaling velocity.

```ruby
require "harmonica"

# Create velocity and acceleration vectors
velocity = Harmonica::Vector.new(10, 0, 0)
gravity = Harmonica::GRAVITY  # => Vector(0, -9.81, 0)

puts "Initial velocity: #{velocity}"
puts "Gravity: #{gravity}"

# Apply gravity to velocity (one frame at 60 FPS)
delta = Harmonica.fps(60)
gravity_step = gravity * delta
velocity = velocity + gravity_step

puts "Velocity after gravity: #{velocity}"
puts "Speed: #{velocity.magnitude.round(4)}"

# Normalize velocity to get direction
direction = velocity.normalize
puts "Direction: #{direction}"

# Scale velocity to new magnitude
new_velocity = direction * 15  # New speed of 15 units/second
puts "Scaled velocity: #{new_velocity}"
```

--------------------------------

### Projectile Acceleration Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Demonstrates how to create a Projectile and access its acceleration attribute.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(0, 0, 0),
  acceleration: Harmonica::GRAVITY
)

puts projectile.acceleration  # => Vector(0, -9.81, 0)
```

--------------------------------

### Vector Arithmetic

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/README.md

Example demonstrating vector arithmetic operations.

```ruby
require "harmonica"

v1 = Harmonica::Vector.new(3, 4, 0)
v2 = Harmonica::Vector.new(1, 2, 0)

# Addition
sum = v1 + v2           # => Vector(4, 6, 0)

# Subtraction
diff = v1 - v2          # => Vector(2, 2, 0)

# Scalar multiplication
scaled = v1 * 2         # => Vector(6, 8, 0)

# Magnitude (length)
magnitude = v1.magnitude  # => 5.0

# Normalize to unit vector
unit = v1.normalize     # => Vector(0.6, 0.8, 0.0)
```

--------------------------------

### Magnitude Calculation Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Shows how to calculate the magnitude (length) of a vector.

```ruby
# 3-4-5 right triangle
vector = Harmonica::Vector.new(3, 4, 0)
puts vector.magnitude  # => 5.0

# Unit vector
unit = Harmonica::Vector.new(1, 1, 1)
puts unit.magnitude    # => 1.732... (sqrt(3))

# Zero vector
zero = Harmonica::Vector.new(0, 0, 0)
puts zero.magnitude    # => 0.0

# Velocity magnitude (speed)
velocity = Harmonica::Vector.new(3, 4, 0)
speed = velocity.magnitude
puts speed  # => 5.0
```

--------------------------------

### Projectile Position Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Demonstrates how to create a Projectile and access its position after an update.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(5, 0, 0),
  acceleration: Harmonica::GRAVITY
)

projectile.update
puts projectile.position.x  # => 0.08333...
puts projectile.position.y  # => ~100
```

--------------------------------

### Point to_s() Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Demonstrates the string representation of a Point object using the `to_s` method and direct output.

```ruby
point = Harmonica::Point.new(10.5, 20.25, 30)

puts point.to_s  # => "Point(10.5, 20.25, 30.0)"
puts point       # => Point(10.5, 20.25, 30.0)
```

--------------------------------

### Spring Update Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/spring.md

Shows how to use the `update` method to animate a position and velocity towards an equilibrium position over multiple frames.

```ruby
require "harmonica"

spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.5
)

position = 0.0
velocity = 0.0
target = 100.0

# Animate over frames
loop do
  position, velocity = spring.update(position, velocity, target)
  
  puts "Position: #{position.round(2)}, Velocity: #{velocity.round(2)}"
  
  # Stop when close enough to target
  break if (position - target).abs < 0.01
end
```

--------------------------------

### Instance Property 'z' Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Demonstrates reading and writing the 'z' component of a Vector instance.

```ruby
vector = Harmonica::Vector.new(3, 4, 5)

# Read
puts vector.z  # => 5.0

# Write
vector.z = 7
puts vector.z  # => 7.0
```

--------------------------------

### Vector Subtraction Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Demonstrates subtracting one vector from another component-wise.

```ruby
v1 = Harmonica::Vector.new(5, 7, 9)
v2 = Harmonica::Vector.new(1, 2, 3)

result = v1 - v2
puts result  # => Vector(4.0, 5.0, 6.0)

# Velocity difference
v1 = Harmonica::Vector.new(10, 0, 0)
v2 = Harmonica::Vector.new(5, 0, 0)
difference = v1 - v2
# => Vector(5.0, 0.0, 0.0)
```

--------------------------------

### Instance Property 'y' Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Demonstrates reading and writing the 'y' component of a Vector instance.

```ruby
vector = Harmonica::Vector.new(3, 4, 0)

# Read
puts vector.y  # => 4.0

# Write
vector.y = 6
puts vector.y  # => 6.0
```

--------------------------------

### Point Creation and Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/types.md

Example of creating a Point object, accessing its coordinates, modifying them, and converting to an array.

```ruby
require "harmonica"

# Create a point
point = Harmonica::Point.new(10.0, 20.0, 30.0)

# Access coordinates
x = point.x  # => 10.0
y = point.y  # => 20.0
z = point.z  # => 30.0

# Modify coordinates
point.x = 15.0
point.y = 25.0

# Convert to array
coords = point.to_a  # => [15.0, 25.0, 30.0]
```

--------------------------------

### Projectile Delta Time Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Demonstrates how to create a Projectile and access its delta_time attribute.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(0, 0, 0),
  acceleration: Harmonica::GRAVITY
)

puts projectile.delta_time  # => 0.01666...
```

--------------------------------

### Spring Creation and Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/types.md

Example of creating a Spring instance and using it in an animation loop to update position and velocity towards a target.

```ruby
require "harmonica"

# Create spring
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.5
)

# Use in animation loop
position = 0.0
velocity = 0.0
target = 100.0

loop do
  position, velocity = spring.update(position, velocity, target)
  break if (position - target).abs < 0.01
end
```

--------------------------------

### Projectile Reset Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Demonstrates resetting a projectile's position and velocity to a new state while maintaining its acceleration.

```ruby
require "harmonica"

projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(5, 0, 0),
  acceleration: Harmonica::GRAVITY
)

# Simulate several frames
5.times { projectile.update }

# Reset to a new state without changing acceleration
projectile.reset(
  position: Harmonica::Point.new(50, 50, 0),
  velocity: Harmonica::Vector.new(10, 10, 0)
)

# Continue simulation from new state
5.times { projectile.update }
```

--------------------------------

### Vector Normalization Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Demonstrates normalizing a vector to a unit vector (magnitude 1.0).

```ruby
# Normalize a velocity vector
velocity = Harmonica::Vector.new(3, 4, 0)
normalized = velocity.normalize
puts normalized  # => Vector(0.6, 0.8, 0.0)
puts normalized.magnitude  # => 1.0

# Normalize an arbitrary vector
vector = Harmonica::Vector.new(1, 1, 1)
unit = vector.normalize
puts unit  # => Vector(0.577..., 0.577..., 0.577...)

# Handle zero vector
zero = Harmonica::Vector.new(0, 0, 0)
result = zero.normalize
puts result  # => Vector(0.0, 0.0, 0.0)

# Use normalized velocity for direction
velocity = Harmonica::Vector.new(10, 5, 0)
direction = velocity.normalize
speed = velocity.magnitude
# direction is the unit direction, speed is the magnitude
```

--------------------------------

### Harmonica.fps() Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/harmonica-module.md

Calculate the time delta value for a given frame rate. Used when initializing Spring or Projectile instances to ensure consistent timing across different frame rates.

```ruby
require "harmonica"

# Calculate delta time for 60 FPS
delta = Harmonica.fps(60)  # => 0.016666...

# Calculate delta time for 30 FPS  
delta = Harmonica.fps(30)  # => 0.033333...

# Calculate delta time for 120 FPS
delta = Harmonica.fps(120) # => 0.008333...

# Use in Spring initialization
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.5
)
```

--------------------------------

### Scalar Multiplication Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/vector.md

Illustrates multiplying a vector by a scalar (integer or float).

```ruby
vector = Harmonica::Vector.new(2, 3, 4)

result = vector * 2
puts result  # => Vector(4.0, 6.0, 8.0)

result = vector * 0.5
puts result  # => Vector(1.0, 1.5, 2.0)

# Scale velocity
velocity = Harmonica::Vector.new(10, 20, 0)
scaled = velocity * 0.5  # Half speed
# => Vector(5.0, 10.0, 0.0)
```

--------------------------------

### Point y Coordinate Accessor Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Illustrates reading and modifying the Y coordinate of a Point instance.

```ruby
point = Harmonica::Point.new(10, 20, 30)

# Read
puts point.y  # => 20.0

# Write
point.y = 25.5
puts point.y  # => 25.5
```

--------------------------------

### Projectile Creation and Usage Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/types.md

Demonstrates how to create a new Harmonica::Projectile instance and simulate its motion over time until it hits the ground (y <= 0).

```ruby
require "harmonica"

# Create projectile
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 20, 0),
  acceleration: Harmonica::GRAVITY
)

# Simulate
loop do
  position = projectile.update
  puts "Position: #{position}"
  break if position.y <= 0
end
```

--------------------------------

### Point inspect() Method Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Shows the inspectable string representation of a Point object, which is identical to `to_s`, and its use in interactive shells.

```ruby
point = Harmonica::Point.new(10, 20, 30)

puts point.inspect  # => "Point(10.0, 20.0, 30.0)"

# In IRB or pry, inspect is used for output
[point1, point2, point3]
# => [Point(10.0, 20.0, 30.0), Point(5.0, 10.0, 15.0), Point(0.0, 0.0, 0.0)]
```

--------------------------------

### Projectile Velocity Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Demonstrates how to create a Projectile and access its velocity after an update, showing the effect of gravity.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 0, 0),
  acceleration: Harmonica::GRAVITY
)

projectile.update
velocity = projectile.velocity
puts velocity.x  # => 10.0 (unchanged)
puts velocity.y  # => -0.1635 (affected by gravity)
```

--------------------------------

### Projectile Update Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/projectile.md

Simulates projectile motion over time using the `update` method until the projectile hits the ground.

```ruby
require "harmonica"

projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 0, 0),
  acceleration: Harmonica::GRAVITY
)

# Simulate projectile motion until it hits the ground
loop do
  position = projectile.update
  
  puts "Position: x=#{position.x.round(2)}, y=#{position.y.round(2)}"
  
  # Stop when projectile reaches or passes ground level
  break if position.y <= 0
end
```

--------------------------------

### Point x Coordinate Accessor Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Shows how to read and write the X coordinate of a Point object using the `attr_accessor`.

```ruby
point = Harmonica::Point.new(10, 20, 30)

# Read
puts point.x  # => 10.0

# Write
point.x = 15.5
puts point.x  # => 15.5
```

--------------------------------

### Vector Creation and Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/types.md

Example of creating a Vector object, accessing its components, performing arithmetic operations, calculating magnitude, normalizing, and converting to an array.

```ruby
require "harmonica"

# Create a vector
vector = Harmonica::Vector.new(3.0, 4.0, 0.0)

# Access components
x = vector.x  # => 3.0
y = vector.y  # => 4.0
z = vector.z  # => 0.0

# Modify components
vector.x = 5.0

# Arithmetic operations
v1 = Harmonica::Vector.new(1, 2, 3)
v2 = Harmonica::Vector.new(4, 5, 6)
sum = v1 + v2         # => Vector(5.0, 7.0, 9.0)
diff = v1 - v2        # => Vector(-3.0, -3.0, -3.0)
scaled = v1 * 2       # => Vector(2.0, 4.0, 6.0)

# Calculate magnitude
magnitude = v1.magnitude  # => 3.741...

# Normalize to unit vector
unit = v1.normalize  # => Vector(0.267..., 0.534..., 0.801...)

# Convert to array
components = vector.to_a  # => [5.0, 4.0, 0.0]
```

--------------------------------

### Numeric Constraints Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/types.md

Illustrates that although Integer inputs are accepted for convenience in constructors, they are internally converted to Float types for calculations.

```ruby
point = Harmonica::Point.new(1, 2, 3)
puts point.x.class  # => Float (converted from Integer)
```

--------------------------------

### GRAVITY Constant Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/harmonica-module.md

A predefined gravity vector constant with origin at bottom-left and Y pointing upward. Standard Earth gravity acceleration (9.81 m/s²) pointing downward. Use this constant when simulating projectile motion with standard downward gravity.

```ruby
require "harmonica"

projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 0, 0),
  acceleration: Harmonica::GRAVITY  # Standard downward gravity
)
```

--------------------------------

### TERMINAL_GRAVITY Constant Example

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/harmonica-module.md

An alternative gravity vector with origin at top-left and Y pointing downward. Inverted gravity vector (9.81 m/s² downward) for coordinate systems where the origin is at the top-left and Y increases downward. Use this when implementing terminal-based UI animations or coordinate systems with inverted Y-axis.

```ruby
require "harmonica"

# For terminal UI with Y-axis pointing downward
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 0, 0),
  velocity: Harmonica::Vector.new(5, 5, 0),
  acceleration: Harmonica::TERMINAL_GRAVITY  # Inverted gravity for terminal coords
)
```

--------------------------------

### Run demos

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Run available demo applications.

```bash
./demo/spring
```

```bash
./demo/damping
```

--------------------------------

### Required Configuration - No Defaults

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Illustrates that all motion parameters must be explicitly provided to constructors as Harmonica has no global defaults or configuration files.

```ruby
# This is REQUIRED - no defaults
spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),
  angular_frequency: 6.0,
  damping_ratio: 0.5
)

# This is REQUIRED - no defaults
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 0, 0),
  velocity: Harmonica::Vector.new(0, 0, 0),
  acceleration: Harmonica::GRAVITY
)
```

--------------------------------

### Run tests

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Execute the project's test suite.

```bash
bundle exec rake test
```

--------------------------------

### Delta Time Calculation using Harmonica.fps()

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Demonstrates how to use the Harmonica.fps() helper function to calculate delta_time for common frame rates.

```ruby
# Common frame rates
Harmonica.fps(24)   # => 0.0416... (film)
Harmonica.fps(30)   # => 0.0333... (video)
Harmonica.fps(60)   # => 0.0166... (standard display)
Harmonica.fps(120)  # => 0.0083... (high-refresh displays)
Harmonica.fps(144)  # => 0.0069... (gaming)
Harmonica.fps(240)  # => 0.0041... (ultra high-refresh)
```

--------------------------------

### Spring Basic Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Demonstrates the basic usage of the Spring component for smooth UI animations.

```ruby
require "harmonica"

spring = Harmonica::Spring.new(
  delta_time: Harmonica.fps(60),   # 60 FPS
  angular_frequency: 6.0,          # Speed of motion
  damping_ratio: 0.5               # Smoothness
)

position = 0.0
velocity = 0.0
target = 100.0

loop do
  position, velocity = spring.update(position, velocity, target)

  break if (position - target).abs < 0.01
end
```

--------------------------------

### Spring Constructor Parameters

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Defines the constructor parameters for the Harmonica::Spring class, controlling motion behavior.

```ruby
Harmonica::Spring.new(
  delta_time: Float,
  angular_frequency: Float,
  damping_ratio: Float
)
```

--------------------------------

### Point Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Demonstrates how to create and access properties of a Point object.

```ruby
point = Harmonica::Point.new(10.0, 20.0, 30.0)

point.x  # => 10.0
point.y  # => 20.0
point.z  # => 30.0

point.to_a  # => [10.0, 20.0, 30.0]
```

--------------------------------

### Projectile Basic Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Demonstrates the basic usage of the Projectile component for simulating physics motion.

```ruby
require "harmonica"

projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 20, 0),
  acceleration: Harmonica::GRAVITY
)

loop do
  position = projectile.update

  puts "Position: #{position.x}, #{position.y}"
  break if position.y <= 0
end
```

--------------------------------

### Projectile Constructor Parameters

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Defines the constructor parameters for the Harmonica::Projectile class, used for physics simulation.

```ruby
Harmonica::Projectile.new(
  delta_time: Float,
  position: Point,
  velocity: Vector,
  acceleration: Vector
)
```

--------------------------------

### Zero Gravity (Space) Projectile

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Configures a projectile for use in space or for objects moving without external forces.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 0, 0),
  velocity: Harmonica::Vector.new(5, 5, 5),
  acceleration: Harmonica::Vector.new(0, 0, 0)
)
```

--------------------------------

### Strong Gravity Projectile

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Configures a projectile to simulate heavier gravity or faster falling motion.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(0, 0, 0),
  acceleration: Harmonica::Vector.new(0, -20, 0)  # 2x normal gravity
)
```

--------------------------------

### Frame Rate Helper

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Shows how to use Harmonica.fps to calculate the time delta for a given frame rate.

```ruby
Harmonica.fps(60)   # => 0.01666... (1/60 second)
Harmonica.fps(30)   # => 0.03333... (1/30 second)
Harmonica.fps(120)  # => 0.00833... (1/120 second)
```

--------------------------------

### Standard Gravity Projectile

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Configures a projectile with standard Earth gravity, with the origin at the bottom-left and Y pointing upwards.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(10, 0, 0),
  acceleration: Harmonica::GRAVITY
)
```

--------------------------------

### Vector Usage

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/README.md

Demonstrates the creation and common operations for Vector objects.

```ruby
vector = Harmonica::Vector.new(3.0, 4.0, 0.0)

vector.magnitude   # => 5.0
vector.normalize   # => Vector(0.6, 0.8, 0.0)

v1 = Harmonica::Vector.new(1, 2, 3)
v2 = Harmonica::Vector.new(4, 5, 6)

v1 + v2   # => Vector(5, 7, 9)
v1 - v2   # => Vector(-3, -3, -3)
v1 * 2    # => Vector(2, 4, 6)
```

--------------------------------

### Spring Class

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/README.md

Creates a spring with precomputed motion coefficients and updates position/velocity towards equilibrium each frame.

```ruby
Spring.new(
  delta_time: Float,
  angular_frequency: Float,
  damping_ratio: Float
) -> Spring

spring.update(position, velocity, equilibrium_position) -> [Float, Float]
```

--------------------------------

### Terminal Coordinate System Projectile

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Configures a projectile for terminal UI systems where the origin is top-left and Y increases downwards.

```ruby
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 0, 0),
  velocity: Harmonica::Vector.new(5, 5, 0),
  acceleration: Harmonica::TERMINAL_GRAVITY
)
```

--------------------------------

### Horizontal Wind Force Projectile

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/configuration.md

Configures a projectile to be affected by wind or other directional forces.

```ruby
wind = Harmonica::Vector.new(5, 0, 0)  # Constant wind to the right
projectile = Harmonica::Projectile.new(
  delta_time: Harmonica.fps(60),
  position: Harmonica::Point.new(0, 100, 0),
  velocity: Harmonica::Vector.new(0, 0, 0),
  acceleration: Harmonica::GRAVITY + wind
)
```

--------------------------------

### Compare points

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/api-reference/point.md

Compares the current position with a checkpoint.

```ruby
checkpoint = Harmonica::Point.new(10, 90.19, 0)
if position == checkpoint
  puts "Reached checkpoint!"
else
  puts "Not at checkpoint yet"
end
```

--------------------------------

### Harmonica FPS Calculation

Source: https://github.com/marcoroth/harmonica-ruby/blob/main/_autodocs/README.md

Calculates the delta time (time step) for each frame based on a given frames per second (FPS) rate.

```ruby
Harmonica.fps(60) # → 0.0166...
Harmonica.fps(30) # → 0.0333...
```