Learning Pixi

A step-by-step introduction to making games and interactive media with the Pixi rendering engine. Updated for Pixi v5.3.10. Chinese version here: Pixi官方教程中文版. If you like this tutorial, you'll love the book, which contains 80% more content!.

Table of contents

1. Introduction
2. Setting up
   1. Installing Pixi
3. Creating the stage and renderer
4. Pixi sprites
5. Loading images into the texture cache
6. Displaying sprites
   1. Using Aliases
   2. A little more about loading things
      1. Make a sprite from an ordinary JavaScript Image object or Canvas
      2. Assigning a name to a loaded file
      3. Monitoring load progress
      4. More about Pixi's loader
7. Positioning sprites
8. Size and scale
9. Rotation
10. Make a sprite from a tileset sub-image
11. Using a texture atlas
12. Loading the texture atlas
13. Creating sprites from a loaded texture atlas
14. Moving Sprites
15. Using velocity properties
16. Game states
17. Keyboard Movement
18. Grouping Sprites
    1. Local and global positions
    2. Using a ParticleContainer to group sprites
19. Pixi's Graphic Primitives
    1. Rectangle
    2. Circles
    3. Ellipses
    4. Rounded rectangles
    5. Lines
    6. Polygons
20. Displaying text
21. Collision detection
    1. The hitTestRectangle function
22. Case study: Treasure Hunter
    1. Initialize the game in the setup function
       1. Creating the game scenes
       2. Making the dungeon, door, explorer and treasure
       3. Making the blob monsters
       4. Making health bar
       5. Making message text
    2. Playing the game
    3. Moving the explorer
       1. Containing movement
    4. Moving the monsters
    5. Checking for collisions
    6. Reaching the exit door and ending game
23. More about sprites
24. Taking it further</br> 1.Hexi</br> 2.BabylonJS</br>
25. Supporting this project

<a id='introduction'></a> Introduction

Pixi is an extremely fast 2D sprite rendering engine. What does that mean? It means that it helps you to display, animate and manage interactive graphics so that it's easy for you to make games and applications using JavaScript and other HTML5 technologies. It has a sensible, uncluttered API and includes many useful features, like supporting texture atlases and providing a streamlined system for animating sprites (interactive images). It also gives you a complete scene graph so that you can create hierarchies of nested sprites (sprites inside sprites), as well as letting you attach mouse and touch events directly to sprites. And, most importantly, Pixi gets out of your way so that you can use as much or as little of it as you want to, adapt it to your personal coding style, and integrate it seamlessly with other useful frameworks.

Pixi’s API is actually a refinement of a well-worn and battle-tested API pioneered by Macromedia/Adobe Flash. Old-skool Flash developers will feel right at home. Other current sprite rendering frameworks use a similar API: CreateJS, Starling, Sparrow and Apple’s SpriteKit. The strength of Pixi’s API is that it’s general-purpose: it’s not a game engine. That’s good because it gives you total expressive freedom to make anything you like, and wrap your own custom game engine around it.

In this tutorial you’re going to find out how to combine Pixi’s powerful image rendering features and scene graph to start making games. But Pixi isn't just for games - you can use these same techniques to create any interactive media applications. That means apps for phones!

What do you need to know before you get started with this tutorial?

You should have a reasonable understanding of HTML and JavaScript. You don't have to be an expert, just an ambitious beginner with an eagerness to learn. If you don't know HTML and JavaScript, the best place to start learning it is this book:

Foundation Game Design with HTML5 and JavaScript

I know for a fact that it's the best book, because I wrote it!

There are also some good internet resources to help get you started:

Khan Academy: Computer Programming

Code Academy: JavaScript

Choose whichever best suits your learning style.

Ok, got it? Do you know what JavaScript variables, functions, arrays and objects are and how to use them? Do you know what JSON data files are? Have you used the Canvas Drawing API?

To use Pixi, you'll also need to run a webserver in your root project directory. Do you know what a webserver is and how to launch one in your project folder? The best way is to use node.js and then to install the extremely easy to use http-server. However, you need to be comfortable working with the Unix command line if you want to do that. You can learn how to use Unix in this video and, when you're finished, follow it with this video. You should learn how to use Unix - it only takes a couple of hours to learn and is a really fun and easy way to interact with your computer.

But if you don't want to mess around with the command line just yet, try the Mongoose webserver:

Or, just write all your code using the excellent Brackets text editor. Brackets automatically launches a webserver and browser for you when you click the lightning bolt button in its main workspace.

Now if you think you're ready, read on!

(Request to readers: this is a living document. If you have any questions about specific details or need any of the content clarified, please create an issue in this GitHub repository and I'll update the text with more information.)

<a id='settingup'></a> Setting up

Before you start writing any code, create a folder for your project, and launch a webserver in the project's root directory. If you aren't running a webserver, Pixi won't work.

Next, you need to install Pixi.

<a id='installingpixi'></a>

Installing Pixi

The version used for this introduction is v5.3.10 and you can find the pixi.min.js file either in this repository's pixi folder or on Pixi's release page for v5.3.10. Or, you can get the latest version from Pixi's main release page.

This one file is all you need to use Pixi. You can ignore all the other files in the repository: you don't need them.

Next, create a basic HTML page, and use a <script> tag to link the pixi.min.js file that you've just downloaded. The <script> tag's src should be relative to your root directory where your webserver is running. Your <script> tag might look something like this:

<script src="pixi.min.js"></script>

Here's a basic HTML page that you could use to link Pixi and test that it's working. (This assumes that the pixi.min.js is in a subfolder called pixi):

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>Hello World</title>
</head>
<body>
  <script src="pixi/pixi.min.js"></script>
  <script type="text/javascript">
    let type = "WebGL";
    if (!PIXI.utils.isWebGLSupported()) {
      type = "canvas";
    }

    PIXI.utils.sayHello(type);
  </script>
</body>
</html>

If Pixi is linking correctly, something like this will be displayed in your web browser's JavaScript console by default:

      PixiJS 5.3.10 - * WebGL * http://www.pixijs.com/  ♥♥♥ 

<a id='application'></a> Creating the Pixi Application and stage

Now you can start using Pixi!

But how?

The first step is to create a rectangular display area that you can start displaying images on. Pixi has an Application object that creates this for you. It automatically generates an HTML <canvas> element and figures out how to display your images on the canvas. You then need to create a special Pixi Container object called the stage. As you'll see ahead, this stage object is going to be used as the root container that holds all the things you want Pixi to display.

Here’s the code you need to write to create an app Pixi Application and stage. Add this code to your HTML document between the <script> tags:

//Create a Pixi Application
const app = new PIXI.Application({width: 256, height: 256});

//Add the canvas that Pixi automatically created for you to the HTML document
document.body.appendChild(app.view)