name: filters-and-postfx

description: "Use this skill when applying visual filters or post-processing effects in Phaser 4. Covers bloom, blur, glow, color matrix, barrel distortion, displacement, custom shaders, and the filter pipeline. Triggers on: filter, post-processing, shader, bloom, blur, glow, color effects."

Phaser 4 Filters and Post-FX

Quick Start

Add a glow effect to a sprite:

// In your Scene's create() method:
const sprite = this.add.sprite(400, 300, 'player');

// Step 1: Enable the filter system on the game object (WebGL only)
sprite.enableFilters();

// Step 2: Add filters via .filters.internal or .filters.external
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);

Add a blur to the camera:

// Cameras have filters enabled by default - no enableFilters() needed
const camera = this.cameras.main;
camera.filters.internal.addBlur(0, 2, 2, 1);

Core Concepts

How Filters Work in v4

Filters are GPU-based post-processing effects applied after an object or camera renders to a texture. Each filter runs a shader pass over that texture, producing the final visual output. Filters are WebGL only.

The rendering pipeline for a camera with filters:

1. Objects render to a texture the size of the camera.
2. Internal filters process that texture, applying effects in object/camera local space.
3. The texture is drawn to a context-sized texture, applying camera transformations (position, rotation, zoom).
4. External filters process that context texture, applying effects in screen space.
5. The final texture is composited into the output.

Internal vs External Filters

Every FilterList exposes two sub-lists: filters.internal and filters.external. The distinction controls when the filter runs relative to the camera/object transform:

• Internal -- applied before the camera transform. Effects operate in the object's local coordinate space. A horizontal blur on a rotated object appears rotated with the object. Internal filters only cover the object/camera region, so they are cheaper.
• External -- applied after the camera transform. Effects operate in screen space. A horizontal blur on a rotated object always blurs horizontally on screen. External filters are full-screen and more expensive.

Use internal filters wherever possible for better performance.

FilterList

FilterList (Phaser.GameObjects.Components.FilterList) is the container that holds filter controllers. It provides:

• add(filter, index) -- add a Controller instance at an optional index
• remove(filter, forceDestroy) -- remove and destroy a filter
• clear() -- remove and destroy all filters
• getActive() -- return all filters where active === true
• list -- the raw array of Controllers (safe to reorder)
• Convenience factory methods: addBlur(), addGlow(), addMask(), etc.

Filter Controllers

Every filter is a Phaser.Filters.Controller subclass. Common Controller properties:

Key methods: setActive(bool), setPaddingOverride(left, top, right, bottom), getPadding(), destroy().

Enabling Filters on Game Objects

Cameras have filters available by default. Game objects do not -- you must call enableFilters() first:

const sprite = this.add.sprite(400, 300, 'hero');
sprite.enableFilters();

// Now sprite.filters is available
sprite.filters.internal.addGlow();
sprite.filters.external.addVignette();

enableFilters() creates an internal filterCamera on the game object that handles rendering the object to a texture for filter processing. It returns this for chaining.

Related properties on game objects after enabling:

Use willRenderFilters() to check if any active filters will actually render.

Common Patterns

Adding Filters to Game Objects

const sprite = this.add.sprite(400, 300, 'enemy');
sprite.enableFilters();

// Add a glow
const glow = sprite.filters.internal.addGlo