Nine Slice

A Nine Slice Game Object allows you to display a texture-based object that can be stretched both horizontally and vertically, but that retains fixed-sized corners. The dimensions of the corners are set via the parameters to this class.

This is extremely useful for UI and button like elements, where you need them to expand to accommodate the content without distorting the texture.

The texture you provide for this Game Object should be based on the following layout structure:

     A                          B
   +---+----------------------+---+
 C | 1 |          2           | 3 |
   +---+----------------------+---+
   |   |                      |   |
   | 4 |          5           | 6 |
   |   |                      |   |
   +---+----------------------+---+
 D | 7 |          8           | 9 |
   +---+----------------------+---+

When changing this objects width and / or height:

areas 1, 3, 7 and 9 (the corners) will remain unscaled
areas 2 and 8 will be stretched horizontally only
areas 4 and 6 will be stretched vertically only
area 5 will be stretched both horizontally and vertically

You can also create a 3 slice Game Object:

This works in a similar way, except you can only stretch it horizontally. Therefore, it requires less configuration:

     A                          B
   +---+----------------------+---+
   |   |                      |   |
 C | 1 |          2           | 3 |
   |   |                      |   |
   +---+----------------------+---+

When changing this objects width (you cannot change its height)

areas 1 and 3 will remain unscaled
area 2 will be stretched horizontally

The above configuration concept is adapted from the Pixi NineSlicePlane.

To specify a 3 slice object instead of a 9 slice you should only provide the leftWidth and rightWidth parameters. To create a 9 slice you must supply all parameters.

The minimum width this Game Object can be is the total of leftWidth + rightWidth. The minimum height this Game Object can be is the total of topHeight + bottomHeight. If you need to display this object at a smaller size, you can scale it.

In terms of performance, using a 3 slice Game Object is the equivalent of having 3 Sprites in a row. Using a 9 slice Game Object is the equivalent of having 9 Sprites in a row. The vertices of this object are all batched together and can co-exist with other Sprites and graphics on the display list, without incurring any additional overhead.

As of Phaser 3.60 this Game Object is WebGL only.

As of Phaser 3.70 this Game Object can now populate its values automatically if they have been set within Texture Packer 7.1.0 or above and exported with the atlas json. If this is the case, you can just call this method without specifying anything more than the texture key and frame and it will pull the area data from the atlas.

Load texture

this.load.image(key, url);

Reference: load image

Add nine slice object

var nineSlice = this.add.nineslice(x, y, texture, frame, width, height, leftWidth, rightWidth, topHeight, bottomHeight);

var nineSlice = this.add.nineslice(x, y, texture, frame, width, height);
// var nineSlice = this.add.nineslice(x, y, texture, frame);

If that frame (indexed by texture, frame) is generated by Texture Packer.

Add nine slice from JSON

var nineSlice = this.make.nineslice({
    x: 0,
    y: 0,
    key: '',
    // frame: '',

    // width: 256,
    // height: 256,
    // leftWidth: 10,
    // rightWidth: 10,
    // topHeight: 0,
    // bottomHeight: 0,

    // angle: 0,
    // alpha: 1,
    // scale : {
    //    x: 1,
    //    y: 1
    //},
    // origin: {x: 0.5, y: 0.5},

    add: true
});

Custom class

Define class

class MyNineSlice extends Phaser.GameObjects.NineSlice {
    constructor(scene, x, y, texture, frame, width, height, leftWidth, rightWidth, topHeight, bottomHeight) {
        super(scene, x, y, texture, frame, width, height, leftWidth, rightWidth, topHeight, bottomHeight);
        // ...
        this.add.existing(this);
    }
    // ...

    // preUpdate(time, delta) {}
}

this.add.existing(gameObject) : Adds an existing Game Object to this Scene.
- If the Game Object renders, it will be added to the Display List.
- If it has a preUpdate method, it will be added to the Update List.

Create instance

var nineSlice = new MyNineSlice(scene, x, y, texture, frame, width, height, leftWidth, rightWidth, topHeight, bottomHeight);

Resize

nineSlice.setSize(width, height);

Set texture of source image

nineSlice.setTexture(texture, frame);
nineSlice.setSlices(width, height, leftWidth, rightWidth, topHeight, bottomHeight);

Texture

See game object - texture

Other properties

See game object

Create mask

var mask = nineSlice.createBitmapMask();

See mask

Shader effects

Support postFX effects

!!! note No preFX effect support

Author Credits

Content on this page includes work by:

RexRainbow