Class: ScaleManager

Phaser.Scale. ScaleManager

The Scale Manager handles the scaling, resizing and alignment of the game canvas.

The way scaling is handled is by setting the game canvas to a fixed size, which is defined in the game configuration. You also define the parent container in the game config. If no parent is given, it will default to using the document body. The Scale Manager will then look at the available space within the parent and scale the canvas accordingly. Scaling is handled by setting the canvas CSS width and height properties, leaving the width and height of the canvas element itself untouched. Scaling is therefore achieved by keeping the core canvas the same size and 'stretching' it via its CSS properties. This gives the same result and speed as using the transform-scale CSS property, without the need for browser prefix handling.

The calculations for the scale are heavily influenced by the bounding parent size, which is the computed dimensions of the canvas's parent. The CSS rules of the parent element play an important role in the operation of the Scale Manager. For example, if the parent has no defined width or height, then actions like auto-centering will fail to achieve the required result. The Scale Manager works in tandem with the CSS you set-up on the page hosting your game, rather than taking control of it.

Parent and Display canvas containment guidelines:

  • Style the Parent element (of the game canvas) to control the Parent size and thus the games size and layout.

  • The Parent element's CSS styles should effectively apply maximum (and minimum) bounding behavior.

  • The Parent element should not apply a padding as this is not accounted for. If a padding is required apply it to the Parent's parent or apply a margin to the Parent. If you need to add a border, margin or any other CSS around your game container, then use a parent element and apply the CSS to this instead, otherwise you'll be constantly resizing the shape of the game container.

  • The Display canvas layout CSS styles (i.e. margins, size) should not be altered / specified as they may be updated by the Scale Manager.

Scale Modes

The way the scaling is handled is determined by the scaleMode property. The default is NO_SCALE, which prevents Phaser from scaling or touching the canvas, or its parent, at all. In this mode, you are responsible for all scaling. The other scaling modes afford you automatic scaling.

If you wish to scale your game so that it always fits into the available space within the parent, you should use the scale mode FIT. Look at the documentation for other scale modes to see what options are available. Here is a basic config showing how to set this scale mode:

scale: {
    parent: 'yourgamediv',
    mode: Phaser.Scale.FIT,
    width: 800,
    height: 600
}

Place the scale config object within your game config.

If you wish for the canvas to be resized directly, so that the canvas itself fills the available space (i.e. it isn't scaled, it's resized) then use the RESIZE scale mode. This will give you a 1:1 mapping of canvas pixels to game size. In this mode CSS isn't used to scale the canvas, it's literally adjusted to fill all available space within the parent. You should be extremely careful about the size of the canvas you're creating when doing this, as the larger the area, the more work the GPU has to do and it's very easy to hit fill-rate limits quickly.

For complex, custom-scaling requirements, you should probably consider using the RESIZE scale mode, with your own limitations in place re: canvas dimensions and managing the scaling with the game scenes yourself. For the vast majority of games, however, the FIT mode is likely to be the most used.

Please appreciate that the Scale Manager cannot perform miracles. All it does is scale your game canvas as best it can, based on what it can infer from its surrounding area. There are all kinds of environments where it's up to you to guide and help the canvas position itself, especially when built into rendering frameworks like React and Vue. If your page requires meta tags to prevent user scaling gestures, or such like, then it's up to you to ensure they are present in the html.

Centering

You can also have the game canvas automatically centered. Again, this relies heavily on the parent being properly configured and styled, as the centering offsets are based entirely on the available space within the parent element. Centering is disabled by default, or can be applied horizontally, vertically, or both. Here's an example:

scale: {
    parent: 'yourgamediv',
    autoCenter: Phaser.Scale.CENTER_BOTH,
    width: 800,
    height: 600
}

Fullscreen API

If the browser supports it, you can send your game into fullscreen mode. In this mode, the game will fill the entire display, removing all browser UI and anything else present on the screen. It will remain in this mode until your game either disables it, or until the user tabs out or presses ESCape if on desktop. It's a great way to achieve a desktop-game like experience from the browser, but it does require a modern browser to handle it. Some mobile browsers also support this.


new ScaleManager(game)

Parameters:
Name Type Description
game Phaser.Game

A reference to the Phaser.Game instance.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 21)

Extends

Members


autoCenter :Phaser.Scale.CenterType

Automatically center the canvas within the parent? The different centering modes are:

  1. No centering.
  2. Center both horizontally and vertically.
  3. Center horizontally.
  4. Center vertically.

Please be aware that in order to center the game canvas, you must have specified a parent that has a size set, or the canvas parent is the document.body.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 283)

autoRound :boolean

If set, the canvas sizes will be automatically passed through Math.floor. This results in rounded pixel display values, which is important for performance on legacy and low powered devices, but at the cost of not achieving a 'perfect' fit in some browser windows.

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 272)

baseSize :Phaser.Structs.Size

The Base Size component.

The modified game size, which is the gameSize * resolution, used to set the canvas width and height (but not the CSS style)

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 204)

canvas :HTMLCanvasElement

A reference to the HTML Canvas Element that Phaser uses to render the game.

Type:
  • HTMLCanvasElement
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 144)

canvasBounds :Phaser.Geom.Rectangle

The DOM bounds of the canvas element.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 153)

dirty :boolean

The dirty state of the Scale Manager. Set if there is a change between the parent size and the current size.

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 349)

displayScale :Phaser.Math.Vector2

The scale factor between the baseSize and the canvasBounds.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 263)

displaySize :Phaser.Structs.Size

The Display Size component.

The size used for the canvas style, factoring in the scale mode, parent and other values.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 216)

fullscreen :Phaser.Device.Fullscreen

A reference to the Device.Fullscreen object.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 311)

<nullable> fullscreenTarget :any

The DOM Element which is sent into fullscreen mode.

Type:
  • any
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 320)

<readonly> game :Phaser.Game

A reference to the Phaser.Game instance.

Type:
Since: 3.15.0
Source: src/scale/ScaleManager.js (Line 134)

gameSize :Phaser.Structs.Size

The Game Size component.

The un-modified game size, as requested in the game config (the raw width / height), as used for world bounds, cameras, etc

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 192)

<readonly> height :number

The game height.

This is typically the size given in the game configuration.

Type:
  • number
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1508)

<readonly> isFullscreen :boolean

Is the browser currently in fullscreen mode or not?

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1472)

<readonly> isGameLandscape :boolean

Are the game dimensions landscape? (i.e. wider than they are tall)

This is different to the device itself being in a landscape orientation.

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1582)

<readonly> isGamePortrait :boolean

Are the game dimensions portrait? (i.e. taller than they are wide)

This is different to the device itself being in a portrait orientation.

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1563)

<readonly> isLandscape :boolean

Is the device in a landscape orientation as reported by the Orientation API? This value is usually only available on mobile devices.

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1545)

<readonly> isPortrait :boolean

Is the device in a portrait orientation as reported by the Orientation API? This value is usually only available on mobile devices.

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1527)

orientation :Phaser.Scale.OrientationType

The current device orientation.

Orientation events are dispatched via the Device Orientation API, typically only on mobile browsers.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 300)

<nullable> parent :any

The parent object of the Canvas. Often a div, or the browser window, or nothing in non-browser environments.

This is set in the Game Config as the parent property. If undefined (or just not present), it will default to use the document body. If specifically set to null Phaser will ignore all parent operations.

Type:
  • any
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 162)

parentIsWindow :boolean

Is the parent element the browser window?

Type:
  • boolean
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 174)

parentSize :Phaser.Structs.Size

The Parent Size component.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 183)

resizeInterval :integer

How many milliseconds should elapse before checking if the browser size has changed?

Most modern browsers dispatch a 'resize' event, which the Scale Manager will listen for. However, older browsers fail to do this, or do it consistently, so we fall back to a more traditional 'size check' based on a time interval. You can control how often it is checked here.

Type:
  • integer
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 359)

resolution :number

The canvas resolution.

This is hard-coded to a value of 1 in the 3.16 release of Phaser and will be enabled at a later date.

Type:
  • number
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 236)

scaleMode :Phaser.Scale.ScaleModeType

The game scale mode.

Type:
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 227)

<readonly> width :number

The game width.

This is typically the size given in the game configuration.

Type:
  • number
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1489)

zoom :number

The game zoom factor.

This value allows you to multiply your games base size by the given zoom factor. This is then used when calculating the display size, even in NO_SCALE situations. If you don't want Phaser to touch the canvas style at all, this value should be 1.

Can also be set to MAX_ZOOM in which case the zoom value will be derived based on the game size and available space within the parent.

Type:
  • number
Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 247)

Methods


addListener(event, fn [, context])

Add a listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.

fn function

The listener function.

context * <optional>
this

The context to invoke the listener with.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 111)
Returns:

this.

Type
Phaser.Events.EventEmitter

<protected> boot()

The Boot handler is called by Phaser.Game when it first starts up. The renderer is available by now and the canvas has been added to the DOM.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 427)
Fires:

destroy()

Destroys this Scale Manager, releasing all references to external resources. Once destroyed, the Scale Manager cannot be used again.

Since: 3.16.0
Overrides:
Source: src/scale/ScaleManager.js (Line 1448)

emit(event [, args])

Calls each of the listeners registered for a given event.

Parameters:
Name Type Argument Description
event string | symbol

The event name.

args * <optional>
<repeatable>

Additional arguments that will be passed to the event handler.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 86)
Returns:

true if the event had listeners, else false.

Type
boolean

eventNames()

Return an array listing the events for which the emitter has registered listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 55)
Returns:
Type
array

getFullscreenTarget()

An internal method that gets the target element that is used when entering fullscreen mode.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1198)
Returns:

The fullscreen target element.

Type
object

getMaxZoom()

Calculates and returns the largest possible zoom factor, based on the current parent and game sizes. If the parent has no dimensions (i.e. an unstyled div), or is smaller than the un-zoomed game, then this will return a value of 1 (no zoom)

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1016)
Returns:

The maximum possible zoom factor. At a minimum this value is always at least 1.

Type
integer

getParent(config)

Determines the parent element of the game canvas, if any, based on the game configuration.

Parameters:
Name Type Description
config GameConfig

The Game configuration object.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 583)

getParentBounds()

Calculates the size of the parent bounds and updates the parentSize component, if the canvas has a dom parent.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 633)
Returns:

true if the parent bounds have changed size, otherwise false.

Type
boolean

listenerCount(event)

Return the number of listeners listening to a given event.

Parameters:
Name Type Description
event string | symbol

The event name.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 75)
Returns:

The number of listeners.

Type
number

lockOrientation(orientation)

Attempts to lock the orientation of the web browser using the Screen Orientation API.

This API is only available on modern mobile browsers. See https://developer.mozilla.org/en-US/docs/Web/API/Screen/lockOrientation for details.

Parameters:
Name Type Description
orientation string

The orientation you'd like to lock the browser in. Should be an API string such as 'landscape', 'landscape-primary', 'portrait', etc.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 675)
Returns:

true if the orientation was successfully locked, otherwise false.

Type
boolean

off(event [, fn] [, context] [, once])

Remove the listeners of a given event.

Parameters:
Name Type Argument Description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 151)
Returns:

this.

Type
Phaser.Events.EventEmitter

on(event, fn [, context])

Add a listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.

fn function

The listener function.

context * <optional>
this

The context to invoke the listener with.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 98)
Returns:

this.

Type
Phaser.Events.EventEmitter

once(event, fn [, context])

Add a one-time listener for a given event.

Parameters:
Name Type Argument Default Description
event string | symbol

The event name.

fn function

The listener function.

context * <optional>
this

The context to invoke the listener with.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 124)
Returns:

this.

Type
Phaser.Events.EventEmitter

onFullScreenChange()

Triggered when a fullscreenchange event is dispatched by the DOM.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1363)

onFullScreenError()

Triggered when a fullscreenerror event is dispatched by the DOM.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1380)

<protected> parseConfig(config)

Parses the game configuration to set-up the scale defaults.

Parameters:
Name Type Description
config GameConfig

The Game configuration object.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 471)

<protected> preBoot()

Called before the canvas object is created and added to the DOM.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 411)
Listens to Events:

refresh()

Refreshes the internal scale values, bounds sizes and orientation checks.

Once finished, dispatches the resize event.

This is called automatically by the Scale Manager when the browser window size changes, as long as it is using a Scale Mode other than 'NONE'.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 875)
Fires:
Returns:

The Scale Manager instance.

Type
Phaser.Scale.ScaleManager

removeAllListeners( [event])

Remove all listeners, or those of the specified event.

Parameters:
Name Type Argument Description
event string | symbol <optional>

The event name.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 165)
Returns:

this.

Type
Phaser.Events.EventEmitter

removeListener(event [, fn] [, context] [, once])

Remove the listeners of a given event.

Parameters:
Name Type Argument Description
event string | symbol

The event name.

fn function <optional>

Only remove the listeners that match this function.

context * <optional>

Only remove the listeners that have this context.

once boolean <optional>

Only remove one-time listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 137)
Returns:

this.

Type
Phaser.Events.EventEmitter

resize(width, height)

Call this to modify the size of the Phaser canvas element directly. You should only use this if you are using the NO_SCALE scale mode, it will update all internal components completely.

If all you want to do is change the size of the parent, see the setParentSize method.

If all you want is to change the base size of the game, but still have the Scale Manager manage all the scaling, then see the setGameSize method.

This method will set the gameSize, baseSize and displaySize components to the given dimensions. It will then resize the canvas width and height to the values given, by directly setting the properties. Finally, if you have set the Scale Manager zoom value to anything other than 1 (the default), it will set the canvas CSS width and height to be the given size multiplied by the zoom factor (the canvas pixel size remains untouched).

If you have enabled autoCenter, it is then passed to the updateCenter method and the margins are set, allowing the canvas to be centered based on its parent element alone. Finally, the displayScale is adjusted and the RESIZE event dispatched.

Parameters:
Name Type Description
width number

The new width of the game.

height number

The new height of the game.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 759)
Fires:
Returns:

The Scale Manager instance.

Type
Phaser.Scale.ScaleManager

setGameSize(width, height)

This method will set a new size for your game.

Parameters:
Name Type Description
width number

The new width of the game.

height number

The new height of the game.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 722)
Fires:
Returns:

The Scale Manager instance.

Type
Phaser.Scale.ScaleManager

setMaxZoom()

Sets the zoom to be the maximum possible based on the current parent size.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 859)
Fires:
Returns:

The Scale Manager instance.

Type
Phaser.Scale.ScaleManager

setParentSize(width, height)

This method will set the size of the Parent Size component, which is used in scaling and centering calculations. You only need to call this method if you have explicitly disabled the use of a parent in your game config, but still wish to take advantage of other Scale Manager features.

Parameters:
Name Type Description
width number

The new width of the parent.

height number

The new height of the parent.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 700)
Fires:
Returns:

The Scale Manager instance.

Type
Phaser.Scale.ScaleManager

setZoom(value)

Sets the zoom value of the Scale Manager.

Parameters:
Name Type Description
value integer

The new zoom value of the game.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 841)
Fires:
Returns:

The Scale Manager instance.

Type
Phaser.Scale.ScaleManager

shutdown()

Removes all listeners.

Since: 3.0.0
Inherited From:
Source: src/events/EventEmitter.js (Line 31)

startFullscreen( [fullscreenOptions])

Sends a request to the browser to ask it to go in to full screen mode, using the Fullscreen API.

If the browser does not support this, a FULLSCREEN_UNSUPPORTED event will be emitted.

This method must be called from a user-input gesture, such as pointerdown. You cannot launch games fullscreen without this, as most browsers block it. Games within an iframe will also be blocked from fullscreen unless the iframe has the allowfullscreen attribute.

Performing an action that navigates to another page, or opens another tab, will automatically cancel fullscreen mode, as will the user pressing the ESC key. To cancel fullscreen mode from your game, i.e. from clicking an icon, call the stopFullscreen method.

A browser can only send one DOM element into fullscreen. You can control which element this is by setting the fullscreenTarget property in your game config, or changing the property in the Scale Manager. Note that the game canvas must be a child of the target. If you do not give a target, Phaser will automatically create a blank <div> element and move the canvas into it, before going fullscreen. When it leaves fullscreen, the div will be removed.

Parameters:
Name Type Argument Description
fullscreenOptions object <optional>

The FullscreenOptions dictionary is used to provide configuration options when entering full screen.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1135)
Fires:

startListeners()

An internal method that starts the different DOM event listeners running.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1310)

step(time, delta)

Internal method, called automatically by the game step. Monitors the elapsed time and resize interval to see if a parent bounds check needs to take place.

Parameters:
Name Type Description
time number

The time value from the most recent Game step. Typically a high-resolution timer value, or Date.now().

delta number

The delta value since the last frame. This is smoothed to avoid delta spikes by the TimeStep class.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1390)

stopFullscreen()

Calling this method will cancel fullscreen mode, if the browser has entered it.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1234)
Fires:

stopListeners()

Stops all DOM event listeners.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1422)

toggleFullscreen( [fullscreenOptions])

Toggles the fullscreen mode. If already in fullscreen, calling this will cancel it. If not in fullscreen, this will request the browser to enter fullscreen mode.

If the browser does not support this, a FULLSCREEN_UNSUPPORTED event will be emitted.

This method must be called from a user-input gesture, such as pointerdown. You cannot launch games fullscreen without this, as most browsers block it. Games within an iframe will also be blocked from fullscreen unless the iframe has the allowfullscreen attribute.

Parameters:
Name Type Argument Description
fullscreenOptions object <optional>

The FullscreenOptions dictionary is used to provide configuration options when entering full screen.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1279)
Fires:

transformX(pageX)

Transforms the pageX value into the scaled coordinate space of the Scale Manager.

Parameters:
Name Type Description
pageX number

The DOM pageX value.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1105)
Returns:

The translated value.

Type
number

transformY(pageY)

Transforms the pageY value into the scaled coordinate space of the Scale Manager.

Parameters:
Name Type Description
pageY number

The DOM pageY value.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1120)
Returns:

The translated value.

Type
number

updateBounds()

Updates the canvasBounds rectangle to match the bounding client rectangle of the canvas element being used to track input events.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1087)

updateCenter()

Calculates and updates the canvas CSS style in order to center it within the bounds of its parent. If you have explicitly set parent to be null in your game config then this method will likely give incorrect results unless you have called the setParentSize method first.

It works by modifying the canvas CSS marginLeft and marginTop properties.

If they have already been set by your own style sheet, or code, this will overwrite them.

To prevent the Scale Manager from centering the canvas, either do not set the autoCenter property in your game config, or make sure it is set to NO_CENTER.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 1034)

updateOrientation()

Internal method that checks the current screen orientation, only if the internal check flag is set.

If the orientation has changed it updates the orientation property and then dispatches the orientation change event.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 902)
Fires:

updateScale()

Internal method that manages updating the size components based on the scale mode.

Since: 3.16.0
Source: src/scale/ScaleManager.js (Line 928)