Version: Phaser v4.0.0-rc.6

FilterList

A list of filters being applied to a Phaser.Cameras.Scene2D.Camera.

Filters can apply special effects and masks.

They are only available in WebGL.

Use gameObject.enableFilters() to apply them to Game Objects.

Filters include the following:

Barrel Distortion
Blend
Blocky
Blur
Bokeh / Tilt Shift
Color Matrix
Displacement
Glow
Mask
Parallel Filters
Pixelate
Sampler
Shadow
Threshold

This list is either 'internal' or 'external'.

Internal filters apply to things within the camera.

External filters apply to the camera itself, in its rendering context.

A complete list of rendering steps for a Camera goes:

Objects render to a texture the size of the camera.
Internal filters draw that texture to new textures, applying effects.

These are usually the same size, but may expand to accommodate blur.

The texture is drawn to a texture the size of the context where the camera

will be drawn, accounting for transformation of the camera itself.

External filters draw that texture to new textures,

again applying effects and expanding where necessary.

The final texture draws the filtered camera contents to the context.

For example, consider a game object which is rotated 45 degrees.

Apply a horizontal blur filter.

If the filter is internal, the blur will appear at 45 degrees,

because it is applied before the object is rotated.

If the filter is external, the blur will appear horizontal,

because it is applied after the object is rotated.

You should use internal filters wherever possible,

because they apply only to the region of the camera/game object.

External filters are full-screen and can be more expensive.

Filters can be stacked. The order of the list is the order of application.

As you can appreciate, some effects are more expensive than others. For example, a bloom effect is going to be more

expensive than a simple color matrix effect, so please consider using them wisely and performance test your target

platforms early on in production.

This FilterList is created internally and does not need to be instantiated directly.

In Phaser 3, Filters were known as FX.

Constructor

new FilterList(camera)

Parameters

name	type	optional	description
camera	Phaser.Cameras.Scene2D.Camera	No	The Camera that owns this list.

Scope: static

Source: src/gameobjects/components/FilterList.js#L23
Since: 4.0.0

Public Members

camera

camera: Phaser.Cameras.Scene2D.Camera

Description:

The Camera that owns this list.

Source: src/gameobjects/components/FilterList.js#L93
Since: 4.0.0

list

list: Array.<Phaser.Filters.Controller>

Description:

The list of filters.

This list can be manipulated directly.

If you want to add or remove filters,

please use the appropriate methods to ensure they are handled correctly.

Moving filters around in the list is safe.

Source: src/gameobjects/components/FilterList.js#L102
Since: 4.0.0

Public Methods

add

<instance> add(filter, [index])

Description:

Adds a filter to this list.

Parameters:

name	type	optional	description
filter	Phaser.Filters.Controller	No	The filter to add.
index	number	Yes	The index to insert the filter at. If not given, the filter is added to the end of the list. If negative, it is inserted from the end.

Returns: Phaser.Filters.Controller - The filter that was added.

Source: src/gameobjects/components/FilterList.js#L141
Since: 4.0.0

addBarrel

<instance> addBarrel([amount])

Description:

Adds a Barrel effect.

A barrel effect allows you to apply either a 'pinch' or 'expand' distortion to

a Game Object. The amount of the effect can be modified in real-time.

Parameters:

name	type	optional	default	description
amount	number	Yes	1	The amount of distortion applied to the barrel effect. A value of 1 is no distortion. Typically keep this within +- 1.

Returns: Phaser.Filters.Barrel - The new Barrel filter controller.

Source: src/gameobjects/components/FilterList.js#L205
Since: 4.0.0

addBlend

<instance> addBlend([texture], [blendMode], [amount], [color])

Description:

Adds a Blend effect.

A blend effect allows you to apply another texture to the view

using a specific blend mode.

This supports blend modes not otherwise available in WebGL.

Parameters:

name	type	optional	default	description
texture	string	Yes	"'__WHITE'"	The texture to apply to the view.
blendMode	Phaser.BlendModes	Yes	"Phaser.BlendModes.NORMAL"	The blend mode to apply to the view.
amount	number	Yes	1	The amount of the blend effect to apply to the view. At 0, the original image is preserved. At 1, the blend texture is fully applied. The expected range is 0 to 1, but you can go outside that range for different effects.
color	Array.<number>	Yes	"[1, 1, 1, 1]"	The color to apply to the blend texture. Each value corresponds to a color channel in RGBA. The expected range is 0 to 1, but you can go outside that range for different effects.

Returns: Phaser.Filters.Blend - The new Blend filter controller.

Source: src/gameobjects/components/FilterList.js#L221
Since: 4.0.0

addBlocky

<instance> addBlocky([config])

Description:

Adds a Blocky effect.

This filter controller manages a blocky effect.

The blocky effect works by taking the central pixel of a block of pixels

and using it to fill the entire block, creating a pixelated effect.

It reduces the resolution of an image,

creating a pixelated or blocky appearance.

This is often used for stylistic purposes, such as pixel art.

One technique is to render the game at a higher resolution,

scaled up by a factor of N,

and then apply the blocky effect at size N.

This creates large, visible pixels, suitable for further stylization.

The effect can also be used to obscure certain elements within the game,

such as during a transition or to censor specific content.

Blocky works best on games with no anti-aliasing,

so it can read unfiltered pixel colors from the original image.

It preserves the colors of the original art, instead of blending them

like the Pixelate filter.

Parameters:

name	type	optional	description
config	Phaser.Types.Filters.BlockyConfig	Yes	The configuration object for the Blocky effect.

Returns: Phaser.Filters.Blocky - The new Blocky filter controller.

Source: src/gameobjects/components/FilterList.js#L247
Since: 4.0.0

addBlur

<instance> addBlur([quality], [x], [y], [strength], [color], [steps])

Description:

Adds a Blur effect.

A Gaussian blur is the result of blurring an image by a Gaussian function. It is a widely used effect,

typically to reduce image noise and reduce detail. The visual effect of this blurring technique is a

smooth blur resembling that of viewing the image through a translucent screen, distinctly different

from the bokeh effect produced by an out-of-focus lens or the shadow of an object under usual illumination.

Parameters:

name	type	optional	default	description
quality	number	Yes	0	The quality of the blur effect. Can be either 0 for Low Quality, 1 for Medium Quality or 2 for High Quality.
x	number	Yes	2	The horizontal offset of the blur effect.
y	number	Yes	2	The vertical offset of the blur effect.
strength	number	Yes	1	The strength of the blur effect.
color	number	Yes	"0xffffff"	The color of the blur, as a hex value.
steps	number	Yes	4	The number of steps to run the blur effect for. This value should always be an integer.

Returns: Phaser.Filters.Blur - The new Blur filter controller.

Source: src/gameobjects/components/FilterList.js#L280
Since: 4.0.0

addBokeh

<instance> addBokeh([radius], [amount], [contrast])

Description:

Adds a Bokeh effect.

Bokeh refers to a visual effect that mimics the photographic technique of creating a shallow depth of field.

This effect is used to emphasize the game's main subject or action, by blurring the background or foreground

elements, resulting in a more immersive and visually appealing experience. It is achieved through rendering

techniques that simulate the out-of-focus areas, giving a sense of depth and realism to the game's graphics.

name	type	optional	default	description
radius	number	Yes	0.5	The radius of the bokeh effect.
amount	number	Yes	1	The amount of the bokeh effect.
contrast	number	Yes	0.2	The color contrast of the bokeh effect.

addColorMatrix

<instance> addColorMatrix()

Description:

Adds a Color Matrix effect.

The color matrix effect is a visual technique that involves manipulating the colors of an image

or scene using a mathematical matrix. This process can adjust hue, saturation, brightness, and contrast,

allowing developers to create various stylistic appearances or mood settings within the game.

Common applications include simulating different lighting conditions, applying color filters,

or achieving a specific visual style.

Returns: Phaser.Filters.ColorMatrix - The new ColorMatrix filter controller.

Source: src/gameobjects/components/FilterList.js#L342
Since: 4.0.0

addDisplacement

<instance> addDisplacement([texture], [x], [y])

Description:

Adds a Displacement effect.

The displacement effect is a visual technique that alters the position of pixels in an image

or texture based on the values of a displacement map. This effect is used to create the illusion

of depth, surface irregularities, or distortion in otherwise flat elements. It can be applied to

characters, objects, or backgrounds to enhance realism, convey movement, or achieve various

stylistic appearances.

Parameters:

name	type	optional	default	description
texture	string	Yes	"'__WHITE'"	The unique string-based key of the texture to use for displacement, which must exist in the Texture Manager.
x	number	Yes	0.005	The amount of horizontal displacement to apply. A very small float number, such as 0.005.
y	number	Yes	0.005	The amount of vertical displacement to apply. A very small float number, such as 0.005.

Returns: Phaser.Filters.Displacement - The new Displacement filter controller.

Source: src/gameobjects/components/FilterList.js#L360
Since: 4.0.0

addGlow

<instance> addGlow([color], [outerStrength], [innerStrength], [scale], [knockout], [quality], [distance])

Description:

Adds a Glow effect.

The glow effect is a visual technique that creates a soft, luminous halo around game objects,

characters, or UI elements. This effect is used to emphasize importance, enhance visual appeal,

or convey a sense of energy, magic, or otherworldly presence. The effect can also be set on

the inside of the edge. The color and strength of the glow can be modified.

Parameters:

name	type	optional	default	description
color	number	Yes	"0xffffff"	The color of the glow effect as a number value.
outerStrength	number	Yes	4	The strength of the glow outward from the edge of textures.
innerStrength	number	Yes	0	The strength of the glow inward from the edge of textures.
scale	number	Yes	1	The scale of the glow effect. This multiplies the fixed distance.
knockout	boolean	Yes	false	If `true` only the glow is drawn, not the texture itself.
quality	number	Yes	10	The quality of the glow effect. This cannot be changed after the filter has been created.
distance	number	Yes	10	The distance of the glow effect. This cannot be changed after the filter has been created.

Returns: Phaser.Filters.Glow - The new Glow filter controller.

Source: src/gameobjects/components/FilterList.js#L388
Since: 4.0.0

addMask

<instance> addMask([mask], [invert], [viewCamera], [viewTransform], [scaleFactor])

Description:

Adds a Mask effect.

A mask uses a texture to hide parts of an input.

It multiplies the color and alpha of the input

by the alpha of the mask in the corresponding texel.

Masks can be inverted, which switches what they hide and what they show.

Masks can use either a texture or a GameObject.

If a GameObject is used, the mask will render the GameObject

to a DynamicTexture and use that.

The mask will automatically update when the GameObject changes,

unless the autoUpdate flag is set to false.

When the mask filter is used as an internal filter,

the mask will match the object/view being filtered.

This is useful for creating effects that follow the object,

such as effects intended to match an animated sprite.

When the mask filter is used as an external filter,

the mask will match the context of the camera.

This is useful for creating effects that cover the entire view.

An optional viewCamera can be specified when creating the mask.

If not used, mask objects will be viewed through a default camera.

Set the viewCamera to the scene's main camera (this.cameras.main)

to view the mask through the main camera.

Parameters:

name	type	optional	default	description
mask	string \| Phaser.GameObjects.GameObject	Yes	"'__WHITE'"	The source of the mask. This can be a unique string-based key of the texture to use for the mask, which must exist in the Texture Manager. Or it can be a GameObject, in which case the mask will render the GameObject to a DynamicTexture and use that.
invert	boolean	Yes	false	Whether to invert the mask.
viewCamera	Phaser.Cameras.Scene2D.Camera	Yes		The Camera to use when rendering the mask with a GameObject. If not specified, uses the scene's `main` camera.
viewTransform	'local' \| 'world'	Yes	"'world'"	The transform to use when rendering the mask with a GameObject. 'local' uses the GameObject's own properties. 'world' uses the GameObject's `parentContainer` value to compute a world position.
scaleFactor	number	Yes	1	The scale factor to apply to the underlying mask texture. Can be used to balance memory usage and needed mask precision. This just adjusts the size of the texture; you must also adjust mask size to match, e.g. if scaleFactor is 0.5, your mask might be a Container with scale 0.5. It's easy to make things complicated when combining scale factor, object transform, and camera transform, so try to be precise when using this option.

Returns: Phaser.Filters.Mask - The new Mask filter controller.

Source: src/gameobjects/components/FilterList.js#L423
Since: 4.0.0

addParallelFilters

<instance> addParallelFilters()

Description:

Adds a Parallel Filters effect.

This filter controller splits the input into two lists of filters,

runs each list separately, and then blends the results together.

The Parallel Filters effect is useful for reusing an input.

Ordinarily, a filter modifies the input and passes it to the next filter.

This effect allows you to split the input and re-use it elsewhere.

It does not gain performance benefits from parallel processing;

it is a convenience for reusing the input.

The Parallel Filters effect is not a filter itself.

It is a controller that manages two FilterLists,

and the final Blend filter that combines the results.

The FilterLists are named 'top' and 'bottom'.

The 'top' output is applied as a blend texture to the 'bottom' output.

You do not have to populate both lists. If only one is populated,

it will be blended with the original input at the end.

This is useful when you want to retain image data that would be lost

in the filter process.

Returns: Phaser.Filters.ParallelFilters - The new Parallel Filters filter controller.

Source: src/gameobjects/components/FilterList.js#L475
Since: 4.0.0

addPixelate

<instance> addPixelate([amount])

Description:

Adds a Pixelate effect.

The pixelate effect is a visual technique that deliberately reduces the resolution or detail of an image,

creating a blocky or mosaic appearance composed of large, visible pixels. This effect can be used for stylistic

purposes, as a homage to retro gaming, or as a means to obscure certain elements within the game, such as

during a transition or to censor specific content.

Parameters:

name	type	optional	description
amount	number	Yes	The amount of pixelation. A higher value creates a more pronounced effect.

Returns: Phaser.Filters.Pixelate - The new Pixelate filter controller.

Source: src/gameobjects/components/FilterList.js#L521
Since: 4.0.0

addSampler

<instance> addSampler(callback, [region])

Description:

Adds a Sampler effect.

This controller manages a sampler.

It doesn't actually render anything, and leaves the image unaltered.

It is used to sample a region of the camera view, and pass the results to a callback.

This is useful for extracting data from the camera view.

This operation is expensive, so use sparingly.

Parameters:

name	type	optional	default	description
callback	Phaser.Types.Renderer.Snapshot.SnapshotCallback	No		The callback to call with the results of the sampler.
region	null \| Phaser.Types.Math.Vector2Like	Phaser.Geom.Rectangle	Yes	null

Returns: Phaser.Filters.Sampler - The new Sampler filter controller.

Source: src/gameobjects/components/FilterList.js#L544
Since: 4.0.0

addShadow

<instance> addShadow([x], [y], [decay], [power], [color], [samples], [intensity])

Description:

Adds a Shadow effect.

The shadow effect is a visual technique used to create the illusion of depth and realism by adding darker,

offset silhouettes or shapes beneath game objects, characters, or environments. These simulated shadows

help to enhance the visual appeal and immersion, making the 2D game world appear more dynamic and three-dimensional.

Parameters:

name	type	optional	default	description
x	number	Yes	0	The horizontal offset of the shadow effect.
y	number	Yes	0	The vertical offset of the shadow effect.
decay	number	Yes	0.1	The amount of decay for the shadow effect.
power	number	Yes	1	The power of the shadow effect.
color	number	Yes	"0x000000"	The color of the shadow, as a hex value.
samples	number	Yes	6	The number of samples that the shadow effect will run for.
intensity	number	Yes	1	The intensity of the shadow effect.

Returns: Phaser.Filters.Shadow - The new Shadow filter controller.

Source: src/gameobjects/components/FilterList.js#L571
Since: 4.0.0

addThreshold

<instance> addThreshold([edge1], [edge2], [invert])

Description:

Adds a Threshold effect.

Input values are compared to a threshold value or range.

Values below the threshold are set to 0, and values above the threshold are set to 1.

Values within the range are linearly interpolated between 0 and 1.

This is useful for creating effects such as sharp edges from gradients,

or for creating binary effects.

The threshold is stored as a range, with two edges.

Each edge has a value for each channel, between 0 and 1.

If the two edges are the same, the threshold has no interpolation,

and will output either 0 or 1.

Each channel can also be inverted.

Parameters:

name	type	optional	default	description
edge1	number \| Array.<number>	Yes	0.5	The first edge of the threshold. This may be an array of the RGBA channels, or a single number for all 4 channels.
edge2	number \| Array.<number>	Yes	0.5	The second edge of the threshold. This may be an array of the RGBA channels, or a single number for all 4 channels.
invert	boolean \| Array.<boolean>	Yes	false	Whether each channel is inverted. This may be an array of the RGBA channels, or a single boolean for all 4 channels.

Returns: Phaser.Filters.Threshold - The new Threshold filter controller.

Source: src/gameobjects/components/FilterList.js#L605
Since: 4.0.0

addTiltShift

<instance> addTiltShift([radius], [amount], [contrast], [blurX], [blurY], [strength])

Description:

Adds a Tilt Shift effect.

This Bokeh effect can also be used to generate a Tilt Shift effect, which is a technique used to create a miniature

effect by blurring everything except a small area of the image. This effect is achieved by blurring the

top and bottom elements, while keeping the center area in focus.

name	type	optional	description
radius	number	Yes	The radius of the bokeh effect.
amount	number	Yes	The amount of the bokeh effect.
contrast	number	Yes	The color contrast of the bokeh effect.
blurX	number	Yes	The amount of horizontal blur.
blurY	number	Yes	The amount of vertical blur.
strength	number	Yes	The strength of the blur.

clear

<instance> clear()

Description:

Destroys and removes all filters in this list.

Returns: Phaser.GameObjects.Components.FilterList - This FilterList instance.

Source: src/gameobjects/components/FilterList.js#L118
Since: 4.0.0

destroy

<instance> destroy()

Description:

Destroys this FilterList.

Source: src/gameobjects/components/FilterList.js#L675
Since: 4.0.0

getActive

<instance> getActive()

Description:

Returns all active filters in this list.

Returns: Array.<Phaser.Filters.Controller> - The active filters in this list.

Source: src/gameobjects/components/FilterList.js#L193
Since: 4.0.0

remove

<instance> remove(filter, [forceDestroy])

Description:

Removes a filter from this list, then destroys it.

Parameters:

name	type	optional	default	description
filter	Phaser.Filters.Controller	No		The filter to remove.
forceDestroy	boolean	Yes	false	If `true`, the filter will be destroyed even if it has the `ignoreDestroy` flag set.

Returns: Phaser.GameObjects.Components.FilterList - This FilterList instance.

Source: src/gameobjects/components/FilterList.js#L166
Since: 4.0.0

Public Members​

camera​

camera: Phaser.Cameras.Scene2D.Camera​

list​

list: Array.<Phaser.Filters.Controller>​

Public Methods​

add​

<instance> add(filter, [index])​

addBarrel​

<instance> addBarrel([amount])​

addBlend​

<instance> addBlend([texture], [blendMode], [amount], [color])​

addBlocky​

<instance> addBlocky([config])​

addBlur​

<instance> addBlur([quality], [x], [y], [strength], [color], [steps])​

addBokeh​

<instance> addBokeh([radius], [amount], [contrast])​

addColorMatrix​

<instance> addColorMatrix()​

addDisplacement​

<instance> addDisplacement([texture], [x], [y])​

addGlow​

<instance> addGlow([color], [outerStrength], [innerStrength], [scale], [knockout], [quality], [distance])​

addMask​

<instance> addMask([mask], [invert], [viewCamera], [viewTransform], [scaleFactor])​

addParallelFilters​

<instance> addParallelFilters()​

addPixelate​

<instance> addPixelate([amount])​

addSampler​

<instance> addSampler(callback, [region])​

addShadow​

<instance> addShadow([x], [y], [decay], [power], [color], [samples], [intensity])​

addThreshold​

<instance> addThreshold([edge1], [edge2], [invert])​

addTiltShift​

<instance> addTiltShift([radius], [amount], [contrast], [blurX], [blurY], [strength])​

clear​

<instance> clear()​

destroy​

<instance> destroy()​

getActive​

<instance> getActive()​

remove​

<instance> remove(filter, [forceDestroy])​

Public Members

camera

camera: Phaser.Cameras.Scene2D.Camera

list

list: Array.<Phaser.Filters.Controller>

Public Methods

add

<instance> add(filter, [index])

addBarrel

<instance> addBarrel([amount])

addBlend

<instance> addBlend([texture], [blendMode], [amount], [color])

addBlocky

<instance> addBlocky([config])

addBlur

<instance> addBlur([quality], [x], [y], [strength], [color], [steps])

addBokeh

<instance> addBokeh([radius], [amount], [contrast])

addColorMatrix

<instance> addColorMatrix()

addDisplacement

<instance> addDisplacement([texture], [x], [y])

addGlow

<instance> addGlow([color], [outerStrength], [innerStrength], [scale], [knockout], [quality], [distance])

addMask

<instance> addMask([mask], [invert], [viewCamera], [viewTransform], [scaleFactor])

addParallelFilters

<instance> addParallelFilters()

addPixelate

<instance> addPixelate([amount])

addSampler

<instance> addSampler(callback, [region])

addShadow

<instance> addShadow([x], [y], [decay], [power], [color], [samples], [intensity])

addThreshold

<instance> addThreshold([edge1], [edge2], [invert])

addTiltShift

<instance> addTiltShift([radius], [amount], [contrast], [blurX], [blurY], [strength])

clear

<instance> clear()

destroy

<instance> destroy()

getActive

<instance> getActive()

remove

<instance> remove(filter, [forceDestroy])