/filters-and-postfx

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:

| Property | Type | Description | |---|---|---| | `active` | boolean | Toggle the filter on/off without removing it | | `camera` | Camera | The camera that owns this filter | | `renderNode` | string | The render node ID for the shader | | `paddingOverride` | Rectangle | Override automatic padding calculation | | `ignoreDestroy` | boolean | If true, the filter survives when its FilterList is destroyed (for reuse) |

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:

| Property | Default | Description | |---|---|---| | `filterCamera` | null -> Camera | The internal camera used for filter rendering | | `filters` | null -> {internal, external} | Access to the FilterList pair | | `renderFilters` | true | Master toggle for all filter rendering | | `filtersAutoFocus` | true | Auto-adjust camera to follow the object | | `filtersFocusContext` | false | Focus on the rendering context instead of the object bounds | | `filtersForceComposite` | false | Always draw to a framebuffer even with no active filters | | `maxFilterSize` | null -> Vector2 | Maximum texture size for filter framebuffers |

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.addGlow(0x00ff00, 4);

// Modify at runtime
glow.outerStrength = 8;
glow.color = 0xff0000;

// Temporarily disable
glow.setActive(false);

// Remove and destroy
sprite.filters.internal.remove(glow);

Camera Filters

const camera = this.cameras.main;

// Internal: effect in camera-local space
const blur = camera.filters.internal.addBlur(0, 2, 2, 1);

// External: effect in screen space
const vignette = camera.filters.external.addVignette(0.5, 0.5, 0.5, 0.5);

// Color grading via ColorMatrix
const cm = camera.filters.internal.addColorMatrix();
cm.colorMatrix.sepia();

Chaining Multiple Filters

Filters execute in list order. Each filter receives the output of the previous one:

const cam = this.cameras.main;

// First: apply color grading
const cm = cam.filters.internal.addColorMatrix();
cm.colorMatrix.brightness(0.2);

// Second: apply blur to the color-graded result
cam.filters.internal.addBlur(1, 2, 2, 1);

// Third: add a vignette on top
cam.filters.external.ad