The Camera that owns this list.
The Camera that owns this list.
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.
Adds a filter to this list.
The filter to add.
Optionalindex: number
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.
The filter that was added.
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.
Optionalamount: number
The amount of distortion applied to the barrel effect. A value of 1 is no distortion. Typically keep this within +- 1. Default 1.
The new Barrel filter controller.
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.
Optionaltexture: string
The texture to apply to the view. Default '__WHITE'.
OptionalblendMode: BlendModes
The blend mode to apply to the view. Default Phaser.BlendModes.NORMAL.
Optionalamount: number
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. Default 1.
Optionalcolor: number[]
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. Default [1, 1, 1, 1].
The new Blend filter controller.
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.
Optionalconfig: BlockyConfig
The configuration object for the Blocky effect.
The new Blocky filter controller.
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.
Optionalquality: number
The quality of the blur effect. Can be either 0 for Low Quality, 1 for Medium Quality or 2 for High Quality. Default 0.
Optionalx: number
The horizontal offset of the blur effect. Default 2.
Optionaly: number
The vertical offset of the blur effect. Default 2.
Optionalstrength: number
The strength of the blur effect. Default 1.
Optionalcolor: number
The color of the blur, as a hex value. Default 0xffffff.
Optionalsteps: number
The number of steps to run the blur effect for. This value should always be an integer. Default 4.
The new Blur filter controller.
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.
Optionalradius: number
The radius of the bokeh effect. Default 0.5.
Optionalamount: number
The amount of the bokeh effect. Default 1.
Optionalcontrast: number
The color contrast of the bokeh effect. Default 0.2.
The new Bokeh filter controller.
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.undefined
The new ColorMatrix filter controller.
Adds a Combine Color Matrix effect.
This filter combines channels from two textures.
There are many possibilities with this.
However, a significant purpose is to manipulate alpha channels.
Use setupAlphaTransfer to configure common options,
or set the colorMatrixSelf and colorMatrixTransfer properties
directly.
Optionaltexture: string | Texture
The texture or texture key to use for the transfer texture. Default '__WHITE'.
The new CombineColorMatrix filter controller.
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.
Optionaltexture: string
The unique string-based key of the texture to use for displacement, which must exist in the Texture Manager. Default '__WHITE'.
Optionalx: number
The amount of horizontal displacement to apply. A very small float number, such as 0.005. Default 0.005.
Optionaly: number
The amount of vertical displacement to apply. A very small float number, such as 0.005. Default 0.005.
The new Displacement filter controller.
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.
Optionalcolor: number
The color of the glow effect as a number value. Default 0xffffff.
OptionalouterStrength: number
The strength of the glow outward from the edge of textures. Default 4.
OptionalinnerStrength: number
The strength of the glow inward from the edge of textures. Default 0.
Optionalscale: number
The scale of the glow effect. This multiplies the fixed distance. Default 1.
Optionalknockout: boolean
If true only the glow is drawn, not the texture itself. Default false.
Optionalquality: number
The quality of the glow effect. This cannot be changed after the filter has been created. Default 10.
Optionaldistance: number
The distance of the glow effect. This cannot be changed after the filter has been created. Default 10.
The new Glow filter controller.
Adds a GradientMap effect.
GradientMap recolors an image using a ColorRamp. The image is converted to a progress value at each point, and that progress is evaluated as a color along the ramp.
The progress value is normally the brightness of the image.
You can use the colorFactor and color properties to customize it.
Optionalconfig: GradientMapConfig
The configuration object for the GradientMap effect.
The new GradientMap filter controller.
Adds an ImageLight effect.
ImageLight is a filter for image based lighting (IBL). It is used to simulate the lighting of an image using an environment map and a normal map.
The environment map is an image that describes the lighting of the scene. This filter uses a single panorama image as the environment map. The top of the image is the sky, the bottom is the ground, and the X axis covers a full rotation. This kind of image is distorted towards the top and bottom, as the X axis is stretched wider and wider, so be careful if you're creating your own environment maps.
Cube maps are not supported by Phaser at the time of writing.
The effect is basically a reflection of the environment at infinite range. A sharp environment map will produce a sharp reflection, while a blurry environment map will produce a diffuse reflection. Use the PanoramaBlur filter to create correctly blurred environment maps. Use the NormalTools filter to manipulate the normal map if necessary, using a DynamicTexture to capture the output.
The configuration object for the ImageLight effect.
The new ImageLight filter controller.
Adds a Key effect.
The Key effect removes or isolates a specific color from an image. It can be used to remove a background color from an image, or to isolate a specific color for further processing.
By default, Key will remove pixels that match the key color.
You can instead keep only the matching pixels by setting isolate.
The threshold and feather settings control how closely the key color matches. A match is measured by "distance between color vectors"; that is, how close the RGB values of the pixel are to the RGB values of the key color.
Optionalconfig: KeyConfig
The configuration object for the Key effect.
The new Key filter controller.
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.
Optionalmask: string | GameObject
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. Default '__WHITE'.
Optionalinvert: boolean
Whether to invert the mask. Default false.
OptionalviewCamera: Camera
The Camera to use when rendering the mask with a GameObject. If not specified, uses the scene's main camera.
OptionalviewTransform: "local" | "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. Default 'world'.
OptionalscaleFactor: number
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. Default 1.
The new Mask filter controller.
Adds a NormalTools effect.
NormalTools is a filter for manipulating the normals of a normal map. It has several functions:
The output can be used for various purposes, such as:
You can even use the output as a normal map for regular lighting. Ordinarily, normal maps are loaded alongside the main texture, but you can edit this.
// Given a dynamic texture `dyn` where the filter output is drawn,
// and a texture `spiderTex` with lighting enabled,
// we can inject the WebGL texture straight into the scene lighting as a normal map.
const dynTex = dyn.getWebGLTexture();
const dynSource = new Phaser.Textures.TextureSource(spiderTex, dynTex);
spiderTex.dataSource[0] = dynSource; // This is where the normal map is located.
The configuration object for the NormalTools effect.
The new NormalTools filter controller.
Adds a PanoramaBlur effect.
PanoramaBlur is a filter for blurring a panorama image. This is intended for use with filters like ImageLight that use a panorama image as the environment map. The blur treats a rectangular map as a sphere, and applies heavy distortion close to the poles to get a correct result. You should not use it for general purpose blurring.
The effect can be very slow, as it uses a grid of samples. Total samples equals samplesX * samplesY. This can get very high, very quickly, so be careful when increasing these values. They don't need to be too high for good results.
By default, the blur is fully diffuse, sampling an entire hemisphere per point. If you reduce the radius, the effect will be more focused. Use this to control different levels of glossiness in objects using environment maps.
The configuration object for the PanoramaBlur effect.
The new PanoramaBlur filter controller.
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.undefined
The new Parallel Filters filter controller.
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.
Optionalamount: number
The amount of pixelation. A higher value creates a more pronounced effect.
The new Pixelate filter controller.
Adds a Quantize effect.
Quantization reduces the unique number of colors in an image, based on some limited number of steps per color channel. This is good for creating a retro or stylized effect.
Basic quantization breaks each channel up into a number of steps.
These steps are normally regular. You can bias them towards the top or bottom
by changing that channel's gamma value.
You can adjust the lowest step, thus all subsequent steps, with the offset.
Quantization is done in either RGBA or HSVA space.
The steps, gamma, and offset always apply in the same order,
but depending on color mode, they are either applied to
[ red, green, blue, alpha ] or [ hue, saturation, value, alpha ].
The output may optionally be dithered, to eliminate banding and create the illusion that there are many more colors in use.
Optionalconfig: QuantizeConfig
The configuration object for the Quantize effect.
The new Quantize filter controller.
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.
The callback to call with the results of the sampler.
Optionalregion: Vector2Like | Rectangle | null
The region to sample. If null, the entire camera view is sampled. If a Phaser.Types.Math.Vector2Like, a point is sampled. If a Phaser.Geom.Rectangle, the region is sampled. Default null.
The new Sampler filter controller.
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.
Optionalx: number
The horizontal offset of the shadow effect. Default 0.
Optionaly: number
The vertical offset of the shadow effect. Default 0.
Optionaldecay: number
The amount of decay for the shadow effect. Default 0.1.
Optionalpower: number
The power of the shadow effect. Default 1.
Optionalcolor: number
The color of the shadow, as a hex value. Default 0x000000.
Optionalsamples: number
The number of samples that the shadow effect will run for. Default 6.
Optionalintensity: number
The intensity of the shadow effect. Default 1.
The new Shadow filter controller.
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.
Optionaledge1: number | number[]
The first edge of the threshold. This may be an array of the RGBA channels, or a single number for all 4 channels. Default 0.5.
Optionaledge2: number | number[]
The second edge of the threshold. This may be an array of the RGBA channels, or a single number for all 4 channels. Default 0.5.
Optionalinvert: boolean | boolean[]
Whether each channel is inverted. This may be an array of the RGBA channels, or a single boolean for all 4 channels. Default false.
The new Threshold filter controller.
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.
Optionalradius: number
The radius of the bokeh effect.
Optionalamount: number
The amount of the bokeh effect.
Optionalcontrast: number
The color contrast of the bokeh effect.
OptionalblurX: number
The amount of horizontal blur.
OptionalblurY: number
The amount of vertical blur.
Optionalstrength: number
The strength of the blur.
The new Bokeh filter controller.
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.
This filter supports colored borders, and a limited set of blend modes, to increase its stylistic power.
Optionalx: number
The horizontal offset of the vignette effect. This value is normalized to the range 0 to 1. Default 0.5.
Optionaly: number
The vertical offset of the vignette effect. This value is normalized to the range 0 to 1. Default 0.5.
Optionalradius: number
The radius of the vignette effect. This value is normalized to the range 0 to 1. Default 0.5.
Optionalstrength: number
The strength of the vignette effect. Default 0.5.
Optionalcolor: string | number | Color | InputColorObject
The color of the vignette effect, as a hex code or Color object. Default 0x000000.
OptionalblendMode: number
The blend mode to use with the vignette. Only NORMAL, ADD, MULTIPLY, and SCREEN are supported. Default Phaser.BlendModes.NORMAL.
The new Vignette filter controller.
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:
It is up to you to set the progress value yourself, e.g. via a Tween, in order to transition the effect.
OptionalwipeWidth: number
The width of the wipe effect. This value is normalized in the range 0 to 1. Default 0.1.
Optionaldirection: number
The direction of the wipe effect. Either 0 (left to right, or top to bottom) or 1 (right to left, or bottom to top). Set in conjunction with the axis property. Default 0.
Optionalaxis: number
The axis of the wipe effect. Either 0 (X) or 1 (Y). Set in conjunction with the direction property. Default 0.
Optionalreveal: number
Is this a reveal (1) or a fade (0) effect? Reveal shows the input in wiped areas; fade shows the input in unwiped areas. Default 0.
OptionalwipeTexture: string | Texture
Texture or texture key to use where the input texture is not shown. The default texture is blank. Use another texture for a wipe transition. Default '__DEFAULT'.
Destroys and removes all filters in this list.undefined
This FilterList instance.
Destroys this FilterList.
Returns all active filters in this list.undefined
The active filters in this list.
Removes a filter from this list, then destroys it.
The filter to remove.
OptionalforceDestroy: boolean
If true, the filter will be destroyed even if it has the ignoreDestroy flag set. Default false.
This FilterList instance.
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:
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:
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.