Skip to content

SimpleCurve

A two-dimensional curve made up of some number of CurveKey instances specifying the value of the curve at various points in time. Values between those key points are interpolated based on properties of the curve and the curve keys.

Constructors

Constructor Name Return Type Description Tags
SimpleCurve.New(Array<CurveKey> keys, [table optionalParameters]) SimpleCurve Constructs a SimpleCurve with a set of curve keys. An optional table may be provided to override the following parameters:
preExtrapolation (CurveExtrapolation): Sets the preExtrapolation property of the curve. Defaults to CurveExtrapolation.CYCLE.
postExtrapolation (CurveExtrapolation): Sets the postExtrapolation property of the curve. Defaults to CurveExtrapolation.CYCLE.
defaultValue (number): Sets the defaultValue property of the curve. Defaults to 0.
None
SimpleCurve.New(SimpleCurve other) SimpleCurve Makes a copy of the given SimpleCurve. None

Properties

Property Name Return Type Description Tags
preExtrapolation CurveExtrapolation The extrapolation mode for values before the first curve key. Read-Write
postExtrapolation CurveExtrapolation The extrapolation mode for values after the last curve key. Read-Write
defaultValue number The default value for this curve if no keys are available. Read-Write
minTime number Returns the smallest time from the curve's key points. Returns 0 if the curve contains no keys. Read-Only
maxTime number Returns the largest time from the curve's key points. Returns 0 if the curve contains no keys. Read-Only
minValue number Returns the smallest value from the curve's key points. Returns 0 if the curve contains no keys. Read-Only
maxValue number Returns the largest value from the curve's key points. Returns 0 if the curve contains no keys. Read-Only

Functions

Function Name Return Type Description Tags
GetValue(number time) number Returns the value of the curve at the specified time. None
GetSlope(number time) number Returns the slope (derivative) of the curve at the specified time. This may return nil in certain cases where the curve values are not continuous. None

Examples

Example using:

New

GetValue

Curves are powerful data structures that allow various kinds of interpolation between numbers. In this example, we construct a minimal curve, with only two points. We then ask for the interpolated value at the middle of the curve (time = 0.5). The value of 2.5 should appear in the Event Log.

local keys = {
    CurveKey.New(0, 0),
    CurveKey.New(1, 5)
}

local curve = SimpleCurve.New(keys)

local value = curve:GetValue(0.5)
print(tostring(value))

See also: CurveKey.New


Example using:

GetValue

This example implements a state machine with 4 states, for the purpose of animating a UI element, such as a popup dialog that is center-aligned on screen. Two Simple Curve properties are added to the script to control the animation of the UI as it enters or exits the screen. Given the time elapsed during the enter and exit states, the curves give us a value (between 0 and 1) that we use for the UI's y-axis.

local UI_ELEMENT = script:GetCustomProperty("UIElement"):WaitForObject()
local ENTER_CURVE = script:GetCustomProperty("Enter")
local EXIT_CURVE = script:GetCustomProperty("Exit")

local ANIM_DURATION = 0.3
local DISABLED_POSITION = 600

local STATE_IDLE = 1
local STATE_ENTER = 2
local STATE_EXIT = 3
local STATE_DISABLED = 4

local currentState
local stateElapsedTime = 0

local function SetUIPosition(percent)
    -- Set the y position of the UI. Invert the percent here because the
    -- semantics of the popup are such that 1 means the popup is visible,
    -- in the middle of screen while a value of 0 means the popup is
    -- outside the screen, with a positive Y.
    UI_ELEMENT.y = (1 - percent) * DISABLED_POSITION
end

local function SetState(newState)
    if newState == STATE_IDLE then
        -- Force the UI to the middle of screen
        SetUIPosition(1)

    elseif newState == STATE_ENTER then
        -- Enable the UI, to begin the 'enter' animation
        UI_ELEMENT.visibility = Visibility.INHERIT

    elseif newState == STATE_DISABLED then
        -- Force the UI to be off-screen
        SetUIPosition(0)
        UI_ELEMENT.visibility = Visibility.FORCE_OFF
    end

    currentState = newState
    stateElapsedTime = 0
end

-- These events could be called from elsewhere in the game
local function ShowUI()
    SetState(STATE_ENTER)
end

local function HideUI()
    SetState(STATE_EXIT)
end

function Tick(deltaTime)
    stateElapsedTime = stateElapsedTime + deltaTime

    if currentState == STATE_ENTER then
        if stateElapsedTime >= ANIM_DURATION then
            -- The 'enter' animation has ended, go to Idle
            SetState(STATE_IDLE)
        else
            -- 'Enter' animation
            local percent = stateElapsedTime / ANIM_DURATION
            percent = ENTER_CURVE:GetValue(percent)
            SetUIPosition(percent)
        end

    elseif currentState == STATE_EXIT then
        if stateElapsedTime >= ANIM_DURATION then
            -- The 'exit' animation has ended, go to Disabled
            SetState(STATE_DISABLED)
        else
            -- 'Exit' animation
            local percent = stateElapsedTime / ANIM_DURATION
            percent = EXIT_CURVE:GetValue(percent)
            SetUIPosition(percent)
        end
    end
end

-- Set the initial state of the UI to 'disabled'
SetState(STATE_DISABLED)

See also: CoreObject.visibility | Events.Connect | UIControl.y


Example using:

preExtrapolation

postExtrapolation

defaultValue

minTime

maxTime

minValue

maxValue

In this example, the script has a custom property of type SimpleCurve. At runtime, the properties of the curve are print into the Event Log. The min/max properties are read-only, but can be useful to some algorithms, as they define the "bounds" of the curve.

local CURVE = script:GetCustomProperty("Curve")

local function ExtrapolationToString(value)
    if value == CurveExtrapolation.CYCLE then return "CYCLE" end
    if value == CurveExtrapolation.CYCLE_WITH_OFFSET then return "CYCLE_WITH_OFFSET" end
    if value == CurveExtrapolation.OSCILLATE then return "OSCILLATE" end
    if value == CurveExtrapolation.LINEAR then return "LINEAR" end
    if value == CurveExtrapolation.CONSTANT then return "CONSTANT" end
    return "UNKNOWN"
end

print("preExtrapolation = " .. ExtrapolationToString(CURVE.preExtrapolation))
print("postExtrapolation = " .. ExtrapolationToString(CURVE.postExtrapolation))
print("defaultValue = " .. CURVE.defaultValue)
print("minTime = " .. CURVE.minTime)
print("maxTime = " .. CURVE.maxTime)
print("minValue = " .. CURVE.minValue)
print("maxValue = " .. CURVE.maxValue)

See also: CoreObject.GetCustomProperty



Last update: June 30, 2022