NineSlice

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.

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 create this Game Object without specifying anything more than the texture key and frame and it will pull the area data from the atlas.

This object does not support trimmed textures from Texture Packer. Trimming interferes with the ability to stretch the texture correctly.

Constructor

new NineSlice(scene, x, y, texture, [frame], [width], [height], [leftWidth], [rightWidth], [topHeight], [bottomHeight], [tileX], [tileY])

Parameters

name	type	optional	default	description
scene	Phaser.Scene	No		The Scene to which this Game Object belongs. A Game Object can only belong to one Scene at a time.
x	number	No		The horizontal position of the center of this Game Object in the world.
y	number	No		The vertical position of the center of this Game Object in the world.
texture	string | Phaser.Textures.Texture	No		The key, or instance of the Texture this Game Object will use to render with, as stored in the Texture Manager.
frame	string | number	Yes		An optional frame from the Texture this Game Object is rendering with.
width	number	Yes	256	The width of the Nine Slice Game Object. You can adjust the width post-creation.
height	number	Yes	256	The height of the Nine Slice Game Object. If this is a 3 slice object the height will be fixed to the height of the texture and cannot be changed.
leftWidth	number	Yes	10	The size of the left vertical column (A).
rightWidth	number	Yes	10	The size of the right vertical column (B).
topHeight	number	Yes	0	The size of the top horizontal row (C). Set to zero or undefined to create a 3 slice object.
bottomHeight	number	Yes	0	The size of the bottom horizontal row (D). Set to zero or undefined to create a 3 slice object.
tileX	boolean	Yes	false	When enabled, the scalable horizontal regions are repeated across the object instead of being stretched. Each tile is still slightly stretched so that it remains visible in full, which may cause minor distortion but far less than pure stretching. The texture should be seamless to avoid visible artifacts between tiles.
tileY	boolean	Yes	false	When enabled, the scalable vertical regions are repeated across the object instead of being stretched. Each tile is still slightly stretched so that it remains visible in full, which may cause minor distortion but far less than pure stretching. The texture should be seamless to avoid visible artifacts between tiles.

---

Scope: static

Extends

Phaser.GameObjects.GameObject
Phaser.GameObjects.Components.AlphaSingle
Phaser.GameObjects.Components.BlendMode
Phaser.GameObjects.Components.Depth
Phaser.GameObjects.Components.GetBounds
Phaser.GameObjects.Components.Mask
Phaser.GameObjects.Components.Origin
Phaser.GameObjects.Components.RenderNodes
Phaser.GameObjects.Components.ScrollFactor
Phaser.GameObjects.Components.Texture
Phaser.GameObjects.Components.Transform
Phaser.GameObjects.Components.Visible

Source: src/gameobjects/nineslice/NineSlice.js#L15
Since: 3.60.0

Inherited Members

From Phaser.GameObjects.Components.AlphaSingle:

• alpha

From Phaser.GameObjects.Components.BlendMode:

• blendMode

From Phaser.GameObjects.Components.Depth:

• depth

From Phaser.GameObjects.Components.Filters:

• filterCamera
• filters
• filtersAutoFocus
• filtersFocusContext
• filtersForceComposite
• maxFilterSize
• renderFilters

From Phaser.GameObjects.Components.Mask:

• mask

From Phaser.GameObjects.Components.Origin:

• displayOriginX
• displayOriginY

From Phaser.GameObjects.Components.RenderNodes:

• customRenderNodes
• defaultRenderNodes
• renderNodeData

From Phaser.GameObjects.Components.ScrollFactor:

• scrollFactorX
• scrollFactorY

From Phaser.GameObjects.Components.Texture:

• frame
• texture

From Phaser.GameObjects.Components.Transform:

• angle
• hasTransformComponent
• rotation
• scale
• scaleX
• scaleY
• w
• x
• y
• z

From Phaser.GameObjects.Components.Visible:

• visible

From Phaser.GameObjects.GameObject:

• active
• body
• cameraFilter
• data
• displayList
• ignoreDestroy
• input
• isDestroyed
• name
• parentContainer
• renderFlags
• scene
• state
• tabIndex
• type
• vertexRoundMode

---

Public Members

bottomHeight

bottomHeight: number

Description:

The size of the bottom horizontal bar (D).

If this is a 3 slice object this property will be set to zero.

Source: src/gameobjects/nineslice/NineSlice.js#L268
Since: 3.60.0

---

displayHeight

displayHeight: number

Description:

The displayed height of this Game Object.

This value takes into account the scale factor.

Setting this value will adjust the Game Object's scale property.

Source: src/gameobjects/nineslice/NineSlice.js#L1033
Since: 3.60.0

---

displayWidth

displayWidth: number

Description:

The displayed width of this Game Object.

This value takes into account the scale factor.

Setting this value will adjust the Game Object's scale property.

Source: src/gameobjects/nineslice/NineSlice.js#L1008
Since: 3.60.0

---

height

height: number

Description:

The displayed height of this Game Object.

Setting this value will adjust the way in which this Nine Slice object scales vertically, if configured to do so.

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 also scale it.

If this is a 3-slice object, you can only stretch it horizontally and changing the height will be ignored.

Source: src/gameobjects/nineslice/NineSlice.js#L972
Since: 3.60.0

---

is3Slice

is3Slice: boolean

Description:

This property is true if this Nine Slice Game Object was configured with just leftWidth and rightWidth values, making it a 3-slice instead of a 9-slice object.

Source: src/gameobjects/nineslice/NineSlice.js#L355
Since: 3.60.0

---

isTinted

isTinted: boolean

Description:

Does this Game Object have a tint applied?

It checks to see if the tint property is set to a value other than 0xffffff or the tint mode is not the default Phaser.TintModes.MULTIPLY. This indicates that a Game Object is tinted.

Tags:

• webglOnly

Source: src/gameobjects/nineslice/NineSlice.js#L920
Since: 3.60.0

---

leftWidth

leftWidth: number

Description:

The size of the left vertical bar (A).

Source: src/gameobjects/nineslice/NineSlice.js#L235
Since: 3.60.0

---

originX

originX: number

Description:

The horizontal origin of this Game Object. The origin maps the relationship between the size and position of the Game Object. The default value is 0.5, meaning all Game Objects are positioned based on their center. Setting the value to 0 means the position now relates to the left of the Game Object.

Overrides: Phaser.GameObjects.Components.Origin#originX

Source: src/gameobjects/nineslice/NineSlice.js#L1118
Since: 3.60.0

---

originY

originY: number

Description:

The vertical origin of this Game Object. The origin maps the relationship between the size and position of the Game Object. The default value is 0.5, meaning all Game Objects are positioned based on their center. Setting the value to 0 means the position now relates to the top of the Game Object.

Overrides: Phaser.GameObjects.Components.Origin#originY

Source: src/gameobjects/nineslice/NineSlice.js#L1143
Since: 3.60.0

---

rightWidth

rightWidth: number

Description:

The size of the right vertical bar (B).

Source: src/gameobjects/nineslice/NineSlice.js#L245
Since: 3.60.0

---

tileX

tileX: boolean

Description:

Indicates whether the scalable horizontal regions of the Nine Slice are repeated across the object instead of being stretched. Each tile is still slightly stretched so that it remains visible in full.

Source: src/gameobjects/nineslice/NineSlice.js#L280
Since: 4.0.0

---

tileY

tileY: boolean

Description:

Indicates whether the scalable vertical regions of the Nine Slice are repeated across the object instead of being stretched. Each tile is still slightly stretched so that it remains visible in full.

Source: src/gameobjects/nineslice/NineSlice.js#L292
Since: 4.0.0

---

tint

tint: number

Description:

The tint value being applied to the Game Object. The value should be set as a hex number, i.e. 0xff0000 for red, or 0xff00ff for purple.

Source: src/gameobjects/nineslice/NineSlice.js#L324
Since: 3.60.0

---

tintMode

tintMode: Phaser.TintModes

Description:

The tint mode to use when applying the tint to the texture.

Available modes are:

• Phaser.TintModes.MULTIPLY (default)

• Phaser.TintModes.FILL

• Phaser.TintModes.ADD

• Phaser.TintModes.SCREEN

• Phaser.TintModes.OVERLAY

• Phaser.TintModes.HARD_LIGHT

Source: src/gameobjects/nineslice/NineSlice.js#L335
Since: 4.0.0

---

topHeight

topHeight: number

Description:

The size of the top horizontal bar (C).

If this is a 3 slice object this property will be set to the height of the texture being used.

Source: src/gameobjects/nineslice/NineSlice.js#L255
Since: 3.60.0

---

vertices

vertices: Array.<Phaser.GameObjects.NineSliceVertex>

Description:

An array of Vertex objects that correspond to the quads that make-up this Nine Slice Game Object. They are stored in the following order:

Top Left - Indexes 0 - 5 Top Center - Indexes 6 - 11 Top Right - Indexes 12 - 17 Center Left - Indexes 18 - 23 Center - Indexes 24 - 29 Center Right - Indexes 30 - 35 Bottom Left - Indexes 36 - 41 Bottom Center - Indexes 42 - 47 Bottom Right - Indexes 48 - 53

Each quad is represented by 6 Vertex instances.

This array will contain 18 elements for a 3 slice object and 54 for a nine slice object.

You should never modify this array once it has been populated.

Source: src/gameobjects/nineslice/NineSlice.js#L208
Since: 3.60.0

---

width

width: number

Description:

The displayed width of this Game Object.

Setting this value will adjust the way in which this Nine Slice object scales horizontally, if configured to do so.

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

Source: src/gameobjects/nineslice/NineSlice.js#L942
Since: 3.60.0

---

Inherited Methods

From Phaser.Events.EventEmitter:

• addListener
• emit
• eventNames
• listenerCount
• listeners
• off
• on
• once
• removeAllListeners
• removeListener
• shutdown

From Phaser.GameObjects.Components.AlphaSingle:

• clearAlpha
• setAlpha

From Phaser.GameObjects.Components.BlendMode:

• setBlendMode

From Phaser.GameObjects.Components.Depth:

• setAbove
• setBelow
• setDepth
• setToBack
• setToTop

From Phaser.GameObjects.Components.Filters:

• enableFilters
• focusFilters
• focusFiltersOnCamera
• focusFiltersOverride
• renderWebGLFilters
• setFiltersAutoFocus
• setFiltersFocusContext
• setFiltersForceComposite
• setFilterSize
• setRenderFilters
• willRenderFilters

From Phaser.GameObjects.Components.GetBounds:

• getBottomCenter
• getBottomLeft
• getBottomRight
• getBounds
• getCenter
• getLeftCenter
• getRightCenter
• getTopCenter
• getTopLeft
• getTopRight

From Phaser.GameObjects.Components.Mask:

• clearMask
• createGeometryMask
• setMask

From Phaser.GameObjects.Components.Origin:

• setDisplayOrigin
• setOriginFromFrame
• updateDisplayOrigin

From Phaser.GameObjects.Components.RenderNodes:

• initRenderNodes
• setRenderNodeData
• setRenderNodeRole

From Phaser.GameObjects.Components.RenderSteps:

• addRenderStep
• renderWebGLStep

From Phaser.GameObjects.Components.ScrollFactor:

• setScrollFactor

From Phaser.GameObjects.Components.Texture:

• setFrame
• setTexture

From Phaser.GameObjects.Components.Transform:

• copyPosition
• getLocalPoint
• getLocalTransformMatrix
• getParentRotation
• getWorldPoint
• getWorldTransformMatrix
• setAngle
• setPosition
• setRandomPosition
• setRotation
• setScale
• setW
• setX
• setY
• setZ

From Phaser.GameObjects.Components.Visible:

• setVisible

From Phaser.GameObjects.GameObject:

• addedToScene
• addToDisplayList
• addToUpdateList
• destroy
• disableInteractive
• getData
• getDisplayList
• getIndexList
• incData
• removedFromScene
• removeFromDisplayList
• removeFromUpdateList
• removeInteractive
• setActive
• setData
• setDataEnabled
• setInteractive
• setName
• setState
• setVertexRoundMode
• toggleData
• toJSON
• update
• willRender
• willRoundVertices

---

Public Methods

clearTint

<instance> clearTint()

Description:

Clears all tint values associated with this Game Object.

Immediately sets the color values back to 0xffffff and the tint type to 'multiply', which results in no visible change to the texture.

Tags:

• webglOnly

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L842
Since: 3.60.0

---

setDisplaySize

<instance> setDisplaySize(width, height)

Description:

Sets the display size of this Game Object.

Calling this will adjust the scale.

Parameters:

name	type	optional	description
width	number	No	The width of this Game Object.
height	number	No	The height of this Game Object.

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L1097
Since: 3.60.0

---

setOrigin

<instance> setOrigin([x], [y])

Description:

Sets the origin of this Game Object.

The values are given in the range 0 to 1.

Parameters:

name	type	optional	default	description
x	number	Yes	0.5	The horizontal origin value.
y	number	Yes	"x"	The vertical origin value. If not defined it will be set to the value of x.

Overrides: Phaser.GameObjects.Components.Origin#setOrigin

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L1168
Since: 3.60.0

---

setSize

<instance> setSize(width, height)

Description:

Sets the size of this Game Object.

For a Nine Slice Game Object this means it will be stretched (or shrunk) horizontally and vertically depending on the dimensions given to this method, in accordance with how it has been configured for the various corner sizes.

If this is a 3-slice object, you can only stretch it horizontally and changing the height will be ignored.

If you have enabled this Game Object for input, changing the size will also change the size of the hit area.

Parameters:

name	type	optional	description
width	number	No	The width of this Game Object.
height	number	No	The height of this Game Object.

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L1058
Since: 3.60.0

---

setSizeToFrame

<instance> setSizeToFrame()

Description:

Resets the size of this Nine Slice Game Object to match the current texture frame.

For a 3-slice object, this sets the height to match the frame height and refreshes the UV coordinates. For a 9-slice object, only the UVs are refreshed. This is called automatically when the texture frame changes and should not normally need to be called directly.

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L1194
Since: 3.60.0

---

setSlices

<instance> setSlices([width], [height], [leftWidth], [rightWidth], [topHeight], [bottomHeight], [skipScale9])

Description:

Resets the width, height and slices for this NineSlice Game Object.

This allows you to modify the texture being used by this object and then reset the slice configuration, to avoid having to destroy this Game Object in order to use it for a different game element.

Please note that you cannot change a 9-slice to a 3-slice or vice versa.

Parameters:

name	type	optional	default	description
width	number	Yes	256	The width of the Nine Slice Game Object. You can adjust the width post-creation.
height	number	Yes	256	The height of the Nine Slice Game Object. If this is a 3 slice object the height will be fixed to the height of the texture and cannot be changed.
leftWidth	number	Yes	10	The size of the left vertical column (A).
rightWidth	number	Yes	10	The size of the right vertical column (B).
topHeight	number	Yes	0	The size of the top horizontal row (C). Set to zero or undefined to create a 3 slice object.
bottomHeight	number	Yes	0	The size of the bottom horizontal row (D). Set to zero or undefined to create a 3 slice object.
skipScale9	boolean	Yes	false	If this Nine Slice was created from Texture Packer scale9 atlas data, set this property to use the given column sizes instead of those specified in the JSON.

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L407
Since: 3.60.0

---

setTint

<instance> setTint([color])

Description:

Sets a tint on this Game Object.

The tint applies a color to the pixel color values from the GameObject's texture in one of several modes, set with setTintMode or the tintMode property.

To modify the tint color once set, either call this method again with new values or use the tint property.

To remove a tint call clearTint, or call this method with no parameters.

Tags:

• webglOnly

Parameters:

name	type	optional	default	description
color	number	Yes	"0xffffff"	The tint being applied to the entire Game Object.

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L862
Since: 3.60.0

---

setTintMode

<instance> setTintMode([mode])

Description:

Sets the tint mode for this Game Object.

The tint mode applies a color to the pixel color values from the GameObject's texture in one of several modes:

• Phaser.TintModes.MULTIPLY (default)

• Phaser.TintModes.FILL

• Phaser.TintModes.ADD

• Phaser.TintModes.SCREEN

• Phaser.TintModes.OVERLAY

• Phaser.TintModes.HARD_LIGHT

Tags:

• webglOnly

Parameters:

name	type	optional	default	description
mode	Phaser.TintModes	Yes	"Phaser.TintModes.MULTIPLY"	The tint mode to use.

Returns: Phaser.GameObjects.NineSlice - This Game Object instance.

Source: src/gameobjects/nineslice/NineSlice.js#L891
Since: 4.0.0

---

updateQuad

<instance> updateQuad(offset, x1, y1, x2, y2)

Description:

Internally updates the position coordinates across all vertices of the given quad offset.

You should not typically need to call this method directly, but it is left public should an extended class require it.

Parameters:

name	type	optional	description
offset	number	No	The offset in the vertices array of the quad to update.
x1	number	No	The top-left X coordinate of the quad, in normalized space (-0.5 to 0.5).
y1	number	No	The top-left Y coordinate of the quad, in normalized space (-0.5 to 0.5).
x2	number	No	The bottom-right X coordinate of the quad, in normalized space (-0.5 to 0.5).
y2	number	No	The bottom-right Y coordinate of the quad, in normalized space (-0.5 to 0.5).

Source: src/gameobjects/nineslice/NineSlice.js#L756
Since: 3.60.0

---

updateQuadUVs

<instance> updateQuadUVs(offset, u1, v1, u2, v2)

Description:

Internally updates the UV coordinates across all vertices of the given quad offset, based on the frame size.

You should not typically need to call this method directly, but it is left public should an extended class require it.

Parameters:

name	type	optional	description
offset	number	No	The offset in the vertices array of the quad to update.
u1	number	No	The top-left U coordinate of the quad, in the range 0 to 1.
v1	number	No	The top-left V coordinate of the quad, in the range 0 to 1.
u2	number	No	The bottom-right U coordinate of the quad, in the range 0 to 1.
v2	number	No	The bottom-right V coordinate of the quad, in the range 0 to 1.

Source: src/gameobjects/nineslice/NineSlice.js#L789
Since: 3.60.0

---

updateUVs

<instance> updateUVs()

Description:

Updates all of the vertex UV coordinates. This is called automatically when the NineSlice Game Object is created, or if the texture frame changes.

Unlike with the updateVertices method, you do not need to call this method if the Nine Slice changes size. Only if it changes texture frame.

Source: src/gameobjects/nineslice/NineSlice.js#L504
Since: 3.60.0

---

updateVertices

<instance> updateVertices()

Description:

Recalculates all of the vertices in this Nine Slice Game Object based on the leftWidth, rightWidth, topHeight, bottomHeight, tileX and tileY properties, combined with the Game Object size.

This method is called automatically when this object is created or if its origin is changed.

You should not typically need to call this method directly, but it is left public should you find a need to modify one of those properties after creation.

Source: src/gameobjects/nineslice/NineSlice.js#L580
Since: 3.60.0

---