---
title: "ColorSequence"
description: "The ColorSequence namespace — the engine's Luau API reference for ColorSequence."
section: "API Reference"
slug: "api-colorsequence"
canonical: "https://origozero.ai/docs/api-colorsequence"
updated: "2026-08-31T23:15:00.289691548+00:00"
tags: ["api", "reference"]
---

# ColorSequence

The `ColorSequence` namespace — 2 functions.

## globals/ColorSequence/deserialize {#globals-colorsequence-deserialize}

```lua
ColorSequence.deserialize(data: any?) -> ColorSequenceObj
```

Rebuild a ColorSequence from a `{kind = "ColorSequence", keypoints = {...}}` payload produced by `:serialize()`. Used by scene save/load.

**Parameters**

- `data` `any` _(optional)_ — The serialized payload.

**Returns** `ColorSequenceObj` — A fresh ColorSequenceObj with the deserialized keypoints.

```lua
local c = ColorSequence.deserialize(savedData)
```

## globals/ColorSequence/new {#globals-colorsequence-new}

```lua
ColorSequence.new(...: any?) -> ColorSequenceObj
```

Construct a ColorSequence from a constant color (3-array `{r,g,b}` or `{r=,g=,b=}` record), a two-point lerp from `c0` to `c1`, or a keypoints array. An entry of that array is a named `{ time =, value =, envelope? = }` record, a `{ time, {r,g,b}, envelope? }` pair, or a bare `{r,g,b}` colour whose time is its place in the list — so a list of colours is a ramp through them. `envelope` is optional and may be a single number (broadcast across channels) or a 3-array. Up to 64 keypoints; the first must anchor at `time = 0`, the last at `time = 1`. NaN / Inf rejected. `@builtin::systems.particles.curves` reads the same three keypoint shapes.

**Parameters**

- `...` `any` _(optional)_ — `(color)`, `(c0, c1)`, or `({ keypoint, ... })` where a keypoint is `{time =, value =, envelope? =}`, `{time, {r,g,b}, envelope?}`, or `{r,g,b}`.

**Returns** `ColorSequenceObj` — A ColorSequenceObj with `:evaluate`, `:sample`, `:keypoints`, `:duration`, `:serialize`, `:destroy`.

```lua
local solid = ColorSequence.new({ 1, 0.5, 0.25 })
local fade  = ColorSequence.new({ 1, 1, 1 }, { 0, 0, 0 })
local bow   = ColorSequence.new({ { time = 0, value = {1,0,0} }, { time = 0.5, value = {0,1,0} }, { time = 1, value = {0,0,1} } })
local stops = ColorSequence.new({ { 0, {1,0,0} }, { 1, {0,0,1} } })
local ramp  = ColorSequence.new({ { 1, 0.85, 0.35 }, { 1, 0.35, 0.05 } })
```