Phaser Class: Sprite

new Sprite(game, x, y, key, frame)

Create a new Sprite object. Sprites are the lifeblood of your game, used for nearly everything visual. At its most basic a Sprite consists of a set of coordinates and a texture that is rendered to the canvas. They also contain additional properties allowing for physics motion (via Sprite.body), input handling (via Sprite.input), events (via Sprite.events), animation (via Sprite.animations), camera culling and more. Please see the Examples for use cases.

Parameters:

Name	Type	Description
`game`	Phaser.Game	A reference to the currently running game.
`x`	number	The x coordinate (in world space) to position the Sprite at.
`y`	number	The y coordinate (in world space) to position the Sprite at.
`key`	string \| Phaser.RenderTexture \| PIXI.Texture	This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache entry, or an instance of a RenderTexture or PIXI.Texture.
`frame`	string \| number	If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

Source:

gameobjects/Sprite.js, line 21

Members

alive

Properties:

Name	Type	Description
`alive`	boolean	This is a handy little var your game can use to determine if a sprite is alive or not, it doesn't effect rendering.

Default Value:

true

Source:

gameobjects/Sprite.js, line 43

anchor

The anchor sets the origin point of the texture. The default is 0,0 this means the textures origin is the top left Setting than anchor to 0.5,0.5 means the textures origin is centered Setting the anchor to 1,1 would mean the textures origin points will be the bottom right

Properties:

Name	Type	Description
`anchor`	Phaser.Point	The anchor around with Sprite rotation and scaling takes place.

Source:

gameobjects/Sprite.js, line 159

angle

Indicates the rotation of the Sprite, in degrees, from its original orientation. Values from 0 to 180 represent clockwise rotation; values from 0 to -180 represent counterclockwise rotation. Values outside this range are added to or subtracted from 360 to obtain a value within the range. For example, the statement player.angle = 450 is the same as player.angle = 90. If you wish to work in radians instead of degrees use the property Sprite.rotation instead.

Properties:

Name	Type	Description
`angle`	number	Gets or sets the Sprites angle of rotation in degrees.

Source:

gameobjects/Sprite.js, line 928

animations

Properties:

Name	Type	Description
`animations`	Phaser.AnimationManager	This manages animations of the sprite. You can modify animations through it (see Phaser.AnimationManager)

Source:

gameobjects/Sprite.js, line 84

autoCull

Should this Sprite be automatically culled if out of range of the camera? A culled sprite has its renderable property set to 'false'.

Properties:

Name	Type	Description
`autoCull`	boolean	A flag indicating if the Sprite should be automatically camera culled or not.

Default Value:

false

Source:

gameobjects/Sprite.js, line 186

body

Properties:

Name	Type	Description
`body`	Phaser.Physics.Arcade.Body	By default Sprites have a Phaser.Physics Body attached to them. You can operate physics actions via this property, or null it to skip all physics updates.

Source:

gameobjects/Sprite.js, line 281

bottomLeft

Properties:

Name	Type	Description
`bottomLeft`	Phaser.Point	A Point containing the bottom left coordinate of the Sprite. Takes rotation and scale into account.

Source:

gameobjects/Sprite.js, line 268

bottomRight

Properties:

Name	Type	Description
`bottomRight`	Phaser.Point	A Point containing the bottom right coordinate of the Sprite. Takes rotation and scale into account.

Source:

gameobjects/Sprite.js, line 263

bounds

This Rectangle object fully encompasses the Sprite and is updated in real-time. The bounds is the full bounding area after rotation and scale have been taken into account. It should not be modified directly. It's used for Camera culling and physics body alignment.

Properties:

Name	Type	Description
`bounds`	Phaser.Rectangle

Source:

gameobjects/Sprite.js, line 276

cameraOffset

Properties:

Name	Type	Description
`cameraOffset`	Phaser.Point	If this Sprite is fixed to the camera then use this Point to specify how far away from the Camera x/y it's rendered.

Source:

gameobjects/Sprite.js, line 322

center

Properties:

Name	Type	Description
`center`	Phaser.Point	A Point containing the center coordinate of the Sprite. Takes rotation and scale into account.

Source:

gameobjects/Sprite.js, line 248

crop

You can crop the Sprites texture by modifying the crop properties. For example crop.width = 50 would set the Sprite to only render 50px wide. The crop is only applied if you have set Sprite.cropEnabled to true.

Properties:

Name	Type	Description
`crop`	Phaser.Rectangle	The crop Rectangle applied to the Sprite texture before rendering.

Source:

gameobjects/Sprite.js, line 330

cropEnabled

Properties:

Name	Type	Description
`cropEnabled`	boolean	If true the Sprite.crop property is used to crop the texture before render. Set to false to disable.

Default Value:

false

Source:

gameobjects/Sprite.js, line 336

currentFrame

Properties:

Name	Type	Description
`currentFrame`	Phaser.Frame	A reference to the currently displayed frame.

Source:

gameobjects/Sprite.js, line 99

events

Properties:

Name	Type	Description
`events`	Events	The Events you can subscribe to that are dispatched when certain things happen on this Sprite or its components.

Source:

gameobjects/Sprite.js, line 79

exists

Properties:

Name	Type	Description
`exists`	boolean	If exists = false then the Sprite isn't updated by the core game loop or physics subsystem at all.

Default Value:

true

Source:

gameobjects/Sprite.js, line 37

fixedToCamera

A Sprite that is fixed to the camera ignores the position of any ancestors in the display list and uses its x/y coordinates as offsets from the top left of the camera.

Properties:

Name	Type	Description
`fixedToCamera`	boolean	Fixes this Sprite to the Camera.

Default Value:

false

Source:

gameobjects/Sprite.js, line 317

frame

Properties:

Name	Type	Description
`frame`	number	Gets or sets the current frame index and updates the Texture Cache for display.

Source:

gameobjects/Sprite.js, line 947

frameName

Properties:

Name	Type	Description
`frameName`	string	Gets or sets the current frame name and updates the Texture Cache for display.

Source:

gameobjects/Sprite.js, line 963

game

Properties:

Name	Type	Description
`game`	Phaser.Game	A reference to the currently running Game.

Source:

gameobjects/Sprite.js, line 31

group

Properties:

Name	Type	Description
`group`	Phaser.Group	The parent Group of this Sprite. This is usually set after Sprite instantiation by the parent.

Source:

gameobjects/Sprite.js, line 48

health

Properties:

Name	Type	Description
`health`	number	Health value. Used in combination with damage() to allow for quick killing of Sprites.

Source:

gameobjects/Sprite.js, line 286

height

The height of the sprite in pixels, setting this will actually modify the scale to acheive the value desired. If you wish to crop the Sprite instead see the Sprite.crop value.

Properties:

Name	Type	Description
`height`	number	The height of the Sprite in pixels.

Source:

gameobjects/Sprite.js, line 1015

<readonly> inCamera

Properties:

Name	Type	Description
`inCamera`	boolean	Is this sprite visible to the camera or not?

Source:

gameobjects/Sprite.js, line 979

input

Properties:

Name	Type	Description
`input`	InputHandler	The Input Handler Component.

Source:

gameobjects/Sprite.js, line 89

inputEnabled

By default a Sprite won't process any input events at all. By setting inputEnabled to true the Phaser.InputHandler is activated for this Sprite instance and it will then start to process click/touch events and more.

Properties:

Name	Type	Description
`inputEnabled`	boolean	Set to true to allow this Sprite to receive input events, otherwise false.

Source:

gameobjects/Sprite.js, line 1038

inWorld

Properties:

Name	Type	Description
`inWorld`	boolean	This value is set to true if the Sprite is positioned within the World, otherwise false.

Source:

gameobjects/Sprite.js, line 291

inWorldThreshold

Properties:

Name	Type	Description
`inWorldThreshold`	number	A threshold value applied to the inWorld check. If you don't want a Sprite to be considered "out of the world" until at least 100px away for example then set it to 100.

Default Value:

Source:

gameobjects/Sprite.js, line 297

key

Properties:

Name	Type	Description
`key`	string \| Phaser.RenderTexture \| PIXI.Texture	This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache entry, or an instance of a RenderTexture or PIXI.Texture.

Source:

gameobjects/Sprite.js, line 94

lifespan

If you would like the Sprite to have a lifespan once 'born' you can set this to a positive value. Handy for particles, bullets, etc. The lifespan is decremented by game.time.elapsed each update, once it reaches zero the kill() function is called.

Properties:

Name	Type	Description
`lifespan`	number	The lifespan of the Sprite (in ms) before it will be killed.

Default Value:

Source:

gameobjects/Sprite.js, line 74

name

Properties:

Name	Type	Description
`name`	string	The user defined name given to this Sprite.

Source:

gameobjects/Sprite.js, line 54

offset

Properties:

Name	Type	Description
`offset`	Phaser.Point	Corner point defaults. Should not typically be modified.

Source:

gameobjects/Sprite.js, line 243

outOfBoundsKill

Properties:

Name	Type	Description
`outOfBoundsKill`	boolean	If true the Sprite is killed as soon as Sprite.inWorld is false.

Default Value:

false

Source:

gameobjects/Sprite.js, line 303

renderOrderID

Properties:

Name	Type	Description
`renderOrderID`	number	Used by the Renderer and Input Manager to control picking order.

Source:

gameobjects/Sprite.js, line 66

scale

Properties:

Name	Type	Description
`scale`	Phaser.Point	The scale of the Sprite when rendered. By default it's set to 1 (no scale). You can modify it via scale.x or scale.y or scale.setTo(x, y). A value of 1 means no change to the scale, 0.5 means "half the size", 2 means "twice the size", etc.

Source:

gameobjects/Sprite.js, line 191

textureRegion

The rectangular area from the texture that will be rendered.

Properties:

Name	Type	Description
`textureRegion`	Phaser.Rectangle

Source:

gameobjects/Sprite.js, line 149

topLeft

Properties:

Name	Type	Description
`topLeft`	Phaser.Point	A Point containing the top left coordinate of the Sprite. Takes rotation and scale into account.

Source:

gameobjects/Sprite.js, line 253

topRight

Properties:

Name	Type	Description
`topRight`	Phaser.Point	A Point containing the top right coordinate of the Sprite. Takes rotation and scale into account.

Source:

gameobjects/Sprite.js, line 258

type

Properties:

Name	Type	Description
`type`	number	The const type of this object.

Source:

gameobjects/Sprite.js, line 60

width

The width of the sprite in pixels, setting this will actually modify the scale to acheive the value desired. If you wish to crop the Sprite instead see the Sprite.crop value.

Properties:

Name	Type	Description
`width`	number	The width of the Sprite in pixels.

Source:

gameobjects/Sprite.js, line 992

world

Properties:

Name	Type	Description
`world`	Phaser.Point	The world coordinates of this Sprite. This differs from the x/y coordinates which are relative to the Sprites container.

Source:

gameobjects/Sprite.js, line 177

x

Properties:

Name	Type	Description
`x`	number	The x coordinate (in world space) of this Sprite.

Source:

gameobjects/Sprite.js, line 164

y

Properties:

Name	Type	Description
`y`	number	The y coordinate (in world space) of this Sprite.

Source:

gameobjects/Sprite.js, line 169

Methods

bringToTop()

Brings the Sprite to the top of the display list it is a child of. Sprites that are members of a Phaser.Group are only bought to the top of that Group, not the entire display list.

Source:

gameobjects/Sprite.js, line 884

Returns:

(Phaser.Sprite) This instance.

centerOn(x, y)

Moves the sprite so its center is located on the given x and y coordinates. Doesn't change the anchor point of the sprite.

Parameters:

Name	Type	Description
`x`	number	The x coordinate (in world space) to position the Sprite at.
`y`	number	The y coordinate (in world space) to position the Sprite at.

Source:

gameobjects/Sprite.js, line 714

Returns:

(Phaser.Sprite) This instance.

damage(amount)

Damages the Sprite, this removes the given amount from the Sprites health property. If health is then taken below zero Sprite.kill is called.

Parameters:

Name	Type	Description
`amount`	number	The amount to subtract from the Sprite.health value.

Source:

gameobjects/Sprite.js, line 822

Returns:

(Phaser.Sprite) This instance.

destroy()

Description.

Source:

gameobjects/Graphics.js, line 35

destroy()

Destroys the Sprite. This removes it from its parent group, destroys the input, event and animation handlers if present and nulls its reference to game, freeing it up for garbage collection.

Source:

gameobjects/Sprite.js, line 785

getLocalPosition(p, x, y, sx, sy) → {Phaser.Point}

Gets the local position of a coordinate relative to the Sprite, factoring in rotation and scale. Mostly only used internally.

Parameters:

Name	Type	Description
`p`	Phaser.Point	The Point object to store the results in.
`x`	number	x coordinate within the Sprite to translate.
`y`	number	x coordinate within the Sprite to translate.
`sx`	number	Scale factor to be applied.
`sy`	number	Scale factor to be applied.

Source:

gameobjects/Sprite.js, line 569

Returns:

The translated point.

Type: Phaser.Point

getLocalUnmodifiedPosition(p, x, y) → {Phaser.Point}

Gets the local unmodified position of a coordinate relative to the Sprite, factoring in rotation and scale. Mostly only used internally by the Input Manager, but also useful for custom hit detection.

Parameters:

Name	Type	Description
`p`	Phaser.Point	The Point object to store the results in.
`x`	number	x coordinate within the Sprite to translate.
`y`	number	x coordinate within the Sprite to translate.

Source:

gameobjects/Sprite.js, line 591

Returns:

The translated point.

Type: Phaser.Point

kill()

Kills a Sprite. A killed Sprite has its alive, exists and visible properties all set to false. It will dispatch the onKilled event, you can listen to Sprite.events.onKilled for the signal. Note that killing a Sprite is a way for you to quickly recycle it in a Sprite pool, it doesn't free it up from memory. If you don't need this Sprite any more you should call Sprite.destroy instead.

Source:

gameobjects/Sprite.js, line 760

Returns:

(Phaser.Sprite) This instance.

loadTexture(key, frame)

Changes the Texture the Sprite is using entirely. The old texture is removed and the new one is referenced or fetched from the Cache. This causes a WebGL texture update, so use sparingly or in low-intensity portions of your game.

Parameters:

Name	Type	Description
`key`	string \| Phaser.RenderTexture \| PIXI.Texture	This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache entry, or an instance of a RenderTexture or PIXI.Texture.
`frame`	string \| number	If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

Source:

gameobjects/Sprite.js, line 660

play(name, frameRate, loop, killOnComplete) → {Phaser.Animation}

Play an animation based on the given key. The animation should previously have been added via sprite.animations.add() If the requested animation is already playing this request will be ignored. If you need to reset an already running animation do so directly on the Animation object itself.

Parameters:

Name	Type	Argument	Default	Description
`name`	string			The name of the animation to be played, e.g. "fire", "walk", "jump".
`frameRate`	number	<optional>	null	The framerate to play the animation at. The speed is given in frames per second. If not provided the previously set frameRate of the Animation is used.
`loop`	boolean	<optional>	false	Should the animation be looped after playback. If not provided the previously set loop value of the Animation is used.
`killOnComplete`	boolean	<optional>	false	If set to true when the animation completes (only happens if loop=false) the parent Sprite will be killed.

Source:

gameobjects/Sprite.js, line 907

Returns:

A reference to playing Animation instance.

Type: Phaser.Animation

postUpdate()

Internal function called by the World postUpdate cycle.

Source:

gameobjects/Sprite.js, line 625

preUpdate()

Automatically called by World.preUpdate. Handles cache updates, lifespan checks, animation updates and physics updates.

Source:

gameobjects/Sprite.js, line 347

reset(x, y, health)

Resets the Sprite. This places the Sprite at the given x/y world coordinates and then sets alive, exists, visible and renderable all to true. Also resets the outOfBounds state and health values. If the Sprite has a physics body that too is reset.

Parameters:

Name	Type	Argument	Default	Description
`x`	number			The x coordinate (in world space) to position the Sprite at.
`y`	number			The y coordinate (in world space) to position the Sprite at.
`health`	number	<optional>	1	The health to give the Sprite.

Source:

gameobjects/Sprite.js, line 847

Returns:

(Phaser.Sprite) This instance.

resetCrop()

Resets the Sprite.crop value back to the frame dimensions.

Source:

gameobjects/Sprite.js, line 611

revive(health)

Brings a 'dead' Sprite back to life, optionally giving it the health value specified. A resurrected Sprite has its alive, exists and visible properties all set to true. It will dispatch the onRevived event, you can listen to Sprite.events.onRevived for the signal.