Phaser home
Log inCreate a game

← Expansion packsLook

Phaser AE

Loading screen

Free packv3.0.0-52D and 3DLook

A loading screen that looks after itself. While the game's first files arrive, a gradient bar fills on the game's own background colour, so the loader and the first frame meet without a flash, and a failed file stays on screen with Retry until it lands.

This is a Free pack. Every phaser.io account can use it in their games.

Released October 14, 2026 · updated October 19, 2026

Loading screen: a screenshot of its demo
A note about these graphics

Expansion packs don't come with graphics. This screenshot is one way of drawing what the pack does, made for its demo: none of the sprites, tiles or backgrounds in it are in the pack.

That's by design. A pack is a game's logic, mechanics and effects, and it works with whatever art you give it. Some packs draw effects, backdrops or 3D scenes of their own, but none carries a game's sprites.

So the look is yours. Make the art on phaser.io, bring your own, or let your agent draw it in code: the same pack can look like anything.

The pack

preloader

function preloader(options: PreloaderOptions = {}): Pack<{ preloader: PreloaderApi }>

Renderer-independent loading screen: automatic over the preload, on request (run/show) after it. Safe before start(), in 2D/3D.

Functions

easeFill

function easeFill(shown: number, target: number, dt: number): number

v2's loading-bar maths: the bar never moves backwards and approaches the target at ~6/s, at least a sliver per frame.

installPreloader

function installPreloader(k: Kernel, defaults: PreloaderOptions = {}): PreloaderApi

Install once per game. Backends supply the built-in screen; the explicit pack configures the same instance.

minTimeProgress

function minTimeProgress(real: number, elapsed: number, minTime: number): number

v2's minimum-time rule: the bar shows at most elapsed / minTime of the real progress so a 20 ms load still reads.

Types

PreloaderApi

interface PreloaderApi

game.preloader.

  • run(items: ReadonlyArray<LoadItem>, opts?: PreloaderOptions): LoadJob — Load a stack and show a bar until it lands (or fails), at any point in the game: the deliberate loading screen, between levels say. Returns the JOB, which is itself awaitable — const job = preloader.run(items); await job; job.ok. It cannot hand back a promise OF the job: a job is thenable, and awaiting a promise that resolves with a thenable awaits it again, so the value would come back undefined.
  • show(job: AssetActivity, opts?: PreloaderOptions): Promise<void> — Show a bar over a job you started yourself, silent or not. Resolves after the fade, dismissal, or destruction. Failed loads stay visible until dismissed.
  • configure(opts: PreloaderOptions): void — Configure the automatic loading screen, including opting out with automatic: false.
  • dismiss(): void — Dismiss the current screen without cancelling the underlying asset work.
  • retry(): void — Try the files that failed again, under the same screen (what its Retry button does). Work that cannot be retried reloads the page.
  • readonly shown: number — The fill the bar is showing now, 0..1 (eased; never moves backwards).
  • readonly visible: boolean — True while a bar is up.

PreloaderOptions

interface PreloaderOptions extends LoadOptions

What run takes beyond the items.

  • background?: string — The colour behind it, CSS. Default: the game's own background (the manifest's screen.background), so the loader and the first frame meet without a flash.
  • automatic?: boolean — Show the screen by itself for loads started during the preload, before the first scene enters. Default true.
  • delay?: number — Delay automatic display to avoid flashing for cached/instant loads, seconds. Default 0.12.
  • layer?: string — Legacy option, retained for compatibility; the DOM overlay sits above all game layers.
  • x?: number — Centre x in CSS pixels. Default the screen centre.
  • y?: number — Centre y in CSS pixels. Default the screen centre.
  • minTime?: number — Keep the bar up at least this long, seconds, so a fast load does not flash. Default 0.4.
  • fadeOut?: number — Fade the bar out over this many seconds when done. Default 0.3.
  • style?: PreloaderStyle — The look.

PreloaderStyle

interface PreloaderStyle

How the bar looks. Colours are CSS.

  • width?: number — Content width in CSS pixels. Default 360; clamps to the host.
  • height?: number — Bar height in CSS pixels. Default 8.
  • track?: string — Track colour behind the fill. Default a faint white on a dark background, a faint black on a light one.
  • fill?: string — The fill: a colour (it fills with a gradient from a lighter tint of it, and its sparks match) or any CSS background. Default a cyan, violet and pink gradient.
  • fail?: string — Fill colour once something has failed. Default '#ff7a68' ('#c73a28' on a light background).
  • border?: string — The track's edge. Default a hairline a shade off the track.
  • text?: string — The percentage's colour. Default near-white, or near-black on a light background.
  • font?: string — CSS font for the label. Default system-ui.
  • title?: string — A line above the bar, for a loading screen put up on purpose ('Preparing the next chapter'). Default: none shown, 'Loading' read out.
  • showKey?: boolean — Opt in to a current-asset label under the bar. Default false; ?debug in the page's address turns it on.