Make a sprite from a tileset sub-image

You now know how to make a sprite from a single image file. But, as a game designer, you’ll usually be making your sprites using tilesets (also known as spritesheets.) Pixi has some convenient built-in ways to help you do this. A tileset is a single image file that contains sub-images. The sub-images represent all the graphics you want to use in your game. Here’s an example of a tileset image that contains game characters and game objects as sub-images.

An example tileset

The entire tileset is 192 by 192 pixels. Each image is in its own 32 by 32 pixel grid cell. Storing and accessing all your game graphics on a tileset is a very processor and memory efficient way to work with graphics, and Pixi is optimized for this.

You can capture a sub-image from a tileset by defining a rectangular area that’s the same size and position as the sub-image you want to extract. Here’s an example of the rocket sub-image that’s been extracted from the tileset.

Rocket extracted from tileset

Let’s look at the code that does this. First, load the tileset.png image with Pixi’s loader, just as you’ve done in earlier examples.

  1. loader
  2.   .add("images/tileset.png")
  3.   .load(setup);

Next, when the image has loaded, use a rectangular sub-section of the tileset to create the sprite’s image. Here’s the code that extracts the sub image, creates the rocket sprite, and positions and displays it on the canvas.

  1. function setup() {
  3.   //Create the `tileset` sprite from the texture
  4.   let texture = TextureCache["images/tileset.png"];
  6.   //Create a rectangle object that defines the position and
  7.   //size of the sub-image you want to extract from the texture
  8.   //(`Rectangle` is an alias for `PIXI.Rectangle`)
  9.   let rectangle = new Rectangle(192, 128, 64, 64);
  11.   //Tell the texture to use that rectangular section
  12.   texture.frame = rectangle;
  14.   //Create the sprite from the texture
  15.   let rocket = new Sprite(texture);
  17.   //Position the rocket sprite on the canvas
  18.   rocket.x = 32;
  19.   rocket.y = 32;
  21.   //Add the rocket to the stage
  22.   app.stage.addChild(rocket);
  24.   //Render the stage   
  25.   app.renderer.render(app.stage);
  26. }

How does this work?

Pixi has a built-in Rectangle object (PIXI.Rectangle) that is a general-purpose object for defining rectangular shapes. It takes four arguments. The first two arguments define the rectangle’s x and y position. The last two define its width and height. Here’s the format for defining a new Rectangle object.

  1. let rectangle = new PIXI.Rectangle(x, y, width, height);

The rectangle object is just a data object; it’s up to you to decide how you want to use it. In our example we’re using it to define the position and area of the sub-image on the tileset that we want to extract. Pixi textures have a useful property called frame that can be set to any Rectangle objects. The frame crops the texture to the dimensions of the Rectangle. Here’s how to use frame to crop the texture to the size and position of the rocket.

  1. let rectangle = new Rectangle(192, 128, 64, 64);
  2. texture.frame = rectangle;

You can then use that cropped texture to create the sprite:

  1. let rocket = new Sprite(texture);

And that’s how it works!

Because making sprite textures from a tileset is something you’ll do with great frequency, Pixi has a more convenient way to help you do this - let’s find out what that is next.