Class Sprite

An object to display a fixed or animated sprite on screen.

Hierarchy (view full)

Constructors

constructor

Properties

GUID alpha alwaysUpdate ancestor anchorPoint anim animationpause animationspeed atlasIndices autoTransform blendMode body current currentTransform dt edges floating height image indices isDirty isKinematic isPersistent isVideo mask name offset onVisibilityChange points pos resetAnim shader source textureAtlas type updateWhenPaused width

Accessors

bottom centerX centerY depth inViewport isFlippedX isFlippedY isFloating left parentApp right tint top

Methods

addAnimation angleTo centerOn clone contains containsRectangle copy distanceTo draw equals flicker flipX flipY getAbsolutePosition getBounds getCurrentAnimationFrame getIndices getOpacity isConvex isCurrentAnimation isFinite isFlickering lookAt onCollision onDestroyEvent overlaps pause play postDraw preDraw recalc resize reverseAnimation rotate scale scaleV setAnimationFrame setCurrentAnimation setOpacity setRegion setShape setSize setVertices shift to2d toIso toPolygon transform translate union update updateBounds

Constructors

constructor

  • new Sprite(x, y, settings): Sprite

  • Parameters

    • x: number

      the x coordinates of the sprite object

    • y: number

      the y coordinates of the sprite object

    • settings: {
          anchorPoint: undefined | Vector2d;
          flipX: undefined | number;
          flipY: undefined | number;
          frameheight: undefined | number;
          framewidth: undefined | number;
          image:
              | string
              | HTMLCanvasElement
              | HTMLImageElement
              | HTMLVideoElement
              | TextureAtlas;
          name: undefined | string;
          region: undefined | string;
          tint: undefined | string | Color;
      }

      Configuration parameters for the Sprite object

      • anchorPoint: undefined | Vector2d

        Anchor point to draw the frame at (defaults to the center of the frame).

      • flipX: undefined | number

        flip the sprite on the horizontal axis

      • flipY: undefined | number

        flip the sprite on the vertical axis

      • frameheight: undefined | number

        Height of a single frame within the spritesheet

      • framewidth: undefined | number

        Width of a single frame within the spritesheet

      • image:
            | string
            | HTMLCanvasElement
            | HTMLImageElement
            | HTMLVideoElement
            | TextureAtlas

        reference to spritesheet image, a texture atlas, a video element, or to a texture atlas

      • name: undefined | string

        name of this object

      • region: undefined | string

        region name of a specific region to use when using a texture atlas, see TextureAtlas

      • tint: undefined | string | Color

        a tint to be applied to this sprite

    Returns Sprite

    Example

    // create a single sprite from a standalone image, with anchor in the center
    let sprite = new me.Sprite(0, 0, {
        image : "PlayerTexture",
        framewidth : 64,
        frameheight : 64,
        anchorPoint : new me.Vector2d(0.5, 0.5)
    });

    // create a single sprite from a packed texture
    mytexture = new me.TextureAtlas(
        me.loader.getJSON("texture"),
        me.loader.getImage("texture")
    );
    let sprite = new me.Sprite(0, 0, {
        image : mytexture,
        region : "npc2.png",
    });

    // create a video sprite
    let videoSprite = new me.Sprite(0, 0, {
        image : me.loader.getVideo("bigbunny"),
        anchorPoint : new me.Vector2d(0.5, 0.5)
    });
    // scale the video sprite
    videoSprite.currentTransform.scale(2);
    // start playing the video (if video is preloaded with `autoplay` set to false)
    videoSprite.play();

Properties

GUID

GUID: string

(G)ame (U)nique (Id)entifier"
a GUID will be allocated for any renderable object added
to an object container (including the me.game.world container)

alpha

alpha: number

Define the renderable opacity
Set to zero if you do not wish an object to be drawn

See

  • Renderable#setOpacity
  • Renderable#getOpacity

Default

1.0

alwaysUpdate

alwaysUpdate: boolean

Whether the renderable object will always update, even when outside of the viewport

Default

false

ancestor

ancestor: Container | Entity

a reference to the parent object that contains this renderable

Default

undefined

anchorPoint

anchorPoint: ObservablePoint

The anchor point is used for attachment behavior, and/or when applying transformations.
The coordinate system places the origin at the top left corner of the frame (0, 0) and (1, 1) means the bottom-right corner

a Renderable's anchor point defaults to (0.5,0.5), which corresponds to the center position.

Note: Object created through Tiled will have their anchorPoint set to (0, 0) to match Tiled Level editor implementation. To specify a value through Tiled, use a json expression like json:{"x":0.5,"y":0.5}.

Default

<0.5,0.5>

anim

anim: {}

animationpause

animationpause: boolean

Default

false

animationspeed

animationspeed: number

animation cycling speed (delay between frame in ms)

Default

100

atlasIndices

atlasIndices: any

autoTransform

autoTransform: boolean

When enabled, an object container will automatically apply any defined transformation before calling the child draw method.

Default

true

Example

// enable "automatic" transformation when the object is activated
onActivateEvent: function () {
    // reset the transformation matrix
    this.currentTransform.identity();
    // ensure the anchor point is the renderable center
    this.anchorPoint.set(0.5, 0.5);
    // enable auto transform
    this.autoTransform = true;
    ....
}

blendMode

blendMode: string

the blend mode to be applied to this renderable (see renderer setBlendMode for available blend mode)

Default

"normal"

See

  • CanvasRenderer#setBlendMode
  • WebGLRenderer#setBlendMode

body

body: Body

the renderable physic body

Example

// define a new Player Class
 class PlayerEntity extends me.Sprite {
     // constructor
     constructor(x, y, settings) {
         // call the parent constructor
         super(x, y , settings);

         // define a basic walking animation
         this.addAnimation("walk",  [...]);
         // define a standing animation (using the first frame)
         this.addAnimation("stand",  [...]);
         // set the standing animation as default
         this.setCurrentAnimation("stand");

         // add a physic body
         this.body = new me.Body(this);
         // add a default collision shape
         this.body.addShape(new me.Rect(0, 0, this.width, this.height));
         // configure max speed, friction, and initial force to be applied
         this.body.setMaxVelocity(3, 15);
         this.body.setFriction(0.4, 0);
         this.body.force.set(3, 0);
         this.isKinematic = false;

         // set the display to follow our position on both axis
         me.game.viewport.follow(this.pos, me.game.viewport.AXIS.BOTH);
     }

     ...

}

current

current: {
    angle: number;
    height: number;
    idx: number;
    length: number;
    name: undefined;
    offset: Vector2d;
    width: number;
}

currentTransform

currentTransform: Matrix2d

the renderable default transformation matrix

dt

dt: number

edges

edges: Vector2d[]

The edges here are the direction of the nth edge of the polygon, relative to the nth point. If you want to draw a given edge from the edge value, you must first translate to the position of the starting point.

floating

floating: boolean

If true, this renderable will be rendered using screen coordinates, as opposed to world coordinates. Use this, for example, to define UI elements.

Default

false

height

height: any

image

image: HTMLCanvasElement | HTMLImageElement | HTMLVideoElement

indices

indices: number[]

a list of indices for all vertices composing this polygon

isDirty

isDirty: boolean

when true the renderable will be redrawn during the next update cycle

Default

true

isKinematic

isKinematic: boolean

If true then physic collision and input events will not impact this renderable

Default

true

isPersistent

isPersistent: boolean

make the renderable object persistent over level changes

Default

false

isVideo

isVideo: boolean

true if this is a video sprite (e.g. a HTMLVideoElement was passed as as source)

Default

false

mask

mask:
    | Polygon
    | Rect
    | Ellipse
    | Line
    | RoundRect

A mask limits rendering elements to the shape and position of the given mask object. So, if the renderable is larger than the mask, only the intersecting part of the renderable will be visible.

Default

undefined

Example

// apply a mask in the shape of a Star
myNPCSprite.mask = new me.Polygon(myNPCSprite.width / 2, 0, [
   // draw a star
   {x: 0, y: 0},
   {x: 14, y: 30},
   {x: 47, y: 35},
   {x: 23, y: 57},
   {x: 44, y: 90},
   {x: 0, y: 62},
   {x: -44, y: 90},
   {x: -23, y: 57},
   {x: -47, y: 35},
   {x: -14, y: 30}
]);

name

name: string

The name of the renderable

Default

""

offset

offset: Vector2d

global offset for the position to draw from on the source image.

Default

<0.0,0.0>

onVisibilityChange

onVisibilityChange: Function

an event handler that is called when the renderable leave or enter a camera viewport

Default

undefined

Example

this.onVisibilityChange = function(inViewport) {
    if (inViewport === true) {
        console.log("object has entered the in a camera viewport!");
    }
};

points

points: Vector2d[]

Array of points defining the Polygon
Note: If you manually change points, you must call recalcafterwards so that the changes get applied correctly.

pos

pos: Vector2d

origin point of the Polygon

resetAnim

resetAnim: undefined | Function | ((...args: []) => Sprite)

shader

shader: GLShader

(Experimental) an optional shader, to be used instead of the default built-in one, when drawing this renderable (WebGL only)

Default

undefined

source

source: TextureAtlas

The source texture object this sprite object is using

textureAtlas

textureAtlas: any

type

type: string = "Rectangle"

The shape type (used internally).

updateWhenPaused

updateWhenPaused: boolean

Whether to update this object when the game is paused.

Default

false

width

width: any

Accessors

bottom

centerX

centerY

depth

inViewport

isFlippedX

isFlippedY

isFloating

  • get isFloating(): boolean

  • Whether the renderable object is floating (i.e. used screen coordinates), or contained in a floating parent container

    Returns boolean

    See

    Renderable#floating

left

parentApp

right

tint

top

Methods

addAnimation

  • addAnimation(name, index, animationspeed?): number

  • add an animation
    For fixed-sized cell sprite sheet, the index list must follow the logic as per the following example :

    Parameters

    • name: string

      animation id

    • index: string[] | number[] | object[]

      list of sprite index or name defining the animation. Can also use objects to specify delay for each frame, see below

    • Optionalanimationspeed: number

      cycling speed for animation in ms

    Returns number

    frame amount of frame added to the animation (delay between each frame).

    See

    Sprite#animationspeed

    Example

    // walking animation
    this.addAnimation("walk", [ 0, 1, 2, 3, 4, 5 ]);
    // standing animation
    this.addAnimation("stand", [ 11, 12 ]);
    // eating animation
    this.addAnimation("eat", [ 6, 6 ]);
    // rolling animation
    this.addAnimation("roll", [ 7, 8, 9, 10 ]);
    // slower animation
    this.addAnimation("roll", [ 7, 8, 9, 10 ], 200);
    // or get more specific with delay for each frame. Good solution instead of repeating:
    this.addAnimation("turn", [{ name: 0, delay: 200 }, { name: 1, delay: 100 }])
    // can do this with atlas values as well:
    this.addAnimation("turn", [{ name: "turnone", delay: 200 }, { name: "turntwo", delay: 100 }])
    // define an dying animation that stop on the last frame
    this.addAnimation("die", [{ name: 3, delay: 200 }, { name: 4, delay: 100 }, { name: 5, delay: Infinity }])
    // set the standing animation as default
    this.setCurrentAnimation("stand");

angleTo

centerOn

clone

contains

  • contains(x, y): boolean

  • Returns true if the polygon contains the given point.
    (Note: it is highly recommended to first do a hit test on the corresponding
    bounding rect, as the function can be highly consuming with complex shapes)

    Parameters

    • x: number

      x coordinate or a vector point to check

    • y: number

      y coordinate

    Returns boolean

    True if the polygon contain the point, otherwise false

    Example

    if (polygon.contains(10, 10)) {
      // do something
    }
    // or
    if (polygon.contains(myVector2d)) {
      // do something
    }
  • contains(vector): boolean

  • Returns true if the polygon contains the given point.
    (Note: it is highly recommended to first do a hit test on the corresponding
    bounding rect, as the function can be highly consuming with complex shapes)

    Parameters

    Returns boolean

    True if the polygon contain the point, otherwise false

    Example

    if (polygon.contains(10, 10)) {
      // do something
    }
    // or
    if (polygon.contains(myVector2d)) {
      // do something
    }

containsRectangle

copy

distanceTo

draw

equals

flicker

  • flicker(duration, callback?): Sprite

  • make the object flicker

    Parameters

    • duration: number

      expressed in milliseconds

    • Optionalcallback: Function = undefined

      Function to call when flickering ends

    Returns Sprite

    Reference to this object for method chaining

    Example

    // make the object flicker for 1 second
    // and then remove it
    this.flicker(1000, function () {
        world.removeChild(this);
    });

flipX

flipY

getAbsolutePosition

getBounds

getCurrentAnimationFrame

getIndices

getOpacity

isConvex

  • isConvex(): null | boolean

  • Returns true if the vertices composing this polygon form a convex shape (vertices must be in clockwise order).

    Returns null | boolean

    true if the vertices are convex, false if not, null if not computable

isCurrentAnimation

  • isCurrentAnimation(name): boolean

  • return true if the specified animation is the current one.

    Parameters

    • name: string

      animation id

    Returns boolean

    Example

    if (!this.isCurrentAnimation("walk")) {
        // do something funny...
    }

isFinite

isFlickering

lookAt

onCollision

  • onCollision(): boolean

  • onCollision callback, triggered in case of collision, when this renderable body is colliding with another one

    Returns boolean

    true if the object should respond to the collision (its position and velocity will be corrected)

    Example

    // colision handler
    onCollision(response) {
        if (response.b.body.collisionType === me.collision.types.ENEMY_OBJECT) {
            // makes the other object solid, by substracting the overlap vector to the current position
            this.pos.sub(response.overlapV);
            this.hurt();
            // not solid
            return false;
        }
        // Make the object solid
        return true;
    },

onDestroyEvent

overlaps

pause

play

postDraw

preDraw

recalc

resize

reverseAnimation

rotate

scale

  • scale(x, y?): Renderable

  • scale the renderable around his anchor point. Scaling actually applies changes to the currentTransform member wich is used by the renderer to scale the object when rendering. It does not scale the object itself. For example if the renderable is an image, the image.width and image.height properties are unaltered but the currentTransform member will be changed.

    Parameters

    • x: number

      a number representing the abscissa of the scaling vector.

    • Optionaly: number = x

      a number representing the ordinate of the scaling vector.

    Returns Renderable

    Reference to this object for method chaining

scaleV

setAnimationFrame

  • setAnimationFrame(index?): Sprite

  • force the current animation frame index.

    Parameters

    • Optionalindex: number = 0

      animation frame index

    Returns Sprite

    Reference to this object for method chaining

    Example

    // reset the current animation to the first frame
    this.setAnimationFrame();

setCurrentAnimation

  • setCurrentAnimation(name, resetAnim?, preserve_dt?): Sprite

  • set the current animation this will always change the animation & set the frame to zero

    Parameters

    • name: string

      animation id

    • OptionalresetAnim: string | Function

      animation id to switch to when complete, or callback

    • Optionalpreserve_dt: boolean = false

      if false will reset the elapsed time counter since last frame

    Returns Sprite

    Reference to this object for method chaining

    Example

    // set "walk" animation
    this.setCurrentAnimation("walk");

    // set "walk" animation if it is not the current animation
    if (this.isCurrentAnimation("walk")) {
        this.setCurrentAnimation("walk");
    }

    // set "eat" animation, and switch to "walk" when complete
    this.setCurrentAnimation("eat", "walk");

    // set "die" animation, and remove the object when finished
    this.setCurrentAnimation("die", () => {
       world.removeChild(this);
       return false; // do not reset to first frame
    });

    // set "attack" animation, and pause for a short duration
    this.setCurrentAnimation("die", () => {
       this.animationpause = true;

       // back to "standing" animation after 1 second
       setTimeout(function () {
           this.setCurrentAnimation("standing");
       }, 1000);

       return false; // do not reset to first frame
    });

setOpacity

setRegion

  • setRegion(region): Sprite

  • change the current texture atlas region for this sprite

    Parameters

    • region: object

      typically returned through me.Texture.getRegion()

    Returns Sprite

    Reference to this object for method chaining

    See

    Texture.getRegion

    Example

    // change the sprite to "shadedDark13.png";
    mySprite.setRegion(mytexture.getRegion("shadedDark13.png"));

setShape

setSize

setVertices

shift

to2d

toIso

toPolygon

transform

translate

union

Protectedupdate

updateBounds

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods