Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Sprites and Animation

Phaser Images and Sprites: Origin, Flip, Tint and Depth

Learn the difference between Phaser images and sprites and how to position, scale, rotate, flip, tint, crop and layer them, with live examples you can edit.

Pictures are what most players remember about a game. In Phaser there are two main picture objects: the Image and the Sprite. They look the same on screen; they differ in what they can do. This lesson explains how to choose, and shows every property you will use daily: position, origin, scale, rotation, flip, tint, alpha, blend mode, depth and display size.

Live examples draw their pictures in code (see Loading Assets) so they need no files. With real files, replace the generated key with a loaded key; everything else stays the same.

Image or sprite?

JavaScript
this.add.image(x, y, 'key');     // a static picture
this.add.sprite(x, y, 'key');    // a picture that can play frame animations
  • An Image has position, scale, rotation, tint, alpha and depth. It is lightweight. Use it for backgrounds, decorations, icons and anything that never animates.
  • A Sprite is an Image plus an animation component. Use it for characters, coins, explosions: anything with frames. Sprites cost slightly more memory, so do not use them for static scenery.
  • For physics, this.physics.add.image(...) and this.physics.add.sprite(...) create the same two kinds already equipped with an Arcade body.

Both are created with a texture key and optionally a frame: this.add.sprite(100, 100, 'hero', 3) shows frame 3 of the texture named hero.

A texture to play with

The examples need an image, so this helper draws a small spaceship and registers it under the key ship. You will see the same helper in later lessons.

JavaScript
function makeShip(scene) {
  const g = scene.add.graphics();
  g.fillStyle(0xe2e8f0).fillTriangle(32, 0, 64, 56, 0, 56);       // body
  g.fillStyle(0x38bdf8).fillCircle(32, 36, 9);                    // window
  g.fillStyle(0xf97316).fillRect(10, 56, 14, 8).fillRect(40, 56, 14, 8);   // engines
  g.generateTexture('ship', 64, 64);
  g.destroy();
}

Position, origin and rotation

x and y place the object's origin point. By default the origin is the center (0.5, 0.5). Change it to rotate around another point:

JavaScript
const ship = this.add.image(200, 150, 'ship');
ship.setOrigin(0.5, 1);     // pivot at the bottom center
ship.setAngle(30);          // degrees (rotation is in radians)

A door should swing around its hinge, so its origin is on the hinge side. A bar that grows rightward needs origin (0, 0.5). A character should usually have its origin at its feet (0.5, 1) so that its y means "where it stands".

Scale, size and flipping

  • setScale(2) doubles the size; setScale(2, 0.5) stretches. Scaling is relative to the texture size.
  • setDisplaySize(w, h) forces an exact pixel size, handy for backgrounds that must fill the screen.
  • setFlipX(true) and setFlipY(true) mirror the picture without a second image. A character walking left uses the right-facing image flipped, halving the artwork.
  • width and height are the texture's size; displayWidth and displayHeight include scale.

Tint, alpha and blend modes

JavaScript
ship.setTint(0xff6666);          // multiply the picture's colors
ship.setTint(0xff0000, 0x00ff00, 0x0000ff, 0xffff00);  // a corner each
ship.clearTint();
ship.setAlpha(0.5);              // half transparent
ship.setBlendMode(Phaser.BlendModes.ADD);   // glowing, additive blending

Tint multiplies each pixel, so a white picture tinted red becomes red, while a black pixel stays black. This is how one white sprite becomes enemies of many colors, or how a character flashes red when hit. Additive blending (ADD) brightens what is behind the object, which suits fire, sparks and lights.

Depth and layering

When two pictures overlap, the later-created one is drawn on top. Use setDepth for a game with layers:

JavaScript
background.setDepth(0);
enemies.setDepth(10);
player.setDepth(20);
hud.setDepth(100);

For a top-down view where lower objects should cover those behind them, set depth = y every frame (this is called y-sorting).

Origin, flip, tint and depth

In the bottom row, all three ships use the same angle, but each swings around a different point, which is the dot. That is the essence of origin.

Following the pointer: angles and vectors

Rotating something toward the mouse is a classic. Phaser.Math.Angle.Between(x1, y1, x2, y2) returns the angle in radians from point 1 to point 2. Our ship points up in the picture, but Phaser's angle zero points right, so we add a quarter turn (a 90 degree offset). The example rotates the ship to face the pointer and drifts toward it.

A ship that faces the pointer

The two key ideas: angle = Between(source, target) and movement = cos(angle) and sin(angle) times speed. Phaser also has this.physics.moveToObject and velocityFromRotation, which wrap this math for physics bodies.

Cropping, frames and swapping textures

  • setCrop(x, y, w, h) shows only part of the picture, handy for progress bars: crop a full bar image by the health fraction.
  • setFrame(nameOrIndex) switches to another frame of the same texture (covered in Spritesheets and Animation).
  • setTexture('otherKey') swaps the picture entirely, for example to a damaged version of an enemy.

Pixel-perfect input and bounds

An image's clickable area is its rectangle unless you ask for pixel testing: setInteractive({ pixelPerfect: true }). Use it for irregular shapes, but sparingly because it checks the texture on every pointer move. getBounds() returns the rectangle that covers the object, including scale and rotation, which is useful for layout and for custom hit tests.

Destroying objects

When an object is no longer needed, call obj.destroy(). It removes the object from the scene and frees its resources; it also stops its timers and tweens that target it. Hiding with setVisible(false) keeps it in memory and in physics. For many short-lived objects (bullets), prefer groups with pooling, covered in Containers, Groups and Particles.

Common mistakes

  • Using sprites for everything. Use images for static pictures.
  • Rotating around the wrong point. Set the origin first.
  • Mixing degrees and radians. angle is degrees, rotation is radians.
  • A picture that points up but moves right. Add or subtract Math.PI / 2 when your art does not face right.
  • Scaling pixel art without pixelArt: true. It blurs; set it in the game config.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. When should you use a Sprite instead of an Image?

    A Sprite adds the animation component to an Image. Static pictures should be Images because they are lighter.
  2. 2. You want a door to swing around its left hinge. What do you change?

    Rotation happens around the origin, so putting the origin on the hinge side makes the door swing correctly.
  3. 3. What is the unit of the angle property, and of rotation?

    angle is a convenience in degrees; rotation is the underlying radian value.
  4. 4. How can one white sprite appear red, green or blue in different enemies?

    setTint multiplies the texture colors, so a white texture takes on the tint color.
  5. 5. Which call returns the radian angle from one point to another?

    Angle.Between(x1, y1, x2, y2) gives the angle in radians, with 0 pointing right.

Summary

  • Use add.image for static pictures and add.sprite for animated ones; physics versions come from this.physics.add.
  • origin sets the pivot for position, rotation and scale; feet-origin and hinge-origin are common choices.
  • setScale, setDisplaySize, setFlipX, setTint, setAlpha, setBlendMode and setDepth change appearance without new art.
  • Phaser.Math.Angle.Between and cos/sin turn angles into movement; mind degrees versus radians and the picture's facing direction.
  • Destroy objects you no longer need; pool the ones you create constantly.

Next: Spritesheets and Frame Animation