Show:

What is a sprite? Sprites are ghosts!

Video game developers use the word sprite to refer to characters, items, enemies, or any other objects that move above a background.

In p5.play a sprite can be anything. Sprites have properties such as: position, width, height, and speed. They can be displayed using a simple shape, image, or animation.

By default sprites have a dynamic physics collider. Colliders are used to resolve overlaps or collisions with other sprites.

Every sprite you create is added to the allSprites group and put on the top layer, in front of all other previously created sprites.

Look at all the examples to learn how to create many different kinds of sprites.

Constructor

Sprite
(
  • aniName|ani|image
  • x
  • y
  • width|diameter
  • height
  • physics
)

Defined in v3/p5.play.js:34

Parameters:

  • [aniName|ani|image] String | SpriteAnimation | p5.Image optional
  • x Number

    Horizontal position of the sprite

  • y Number

    Vertical position of the sprite

  • [width|diameter] Number optional

    Width of the placeholder rectangle and of the collider until an image or new collider are set. OR If height is not set then this parameter becomes the diameter of the placeholder circle.

  • [height] Number optional

    Height of the placeholder rectangle and of the collider until an image or new collider are set

  • [physics] String optional

    collider type is 'dynamic' by default, can be 'static', 'kinematic', or 'none'

Example:

let rectangle = new Sprite(x, y, width, height);

let circle = new Sprite(x, y, diameter);

let line = new Sprite(x, y, [length, angle]);

let chain = new Sprite(x, y, [length0, angle0, length1, angle1]);

Methods

addAnimation
(
  • label
  • animation
)

Defined in v3/p5.play.js:1212

Adds an animation to the sprite. Use this function in the preload p5.js function. You don't need to name the animation if the sprite will only use one animation. See SpriteAnimation for more information.

Uses:

  • sprite.addAnimation(label, animation);
  • sprite.addAnimation(label, firstFrame, lastFrame);
  • sprite.addAnimation(label, frame1, frame2, frame3...);

Parameters:

  • label String

    SpriteAnimation identifier

  • animation SpriteAnimation

    The preloaded animation

addAnis
(
  • atlases
)

Defined in v3/p5.play.js:1603

Add multiple animations

Parameters:

  • atlases Object
addImage
(
  • label
  • img
)

Defined in v3/p5.play.js:1182

Adds an image to the sprite. An image will be considered a one-frame animation. The image should be preloaded in the preload() function using p5 loadImage. Animations require a identifying label (string) to change them. The image is stored in the sprite but not necessarily displayed until Sprite.changeAnimation(label) is called

Usages:

  • sprite.addImage(label, image);
  • sprite.addImage(image);

If only an image is passed no label is specified

Parameters:

  • label String | p5.Image

    Label or image

  • [img] p5.Image optional

    Image

addSpeed
(
  • speed
  • angle
)

Defined in v3/p5.play.js:1325

Add to the speed of the sprite. If direction is not supplied, the current direction is maintained. If direction is not supplied and there is no current velocity, the current rotation angle used for the direction.

Parameters:

  • speed Number

    Scalar speed

  • [angle] Number optional

    Direction in degrees

addToGroup
(
  • group
)

Defined in v3/p5.play.js:1632

Adds the sprite to an existing group

Parameters:

ani
(
  • anis
)

Defined in v3/p5.play.js:1520

Changes the sprite's animation. Use addAni to define the animation(s) first.

Parameters:

  • anis ...String

    the names of one or many animations to be played in sequence

Returns:

A promise that fulfills when the animation or sequence of animations completes

bounce
(
  • target
  • callback
)
deprecated

Defined in v3/p5.play.js:1758

Deprecated, use sprite.collide instead.

Parameters:

changeAnimation
(
  • label
)

Defined in v3/p5.play.js:1262

Changes the displayed animation. The animation must be added first using the sprite.addAnimation method. The animation could also be added using the group.addAnimation method to a group the sprite has been added to.

See SpriteAnimation for more control over the sequence.

Parameters:

  • label String

    SpriteAnimation identifier

changeImage
(
  • label
)

Defined in v3/p5.play.js:1251

Changes the displayed image/animation. Equivalent to changeAnimation

Parameters:

  • label String

    Image/SpriteAnimation identifier

collide
(
  • target
  • callback
)

Defined in v3/p5.play.js:1733

Checks if the the sprite is colliding with another sprite or a group. The check is performed using the sprite's physics body (colliders).

A callback function can be specified to perform additional operations when contact occurs. If the target is a group the function will be called for each single sprite colliding. The parameter of the function are respectively the current sprite and the colliding sprite.

Parameters:

  • target Sprite | Group

    Sprite or group to check against the current one

  • [callback] Function optional

    The function to be called if overlap is positive

Example:

sprite.collide(otherSprite, explosion);

function explosion(spriteA, spriteB) {
  spriteA.remove();
  spriteB.score++;
}
displace
(
  • target
  • callback
)
deprecated

Defined in v3/p5.play.js:1770

Deprecated, use sprite.collide instead.

Parameters:

draw ()

Defined in v3/p5.play.js:1131

Manages the visuals of the sprite. It can be overridden with a custom drawing function. The center of the sprite is (0, 0).

Example:

sprite.draw = function() { // an oval ellipse(0,0,20,10); }

move
(
  • destX
  • destY
  • speed
  • cb
)
Promise

Defined in v3/p5.play.js:1361

Move the sprite to a destination position

Parameters:

  • destX Number

    destination x

  • destY Number

    destination y

  • speed Number

    scalar

  • cb Function

    callback, called when movement is complete

Returns:

Promise:

resolves when the movement is complete

moveTo ()

Defined in v3/p5.play.js:1456

Same as sprite.move

moveTowards
(
  • destX
  • destY
  • tracking
)

Defined in v3/p5.play.js:1346

Move a sprite towards a position

Parameters:

  • destX Number

    destination x

  • destY Number

    destination y

  • tracking Number

    1 represents 1:1 tracking, the mouse moves to the destination immediately, 0 represents no tracking

overlap
(
  • target
  • callback
)

Defined in v3/p5.play.js:1782

Checks if this sprite is overlapping with another sprite or a group. The check is performed using the sprite's physics body (colliders).

A callback function can be specified to perform additional operations when contact occurs. If the target is a group the function will be called for each single sprite overlapping. The parameters of the callback function are the current sprite and the overlapping sprite.

Since v3, this function only needs to be called once, it doesn't need to be used in the p5.js draw loop.

Parameters:

  • target Sprite | Group

    Sprite or group to check against the current one

  • [callback] Function optional

    The function to be called if an overlap occurs

Example:

sprite.overlap(otherSprite, pickup);

function pickup(spriteA, spriteB) { spriteA.remove(); spriteB.itemCount++; }

remove ()

Defined in v3/p5.play.js:1616

Removes the Sprite from the sketch. The removed Sprite will not be drawn or updated anymore.

removeCollider ()

Defined in v3/p5.play.js:510

Removes the physics body collider from the sprite.

Avoid using this method. It is more efficient to set the physics body type of the sprite to 'none'.

rotate
(
  • angle
  • speed
)

Defined in v3/p5.play.js:1495

Rotates the sprite to an angle with a specified speed.

Parameters:

  • angle Number
  • speed Number
rotateTowards
(
  • angle
  • tracking
)

Defined in v3/p5.play.js:1482

Rotates the sprite towards a position or angle.

Parameters:

  • angle
  • tracking
setSpeed
(
  • speed
  • direction
)
deprecated

Defined in v3/p5.play.js:1306

Deprecated: set direction and speed separately

Set the speed of the sprite. The action overwrites the current velocity. If direction is not supplied, the current direction is maintained. If direction is not supplied and there is no current velocity, the current rotation angle used for the direction.

Parameters:

  • speed Number

    Scalar speed

  • [direction] Number optional

    angle

toString ()

Defined in v3/p5.play.js:1645

Returns the sprite's unique identifier

Returns:

the sprite's id

Properties

animation

SpriteAnimation

Defined in v3/p5.play.js:103

Reference to the sprite's current animation.

animations

Object

Defined in v3/p5.play.js:95

Keys are the animation label, values are SpriteAnimation objects.

autoResetAnimations

SpriteAnimation

Defined in v3/p5.play.js:111

If false, animations that are stopped before they are completed, typically by a call to sprite.changeAnimation, will start at the frame they were stopped at. If true, animations will always start playing from frame 0 unless specified by the user in a separate anim.changeFrame call.

Default: false

bounciness

Number

Defined in v3/p5.play.js:539

The bounciness of the sprite's physics body.

centerOfMass

Number

Defined in v3/p5.play.js:555

The center of mass of the sprite's physics body.

d

Number

Defined in v3/p5.play.js:1019

The diameter of a circular sprite.

density

Number

Defined in v3/p5.play.js:574

The density of the sprite's physics body.

depth

Unknown deprecated

Defined in v3/p5.play.js:590

Use .layer instead.

diameter

Number

Defined in v3/p5.play.js:1033

The diameter of a circular sprite.

drag

Number

Defined in v3/p5.play.js:603

The angle of the sprite's movement or it's rotation angle if the sprite is not moving.

drag

Number

Defined in v3/p5.play.js:621

The amount of resistance a sprite has to being moved.

dynamic

Boolean

Defined in v3/p5.play.js:634

True if the sprite's physics body is dynamic.

friction

Number

Defined in v3/p5.play.js:671

The amount the sprite's physics body resists moving when rubbing against another physics body.

groups

Array

Defined in v3/p5.play.js:86

Groups the sprite belongs to, including allSprites

h

Number

Defined in v3/p5.play.js:996

The height of the sprite.

height

Number

Defined in v3/p5.play.js:1008

The height of the sprite.

immovable

Unknown deprecated

Defined in v3/p5.play.js:688

Use .static instead.

isSuperFast

Boolean

Defined in v3/p5.play.js:707

Set this to true if the sprite goes really fast to prevent inaccurate physics simulation.

kinematic

Boolean

Defined in v3/p5.play.js:728

True if the sprite's physics body is kinematic.

life

Number

Defined in v3/p5.play.js:181

Cycles before self removal. Set it to initiate a countdown, every draw cycle the property is reduced by 1 unit. If less than or equal to 0, this sprite will be removed.

Default: 10000000

mass

Number

Defined in v3/p5.play.js:740

The mass of the sprite's physics body.

mirrorX

Boolean

Defined in v3/p5.play.js:768

Setting mirrorX to true will mirror the sprite horizontally.

mirrorY

Boolean

Defined in v3/p5.play.js:780

Setting mirrorY to true will mirror the sprite vertically.

pos

Object

Defined in v3/p5.play.js:963

Set the position vector {x, y}

removed

Boolean

Defined in v3/p5.play.js:124

True if the sprite was removed from the world

Default: false

rotation

Number

Defined in v3/p5.play.js:797

The angle of the sprite's rotation, not the direction it is moving.

rotationDrag

Number

Defined in v3/p5.play.js:821

The amount of the sprite resists rotating.

rotationLocked

Boolean

Defined in v3/p5.play.js:647

If true the sprite can not rotate.

rotationSpeed

Number

Defined in v3/p5.play.js:833

The speed of the sprite's rotation.

shape

String

Defined in v3/p5.play.js:133

The kind of shape: 'box', 'circle', 'polygon', or 'chain'

Default: box

shapeColor

Color

Defined in v3/p5.play.js:201

If no image or animations are set this is color of the placeholder rectangle

Default: a randomly generated color

speed

Number

Defined in v3/p5.play.js:869

The sprite's speed.

speed

Number

Defined in v3/p5.play.js:885

The sprite's speed.

Sub-properties:

  • speed Number

    that the sprite will move at in the direction of its current rotation

static

Boolean

Defined in v3/p5.play.js:901

Is the sprite's physics collider static?

touching

Object

Defined in v3/p5.play.js:306

Object containing information about the most recent collision/overlapping To be typically used in combination with Sprite.overlap or Sprite.collide functions. The properties are touching.left, touching.right, touching.top, touching.bottom and are either true or false depending on the side of the collider.

vel

Unknown

Defined in v3/p5.play.js:255

A vector representing how fast the sprite is moving horizontally and vertically.

velocity

Unknown

Defined in v3/p5.play.js:286

Verbose/legacy version of sprite.vel

visible

Boolean

Defined in v3/p5.play.js:192

The sprite's visibility.

Default: true

w

Number

Defined in v3/p5.play.js:973

The width of the sprite.

width

Number

Defined in v3/p5.play.js:985

The width of the sprite.

x

Number

Defined in v3/p5.play.js:927

The horizontal position of the sprite.

y

Number

Defined in v3/p5.play.js:945

The vertical position of the sprite.