Phaser API Documentation

  Version: 
Filter

A Texture consists of a source, usually an Image from the Cache, and a collection of Frames. The Frames represent the different areas of the Texture. For example a texture atlas may have many Frames, one for each element within the atlas. Where-as a single image would have just one frame, that encompasses the whole image.

Every Texture, no matter where it comes from, always has at least 1 frame called the __BASE frame. This frame represents the entirety of the source image.

Textures are managed by the global TextureManager. This is a singleton class that is responsible for creating and delivering Textures and their corresponding Frames to Game Objects.

Sprites and other Game Objects get the texture data they need from the TextureManager.

Constructor:

new Texture(manager, key, source, [width], [height])

Parameters:

name type arguments description
manager Phaser.Textures.TextureManager

A reference to the Texture Manager this Texture belongs to.

key string

The unique string-based key of this Texture.

source HTMLImageElement | HTMLCanvasElement | Array.<HTMLImageElement> | Array.<HTMLCanvasElement> | Phaser.Renderer.WebGL.Wrappers.WebGLTextureWrapper

An array of sources that are used to create the texture. Usually Images, but can also be a Canvas.

width number <optional>

The width of the Texture. This is optional and automatically derived from the source images.

height number <optional>

The height of the Texture. This is optional and automatically derived from the source images.

Since: 3.0.0
Source: src/textures/Texture.js (Line 13)

Members

customData: object
Focus
Focus

Description:

Any additional data that was set in the source JSON (if any), or any extra data you'd like to store relating to this texture

Type:
object
Since: 3.0.0
Source: src/textures/Texture.js (Line 97)
Focus
Focus
dataSource: array
Focus
Focus

Description:

An array of TextureSource data instances. Used to store additional data images, such as normal maps or specular maps.

Type:
array
Since: 3.0.0
Source: src/textures/Texture.js (Line 78)
Focus
Focus
firstFrame: string
Focus
Focus

Description:

The name of the first frame of the Texture.

Type:
string
Since: 3.0.0
Source: src/textures/Texture.js (Line 107)
Focus
Focus
frameTotal: number
Focus
Focus

Description:

The total number of Frames in this Texture, including the __BASE frame.

A Texture will always contain at least 1 frame because every Texture contains a __BASE frame by default, in addition to any extra frames that have been added to it, such as when parsing a Sprite Sheet or Texture Atlas.

Type:
number
Default: 0
Since: 3.0.0
Source: src/textures/Texture.js (Line 116)
Focus
Focus
frames: object
Focus
Focus

Description:

A key-value object pair associating the unique Frame keys with the Frames objects.

Type:
object
Since: 3.0.0
Source: src/textures/Texture.js (Line 88)
Focus
Focus
key: string
Focus
Focus

Description:

The unique string-based key of this Texture.

Type:
string
Since: 3.0.0
Source: src/textures/Texture.js (Line 59)
Focus
Focus

Description:

A reference to the Texture Manager this Texture belongs to.

Type:
Since: 3.0.0
Source: src/textures/Texture.js (Line 50)
Focus
Focus

Description:

An array of TextureSource instances. These are unique to this Texture and contain the actual Image (or Canvas) data.

Type:
Since: 3.0.0
Source: src/textures/Texture.js (Line 68)
Focus
Focus

Methods

add(name, sourceIndex, x, y, width, height)
Focus
Focus

Description:

Adds a new Frame to this Texture.

A Frame is a rectangular region of a TextureSource with a unique index or string-based key.

The name given must be unique within this Texture. If it already exists, this method will return null.

Parameters:

name type description
name number | string

The name of this Frame. The name is unique within the Texture.

sourceIndex number

The index of the TextureSource that this Frame is a part of.

x number

The x coordinate of the top-left of this Frame.

y number

The y coordinate of the top-left of this Frame.

width number

The width of this Frame.

height number

The height of this Frame.

Returns:
Description:

The Frame that was added to this Texture, or null if the given name already exists.

Since: 3.0.0
Source: src/textures/Texture.js (Line 136)
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys this Texture and releases references to its sources and frames.

Since: 3.0.0
Source: src/textures/Texture.js (Line 531)
Focus
Focus
get([name])
Focus
Focus

Description:

Gets a Frame from this Texture based on either the key or the index of the Frame.

In a Texture Atlas Frames are typically referenced by a key. In a Sprite Sheet Frames are referenced by an index. Passing no value for the name returns the base texture.

Parameters:

name type arguments description
name string | number <optional>

The string-based name, or integer based index, of the Frame to get from this Texture.

Returns:
Description:

The Texture Frame.

Since: 3.0.0
Source: src/textures/Texture.js (Line 224)
Focus
Focus
getDataSourceImage([name])
Focus
Focus

Description:

Given a Frame name, return the data source image it uses to render with. You can use this to get the normal map for an image for example.

This will return the actual DOM Image.

Parameters:

name type arguments description
name string | number <optional>

The string-based name, or integer based index, of the Frame to get from this Texture.

Returns:
Description:

The DOM Image or Canvas Element.

Type:
  • HTMLImageElement
  • HTMLCanvasElement
Since: 3.7.0
Source: src/textures/Texture.js (Line 439)
Focus
Focus
getFrameBounds([sourceIndex])
Focus
Focus

Description:

Based on the given Texture Source Index, this method will get all of the Frames using that source and then work out the bounds that they encompass, returning them in an object.

This is useful if this Texture is, for example, a sprite sheet within an Atlas, and you need to know the total bounds of the sprite sheet.

Parameters:

name type arguments description
sourceIndex number <optional>

The index of the TextureSource to get the Frame bounds from.

Returns:
Description:

An object containing the bounds of the Frames using the given Texture Source Index.

Since: 3.80.0
Source: src/textures/Texture.js (Line 319)
Focus
Focus
getFrameNames([includeBase])
Focus
Focus

Description:

Returns an array with all of the names of the Frames in this Texture.

Useful if you want to randomly assign a Frame to a Game Object, as you can pick a random element from the returned array.

Parameters:

name type arguments Default description
includeBase boolean <optional> false

Include the __BASE Frame in the output array?

Returns:
Description:

An array of all Frame names in this Texture.

Type:
  • Array.<string>
Since: 3.0.0
Source: src/textures/Texture.js (Line 374)
Focus
Focus
getFramesFromTextureSource(sourceIndex, [includeBase])
Focus
Focus

Description:

Returns an array of all the Frames in the given TextureSource.

Parameters:

name type arguments Default description
sourceIndex number

The index of the TextureSource to get the Frames from.

includeBase boolean <optional> false

Include the __BASE Frame in the output array?

Returns:
Description:

An array of Texture Frames.

Type:
Since: 3.0.0
Source: src/textures/Texture.js (Line 284)
Focus
Focus
getSourceImage([name])
Focus
Focus

Description:

Given a Frame name, return the source image it uses to render with.

This will return the actual DOM Image or Canvas element.

Parameters:

name type arguments description
name string | number <optional>

The string-based name, or integer based index, of the Frame to get from this Texture.

Returns:
Description:

The DOM Image, Canvas Element or Render Texture.

Type:
Since: 3.0.0
Source: src/textures/Texture.js (Line 406)
Focus
Focus
getTextureSourceIndex(source)
Focus
Focus

Description:

Takes the given TextureSource and returns the index of it within this Texture. If it's not in this Texture, it returns -1. Unless this Texture has multiple TextureSources, such as with a multi-atlas, this method will always return zero or -1.

Parameters:

name type description
source Phaser.Textures.TextureSource

The TextureSource to check.

Returns:
Description:

The index of the TextureSource within this Texture, or -1 if not in this Texture.

Type:
  • number
Since: 3.0.0
Source: src/textures/Texture.js (Line 258)
Focus
Focus
has(name)
Focus
Focus

Description:

Checks to see if a Frame matching the given key exists within this Texture.

Parameters:

name type description
name string

The key of the Frame to check for.

Returns:
Description:

True if a Frame with the matching key exists in this Texture.

Type:
  • boolean
Since: 3.0.0
Source: src/textures/Texture.js (Line 209)
Focus
Focus
remove(name)
Focus
Focus

Description:

Removes the given Frame from this Texture. The Frame is destroyed immediately.

Any Game Objects using this Frame should stop using it before you remove it, as it does not happen automatically.

Parameters:

name type description
name string

The key of the Frame to remove.

Returns:
Description:

True if a Frame with the matching key was removed from this Texture.

Type:
  • boolean
Since: 3.19.0
Source: src/textures/Texture.js (Line 180)
Focus
Focus
setDataSource(data)
Focus
Focus

Description:

Adds a data source image to this Texture.

An example of a data source image would be a normal map, where all of the Frames for this Texture equally apply to the normal map.

Parameters:

name type description
data HTMLImageElement | HTMLCanvasElement | Array.<HTMLImageElement> | Array.<HTMLCanvasElement>

The source image.

Since: 3.0.0
Source: src/textures/Texture.js (Line 476)
Focus
Focus
setFilter(filterMode)
Focus
Focus

Description:

Sets the Filter Mode for this Texture.

The mode can be either Linear, the default, or Nearest.

For pixel-art you should use Nearest.

The mode applies to the entire Texture, not just a specific Frame of it.

Parameters:

name type description
filterMode Phaser.Textures.FilterMode

The Filter Mode.

Since: 3.0.0
Source: src/textures/Texture.js (Line 502)
Focus
Focus