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 a 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
let 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);

This is the most basic code you need write to get started using Pixi. It produces a black 256 pixel by 256 pixel canvas element and adds it to your HTML document. Here’s what this looks like in a browser when you run this code.

Yay, a black square!

PIXI.Application figures out whether to use the Canvas Drawing API or WebGL to render graphics, depending on which is available on the web browser you’re using. Its argument is a single object called the options object. In this example its width and height properties are set to determine the width and height of the canvas, in pixels. You can set many more optional properties inside this options object; here’s how you could use it to set anti-aliasing, transparency and resolution:

let app = new PIXI.Application({ 
    width: 256,         // default: 800
    height: 256,        // default: 600
    antialias: true,    // default: false
    transparent: false, // default: false
    resolution: 1       // default: 1
  }
);

If you’re happy with Pixi’s default settings, you don’t need to set any of these options. But, if you need to, see Pixi’s documentation on PIXI.Application.

What do those options do? antialias smoothes the edges of fonts and graphic primitives. (WebGL anti-aliasing isn’t available on all platforms, so you’ll need to test this on your game’s target platform.) transparent makes the canvas background transparent. resolution makes it easier to work with displays of varying resolutions and pixel densities. Setting the resolutions is a little outside the scope of this tutorial, but check out Mat Grove’s explanation about how to use resolution for all the details. But usually, just keep resolution at 1 for most projects and you’ll be fine.

Pixi’s renderer object will default to WebGL, which is good, because WebGL is incredibly fast, and lets you use some spectacular visual effects that you’ll learn all about ahead. But if you need to force the Canvas Drawing API rendering over WebGL, you can set the forceCanvas option to true, like this:

forceCanvas: true,

If you need to change the background color of the canvas after you’ve created it, set the app.renderer object’s backgroundColor property to any hexadecimal color value:

app.renderer.backgroundColor = 0x061639;

If you want to find the width or the height of the renderer, use app.renderer.view.width and app.renderer.view.height.

To change the size of the canvas, use the renderer’s resize method, and supply any new width and height values. But, to make sure the canvas is resized to match the resolution, set autoResize to true.

app.renderer.autoResize = true;
app.renderer.resize(512, 512);

If you want to make the canvas fill the entire window, you can apply this CSS styling and resize the renderer to the size of the browser window.

app.renderer.view.style.position = "absolute";
app.renderer.view.style.display = "block";
app.renderer.autoResize = true;
app.renderer.resize(window.innerWidth, window.innerHeight);

But, if you do that, make sure you also set the default padding and margins to 0 on all your HTML elements with this bit of CSS code:

<style>* {padding: 0; margin: 0}</style>

(The asterisk, *, in the code above, is the CSS “universal selector”, which just means “all the tags in the HTML document”.)

If you want the canvas to scale proportionally to any browser window size, you can use this custom scaleToWindow function.