Types
Fit
type Fit = 'letterbox' | 'height' | 'fill' | 'fixed'From @phaser-ae/kernel
How the logical screen maps onto the page; see ScreenPolicy.fit.
ScreenPolicy
interface ScreenPolicyFrom @phaser-ae/kernel
How the logical screen maps onto the page.
safe?: Readonly<{ top: number; right: number; bottom: number; left: number }>— Written by the engine: the insets, in logical pixels, that notches, rounded corners and the software keyboard take from the canvas. Zero headless.width: number— Logical width in pixels; what worlds and HUDs see. Under'height'and'fill'this is the STARTING width — the host's aspect sets it from then on, so read it, never assume it.height: number— Logical height in pixels.fit: Fit— How the logical screen maps onto the host. -'letterbox'— scale to fit the host, keeping the aspect and the logical size. Bars where the aspect does not match. -'height'— fill the host, keepingheightas the logical height and taking the WIDTH from the host's aspect. Nothing is cropped and there are no bars: a wider window simply sees more world at the same scale. This is what a game or a demo that should fill the page almost always wants, and it is the only fit where the author can rely on a fixed scale — readwidthat runtime rather than assuming it (world.view,world.vw/vh,screen.vw/vh). -'fill'— the logical size BECOMES the host size, so one logical pixel is one CSS pixel and the scale changes with the window. For a page-sized UI, not for a world. -'fixed'— the canvas iswidth×heightCSS pixels, whatever size the host is.cssScale?: number— CSS pixels per LOGICAL pixel — written by the engine, on every resize, exactly aswidthandheightare under'fill'and'height'. 1 headless, and 1 whenever the two coincide. It is the only way to ask for a REAL size. A logical pixel is whatever the fit made it: a game authored 270 logical pixels wide on a 928px canvas has acssScaleof 3.44, so its 10-unit HUD text lands as 34 CSS pixels. That is the right default — a HUD that scales with the game looks deliberate on any display — and10 / cssScaleis how to say "ten CSS pixels" when it is not (world-screen'sscreen.px(10)does the same).pixelArt?: boolean— Nearest-neighbour magnification for pixel art; backends read it. Default false.dprCap?: number— Highest device pixel ratio to render at: the backing store is the CSS size × min(devicePixelRatio, dprCap). Default 2.background?: string— The colour the frame is cleared to,'#rrggbb'or'#rrggbbaa'. Default a near-black'#14171c'. Anything a game draws behind everything else — a sky, a parallax, a backdrop pack — covers it; this is what shows where nothing does. Letterbox bars are outside the canvas: they are the host element's own background.
Surface
interface SurfaceFrom @phaser-ae/kernel
What a backend sees: the canvas and its sizes. Never reachable from game code.
readonly canvas: HTMLCanvasElement | OffscreenCanvas— The canvas the backend draws to: an HTML canvas in a page, an OffscreenCanvas (or a stand-in) headless.replaceCanvas(canvas: HTMLCanvasElement): void— Put another canvas in the page in place of this one, keeping its size and style: a backend that probed a canvas of its own during boot adopts it here, before input attaches.readonly width: number— Logical width in pixels. The backing store is the canvas's CSS size ×dpr.readonly height: number— Logical height in pixels.readonly dpr: number— Device pixel ratio in use, afterdprCap. 1 headless.readonly offsetX: number— Letterbox offset in physical pixels. Always 0 from the kernel: under'letterbox'the canvas element itself is sized to the fitted box, and the bars are the page around it.readonly offsetY: number— Letterbox offset in physical pixels; 0, asoffsetX.readonly safe: { top: number; right: number; bottom: number; left: number }— Safe-area insets in logical pixels (notches), forworld-screen.readonly clear: { r: number; g: number; b: number; a: number }— The clear colour as rgba 0..1, parsed once from the policy'sbackgroundhex.