Value Interpolation (Lerp)

Smoothly interpolate between two values (numbers, vectors, or tables) to create seamless transitions and animations.

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.

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:

-- 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:

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.

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:

-- 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:

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:

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:

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

Then import as shown:

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

---

Location

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