Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Display . Color

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Display . Color

The Color class holds a single color value and allows for easy modification and reading of it.

Constructor:

new Color([red], [green], [blue], [alpha])

Parameters:

name type arguments Default description
red number <optional> 0

The red color value. A number between 0 and 255.

green number <optional> 0

The green color value. A number between 0 and 255.

blue number <optional> 0

The blue color value. A number between 0 and 255.

alpha number <optional> 255

The alpha value. A number between 0 and 255.

Since: 3.0.0

Members

<private> _color: number
Focus
Focus

Description:

Pre-calculated internal color value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
<private> _color32: number
Focus
Focus

Description:

Pre-calculated internal color32 value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
<private> _h: number
Focus
Focus

Description:

The hue color value. A number between 0 and 1. This is the base color.

Type:
number
Default: 0
Since: 3.13.0
Focus
Focus
<private> _locked: boolean
Focus
Focus

Description:

Is this color update locked?

Type:
boolean
Since: 3.13.0
Focus
Focus
<private> _rgba: string
Focus
Focus

Description:

Pre-calculated internal color rgb string value.

Type:
string
Default: ''
Since: 3.0.0
Focus
Focus
<private> _s: number
Focus
Focus

Description:

The saturation color value. A number between 0 and 1. This controls how much of the hue will be in the final color, where 1 is fully saturated and 0 will give you white.

Type:
number
Default: 0
Since: 3.13.0
Focus
Focus
<private> _v: number
Focus
Focus

Description:

The lightness color value. A number between 0 and 1. This controls how dark the color is. Where 1 is as bright as possible and 0 is black.

Type:
number
Default: 0
Since: 3.13.0
Focus
Focus
<private> a: number
Focus
Focus

Description:

The internal alpha color value.

Type:
number
Default: 255
Since: 3.0.0
Focus
Focus
alpha: number
Focus
Focus

Description:

The alpha color value, normalized to the range 0 to 255.

Type:
number
Since: 3.0.0
Focus
Focus
alphaGL: number
Focus
Focus

Description:

The alpha color value, normalized to the range 0 to 1.

Type:
number
Since: 3.0.0
Focus
Focus
<private> b: number
Focus
Focus

Description:

The internal blue color value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
blue: number
Focus
Focus

Description:

The blue color value, normalized to the range 0 to 255.

Type:
number
Since: 3.0.0
Focus
Focus
blueGL: number
Focus
Focus

Description:

The blue color value, normalized to the range 0 to 1.

Type:
number
Since: 3.0.0
Focus
Focus
<readonly> color: number
Focus
Focus

Description:

The color of this Color component, not including the alpha channel.

Type:
number
Since: 3.0.0
Focus
Focus
<readonly> color32: number
Focus
Focus

Description:

The color of this Color component, including the alpha channel.

Type:
number
Since: 3.0.0
Focus
Focus
<private> g: number
Focus
Focus

Description:

The internal green color value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
gl: Array.<number>
Focus
Focus

Description:

An array containing the calculated color values for WebGL use.

Type:
Array.<number>
Since: 3.0.0
Focus
Focus
green: number
Focus
Focus

Description:

The green color value, normalized to the range 0 to 255.

Type:
number
Since: 3.0.0
Focus
Focus
greenGL: number
Focus
Focus

Description:

The green color value, normalized to the range 0 to 1.

Type:
number
Since: 3.0.0
Focus
Focus
h: number
Focus
Focus

Description:

The hue color value. A number between 0 and 1. This is the base color.

Type:
number
Since: 3.13.0
Focus
Focus
<private> r: number
Focus
Focus

Description:

The internal red color value.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
red: number
Focus
Focus

Description:

The red color value, normalized to the range 0 to 255.

Type:
number
Since: 3.0.0
Focus
Focus
redGL: number
Focus
Focus

Description:

The red color value, normalized to the range 0 to 1.

Type:
number
Since: 3.0.0
Focus
Focus
<readonly> rgba: string
Focus
Focus

Description:

The color of this Color component as a string which can be used in CSS color values.

Type:
string
Since: 3.0.0
Focus
Focus
s: number
Focus
Focus

Description:

The saturation color value. A number between 0 and 1. This controls how much of the hue will be in the final color, where 1 is fully saturated and 0 will give you white.

Type:
number
Since: 3.13.0
Focus
Focus
v: number
Focus
Focus

Description:

The lightness color value. A number between 0 and 1. This controls how dark the color is. Where 1 is as bright as possible and 0 is black.

Type:
number
Since: 3.13.0
Focus
Focus

Methods

brighten(amount)
Focus
Focus

Description:

Brighten this Color by the percentage amount given.

Parameters:

name type description
amount number

The percentage amount to change this color by. A value between 0 and 100.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
clone()
Focus
Focus

Description:

Returns a new Color component using the values from this one.

Returns:
Description:

A new Color object.

Examples:
Since: 3.0.0
Focus
Focus
darken(amount)
Focus
Focus

Description:

Decrease the lightness of this Color by the percentage amount given.

Parameters:

name type description
amount number

The percentage amount to change this color by. A value between 0 and 100.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
desaturate(amount)
Focus
Focus

Description:

Decrease the saturation of this Color by the percentage amount given. The saturation is the amount of the base color in the hue.

Parameters:

name type description
amount number

The percentage amount to change this color by. A value between 0 and 100.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
gray(shade)
Focus
Focus

Description:

Sets this Color object to be grayscaled based on the shade value given.

Parameters:

name type description
shade number

A value between 0 and 255.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
lighten(amount)
Focus
Focus

Description:

Increase the lightness of this Color by the percentage amount given.

Parameters:

name type description
amount number

The percentage amount to change this color by. A value between 0 and 100.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
random([min], [max])
Focus
Focus

Description:

Sets this Color object to be a random color between the min and max values given.

Parameters:

name type arguments Default description
min number <optional> 0

The minimum random color value. Between 0 and 255.

max number <optional> 255

The maximum random color value. Between 0 and 255.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
randomGray([min], [max])
Focus
Focus

Description:

Sets this Color object to be a random grayscale color between the min and max values given.

Parameters:

name type arguments Default description
min number <optional> 0

The minimum random color value. Between 0 and 255.

max number <optional> 255

The maximum random color value. Between 0 and 255.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
saturate(amount)
Focus
Focus

Description:

Increase the saturation of this Color by the percentage amount given. The saturation is the amount of the base color in the hue.

Parameters:

name type description
amount number

The percentage amount to change this color by. A value between 0 and 100.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
setFromHSV(h, s, v)
Focus
Focus

Description:

Sets the color based on the hue, saturation and lightness values given.

Parameters:

name type description
h number

The hue, in the range 0 - 1. This is the base color.

s number

The saturation, in the range 0 - 1. This controls how much of the hue will be in the final color, where 1 is fully saturated and 0 will give you white.

v number

The value, in the range 0 - 1. This controls how dark the color is. Where 1 is as bright as possible and 0 is black.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
setFromRGB(color)
Focus
Focus

Description:

Sets the color based on the color object given.

Parameters:

name type description
color Phaser.Types.Display.InputColorObject

An object containing r, g, b and optionally a values in the range 0 to 255.

Returns:
Description:

This Color object.

Examples:
Since: 3.0.0
Focus
Focus
setGLTo(red, green, blue, [alpha])
Focus
Focus

Description:

Sets the red, green, blue and alpha GL values of this Color component.

Parameters:

name type arguments Default description
red number

The red color value. A number between 0 and 1.

green number

The green color value. A number between 0 and 1.

blue number

The blue color value. A number between 0 and 1.

alpha number <optional> 1

The alpha value. A number between 0 and 1.

Returns:
Description:

This Color object.

Examples:
Since: 3.0.0
Focus
Focus
setTo(red, green, blue, [alpha], [updateHSV])
Focus
Focus

Description:

Sets the color of this Color component.

Parameters:

name type arguments Default description
red number

The red color value. A number between 0 and 255.

green number

The green color value. A number between 0 and 255.

blue number

The blue color value. A number between 0 and 255.

alpha number <optional> 255

The alpha value. A number between 0 and 255.

updateHSV boolean <optional> true

Update the HSV values after setting the RGB values?

Returns:
Description:

This Color object.

Examples:
Since: 3.0.0
Focus
Focus
transparent()
Focus
Focus

Description:

Sets this color to be transparent. Sets all values to zero.

Returns:
Description:

This Color object.

Examples:
Since: 3.0.0
Focus
Focus
<private> update()
Focus
Focus

Description:

Updates the internal cache values.

Returns:
Description:

This Color object.

Examples:
Since: 3.0.0
Focus
Focus
<private> updateHSV()
Focus
Focus

Description:

Updates the internal hsv cache values.

Returns:
Description:

This Color object.

Examples:
Since: 3.13.0
Focus
Focus
<static> ColorSpectrum([limit])
Focus
Focus

Description:

Return an array of Colors in a Color Spectrum.

The spectrum colors flow in the order: red, yellow, green, blue.

By default this function will return an array with 1024 elements in.

However, you can reduce this to a smaller quantity if needed, by specitying the limit parameter.

Parameters:

name type arguments Default description
limit number <optional> 1024

How many colors should be returned? The maximum is 1024 but you can set a smaller quantity if required.

Returns:
Description:

An array containing limit parameter number of elements, where each contains a Color Object.

Examples:
Since: 3.50.0
Focus
Focus
<static> ColorToRGBA(color)
Focus
Focus

Description:

Converts the given color value into an Object containing r,g,b and a properties.

Parameters:

name type description
color number

A color value, optionally including the alpha value.

Returns:
Description:

An object containing the parsed color values.

Examples:
Since: 3.0.0
Focus
Focus
<static> ComponentToHex(color)
Focus
Focus

Description:

Returns a string containing a hex representation of the given color component.

Parameters:

name type description
color number

The color channel to get the hex value for, must be a value between 0 and 255.

Returns:
Description:

A string of length 2 characters, i.e. 255 = ff, 100 = 64.

Type:
  • string
Examples:
Since: 3.0.0
Focus
Focus
<static> GetColor(red, green, blue)
Focus
Focus

Description:

Given 3 separate color values this will return an integer representation of it.

Parameters:

name type description
red number

The red color value. A number between 0 and 255.

green number

The green color value. A number between 0 and 255.

blue number

The blue color value. A number between 0 and 255.

Returns:
Description:

The combined color value.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<static> GetColor32(red, green, blue, alpha)
Focus
Focus

Description:

Given an alpha and 3 color values this will return an integer representation of it.

Parameters:

name type description
red number

The red color value. A number between 0 and 255.

green number

The green color value. A number between 0 and 255.

blue number

The blue color value. A number between 0 and 255.

alpha number

The alpha color value. A number between 0 and 255.

Returns:
Description:

The combined color value.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<static> HSLToColor(h, s, l)
Focus
Focus

Description:

Converts HSL (hue, saturation and lightness) values to a Phaser Color object.

Parameters:

name type description
h number

The hue value in the range 0 to 1.

s number

The saturation value in the range 0 to 1.

l number

The lightness value in the range 0 to 1.

Returns:
Description:

A Color object created from the results of the h, s and l values.

Examples:
Since: 3.0.0
Focus
Focus
<static> HSVColorWheel([s], [v])
Focus
Focus

Description:

Get HSV color wheel values in an array which will be 360 elements in size.

Parameters:

name type arguments Default description
s number <optional> 1

The saturation, in the range 0 - 1.

v number <optional> 1

The value, in the range 0 - 1.

Returns:
Description:

An array containing 360 elements, where each contains a single numeric value corresponding to the color at that point in the HSV color wheel.

Examples:
Since: 3.0.0
Focus
Focus
<static> HSVToRGB(h, s, v, [out])
Focus
Focus

Description:

Converts a HSV (hue, saturation and value) color set to RGB.

Conversion formula from https://en.wikipedia.org/wiki/HSL_and_HSV

Assumes HSV values are contained in the set [0, 1].

Parameters:

name type arguments description
h number

The hue, in the range 0 - 1. This is the base color.

s number

The saturation, in the range 0 - 1. This controls how much of the hue will be in the final color, where 1 is fully saturated and 0 will give you white.

v number

The value, in the range 0 - 1. This controls how dark the color is. Where 1 is as bright as possible and 0 is black.

out Phaser.Display.Color | Phaser.Types.Display.ColorObject <optional>

A Color object to store the results in. If not given a new ColorObject will be created.

Returns:
Description:

An object with the red, green and blue values set in the r, g and b properties.

Examples:
Since: 3.0.0
Focus
Focus
<static> HexStringToColor(hex)
Focus
Focus

Description:

Converts a hex string into a Phaser Color object.

The hex string can supplied as '#0033ff' or the short-hand format of '#03f'; it can begin with an optional "#" or "0x", or be unprefixed.

An alpha channel is not supported.

Parameters:

name type description
hex string

The hex color value to convert, such as #0033ff or the short-hand format: #03f.

Returns:
Description:

A Color object populated by the values of the given string.

Examples:
Since: 3.0.0
Focus
Focus
<static> HueToComponent(p, q, t)
Focus
Focus

Description:

Converts a hue to an RGB color. Based on code by Michael Jackson (https://github.com/mjijackson)

Parameters:

name type
p number
q number
t number
Returns:
Description:

The combined color value.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<static> IntegerToColor(input)
Focus
Focus

Description:

Converts the given color value into an instance of a Color object.

Parameters:

name type description
input number

The color value to convert into a Color object.

Returns:
Description:

A Color object.

Examples:
Since: 3.0.0
Focus
Focus
<static> IntegerToRGB(input)
Focus
Focus

Description:

Return the component parts of a color as an Object with the properties alpha, red, green, blue.

Alpha will only be set if it exists in the given color (0xAARRGGBB)

Parameters:

name type description
input number

The color value to convert into a Color object.

Returns:
Description:

An object with the red, green and blue values set in the r, g and b properties.

Examples:
Since: 3.0.0
Focus
Focus
<static> ObjectToColor(input)
Focus
Focus

Description:

Converts an object containing r, g, b and a properties into a Color class instance.

Parameters:

name type description
input Phaser.Types.Display.InputColorObject

An object containing r, g, b and a properties in the range 0 to 255.

Returns:
Description:

A Color object.

Examples:
Since: 3.0.0
Focus
Focus
<static> RGBStringToColor(rgb)
Focus
Focus

Description:

Converts a CSS 'web' string into a Phaser Color object.

The web string can be in the format 'rgb(r,g,b)' or 'rgba(r,g,b,a)' where r/g/b are in the range [0..255] and a is in the range [0..1].

Parameters:

name type description
rgb string

The CSS format color string, using the rgb or rgba format.

Returns:
Description:

A Color object.

Examples:
Since: 3.0.0
Focus
Focus
<static> RGBToHSV(r, g, b, [out])
Focus
Focus

Description:

Converts an RGB color value to HSV (hue, saturation and value). Conversion formula from http://en.wikipedia.org/wiki/HSL_color_space. Assumes RGB values are contained in the set [0, 255] and returns h, s and v in the set [0, 1]. Based on code by Michael Jackson (https://github.com/mjijackson)

Parameters:

name type arguments description
r number

The red color value. A number between 0 and 255.

g number

The green color value. A number between 0 and 255.

b number

The blue color value. A number between 0 and 255.

out Phaser.Display.Color | Phaser.Types.Display.HSVColorObject <optional>

An object to store the color values in. If not given an HSV Color Object will be created.

Returns:
Description:

An object with the properties h, s and v set.

Examples:
Since: 3.0.0
Focus
Focus
<static> RGBToString(r, g, b, [a], [prefix])
Focus
Focus

Description:

Converts the color values into an HTML compatible color string, prefixed with either # or 0x.

Parameters:

name type arguments Default description
r number

The red color value. A number between 0 and 255.

g number

The green color value. A number between 0 and 255.

b number

The blue color value. A number between 0 and 255.

a number <optional> 255

The alpha value. A number between 0 and 255.

prefix string <optional> #

The prefix of the string. Either # or 0x.

Returns:
Description:

A string-based representation of the color values.

Type:
  • string
Examples:
Since: 3.0.0
Focus
Focus
<static> RandomRGB([min], [max])
Focus
Focus

Description:

Creates a new Color object where the r, g, and b values have been set to random values based on the given min max values.

Parameters:

name type arguments Default description
min number <optional> 0

The minimum value to set the random range from (between 0 and 255)

max number <optional> 255

The maximum value to set the random range from (between 0 and 255)

Returns:
Description:

A Color object.

Examples:
Since: 3.0.0
Focus
Focus
<static> ValueToColor(input)
Focus
Focus

Description:

Converts the given source color value into an instance of a Color class. The value can be either a string, prefixed with rgb or a hex string, a number or an Object.

Parameters:

name type description
input string | number | Phaser.Types.Display.InputColorObject

The source color value to convert.

Returns:
Description:

A Color object.

Examples:
Since: 3.0.0
Focus
Focus