Foundation.Sprite

Sprites are complex drawable objects which can be transformed (translated, scaled, rotated). Sprites can be assigned Rectangle or Polygon colliders. Sprites retain memory of their original geometry.

For a simpler drawbale object, see the Tile type.

Example

// Create a sprite at 100, 200 which is 300 units wide by 400 units high
var sprite = new Foundation.Sprite(
  new Foundation.Rectangle(100, 200, 300, 400),
  someTexture.getRegion('all')
);

// Add a 4-point polygon collider which wraps the sprite 
sprite.collider = Foundation.Polygon.createRect(sprite.bounds);

...

// Add the sprite to a layer (path from default game prefab)
someGame['layers']['default'].pushBack(sprite);

...

// Apply transformations (radians for rotation)
sprite.rotate(Math.PI);
sprite.translate(10, 20);
sprite.scale(-1, 1); // Mirror on x

// Get current amount of rotation
console.log(sprite.currentRotation)

// Reset geometry (i.e. undo transforms)
sprite.resetGeometry();

...

// Move sprite to another layer
someGame['layers']['another'].pushBack(sprite);

// Remove sprite from its current layer
sprite.layer.remove(sprite);

Implementation Details

Reference paths

  • '/foundation/_digest.ts'
  • '/foundation/core/actors/_digest.ts'
  • '/foundation/core/actors/Sprite.ts'

Extends

This type extends:

Equality check is deep. Clone is deep.

Implements

This type implements the following interfaces:

Constructors

(bounds: Rectangle, image: TextureRegion = null, alpha: number = 1, origin: Vector2 = bounds.midpoint(), collider: Shape = null, rotate: number = 0, translateX: number = 0, translateY: number = 0, scaleX: number = 1, scaleY: number = 1)

  • bounds: Initial bounding rectangle for the sprite. Required.
  • image: Texture regions to fill the sprite bounds. Optional. Defaults to null.
  • alpha: In the range 0-1. Optional. Defaults to 1.
  • origin: World point around which rotations and scales are performed. Optional. Defaults to the midpoint of the sprite's bounds.
  • collider: A shape object used to test for collisions. Optional. Defaults to null.
  • rotate: Initial rotation to apply to the sprite (in radians). Optional. Defaults to 0.
  • translateX: Initial translation to apply on X. Optional. Defaults to 0.
  • translateY: Initial translation to apply on Y. Optional. Defaults to 0.
  • scaleX: Initial scaling to apply on X. Optional. Defaults to 1.
  • scaleY: Initial scaling to apply on Y. Optional. Defaults to 1.

Properties

alpha: number

  • Get or set the sprite's alpha value in the range 0-1.

image: TextureRegion

  • Get or set the texture region used to fill the sprite.

currentTranslationX: number

  • Returns the amount of translation between the sprite's original and current origin points on the X axis.

currentTranslationY: number

  • Returns the amount of translation between the sprite's original and current origin points on the Y axis.

currentScalingX: number

  • Returns the amount of scaling between the sprite's original and current vertexes on the X axis.
  • This is calculated from the distance between the sprite's 0th and 1st vertex points and the original bounds width.
  • The returned value is not absolute and will account for negative scaling.

currentScalingY: number

  • Returns the amount of scaling between the sprite's original and current vertexes on the Y axis.
  • This is calculated from the distance between the sprite's 1st and 2nd vertex points and the original bounds height.
  • The returned value is not absolute and will account for negative scaling.

currentRotation: number

  • Returns the current amount of rotation between the sprite's original and transformed state, in the range -PI to PI.

bounds: Rectangle

  • Returns the sprite's axis-aligned bounding rectangle, accounting for all input transformations.
  • Changes made to the returned object will not persist beyond the next geometry update.

verts: Polygon

  • Returns a 4 point polygon containing the sprite's vertexes, accounting for all input transformations.
  • Changes made to the returned object will not persist beyond the next geometry update.

origin: Vector2

  • Returns the sprite's origin point, accounting for all input transformations.
  • Changes made to the returned object will not persist beyond the next geometry update.
  • NB: The origin point is in word units--it is not relative to the sprite.

collider: Shape

  • Returns the sprite's collider shape, accounting for all input transformations.
  • Changes made to the returned object will not persist beyond the next geometry update.
  • NB: collider shapes are in word units--they are not relative to the sprite.

Instance Methods

clearImage(): TextureRegion

  • Removes and returns the sprite's texture region ([sprite].image will be null).

removeCollider(): Shape

  • Removes and returns the sprite's current collider ([sprite].collider will return null).

transform(rotate: number, translateX: number, translateY: number, scaleX: number, scaleY: number): Sprite

  • Apply rotate, translate, and scale transformations to the sprite in one method call.
  • Note, transformations are compounded to those already input to the sprite.
  • Returns the current sprite for chaining.

setTransform(rotRads: number, transX: number, transY: number, scaleX: number, scaleY: number): Sprite

  • Set total values for all transform values in one call.
  • Note, Transformations override those already input.
  • Returns the current sprite for chaining

translate(x: number, y: number = x): Sprite

  • Translate the sprite on X and Y.
  • If Y is undefined, the X value will be used for both axes.
  • Note, transformations are compounded to those already input to the sprite.
  • Returns the current sprite for chaining.

setTranslation(x: number, y: number): Sprite

  • Set the sprite's total translation on x and y.
  • Note, Transformations override those already input.
  • If the sprite's origin point has been moved throughout its lifetime, results here may not be accurate.
  • Returns the current sprite for chaining

scale(x: number, y: number = x): Sprite

  • Scale to the sprite on X and Y.
  • Scaling will be applied in relation to the sprite's origin point.
  • If Y is undefined, the X value will be used for both axes.
  • Note, transformations are compounded to those already input to the sprite.
  • Returns the current sprite for chaining.

scaleAround(originX: number, originY: number, scaleX: number, scaleY: number): Sprite

  • Like scale(), but scaling will be applied in relation to the specified originX and originY point.

setScale(x: number, y: number): Sprite

  • Set the sprite's total scale on x and y.
  • Note, Transformations override those already input.
  • If the sprite's origin point has been moved throughout its lifetime, results here may not be accurate.
  • Returns the current sprite for chaining

rotate(radians: number): Sprite

  • Rotate the sprite by the specified radian value.
  • Rotation will be applied in relation to the sprite's origin point.
  • Note, transformations are compounded to those already input to the sprite.
  • Returns the current sprite for chaining.

rotateAround(originX: number, originY: number, radians: number): Sprite

  • Like rotate(), but rotation will be applied around the specified originX and originY point.

setRotation(rads: number): Sprite

  • Set the sprite's total rotation to the specified radian value.
  • Note, Transformations override those already input.
  • If the sprite's origin point has been moved throughout its lifetime, results here may not be accurate.
  • Returns the current sprite for chaining

updateGeometry(): Sprite

  • This method is called automatically when the transformation state is dirty. You should not have to call it manually.
  • If transformations have been input, this method must be called to update the state of bounds, verts, origin, collider, etc.
  • Returns the current sprite for chaining.

getOriginalBounds(out: Rectangle = new Rectangle()): Rectangle

  • Returns a new rectangle with a copy of the sprite's original bounds (i.e. the bounding rectangle of the sprite without transformations).
  • Optionally, and out rectangle can be passed to avoid instantiation.

getOriginalCollider(out?: Shape): Shape

  • Returns a new shape with a copy of the sprite's original collider (i.e. the collider shape without transformations).
  • Optionally, and out shape can be passed to avoid instantiation.

getOriginalOrigin(out: Vector2 = new Vector2()): Vector2

  • Returns a new vector2 with a copy of the sprite's original origin (i.e. the origin point without transformations).
  • Optionally, and out vector can be passed to avoid instantiation.

resetGeometry(): Sprite

  • Removes all transformations from the sprite
  • Returns the current sprite for chaining

setOriginalOrigin(x: number, y: number = x): Sprite

  • Reset / change the sprite's original origin point to the specified world unit x and y values.
  • The internal vector object is reused.
  • Returns the current sprite for chaining

setOriginalOriginByScale(x: number, y: number = x): Sprite

  • Like, setOriginalOrigin() but sets the point as a factor (0 to 1) of the sprite's original bounds.
  • E.g.: x = 0.5, y = 0.5 would set the origin point as the midpoint of the sprite's original bounds.
  • x and y are not clamped, over-scaling is permitted.
  • Returns the current sprite for chaining

setOriginalBounds(x: number, y: number, width: number, height: number): Sprite

  • Reset / change the sprite's original bounding rectangle to the specified values.
  • The internal rectangle object is reused.
  • Returns the current sprite for chaining

setOriginalCollider(collider: Shape): Sprite

  • Reset / change the sprite's original collider to the specified shape.
  • The internal shape object is not reused.
  • Returns the current sprite for chaining

getMatrixCopy(outMatrix?: Affine2): Affine2

  • Returns a new affine matrix which is a copy of that used internally by the sprite.
  • The sprite type does not offer public access to its matrix object (use transform, rotate, scale, and translate methods instead). The object returned here is a copy.
  • Optionally, and out affine object can be passed to avoid instantiation.

overlaps(other: {bounds: Rectangle}): boolean

  • Returns true if the sprite's bounds overlap the bounds of the passed object.

collidesWith(other: Sprite): boolean

  • Returns true is the current and input sprite's collide (i.e. if the collider shapes of both sprites overlap).
  • The method performs a hierarchy of check for collision (broad and narrow phases): self-checks are culled; both sprites are confirmed to be active; both sprites are confirmed to have collider shapes; collisions are culled on bounding rectangles; finally, collider shaped are checked for overlap.

handleOverlap(other: Tile|Sprite): void

  • Base implementation intended for overriding.
  • When using collision utilities, this method will be called for each identified overlap. A reference to the overlapping object is passed.

handleCollision(other: Sprite): void

  • Base implementation intended for overriding.
  • When using collision utilities, this method will be called for each identified collision. A reference to the colliding object is passed.