Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Sprite

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 Effects.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.

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

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

// lighten a sprite by a percentage
playerSprite.lighten(.2); // 20%
// saturate a sprite by a percentage
playerSprite.saturate(.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

  • Sprite

Implements

Index

Constructors

constructor

  • new Sprite(image: Texture, sx: number, sy: number, swidth: number, sheight: number): Sprite
  • Parameters

    • image: Texture

      The backing image texture to build the Sprite

    • sx: number

      The x position of the sprite

    • sy: number

      The y position of the sprite

    • swidth: number

      The width of the sprite in pixels

    • sheight: number

      The height of the sprite in pixels

    Returns Sprite

Properties

Private _dirtyEffect

_dirtyEffect: boolean = false

Private _pixelData

_pixelData: ImageData = null

Private _pixelsLoaded

_pixelsLoaded: boolean = false

Private _spriteCanvas

_spriteCanvas: HTMLCanvasElement = null

Private _spriteCtx

_spriteCtx: CanvasRenderingContext2D = null

Private _texture

_texture: Texture

anchor

anchor: Vector = new Vector(0.0, 0.0)

effects

effects: ISpriteEffect[] = []

flipHorizontal

flipHorizontal: boolean = false

Draws the sprite flipped horizontally

flipVertical

flipVertical: boolean = false

Draws the sprite flipped vertically

height

height: number = 0

internalImage

internalImage: HTMLImageElement = new Image()

logger

logger: Logger = Logger.getInstance()

naturalHeight

naturalHeight: number = 0

naturalWidth

naturalWidth: number = 0

rotation

rotation: number = 0

scale

scale: Vector = new ex.Vector(1, 1)

sheight

sheight: number

The height of the sprite in pixels

swidth

swidth: number

The width of the sprite in pixels

sx

sx: number

The x position of the sprite

sy

sy: number

The y position of the sprite

width

width: number = 0

Methods

Private _applyEffects

  • _applyEffects(): void
  • Returns void

Private _loadPixels

  • _loadPixels(): void
  • Returns void

addEffect

clearEffects

  • clearEffects(): void
  • Clears all effects from the drawing and return it to its original state.

    Returns void

clone

  • Produces a copy of the current sprite

    Returns Sprite

colorize

  • colorize(color: Color): void
  • Applies the Effects.Colorize 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 Effects.Darken 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 Effects.Desaturate 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 Effects.Fill 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 Effects.Grayscale to a sprite, removing color information.

    Returns void

invert

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

    Returns void

lighten

  • lighten(factor?: number): void
  • Applies the Effects.Lighten 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 Effects.Opacity to a sprite, setting the alpha of all pixels to a given value

    Parameters

    • value: number

    Returns void

removeEffect

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

    Parameters

    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
  • Resets the internal state of the drawing (if any)

    Returns void

saturate

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

    Parameters

    • Default value factor: number = 0.1

    Returns void