Creating a Preloading Screen in Phaser 3

One of the things that almost all games have in common is a loading screen, which can be used to inform the player how long they must wait to play the game. Even though no one likes waiting to play a game, a loading screen is a valuable tool. Instead of having players stare at a blank screen, the loading screen can be used to inform the player how much longer they have to wait, or at minimum let the player know the game is doing something.

In Phaser, before you can use any assets, you must first load them in  preload  function of the scene. If you load a large number of assets, it can take some time for all of the assets to be loaded into the game, and this is where a preloader really makes a difference.

The goal of this tutorial is to teach you the basics of creating a preloading screen by creating a progress bar that will dynamically update as the game loads the assets. You can see what we will be creating below:

You can download all of the files associated with the source code here:

Learn Phaser 3 with our newest Mini-Degree

The HTML5 Game Development Mini-Degree is now available for Pre-Order on Zenva Academy. Learn to code and make impressive games with JavaScript and Phaser 3!

Get Instant Early Access

Project Setup

In order to run your Phaser game locally, you will need a web server for running your game. If you don’t already have this setup, you can read how to do that here: Getting Start With Phaser. You will also need an IDE or Text Editor for writing your code. If you don’t already have one, I would recommend the Brackets editor since it is easy to use, and it has a feature called Live Preview that will allow you to run your Phaser game without installing a web server.

Once you have these setup, we will setup the basic code for our game. Open your IDE, and create a new file called index.html. We are going to create a basic html page, add a reference to Phaser, and create our Phaser game object. In index.html, add the following code:

Let’s review the code we just added:

  • We created the configuration that will be used for our Phaser game.
  • In the config object, in the type field, we set the renderer type for our game. The two main types are Canvas and WebGL. WebGL is a faster renderer and has better performance, but not all browsers support it. By choosing AUTO for the type, Phaser will use WebGL if it is available, otherwise it will use Canvas.
  • In the config object, the parent field is used to tell Phaser to render our game in an existing  <canvas>  element with that id if it exists. If it does not exists, then Phaser will create a  <canvas>  element for us.
  • In the config object, we specify the width and height of the viewable area of our game.
  • In the config object, we embedded a scene object which will use the  preload  and  create functions we defined.
  • Lastly, we passed our config object to Phaser when we created the new game instance.

If you try running your game, you should see a black screen, and if you open the console in the developer tools, you should see a log with the version of Phaser your game is running.

Loading Our Assets

Now that our project is setup, we can get started. Before we can create our preloader, we will need to load some assets into our game. To keep things simple, we are going to use one image and reload it a few times to simulate loading a large number of assets. The asset for the game can be downloaded here.

You will need to place the image in same folder as index.html.

To load our image and display it in our game, you will need to update the  preload  and  create  functions in index.html:


If you reload your game in the browser, you should see the logo appear in your game.

Creating the Preloader

With our assets loaded, it is time to create our preloader. In the  preload  function, add the following code:


This code creates a few event listeners that will listen for the progress, fileprogress, and  complete events that are emitted from Phaser’s LoaderPlugin. The  progress  and  fileprogress events will be emitted every time a file has been loaded, and the  complete event will only be emitted once all the files are done loading.

When the  progress  event is emitted, you will also receive a value between 0 and 1, which can be used track the overall progress of the loading process. When the  fileprogress  event is emitted, you will also receive an object containing information on the file that was just loaded. Both of these can be used to create custom preloader with the information that is provided.

Here is an example of the data that is sent:

For the preloader, we will use Phaser’s GameObject.Graphics to create the progress bar. In the  preload  function, add the following code at the top of the function, above the code you already added:

Then, update the  progress  event listener in the  preload  function with the following code:


In the code above, we are creating two separate rectangles,  progressBar and progressBox. The  progressBox rectangle is going to be used as a border/container around the progressBar, and the  progressBar will be used to track the overall percentage of the assets being loaded. We are doing this by calculating the width of the rectangle to be based on the progress value we are receiving. So, every time we receive the  progress event, we should see the rectangle grow.

If you reload the game, you should see a nice progress bar that fills up as the assets are being loaded. However, there is one problem with it. When the all of the assets are loaded, the preloader is staying on the screen, and the logo image is being loaded over top of it. To fix this, we can update the complete event listener to destroy our preloader once all assets are loaded.

In the  complete event listener, add the following code below the console.log():


Now, if you reload your game, the progress bar should disappear before the logo image is displayed on the screen.

Adding Some Text

We have the main part of our preloader done, but we can easily enhance the preloader by adding some additional text to it. First, we will add a simple ‘Loading…’ message to the preloader. In the  preload function, add the following code below the  progressBox lines:


Then, in the  complete event listener, add the following code:


Let’s review what we just added:

  • We created two new variables, width and height. These variables are getting the width and height of the current viewable area of our game.
  • We created a new Phaser Text GameObject called loadingText. This game object is using the width and height variables we just created, and we set the style and default text of the game object.
  • We set the origin of the game object to be (0.5, 0.5), which will help center our game object.
  • Lastly, we updated the complete event listener to destroy our loading text once all the games assets were loaded.

If you reload your game, your screen should look like this:

Next, we are going to add some additional text that will display the percent of the loading bar. To do this, we just need to create another text game object, and update the text to use the value that is being sent to the progress event listener. In the preload function add the following code below the  loadingText code:


Now, in the  progress event listener, add the following code above the  progressBar code:


Lastly, in the  complete function add the following code: preload 


Here is a quick summary of what we just did:

  • Created a new Phaser Text GameObject called percentText.
  • We set the origin to (0.5, 0.5) to help center the object.
  • In the  progress event listener, we are updating the text of the object, every time a file is loaded. We are multiplying the value by 100 since the value that is emitted is between 0 and 1.
  • Lastly, we updated the  complete event listener to destroy the object.

If you reload your game, you should see the progress bar percentage update as the progress bar fills up.

With the progress bar now showing the percentage, we will now add some text to display which asset has been loaded. Once again, we will create another text game object and we will update the text of the game object with the file data that is being sent to the  fileprogress event listener. In the  preload function add the following code below the  percentText code:


Then, in the  fileprogress event listener, add the following code:


Lastly, in the  complete function add the following code:


Now, if you reload your game, you should see the asset text being updated as each asset is loaded.

For this example, we ended up outputting the asset key instead of the file name since we are only loading the one image. If you want to output the file name, you can update the following line:


to be:


Here is the completed index.html file:


You can download the completed example here.

Conclusion

With the asset text now being displayed, this brings this tutorial to a close. As you can see, adding a preloader to your game is a great solution when you will be loading a large number of assets, and you want to keep the players informed of the games current state. With Phaser, it is really easy to add a simple preloader and you can easily extend these examples to create a more complex preloader.

I hoped you enjoyed this tutorial and found it helpful. If you have any questions, or suggestions on what we should cover next, let us know in the comments below.

Published by

Scott Westover

Scott Westover is a Fullstack Developer who loves coding, writing tutorials, participating in game jams, and learning about new technologies. When he is not coding, he is either spending time with his wife and two kids or is reading a great book. Scott is looking to form connections and share his knowledge. Connect with Scott on Linkedin.

Share this article

6
Leave a Reply

avatar
4 Comment threads
2 Thread replies
2 Followers
 
Most reacted comment
Hottest comment thread
5 Comment authors
Ilman NurcahyantoXiLinSScott WestoverGustavSaikaVA Recent comment authors
newest oldest most voted
SaikaVA
Guest
SaikaVA

A good and simple tutorial! Can you make a tutorial on creating a Main Menu after the progressbar is finished?

Gustav
Guest
Gustav

this code example seems to be really good for learner.
but I can’t see progress bar , but only see logo icon
what is the problem?

XiLinS
Guest
XiLinS

very nicetoturial,thanx!!

Ilman Nurcahyanto
Guest
Ilman Nurcahyanto

. why progress bar not show bro , i add more image