Introduction

Adding images is one of the most important first steps in Phaser 4 game development. Images are used for backgrounds, players, enemies, props, buttons, icons, and UI elements.

If text helps explain the game, images help bring it to life. If you want to continue building related UI tutorials, check out Adding Text to the Screen in Phaser 4. You can also browse the full Phaser 4 category for more lessons.

Why Images Matter in a Phaser Game

In nearly every game, you will display images for:

• backgrounds
• characters
• enemies
• collectibles
• buttons
• icons
• HUD elements
• logos and splash screens

Once you understand how to load and display an image, you can start building real gameplay scenes.

The Basic Way to Add an Image

Before you can show an image on the screen, you usually need to load it in preload(). Then you can place it in create().

preload() {
    this.load.image('player', 'assets/player.png');
}

create() {
    this.add.image(400, 300, 'player');
}

Understanding the load.image() Method

The syntax is:

this.load.image(key, path);

Parameters:

• key: the name you give the asset inside Phaser
• path: the location of the image file

this.load.image('player', 'assets/player.png');

Here, player is the asset key and assets/player.png is the file path.

Understanding the add.image() Method

After loading the asset, you display it using:

this.add.image(x, y, key);

Parameters:

• x: horizontal position
• y: vertical position
• key: the image key you loaded earlier

this.add.image(400, 300, 'player');

This places the image at x = 400 and y = 300.

Full Example: Loading and Showing an Image

export default class MainScene extends Phaser.Scene {
    constructor() {
        super({ key: 'MainScene' });
    }

    preload() {
        this.load.image('background', 'assets/background.png');
        this.load.image('logo', 'assets/logo.png');
    }

    create() {
        this.add.image(400, 300, 'background');
        this.add.image(400, 150, 'logo');
    }
}

This scene loads two images, displays the background in the center, and places the logo above it.

Image Positioning in Phaser

When you add an image, the position is controlled by the x and y values.

this.add.image(100, 200, 'player');

This places the image 100 pixels from the left and 200 pixels from the top.

Centering an Image

By default, images are positioned from their center point in Phaser, which makes centering easy.

this.add.image(400, 300, 'background');

If your game size is 800 x 600, that places the image in the exact center of the screen.

Working with Image Scale

Sometimes the original image size is too large or too small. You can resize it using setScale().

const player = this.add.image(400, 300, 'player');
player.setScale(0.5);

What this does:

• 1 means original size
• 0.5 means half size
• 2 means double size

This is useful for fitting images into the scene, building UI icons, and adjusting sprite sizes.

Example: Background and Character

A very common setup is to place a background first, then a character on top of it.

create() {
    this.add.image(400, 300, 'background');

    const character = this.add.image(400, 450, 'player');
    character.setScale(0.8);
}

Since objects are drawn in the order they are created, the background is behind and the character appears on top.

Displaying a Logo or Title Image

Images are not only for gameplay. They are also used for menus and branding.

create() {
    this.add.image(400, 120, 'logo').setScale(0.7);
    this.add.text(400, 250, 'Press Start', {
        fontSize: '32px',
        color: '#ffffff'
    }).setOrigin(0.5);
}

This creates a simple title screen layout.

Storing an Image in a Variable

If you want to animate or move an image later, store it in a variable.

create() {
    this.player = this.add.image(400, 300, 'player');
}

update() {
    this.player.x += 1;
}

This is useful when the image becomes a game object you want to control.

Common Mistakes When Adding Images

1. Forgetting to preload the image

If you try to use an image key that was never loaded, Phaser cannot display it.

Wrong:

create() {
    this.add.image(400, 300, 'player');
}

Correct:

preload() {
    this.load.image('player', 'assets/player.png');
}

2. Using the wrong key

The key must match exactly. If you load hero, you must also display hero.

this.load.image('hero', 'assets/player.png');
this.add.image(400, 300, 'hero');

3. Adding images in update()

This creates a new image every frame and quickly causes problems.

Wrong:

update() {
    this.add.image(400, 300, 'player');
}

Correct: add the image once in create(), then move or update it later if needed.

4. Not managing draw order

If you add the player before the background, the background may appear on top of the player.

Always add the background first, then the main characters, and UI elements last.

Best Practices for Phaser Images

• load images in preload()
• display them in create()
• use clear asset keys
• store important images in variables
• use setScale() when needed
• create objects in the correct visual order

These habits make your scenes easier to manage as your game grows.

FAQ

Conclusion

Adding an image to the screen in Phaser 4 is a foundational skill. It introduces you to loading assets, using asset keys, positioning objects, scaling images, and building visual layers.

Once you can load and display an image, you are ready to start building real game scenes with backgrounds, characters, and interactive objects.