Phaser API Documentation

  Version: 
Filter

The FX Component features a set of methods used for applying a range of special built-in effects to a Game Object.

The effects include the following:

  • Barrel Distortion
  • Bloom
  • Blur
  • Bokeh / Tilt Shift
  • Circle Outline
  • Color Matrix
  • Glow
  • Displacement
  • Gradient
  • Pixelate
  • Shine
  • Shadow
  • Vignette
  • Wipe / Reveal

All Game Objects support Post FX. These are effects applied after the Game Object has been rendered.

Texture-based Game Objects also support Pre FX, including:

  • Image
  • Sprite
  • TileSprite
  • Text
  • RenderTexture
  • Video

And any Game Object that extends the above.

The difference between Pre FX and Post FX are that all Post FX take place in a canvas (renderer) sized frame buffer, after the Game Object has been rendered. Pre FX, however, take place in a texture sized frame buffer, which is sized based on the Game Object itself. The end result is then composited back to the main game canvas. For intensive effects, such as blur, bloom or glow, which can require many iterations, this is a much more efficient way to apply the effect, as only it only has to work on a Game Object sized texture and not all pixels in the canvas.

In short, you should always try and use a Pre FX if you can.

Due to the way that FX work they can be stacked-up. For example, you can apply a blur to a Game Object, then apply a bloom effect to the same Game Object. The bloom effect will be applied to the blurred texture, not the original. Keep the order in mind when stacking effects.

All effects are WebGL only and do not have canvas counterparts.

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 component is created automatically by the PostPipeline class and does not need to be instantiated directly.

Constructor:

new FX(gameObject, isPost)

Parameters:

name type description
gameObject Phaser.GameObjects.GameObject

A reference to the Game Object that owns this FX Component.

isPost boolean

Is this a Pre or Post FX Component?

Since: 3.60.0

Members

enabled: boolean
Focus
Focus

Description:

Has this FX Component been enabled?

You should treat this property as read-only, although it is toggled automaticaly during internal use.

Type:
boolean
Since: 3.60.0
Focus
Focus
<readonly> gameObject: Phaser.GameObjects.GameObject
Focus
Focus

Description:

A reference to the Game Object that owns this FX Component.

Type:
Since: 3.60.0
Focus
Focus
<readonly> isPost: boolean
Focus
Focus

Description:

Is this a Post FX Controller? or a Pre FX Controller?

Type:
boolean
Since: 3.60.0
Focus
Focus
list: Array.<Phaser.FX.Controller>
Focus
Focus

Description:

An array containing all of the Pre FX Controllers that have been added to this FX Component. They are processed in the order they are added.

This array is empty if this is a Post FX Component.

Type:
Since: 3.60.0
Focus
Focus
padding: number
Focus
Focus

Description:

The amount of extra padding to be applied to this Game Object when it is being rendered by a PreFX Pipeline.

Lots of FX require additional spacing added to the texture the Game Object uses, for example a glow or shadow effect, and this method allows you to control how much extra padding is included in addition to the texture size.

You do not need to set this if you're only using Post FX.

Type:
number
Default: 0
Since: 3.60.0
Focus
Focus

Methods

add(fx, [config])
Focus
Focus

Description:

Adds the given FX Controler to this FX Component.

Note that adding an FX Controller does not remove any existing FX. They all stack-up on-top of each other. If you don't want this, make sure to call either remove or clear first.

Parameters:

name type arguments description
fx Phaser.FX.Controller

The FX Controller to add to this FX Component.

config object <optional>

Optional configuration object that is passed to the pipeline during instantiation.

Returns:
Description:

The FX Controller.

Since: 3.60.0
Focus
Focus
addBarrel([amount])
Focus
Focus

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 arguments Default description
amount number <optional> 1

The amount of distortion applied to the barrel effect. A value of 1 is no distortion. Typically keep this within +- 1.

Returns:
Description:

The Barrel FX Controller.

Since: 3.60.0
Focus
Focus
addBloom([color], [offsetX], [offsetY], [blurStrength], [strength], [steps])
Focus
Focus

Description:

Adds a Bloom effect.

Bloom is an effect used to reproduce an imaging artifact of real-world cameras. The effect produces fringes of light extending from the borders of bright areas in an image, contributing to the illusion of an extremely bright light overwhelming the camera or eye capturing the scene.

Parameters:

name type arguments Default description
color number <optional>

The color of the Bloom, as a hex value.

offsetX number <optional> 1

The horizontal offset of the bloom effect.

offsetY number <optional> 1

The vertical offset of the bloom effect.

blurStrength number <optional> 1

The strength of the blur process of the bloom effect.

strength number <optional> 1

The strength of the blend process of the bloom effect.

steps number <optional> 4

The number of steps to run the Bloom effect for. This value should always be an integer.

Returns:
Description:

The Bloom FX Controller.

Since: 3.60.0
Focus
Focus
addBlur([quality], [x], [y], [strength], [color], [steps])
Focus
Focus

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 arguments Default description
quality number <optional> 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 <optional> 2

The horizontal offset of the blur effect.

y number <optional> 2

The vertical offset of the blur effect.

strength number <optional> 1

The strength of the blur effect.

color number <optional> 0xffffff

The color of the blur, as a hex value.

steps number <optional> 4

The number of steps to run the blur effect for. This value should always be an integer.

Returns:
Description:

The Blur FX Controller.

Since: 3.60.0
Focus
Focus
addBokeh([radius], [amount], [contrast])
Focus
Focus

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.

See also Tilt Shift.

Parameters:

name type arguments Default description
radius number <optional> 0.5

The radius of the bokeh effect.

amount number <optional> 1

The amount of the bokeh effect.

contrast number <optional> 0.2

The color contrast of the bokeh effect.

Returns:
Description:

The Bokeh FX Controller.

Since: 3.60.0
Focus
Focus
addCircle([thickness], [color], [backgroundColor], [scale], [feather])
Focus
Focus

Description:

Adds a Circle effect.

This effect will draw a circle around the texture of the Game Object, effectively masking off any area outside of the circle without the need for an actual mask. You can control the thickness of the circle, the color of the circle and the color of the background, should the texture be transparent. You can also control the feathering applied to the circle, allowing for a harsh or soft edge.

Please note that adding this effect to a Game Object will not change the input area or physics body of the Game Object, should it have one.

Parameters:

name type arguments Default description
thickness number <optional> 8

The width of the circle around the texture, in pixels.

color number <optional> 0xfeedb6

The color of the circular ring, given as a number value.

backgroundColor number <optional> 0xff0000

The color of the background, behind the texture, given as a number value.

scale number <optional> 1

The scale of the circle. The default scale is 1, which is a circle the full size of the underlying texture.

feather number <optional> 0.005

The amount of feathering to apply to the circle from the ring.

Returns:
Description:

The Circle FX Controller.

Since: 3.60.0
Focus
Focus
addColorMatrix()
Focus
Focus

Description:

Adds a ColorMatrix 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:
Description:

The ColorMatrix FX Controller.

Since: 3.60.0
Focus
Focus
addDisplacement([texture], [x], [y])
Focus
Focus

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 arguments Default description
texture string <optional> '__WHITE'

The unique string-based key of the texture to use for displacement, which must exist in the Texture Manager.

x number <optional> 0.005

The amount of horizontal displacement to apply. A very small float number, such as 0.005.

y number <optional> 0.005

The amount of vertical displacement to apply. A very small float number, such as 0.005.

Returns:
Description:

The Displacement FX Controller.

Since: 3.60.0
Focus
Focus
addGlow([color], [outerStrength], [innerStrength], [knockout], [quality], [distance])
Focus
Focus

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 Game Object. The color and strength of the glow can be modified.

Parameters:

name type arguments Default description
color number <optional> 0xffffff

The color of the glow effect as a number value.

outerStrength number <optional> 4

The strength of the glow outward from the edge of the Sprite.

innerStrength number <optional> 0

The strength of the glow inward from the edge of the Sprite.

knockout boolean <optional> false

If true only the glow is drawn, not the texture itself.

quality number <optional> 0.1

Only available for PostFX. Sets the quality of this Glow effect. Default is 0.1. Cannot be changed post-creation.

distance number <optional> 10

Only available for PostFX. Sets the distance of this Glow effect. Default is 10. Cannot be changed post-creation.

Returns:
Description:

The Glow FX Controller.

Since: 3.60.0
Focus
Focus
addGradient([color1], [color2], [alpha], [fromX], [fromY], [toX], [toY], [size])
Focus
Focus

Description:

Adds a Gradient effect.

The gradient overlay effect is a visual technique where a smooth color transition is applied over Game Objects, such as sprites or UI components. This effect is used to enhance visual appeal, emphasize depth, or create stylistic and atmospheric variations. It can also be utilized to convey information, such as representing progress or health status through color changes.

Parameters:

name type arguments Default description
color1 number <optional> 0xff0000

The first gradient color, given as a number value.

color2 number <optional> 0x00ff00

The second gradient color, given as a number value.

alpha number <optional> 0.2

The alpha value of the gradient effect.

fromX number <optional> 0

The horizontal position the gradient will start from. This value is normalized, between 0 and 1, and is not in pixels.

fromY number <optional> 0

The vertical position the gradient will start from. This value is normalized, between 0 and 1, and is not in pixels.

toX number <optional> 0

The horizontal position the gradient will end at. This value is normalized, between 0 and 1, and is not in pixels.

toY number <optional> 1

The vertical position the gradient will end at. This value is normalized, between 0 and 1, and is not in pixels.

size number <optional> 0

How many 'chunks' the gradient is divided in to, as spread over the entire height of the texture. Leave this at zero for a smooth gradient, or set higher for a more retro chunky effect.

Returns:
Description:

The Gradient FX Controller.

Since: 3.60.0
Focus
Focus
addPixelate([amount])
Focus
Focus

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 arguments Default description
amount number <optional> 1

The amount of pixelation to apply.

Returns:
Description:

The Pixelate FX Controller.

Since: 3.60.0
Focus
Focus
addReveal([wipeWidth], [direction], [axis])
Focus
Focus

Description:

Adds a Reveal Wipe effect.

The wipe or reveal effect is a visual technique that gradually uncovers or conceals elements in the game, such as images, text, or scene transitions. This effect is often used to create a sense of progression, reveal hidden content, or provide a smooth and visually appealing transition between game states.

You can set both the direction and the axis of the wipe effect. The following combinations are possible:

  • left to right: direction 0, axis 0
  • right to left: direction 1, axis 0
  • top to bottom: direction 1, axis 1
  • bottom to top: direction 1, axis 0

It is up to you to set the progress value yourself, i.e. via a Tween, in order to transition the effect.

Parameters:

name type arguments Default description
wipeWidth number <optional> 0.1

The width of the wipe effect. This value is normalized in the range 0 to 1.

direction number <optional> 0

The direction of the wipe effect. Either 0 or 1. Set in conjunction with the axis property.

axis number <optional> 0

The axis of the wipe effect. Either 0 or 1. Set in conjunction with the direction property.

Returns:
Description:

The Wipe FX Controller.

Since: 3.60.0
Focus
Focus
addShadow([x], [y], [decay], [power], [color], [samples], [intensity])
Focus
Focus

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 arguments Default description
x number <optional> 0

The horizontal offset of the shadow effect.

y number <optional> 0

The vertical offset of the shadow effect.

decay number <optional> 0.1

The amount of decay for shadow effect.

power number <optional> 1

The power of the shadow effect.

color number <optional> 0x000000

The color of the shadow.

samples number <optional> 6

The number of samples that the shadow effect will run for. An integer between 1 and 12.

intensity number <optional> 1

The intensity of the shadow effect.

Returns:
Description:

The Shadow FX Controller.

Since: 3.60.0
Focus
Focus
addShine([speed], [lineWidth], [gradient], [reveal])
Focus
Focus

Description:

Adds a Shine effect.

The shine effect is a visual technique that simulates the appearance of reflective or glossy surfaces by passing a light beam across a Game Object. This effect is used to enhance visual appeal, emphasize certain features, and create a sense of depth or material properties.

Parameters:

name type arguments Default description
speed number <optional> 0.5

The speed of the Shine effect.

lineWidth number <optional> 0.5

The line width of the Shine effect.

gradient number <optional> 3

The gradient of the Shine effect.

reveal boolean <optional> false

Does this Shine effect reveal or get added to its target?

Returns:
Description:

The Shine FX Controller.

Since: 3.60.0
Focus
Focus
addTiltShift([radius], [amount], [contrast], [blurX], [blurY], [strength])
Focus
Focus

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.

See also Bokeh.

Parameters:

name type arguments Default description
radius number <optional> 0.5

The radius of the bokeh effect.

amount number <optional> 1

The amount of the bokeh effect.

contrast number <optional> 0.2

The color contrast of the bokeh effect.

blurX number <optional> 1

The amount of horizontal blur.

blurY number <optional> 1

The amount of vertical blur.

strength number <optional> 1

The strength of the blur.

Returns:
Description:

The Bokeh TiltShift FX Controller.

Since: 3.60.0
Focus
Focus
addVignette([x], [y], [radius], [strength])
Focus
Focus

Description:

Adds a Vignette effect.

The vignette effect is a visual technique where the edges of the screen, or a Game Object, gradually darken or blur, creating a frame-like appearance. This effect is used to draw the player's focus towards the central action or subject, enhance immersion, and provide a cinematic or artistic quality to the game's visuals.

Parameters:

name type arguments Default description
x number <optional> 0.5

The horizontal offset of the vignette effect. This value is normalized to the range 0 to 1.

y number <optional> 0.5

The vertical offset of the vignette effect. This value is normalized to the range 0 to 1.

radius number <optional> 0.5

The radius of the vignette effect. This value is normalized to the range 0 to 1.

strength number <optional> 0.5

The strength of the vignette effect.

Returns:
Description:

The Vignette FX Controller.

Since: 3.60.0
Focus
Focus
addWipe([wipeWidth], [direction], [axis])
Focus
Focus

Description:

Adds a Wipe effect.

The wipe or reveal effect is a visual technique that gradually uncovers or conceals elements in the game, such as images, text, or scene transitions. This effect is often used to create a sense of progression, reveal hidden content, or provide a smooth and visually appealing transition between game states.

You can set both the direction and the axis of the wipe effect. The following combinations are possible:

  • left to right: direction 0, axis 0
  • right to left: direction 1, axis 0
  • top to bottom: direction 1, axis 1
  • bottom to top: direction 1, axis 0

It is up to you to set the progress value yourself, i.e. via a Tween, in order to transition the effect.

Parameters:

name type arguments Default description
wipeWidth number <optional> 0.1

The width of the wipe effect. This value is normalized in the range 0 to 1.

direction number <optional> 0

The direction of the wipe effect. Either 0 or 1. Set in conjunction with the axis property.

axis number <optional> 0

The axis of the wipe effect. Either 0 or 1. Set in conjunction with the direction property.

Returns:
Description:

The Wipe FX Controller.

Since: 3.60.0
Focus
Focus
clear()
Focus
Focus

Description:

Destroys and removes all FX Controllers that are part of this FX Component, then disables it.

If this is a Pre FX Component it will only remove Pre FX. If this is a Post FX Component it will only remove Post FX.

To remove both at once use the GameObject.clearFX method instead.

Returns:
Description:

This Game Object instance.

Since: 3.60.0
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys this FX Component.

Called automatically when Game Objects are destroyed.

Since: 3.60.0
Focus
Focus
disable([clear])
Focus
Focus

Description:

Disables this FX Component.

This will reset the pipeline on the Game Object that owns this component back to its default and flag this component as disabled.

You can re-enable it again by calling enable for Pre FX or by adding an FX for Post FX.

Optionally, set clear to destroy all current FX Controllers.

Parameters:

name type arguments Default description
clear boolean <optional> false

Destroy and remove all FX Controllers that are part of this component.

Returns:
Description:

This Game Object instance.

Since: 3.60.0
Focus
Focus
enable([padding])
Focus
Focus

Description:

Enables this FX Component and applies the FXPipeline to the parent Game Object.

This is called automatically whenever you call a method such as addBloom, etc.

You can check the enabled property to see if the Game Object is already enabled, or not.

This only applies to Pre FX. Post FX are always enabled.

Parameters:

name type arguments description
padding number <optional>

The amount of padding to add to this Game Object.

Since: 3.60.0
Focus
Focus
onFX(pipeline)
Focus
Focus

Description:

This callback is invoked when this Game Object is rendered by a PreFX Pipeline.

This happens when the pipeline uses its drawSprite method.

It's invoked prior to the draw, allowing you to set shader uniforms, etc on the pipeline.

Parameters:

name type description
pipeline Phaser.Renderer.WebGL.Pipelines.PreFXPipeline

The PreFX Pipeline that invoked this callback.

Since: 3.60.0
Focus
Focus
onFXCopy(pipeline)
Focus
Focus

Description:

This callback is invoked when this Game Object is copied by a PreFX Pipeline.

This happens when the pipeline uses its copySprite method.

It's invoked prior to the copy, allowing you to set shader uniforms, etc on the pipeline.

Parameters:

name type description
pipeline Phaser.Renderer.WebGL.Pipelines.PreFXPipeline

The PreFX Pipeline that invoked this callback.

Since: 3.60.0
Focus
Focus
remove(fx)
Focus
Focus

Description:

Searches for the given FX Controller within this FX Component.

If found, the controller is removed from this component and then destroyed.

Parameters:

name type description
fx Phaser.FX.Controller

The FX Controller to remove from this FX Component.

Returns:
Description:

This Game Object instance.

Since: 3.60.0
Focus
Focus
Only webGL setPadding([padding])
Focus
Focus

Description:

Sets the amount of extra padding to be applied to this Game Object when it is being rendered by a PreFX Pipeline.

Lots of FX require additional spacing added to the texture the Game Object uses, for example a glow or shadow effect, and this method allows you to control how much extra padding is included in addition to the texture size.

You do not need to set this if you're only using Post FX.

Parameters:

name type arguments description
padding number <optional>

The amount of padding to add to this Game Object.

Returns:
Description:

This Game Object instance.

Since: 3.60.0
Focus
Focus