PcoWSkbVqDnWTu_dm2ix
The Developer Hub is now deprecated and information on this page may no longer be accurate. To see our new and improved documentation, please click here. You can read more about the future of documentation here.
Collapse Sidebar

ColorSequence

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.