ColorSequence

A ColorSequence represents a gradient of color values from 0 to 1. The color values are expressed using the datatype/ColorSequenceKeypoint type. This type is used in various properties of ParticleEmitter, Trail, and Beam. In Studio, this data type is edited using a gradient editor:

Editing the Color property of a ParticleEmitter within Studio. The gradient shows 5 ColorSequenceKeypoint at times 0, 0.25, 0.5, 0.75 and 1. The 2nd and 4th are blue and yellow, respectively.

The above gradient can be set using a script using the following call to ColorSequence.new:

local white = Color3.new(1, 1, 1)
local lightBlue = Color3.new(0, 2/3, 1)
local yellow = Color3.new(1, 1, 0)
particleEmitter.Color = ColorSequence.new{
    ColorSequenceKeypoint.new(0, white),
    ColorSequenceKeypoint.new(0.25, lightBlue),
    ColorSequenceKeypoint.new(0.5, white),
    ColorSequenceKeypoint.new(0.75, yellow),
    ColorSequenceKeypoint.new(1, white)
}

Equality

Two ColorSequences are equivalent if and only if the values of their datatype/ColorSequenceKeypoint are equivalent, even if the two ColorSequence would result in similar gradients.

Evaluation

The ColorSequence type does not have a built-in method for getting the value at a certain time/point. However, you can use the following function to evaluate at a specific time.

function evalCS(cs, time)
	-- If we are at 0 or 1, return the first or last value respectively
	if time == 0 then return cs.Keypoints[1].Value end
	if time == 1 then return cs.Keypoints[#cs.Keypoints].Value end
	-- Step through each sequential pair of keypoints and see if alpha
	-- lies between the points' time values.
	for i = 1, #cs.Keypoints - 1 do
		local this = cs.Keypoints[i]
		local next = cs.Keypoints[i + 1]
		if time >= this.Time and time < next.Time then
			-- Calculate how far alpha lies between the points
			local alpha = (time - this.Time) / (next.Time - this.Time)
			-- Evaluate the real value between the points using alpha
			return Color3.new(
				(next.Value.R - this.Value.R) * alpha + this.Value.R,
				(next.Value.G - this.Value.G) * alpha + this.Value.G,
				(next.Value.B - this.Value.B) * alpha + this.Value.B
			)
		end
	end
end

You can use the function above like this:

local cs = ColorSequence.new{
    ColorSequenceKeypoint.new(0, BrickColor.new("Really red").Color),
    ColorSequenceKeypoint.new(1, BrickColor.new("Really blue").Color)
}
print(evalCS(cs, 0.5)) --> 0.5, 0, 0.5 (purple, since we're half way between red and blue)

Constructors

ColorSequence.new ( Color3 c )
Creates a sequence of two keypoints with `c` for both the start and end values local cs = ColorSequence.new(c) -- is equivalent to local cs = ColorSequence.new{ ColorSequenceKeypoint.new(0, c), ColorSequenceKeypoint.new(1, c) }

ColorSequence.new ( Color3 c0, Color3 c1 )
Creates a sequence of two keypoints with `c0` as the start value and and `c1` as the end value. local cs = ColorSequence.new(c0, c1) -- is equivalent to local cs = ColorSequence.new{ ColorSequenceKeypoint.new(0, c0), ColorSequenceKeypoint.new(1, c1) }

ColorSequence.new ( table keypoints )

Creates a sequence given an array of ColorSequenceKeypoints. The keypoints must be provided in a non-descending time value order. At least two keypoints must be provided, and they must have a time value of 0 (first) and 1 (last).

local white = Color3.new(1, 1, 1)
local lightBlue = Color3.new(0, 2/3, 1)
local yellow = Color3.new(1, 1, 0)
local cs = ColorSequence.new{
    ColorSequenceKeypoint.new(0, white),
    ColorSequenceKeypoint.new(0.25, lightBlue),
    ColorSequenceKeypoint.new(0.5, white),
    ColorSequenceKeypoint.new(0.75, yellow),
    ColorSequenceKeypoint.new(1, white)
}

Properties

table ColorSequence.Keypoints
An array containing ColorSequenceKeypoint values for the ColorSequence.