How to Use Phaser 3 Group With Atlas Images of Different Sizes?

Phaser 3 is a really nice HTML 5 game development framework. If you know JavaScript or Typescript, it is a really easy framework to quickly create nice HTML 5 games. This is also a solid alternative to iPhone or android game development. If you are a Web developer, you don’t want to learn a new tool and maintain the code to keep up with latest version of iOS and Android. Phaser provides all I need in order to create a games.

Just like any other framework, you are learning it from documentation and existing examples. In the current state, Phaser documentations and examples are enough but once you incorporate optimization, documentation does not provide any help for certain situation.

For example, using Phaser Group is well documented and plenty of examples are available but most of the examples are working for images with same size. Those are called sprites. In sprite, all images are of the same size which is useful for animation and things like that. But in order to optimize the project, I need to build image atlas which is a combination of multiple images of different sizes into a single image. The main benefit is to reduce the number of HTTP requests. Online examples only deals with sprite and not with atlas. This gives the impression that Phaser Group cannot be used with atlas images but that is not correct.

What is Phaser Group?

Phaser has a concept called Group. Group is a collection of objects. We can also use it as an object pool. Even though Group may contains objects of multiple types, generally we want to restrict it only for a single type. Single type does not necessary mean the same image. We may use different images of different size within a single group. For example, I am creating a car game. In this game, player collects the stars and avoid obstacles. There can be different obstacles like cones, barriers, pot holes etc. Each obstacle image has a different size and it is a part of atlas. We want to create a single group for all obstacles. This way, we can handle collider function using a single group.

How to Create Phaser Group?

Following code gives a Phaser group example. This example uses Typescript. In the preload() function, I am loading atlas image which contains all image resources needed for the entire game.

export class LevelScene extends BaseScene {

    private ObstacleGroup: Phaser.Physics.Arcade.Group;

    constructor() {
        super({
            key: 'level1'
        });
    }
    preload() {
        this.load.atlas('level1atlas', "/url/to/atlasimg.png", "/url/to/atlasdata.json");
    }
    create() {
        this.ObstacleGroup = this.physics.add.group({ key: 'level1atlas', frame: ['cone', 'barrier'], frameQuantity: 7, randomKey: true, randomFrame:true, active: false, visible:false });
        // your own code
        // now show the new random obstacle
        showNewObstacle();


    }
    showNewObstacle() {
        const x = Phaser.Math.Between(0, 500), y = Phaser.Math.Between(0, 500);
        const obj = this.ObstacleGroup.get(x, y) as Phaser.GameObjects.Sprite;
        obj.setActive(true).setVisible(true);
    }
}

Phaser Group Code Explanation

In this code, I am creating a group of obstacles. This group contains cone and barrier image from the atlas. Both images have different dimensions. In this scenario, main take away is:

• We must explicitly set active: false and visible:false. If we don’t do it, by default all the sprites will be active and visible at coordinates (0, 0).
• If we want to randomize objects, randomKey: true really randomize the object. randomFrame: true has no impact on final randomization. Even though we are using only a single key, setting the randomKey: true will randomize the group objects.
• frameQuantity: 7 will create 7 objects for each frame so code will create total 14 objects.
• group.get function gets the first inactive object and sets its x and y coordinate. But it does not automatically make it active or visible. We must explicitly make it active and visible. In this scenario, group is using Arcade physics so all objects will have arcade body which is enabled by default.

Code Not Included in Example

As this is a simple example, I did not include the code to disable object once it is out of screen or re-enable object body within showNewObstacle() function. When the group is created, the config does not have maximum object limit. If the group does not contain active object, it will try to create new object. Just because defaultKey and defaultFrame is not provided, function will try to create an object with missing frame resulting in green square.