Options
All
  • Public
  • Public/Protected
  • All
Menu

A Sprite is one of the main drawing primitives. It is responsible for drawing images or parts of images from a Texture resource to the screen.

Creating a sprite

To create a Sprite you need to have a loaded Texture resource. You can then use Texture.asSprite to quickly create a Sprite or you can create a new instance of Sprite using the constructor. This is useful if you want to "slice" out a portion of an image or if you want to change the dimensions.

var game = new ex.Engine();
var txPlayer = new ex.Texture('/assets/tx/player.png');
// load assets
var loader = new ex.Loader([txPlayer]);

// start game
game.start(loader).then(function() {
  // create a sprite (quick)
  var playerSprite = txPlayer.asSprite();
  // create a sprite (custom)
  var playerSprite = new ex.Sprite(txPlayer, 0, 0, 80, 80);
});

You can then assign an Actor a sprite through Actor.addDrawing and Actor.setDrawing.

Sprite Effects

Excalibur offers many sprite effects such as Colorize to let you manipulate sprites. Keep in mind, more effects requires more power and can lead to memory or CPU constraints and hurt performance. Each effect must be reprocessed every frame for each sprite.

It's still recommended to create an Animation or build in your effects to the sprites for optimal performance.

There are a number of convenience methods available to perform sprite effects. Sprite effects are side-effecting.

const playerSprite = new ex.Sprite(txPlayer, 0, 0, 80, 80);

// darken a sprite by a percentage
playerSprite.darken(0.2); // 20%

// lighten a sprite by a percentage
playerSprite.lighten(0.2); // 20%
// saturate a sprite by a percentage
playerSprite.saturate(0.2); // 20%
// implement a custom effect
class CustomEffect implements ex.EffectsISpriteEffect {
  updatePixel(x: number, y: number, imageData: ImageData) {
    // modify ImageData
  }
}
playerSprite.addEffect(new CustomEffect());

Hierarchy

  • SpriteImpl
    • Sprite

Implements

Index

Constructors

constructor

Properties

anchor

anchor: Vector = new Vector(0.0, 0.0)

effects

effects: Effects.SpriteEffect[] = []

flipHorizontal

flipHorizontal: boolean = false

Draws the sprite flipped horizontally

flipVertical

flipVertical: boolean = false

Draws the sprite flipped vertically

height

height: number = 0

logger

logger: Logger = Logger.getInstance()

rotation

rotation: number = 0

scale

scale: Vector = new Vector(1, 1)

width

width: number = 0

x

x: number = 0

y

y: number = 0

Accessors

drawHeight

  • get drawHeight(): number

drawWidth

  • get drawWidth(): number

Methods

addEffect

  • addEffect(effect: Effects.SpriteEffect): void
  • Adds a new ISpriteEffect to this drawing.

    Parameters

    • effect: Effects.SpriteEffect

      Effect to add to the this drawing

    Returns void

clearEffects

  • clearEffects(): void

clone

  • clone(): SpriteImpl
  • Produces a copy of the current sprite

    Returns SpriteImpl

colorize

  • colorize(color: Color): void
  • Applies the Colorize effect to a sprite, changing the color channels of all pixels to be the average of the original color and the provided color.

    Parameters

    Returns void

darken

  • darken(factor?: number): void
  • Applies the Darken effect to a sprite, changes the darkness of the color according to HSL

    Parameters

    • Default value factor: number = 0.1

    Returns void

debugDraw

  • debugDraw(ctx: CanvasRenderingContext2D, x: number, y: number): void
  • Parameters

    • ctx: CanvasRenderingContext2D
    • x: number
    • y: number

    Returns void

desaturate

  • desaturate(factor?: number): void
  • Applies the Desaturate effect to a sprite, desaturates the color according to HSL

    Parameters

    • Default value factor: number = 0.1

    Returns void

draw

  • draw(ctx: CanvasRenderingContext2D, x: number, y: number): void
  • Draws the sprite appropriately to the 2D rendering context, at an x and y coordinate.

    Parameters

    • ctx: CanvasRenderingContext2D

      The 2D rendering context

    • x: number

      The x coordinate of where to draw

    • y: number

      The y coordinate of where to draw

    Returns void

fill

  • fill(color: Color): void
  • Applies the Fill effect to a sprite, changing the color channels of all non-transparent pixels to match a given color

    Parameters

    Returns void

grayscale

  • grayscale(): void
  • Applies the Grayscale effect to a sprite, removing color information.

    Returns void

invert

  • invert(): void
  • Applies the Invert effect to a sprite, inverting the pixel colors.

    Returns void

lighten

  • lighten(factor?: number): void
  • Applies the Lighten effect to a sprite, changes the lightness of the color according to HSL

    Parameters

    • Default value factor: number = 0.1

    Returns void

opacity

  • opacity(value: number): void
  • Applies the Opacity effect to a sprite, setting the alpha of all pixels to a given value

    Parameters

    • value: number

    Returns void

removeEffect

  • removeEffect(effect: Effects.SpriteEffect): void
  • removeEffect(index: number): void
  • Removes a ISpriteEffect from this sprite.

    Parameters

    • effect: Effects.SpriteEffect

      Effect to remove from this sprite

    Returns void

  • Removes an effect given the index from this sprite.

    Parameters

    • index: number

      Index of the effect to remove from this sprite

    Returns void

reset

  • reset(): void

saturate

  • saturate(factor?: number): void
  • Applies the Saturate effect to a sprite, saturates the color according to HSL

    Parameters

    • Default value factor: number = 0.1

    Returns void