Cameras - samme/phaser3-faq GitHub Wiki

Four cameras showing a giant robot

Cameras display the game objects in a scene. You create or access them from the scene camera manager, this.cameras. By default each scene has one camera, which you can use from this.cameras.main or this.cameras.cameras[0].

If you create multiple cameras then main is used as the default in some Phaser functions that accept a camera argument. You can assign any camera as main.

this.cameras.default is a non-rendering camera that represents a camera's default state (not resized or transformed).

Cameras are recreated each time the scene starts, so don't keep any references to them.

A camera has two distinct coordinate spaces, its viewport and world view.

Viewport	World view
`x`	`worldView.x` or `worldView.left`
`y`	`worldView.y` or `worldView.top`
`width`	`displayWidth` or `worldView.width`
`height`	`displayHeight` or `worldView.height`
`centerX`	`midPoint.x` or `worldView.centerX`
`centerY`	`midPoint.y` or `worldView.centerY`

Viewport

The camera viewport is its "window" or visible area on the game canvas. x (left), y (top), width, height, centerX, centerY, setSize(), and setViewport() all refer to the viewport. By default the camera viewport is identical to the game viewport, i.e.,

{ x: 0, y: 0, width: this.scale.width, height: this.scale.height }

World view

The camera worldView is the area of the game world it can "see", based on its scroll, rotation, and zoom, in game world coordinates. midPoint, displayWidth, and displayHeight refer to this view area.

midPoint and worldView are updated only after the first scene render. If you need to use these earlier than that, use

function create () {
  // …
  this.cameras.main.preRender();
}

If you never scroll, zoom, or rotate a camera then its world view is identical to its viewport.

Scrolling

scrollX, scrollY are the camera scroll coordinates, where (0, 0) is the initial scroll position. They represent the distance between the top-left of the camera's world view and its viewport. So increasing scrollX and scrollY moves the camera view down and to the right or the game world objects up and to the left, depending on your perspective.

setScroll(x, y) sets scrollX and scrollY directly.

centerOn(x, y) and pan(x, y) also scroll the camera, but their arguments refer to the camera's midPoint, so they are often a more natural choice.

Scroll coordinates are unzoomed.

Culling

Cull and hide

Input

Interactive game objects respond to pointer input on any visible camera, unless you set the camera's inputEnabled to false.

Rendering

You can change each camera's roundPixels property. By default it's the same value you set in the game config, or false.

startFollow() also sets the camera's roundPixels property, even if the roundPixels argument is omitted.

Bounds

Camera bounds limit the camera's scroll movement: e.g., if the right edge of the camera meets the right edge of the camera bounds, then the camera will stop scrolling rightward. Camera bounds are in world coordinates. By default there are no bounds, so the camera view can move anywhere.

If the camera world view is smaller than the bounds (e.g. you set them too small or you zoomed the camera out), then only the top and left edges of the bounds take effect.

Follow

camera.startFollow(target, roundPixels, lerpX, lerpY, offsetX, offsetY)

target can be a game object or point-like object.

The camera scrolls automatically to keep the target in the center of the viewport. The optional lerpX and lerpY arguments smooth the movement by interpolating the two positions.

The camera deadzone (if set) is an area where the follow target can move (relative to the viewport) without scrolling the camera. The deadzone is always centered on the follow target, in world coordinates.

Camera follow midpoint of two sprites

Effects

Cameras have timed fade, flash, pan, rotate, shake, and zoom effects. See the methods for details. Most methods won't interrupt an ongoing effect unless you pass force = true. You can reset a given effect with, e.g., fadeEffect.reset() or flashEffect.reset(). You can monitor an ongoing effect with, e.g., fadeEffect.isRunning, fadeEffect.progress, etc.

You shouldn't start a camera effect during every update. For that you should be using methods like centerOn(), setRotation(), setZoom() instead.

fadeOut() is usually paired with fadeIn().

You can pass a callback or register an event handler (usually with once()) on the camera to act on the event completion.

You can reset all effects by calling the camera's resetFX() method.

You can also tween some camera properties (alpha, rotation, scrollX, scrollY, zoom) yourself instead of using the effects.