name: cameras

description: "Use this skill when working with cameras in Phaser 4. Covers camera effects (shake, fade, flash, pan, zoom), following sprites, scroll, bounds, viewports, multiple cameras, and minimap. Triggers on: camera, viewport, scroll, zoom, follow, shake, fade."

Cameras

Camera system in Phaser 4 -- CameraManager, main camera, viewport vs scroll, zoom, bounds, following sprites, camera effects (fade, flash, shake, pan, zoomTo, rotateTo), ignore lists, filters, and keyboard controls.

Key source paths: src/cameras/2d/CameraManager.js, src/cameras/2d/BaseCamera.js, src/cameras/2d/Camera.js, src/cameras/2d/effects/, src/cameras/controls/

Related skills: ../game-setup-and-config/SKILL.md, ../sprites-and-images/SKILL.md, ../filters-and-postfx/SKILL.md

Quick Start

// In a Scene's create() method:

// Access the default camera (created automatically)
const cam = this.cameras.main;

// Scroll the camera to look at a different part of the world
cam.setScroll(200, 100);

// Center camera on a world coordinate
cam.centerOn(400, 300);

// Zoom in (2x) -- values < 1 zoom out, > 1 zoom in
cam.setZoom(2);

// Follow a sprite with smooth lerp
cam.startFollow(player, false, 0.1, 0.1);

// Constrain the camera to the world bounds
cam.setBounds(0, 0, 2048, 2048);

// Fade in from black over 1 second
cam.fadeIn(1000);

// Add a filter to the camera (v4 feature)
cam.filters.external.addBlur(1, 2);

Core Concepts

CameraManager

Every Scene has a CameraManager accessible via this.cameras. It manages all cameras for that Scene and is registered as a plugin under the key 'CameraManager'.

// The manager is at this.cameras (not this.camera)
this.cameras              // CameraManager instance
this.cameras.cameras      // Array of Camera objects (render order)
this.cameras.main         // Reference to the "main" camera (first one by default)
this.cameras.default      // Un-transformed utility camera (not in the cameras array)

Key methods on CameraManager:

Camera limit: The manager supports up to 32 cameras that can use ignore() for Game Object exclusion (IDs are bitmasks). Cameras beyond 32 get ID 0 and cannot exclude objects.

Main Camera

The main property is a convenience reference to a Camera, typically cameras[0]. It is set automatically when:

• The scene boots (first camera created becomes main)
• You pass makeMain: true to add() or addExisting()
• The current main camera is removed (falls back to cameras[0])

Viewport vs World (Scroll)

A Camera has two independent coordinate concepts:

1. Viewport -- The physical rectangle on the canvas where the Camera renders. Controlled by setPosition(x, y), setSize(w, h), or setViewport(x, y, w, h). By default, fills the entire game canvas.

1. Scroll -- Where the Camera is "looking" in the game world. Controlled by scrollX / scrollY properties or setScroll(x, y). Scrolling does not affect the viewport rectangle.

// Viewport: a 320x200 mini-map in the top-right corner
const miniCam = this.cameras.add(480, 0, 320, 200);

// Scroll: make the mini-map look at a different world area
miniCam.setScroll(1000, 500);

// Zoom: the mini-cam shows more of the world
miniCam.setZoom(0.25);

worldView is a read-only Rectangle updated each frame that reflects what area of the world the camera can currently see, accounting for scroll, zoom, and bounds. Use it for culling or intersection checks.

const view = cam.worldView; // { x, y, width, height }

Common Patterns

Scrolling the Camera

// Direct property access
cam.scrollX = 100;
cam.scrollY = 200;

// Chainable setter
cam.setScroll(100, 200);

// Center the camera on a world coordinate
cam.centerOn(500, 400);

// Get the scroll values needed to center on a point (without moving)
const point = cam.getScroll(500, 400); // returns Vector2

Following a Sprite

// Instant follow (lerp = 1, the default)
cam.startFollow(player);

// Smooth follow with lerp (0..1, lower = smoother)