# Curve

Class · category: Math

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/core/math/curve.js#L22

A curve is a collection of keys (time/value pairs). The shape of the curve is defined by its type
that specifies an interpolation scheme for the keys.

Keys are kept sorted by time. Supply them to the constructor as a flat `[time, value, ...]` array
or insert them one at a time with [add](https://api.playcanvas.com/engine/classes/Curve.md#add), then evaluate the curve at any time with
[value](https://api.playcanvas.com/engine/classes/Curve.md#value). The [type](https://api.playcanvas.com/engine/classes/Curve.md#type) selects how values between keys are computed:
[CURVE_LINEAR](https://api.playcanvas.com/engine/variables/CURVE_LINEAR.md), [CURVE_SMOOTHSTEP](https://api.playcanvas.com/engine/variables/CURVE_SMOOTHSTEP.md), [CURVE_SPLINE](https://api.playcanvas.com/engine/variables/CURVE_SPLINE.md) or [CURVE_STEP](https://api.playcanvas.com/engine/variables/CURVE_STEP.md).
Curves drive values that change over time or over a normalized range, such as particle size over
a particle's lifetime.

**Example**

```ts
// Ease a value in over one second and read it back a quarter of the way through
const curve = new Curve([0, 0, 1, 1]);
curve.type = CURVE_SMOOTHSTEP;
const v = curve.value(0.25);
```

## Constructors

### constructor

```ts
new Curve(data?: number[])
```

Creates a new Curve instance.

**Parameters**

- `data` (`number[]`, optional): An array of keys (pairs of numbers with the time first and value
  second).

**Example**

```ts
const curve = new Curve([
    0, 0,        // At 0 time, value of 0
    0.33, 2,     // At 0.33 time, value of 2
    0.66, 2.6,   // At 0.66 time, value of 2.6
    1, 3         // At 1 time, value of 3
]);
```

## Properties

### keys

```ts
keys: number[][] = []
```

The keys that define the curve. Each key is an array of two numbers with the time first and
the value second.

### tension

```ts
tension: number = 0.5
```

Controls how [CURVE_SPLINE](https://api.playcanvas.com/engine/variables/CURVE_SPLINE.md) tangents are calculated. Valid range is between 0 and 1
where 0 results in a non-smooth curve (equivalent to linear interpolation) and 1 results in
a very smooth curve. Use 0.5 for a Catmull-Rom spline.

### type

```ts
type: number = CURVE_SMOOTHSTEP
```

The curve interpolation scheme. Can be:

- [CURVE_LINEAR](https://api.playcanvas.com/engine/variables/CURVE_LINEAR.md)
- [CURVE_SMOOTHSTEP](https://api.playcanvas.com/engine/variables/CURVE_SMOOTHSTEP.md)
- [CURVE_SPLINE](https://api.playcanvas.com/engine/variables/CURVE_SPLINE.md)
- [CURVE_STEP](https://api.playcanvas.com/engine/variables/CURVE_STEP.md)

Defaults to [CURVE_SMOOTHSTEP](https://api.playcanvas.com/engine/variables/CURVE_SMOOTHSTEP.md).

## Accessors

### length

```ts
get length(): number
```

Gets the number of keys in the curve.

## Methods

### add

```ts
add(time: number, value: number): number[]
```

Adds a new key to the curve.

**Parameters**

- `time` (`number`): Time to add new key.
- `value` (`number`): Value of new key.

**Returns** `number[]`: The newly created `[time, value]` pair.

**Example**

```ts
const curve = new Curve();
curve.add(0, 1);   // add key at time 0 with value 1
curve.add(1, 2);   // add key at time 1 with value 2
```

### clear

```ts
clear(): Curve
```

Removes all keys from the curve.

**Returns** [`Curve`](https://api.playcanvas.com/engine/classes/Curve.md): The curve instance.

**Example**

```ts
const curve = new Curve([0, 1, 1, 2]);
curve.clear(); // curve now has no keys
```

### clone

```ts
clone(): Curve
```

Returns a clone of the specified curve object.

**Returns** [`Curve`](https://api.playcanvas.com/engine/classes/Curve.md): A clone of the specified curve.

**Example**

```ts
const curve = new Curve([0, 0, 1, 10]);
const clonedCurve = curve.clone();
```

### closest

```ts
closest(time: number): number[] | null
```

Returns the key closest to the specified time. When two keys are equally close, the later
one is returned.

**Parameters**

- `time` (`number`): The time to find the closest key to.

**Returns** `number[] | null`: The `[time, value]` pair closest to the specified time, or null if
no keys exist.

**Example**

```ts
const curve = new Curve([0, 1, 0.5, 2, 1, 3]);
const key = curve.closest(0.6); // returns [0.5, 2]
```

### get

```ts
get(index: number): number[]
```

Gets the `[time, value]` pair at the specified index.

**Parameters**

- `index` (`number`): The index of key to return.

**Returns** `number[]`: The `[time, value]` pair at the specified index.

**Example**

```ts
const curve = new Curve([0, 1, 1, 2]);
const key = curve.get(0); // returns [0, 1]
```

### remove

```ts
remove(index: number): number[] | null
```

Removes the key at the specified index.

**Parameters**

- `index` (`number`): The index of the key to remove.

**Returns** `number[] | null`: The removed `[time, value]` pair, or null if the index is out of
range.

**Example**

```ts
const curve = new Curve([0, 1, 1, 2]);
curve.remove(0); // removes the key at time 0
```

### sort

```ts
sort(): void
```

Sorts keys by time.

### value

```ts
value(time: number): number
```

Returns the interpolated value of the curve at specified time.

**Parameters**

- `time` (`number`): The time at which to calculate the value.

**Returns** `number`: The interpolated value.

**Example**

```ts
const curve = new Curve([0, 0, 1, 10]);
const value = curve.value(0.5); // returns interpolated value at time 0.5
```