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
-
<readonly> _resetZoom :boolean
-
Internal flag set when the game zoom factor is modified.
Type:
- boolean
- Since: 3.19.0
- Source: src/scale/ScaleManager.js (Line 263)
-
autoCenter :Phaser.Scale.CenterType
-
Automatically center the canvas within the parent? The different centering modes are:
- No centering.
- Center both horizontally and vertically.
- Center horizontally.
- 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 293)
-
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 282)
-
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 273)
-
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 321)
-
<nullable> fullscreenTarget :any
-
The DOM Element which is sent into fullscreen mode.
Type:
- any
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 330)
-
<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 1605)
-
<readonly> isFullscreen :boolean
-
Is the browser currently in fullscreen mode or not?
Type:
- boolean
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1569)
-
<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 1679)
-
<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 1660)
-
<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 1642)
-
<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 1624)
-
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 310)
-
<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 tonull
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 1586)
-
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
NONE
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
. -
<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 1544)
-
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, elsefalse
.- 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.<(string|symbol)>
-
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 1279)
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 1063)
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
Phaser.Types.Core.GameConfig The Game configuration object.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 589)
-
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 639)
Returns:
true
if the parent bounds have changed size, otherwisefalse
.- 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 681)
Returns:
true
if the orientation was successfully locked, otherwisefalse
.- 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
. -
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
. -
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
. -
onFullScreenChange()
-
Triggered when a fullscreenchange event is dispatched by the DOM.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1456)
-
onFullScreenError()
-
Triggered when a fullscreenerror event is dispatched by the DOM.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1475)
-
<protected> parseConfig(config)
-
Parses the game configuration to set-up the scale defaults.
Parameters:
Name Type Description config
Phaser.Types.Core.GameConfig The Game configuration object.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 472)
-
<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( [previousWidth] [, previousHeight])
-
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'.
Parameters:
Name Type Argument Description previousWidth
number <optional>
The previous width of the game. Only set if the gameSize has changed.
previousHeight
number <optional>
The previous height of the game. Only set if the gameSize has changed.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 899)
Fires:
Returns:
The Scale Manager instance.
-
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
. -
removeFullscreenTarget()
-
Removes the fullscreen target that was added to the DOM.
- Since: 3.17.0
- Source: src/scale/ScaleManager.js (Line 1315)
-
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
. -
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
NONE
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 (i.e. you're not using
NONE
), then see thesetGameSize
method.This method will set the
gameSize
,baseSize
anddisplaySize
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 theupdateCenter
method and the margins are set, allowing the canvas to be centered based on its parent element alone. Finally, thedisplayScale
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 780)
Fires:
Returns:
The Scale Manager instance.
-
setGameSize(width, height)
-
This method will set a new size for your game.
It should only be used if you're looking to change the base size of your game and are using one of the Scale Manager scaling modes, i.e.
FIT
. If you're usingNONE
and wish to change the game and canvas size directly, then please use theresize
method instead.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 728)
Fires:
Returns:
The Scale Manager instance.
-
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 882)
Fires:
Returns:
The Scale Manager instance.
-
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 706)
Fires:
Returns:
The Scale Manager instance.
-
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 863)
Fires:
Returns:
The Scale Manager instance.
-
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
pointerup
. 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 theallowfullscreen
attribute.On touch devices, such as Android and iOS Safari, you should always use
pointerup
and NOTpointerdown
, otherwise the request will fail unless the document in which your game is embedded has already received some form of touch input, which you cannot guarantee. Activating fullscreen viapointerup
circumvents this issue.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 directly from your game, i.e. by 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 1182)
Fires:
-
startListeners()
-
An internal method that starts the different DOM event listeners running.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1403)
-
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 1486)
-
stopFullscreen()
-
Calling this method will cancel fullscreen mode, if the browser has entered it.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1338)
Fires:
-
stopListeners()
-
Stops all DOM event listeners.
- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1518)
-
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 theallowfullscreen
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 1372)
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 1152)
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 1167)
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 1134)
-
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 thesetParentSize
method first.It works by modifying the canvas CSS
marginLeft
andmarginTop
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 toNO_CENTER
.- Since: 3.16.0
- Source: src/scale/ScaleManager.js (Line 1081)
-
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 947)
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 973)