# Value Interpolation (Lerp)

## Overview

Interpolation functions smoothly transition between starting and target values based on a given progress ratio or time duration.

These are crucial for animations, smooth value transitions, and dynamic computations in game logic.

***

## Module Context

The Interpolation module returns a table named `Interpolation` containing two functions for value interpolation:

* `create` – Creates an interpolation iterator.
* `valueAt` – Returns interpolated values at specific progress points.

These functions are **runtime-shared** and available in both client and server contexts.

***

## Create

### **Usage**

Use this function to smoothly animate or transition values over a specific duration, useful for UI animations or smooth game mechanics.

```lua
Interpolation.create(startValue, endValue, duration)
```

#### **Parameters:**

* **startValue:** *`number | table | vector2 | vector3 | vector4`* 
  * Initial value to interpolate from.
* **endValue:** *`number | table | vector2 | vector3 | vector4`* 
  * Target value to interpolate towards.
* **duration:** *`number`*
  * Duration of interpolation in milliseconds.

#### **Returns:**

* **iterator:** *`function`*
  * Iterator function returning the current interpolated value and progress.

### **Examples**

Importing the interpolation module in multiple ways:

```lua
-- Entire module internally from Ambitions
local Interpolation = Import('shared/lib/math/interpolation')

-- Entire module from another script
local Interpolation = Import('@Ambitions.shared.lib.math.interpolation')

-- Specific function only
local create = Import('shared.lib.math.interpolation', 'create')
```

Concrete example demonstrating usage:

```lua
local iterator = Interpolation.create(0, 100, 5000)

while true do
    local currentValue, progress = iterator()
    print("Interpolating value:", currentValue)
    if progress >= 1 then break end
end
```

## Value At

### **Usage**

Use this function to retrieve an interpolated value instantly at a specified progress ratio. Ideal for non-animated or static calculations.

```lua
Interpolation.valueAt(startValue, endValue, progress)
```

#### **Parameters:**

* **startValue:** *`number | table | vector2 | vector3 | vector4`*
  * Initial value
* **endValue:** *`number | table | vector2 | vector3 | vector4`* 
  * Target value
* **progress:** *`number`*
  * Interpolation ratio (between 0 and 1).

#### **Returns:**

* **result:** *`number | table | vector2 | vector3 | vector4`*
  * The interpolated value.

### **Examples**

Importing the interpolation module in multiple ways:

```lua
-- Entire module internally from Ambitions
local Interpolation = Import('shared/lib/math/interpolation')

-- Entire module from another script
local Interpolation = Import('@Ambitions.shared.lib.math.interpolation')

-- Specific function only
local valueAt = Import('shared.lib.math.interpolation', 'valueAt')
```

Concrete example demonstrating direct interpolation:

```lua
local halfWayValue = Interpolation.valueAt(0, 100, 0.5)
print("Value halfway:", halfWayValue) -- Output: 50
```

***

## Import Usage

You can import different modules simultaneously from a script, such as the Interpolation and Round modules:

```lua
local Interpolation, Round = Import({'Interpolation', 'Round'}, '@Ambitions')

local interpolatedValue = Interpolation.valueAt(0, 10, 0.45)
local roundedValue = Round(interpolatedValue, 1)
print("Interpolated and rounded value:", roundedValue)
```

***

## Index Usage

To import specific Module directly via index, ensure the functions are correctly listed in the `shared/index.lua` file:

```lua
return {
    Interpolation = 'shared.lib.math.interpolation',
}
```

Then import as shown:

```lua
local interpolateFunction = Import('Interpolation', '@Ambitions')
```

***

## Location

```tsconfig
shared/lib/math/interpolation.lua
```

***

## Editor Support

This module includes proper Lua annotations (`---@param`, `---@return`), fully compatible with modern editors (e.g., Visual Studio Code with Lua Language Server).

Annotations provide:

* Automatic function and parameter completion
* Inline documentation and type checking
* Enhanced coding efficiency