Show:
Module: p5.play
Parent Module: p5.play

A Sprite is the main building block of p5.play: an element able to store images or animations with a set of properties such as position and visibility. A Sprite can have a collider that defines the active area to detect collisions or overlappings with other sprites and mouse interactions.

Constructor

Sprite
(
  • x
  • y
  • width
  • height
)

Defined in lib/p5.play.js:719

Parameters:

  • x Number

    Initial x coordinate

  • y Number

    Initial y coordinate

  • width Number

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

  • height Number

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

Methods

addAnimation
(
  • label
  • animation
)

Defined in lib/p5.play.js:1699

Adds an animation to the sprite. The animation should be preloaded in the preload() function using loadAnimation. Animations require a identifying label (string) to change them. Animations are stored in the sprite but not necessarily displayed until Sprite.changeAnimation(label) is called.

Usage:

  • sprite.addAnimation(label, animation);

Alternative usages. See Animation for more information on file sequences:

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

Parameters:

  • label String

    Animation identifier

  • animation Animation

    The preloaded animation

addImage
(
  • label
  • img
)

Defined in lib/p5.play.js:1671

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 lib/p5.play.js:1641

Pushes the sprite in a direction defined by an angle. The force is added to the current velocity.

Parameters:

  • speed Number

    Scalar speed to add

  • angle Number

    Direction in degrees

addToGroup
(
  • group
)

Defined in lib/p5.play.js:1594

Adds the sprite to an existing group

Parameters:

  • group Object
attractionPoint
(
  • magnitude
  • pointX
  • pointY
)

Defined in lib/p5.play.js:1655

Pushes the sprite toward a point. The force is added to the current velocity.

Parameters:

  • magnitude Number

    Scalar speed to add

  • pointX Number

    Direction x coordinate

  • pointY Number

    Direction y coordinate

bounce
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1977

Checks if the the sprite is overlapping another sprite or a group. If the overlap is positive the sprites will bounce affecting each other's trajectories depending on their .velocity, .mass and .restitution

The check is performed using the colliders. If colliders are not set they will be created automatically from the image/animation bounding box.

A callback function can be specified to perform additional operations when the collision occours. 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 Object

    Sprite or group to check against the current one

  • [callback] Function optional

    The function to be called if overlap is positive

Returns:

Boolean:

True if overlapping

Example:

sprite.bounce(otherSprite, explosion);

function explosion(spriteA, spriteB) { spriteA.remove(); spriteB.score++; }

changeAnimation
(
  • label
)

Defined in lib/p5.play.js:1792

Changes the displayed animation. See Animation for more control over the sequence.

Parameters:

  • label String

    Animation identifier

changeImage
(
  • label
)

Defined in lib/p5.play.js:1771

Changes the displayed image/animation. Equivalent to changeAnimation

Parameters:

  • label String

    Image/Animation identifier

collide
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1910

Checks if the the sprite is overlapping another sprite or a group. If the overlap is positive the current sprite will be displace by the colliding one in the closest non-overlapping position.

The check is performed using the colliders. If colliders are not set they will be created automatically from the image/animation bounding box.

A callback function can be specified to perform additional operations when the collision occours. 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 Object

    Sprite or group to check against the current one

  • [callback] Function optional

    The function to be called if overlap is positive

Returns:

Boolean:

True if overlapping

Example:

sprite.collide(otherSprite, explosion);

function explosion(spriteA, spriteB) { spriteA.remove(); spriteB.score++; }

displace
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1944

Checks if the the sprite is overlapping another sprite or a group. If the overlap is positive the current sprite will displace the colliding one to the closest non-overlapping position.

The check is performed using the colliders. If colliders are not set they will be created automatically from the image/animation bounding box.

A callback function can be specified to perform additional operations when the collision occours. 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 Object

    Sprite or group to check against the current one

  • [callback] Function optional

    The function to be called if overlap is positive

Returns:

Boolean:

True if overlapping

Example:

sprite.displace(otherSprite, explosion);

function explosion(spriteA, spriteB) { spriteA.remove(); spriteB.score++; }

display ()
private final

Defined in lib/p5.play.js:1458

Manages the positioning, scale and rotation of the sprite Called automatically, it should not be overridden

draw ()

Defined in lib/p5.play.js:1514

Manages the visuals of the sprite. It can be overridden with a custom drawing function. The 0,0 point will be the center of the sprite. Example: sprite.draw = function() { ellipse(0,0,10,10) } Will display the sprite as circle.

getAnimationLabel () String

Defined in lib/p5.play.js:1782

Returns the label of the current animation

Returns:

String:

label Image/Animation identifier

getBoundingBox ()

Defined in lib/p5.play.js:1403

Returns a the bounding box of the current image

getDirection () Number

Defined in lib/p5.play.js:1579

Calculates the movement's direction in degrees.

Returns:

Number:

Angle in degrees

limitSpeed
(
  • max
)

Defined in lib/p5.play.js:1607

Limits the scalar speed.

Parameters:

  • max Number

    Max speed: positive number

mirrorX
(
  • dir
)
Number

Defined in lib/p5.play.js:1423

Sets the sprite's horizontal mirroring. If 1 the images displayed normally If -1 the images are flipped horizontally If no argument returns the current x mirroring

Parameters:

  • dir Number

    Either 1 or -1

Returns:

Number:

Current mirroring if no parameter is specified

mirrorY
(
  • dir
)
Number

Defined in lib/p5.play.js:1440

Sets the sprite's vertical mirroring. If 1 the images displayed normally If -1 the images are flipped vertically If no argument returns the current y mirroring

Parameters:

  • dir Number

    Either 1 or -1

Returns:

Number:

Current mirroring if no parameter is specified

mouseUpdate ()

Defined in lib/p5.play.js:1285

Updates the sprite mouse states and triggers the mouse events: onMouseOver, onMouseOut, onMousePressed, onMouseReleased

overlap
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1879

Checks if the the sprite is overlapping another sprite or a group. The check is performed using the colliders. If colliders are not set they will be created automatically from the image/animation bounding box.

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

Parameters:

  • target Object

    Sprite or group to check against the current one

  • [callback] Function optional

    The function to be called if overlap is positive

Returns:

Boolean:

True if overlapping

Example:

sprite.overlap(otherSprite, explosion);

function explosion(spriteA, spriteB) { spriteA.remove(); spriteB.score++; }

overlapPixel
(
  • pointX
  • pointY
)
Boolean

Defined in lib/p5.play.js:1809

Checks if the given point corresponds to a transparent pixel in the sprite's current image. It can be used to check a point collision against only the visible part of the sprite.

Parameters:

  • pointX Number

    x coordinate of the point to check

  • pointY Number

    y coordinate of the point to check

Returns:

Boolean:

result True if non-transparent

overlapPoint
(
  • pointX
  • pointY
)
Boolean

Defined in lib/p5.play.js:1846

Checks if the given point is inside the sprite's collider.

Parameters:

  • pointX Number

    x coordinate of the point to check

  • pointY Number

    y coordinate of the point to check

Returns:

Boolean:

result True if inside

remove ()

Defined in lib/p5.play.js:1539

Removes the Sprite from the sketch. The removed Sprite won't be drawn or updated anymore.

setCollider
(
  • type
  • offsetX
  • offsetY
  • width
  • height
)

Defined in lib/p5.play.js:1358

Sets a collider for the sprite.

In p5.play a Collider is an invisible circle or rectangle that can have any size or position relative to the sprite and which will be used to detect collisions and overlapping with other sprites, or the mouse cursor.

If the sprite is checked for collision, bounce, overlapping or mouse events a collider is automatically created from the width and height parameter passed at the creation of the sprite or the from the image dimension in case of animate sprites.

Often the image bounding box is not appropriate as active area for a collision detection so you can set a circular or rectangular sprite with different dimensions and offset from the sprite's center.

setCollider

Parameters:

  • type String

    Either "rectangle" or "circle"

  • offsetX Number

    Collider x position from the center of the sprite

  • offsetY Number

    Collider y position from the center of the sprite

  • width Number

    Collider width or radius

  • height Number

    Collider height

setDefaultCollider ()

Defined in lib/p5.play.js:1251

Creates a default collider matching the size of the placeholder rectangle or the bounding box of the image.

setSpeed
(
  • speed
  • angle
)

Defined in lib/p5.play.js:1627

Set the speed and direction of the sprite. The action overwrites the current velocity.

Parameters:

  • speed Number

    Scalar speed to add

  • angle Number

    Direction in degrees

setVelocity () Number

Defined in lib/p5.play.js:1569

Calculates the scalar speed.

Returns:

Number:

Scalar speed

setVelocity
(
  • x
  • x
)

Defined in lib/p5.play.js:1557

Sets the velocity vector.

Parameters:

  • x Number

    X component

  • x Number

    Y component

update ()

Defined in lib/p5.play.js:1106

Updates the sprite. Called automatically at the beginning of the draw cycle.

()
private

Defined in lib/p5.play.js:2010

Internal collision detection function. Do not use directly.

Properties

animation

Animation

Defined in lib/p5.play.js:1098

Reference to the current animation.

camera

Camera

Defined in lib/p5.play.js:2269

The sketch camera automatically created at the beginning of a sketch. A camera facilitates scrolling and zooming for scenes extending beyond the canvas. A camera has a position, a zoom factor, and the mouse coordinates relative to the view.

In p5.js terms the camera wraps the whole drawing cycle in a transformation matrix but it can be disable anytime during the draw cycle for example to draw interface elements in an absolute position.

collider

Object

Defined in lib/p5.play.js:823

The sprite's current collider. It can either be an Axis Aligned Bounding Box (a non-rotated rectangle) or a circular collider. If the sprite is checked for collision, bounce, overlapping or mouse events the collider is automatically created from the width and height parameter passed at the creation of the sprite or the from the image dimension in case of animate sprites

You can set a custom collider with Sprite.setCollider

debug

Boolean

Defined in lib/p5.play.js:1067

If set to true, draws an outline of the collider, the depth, and center.

Default: false

depth

Number

Defined in lib/p5.play.js:930

Determines the rendering order within a group: a sprite with lower depth will appear below the ones with higher depth.

Note: drawing a group before another with drawSprites will make its members appear below the second one, like in normal p5 canvas drawing.

Default: 0

friction

Number

Defined in lib/p5.play.js:812

Friction factor, reduces the sprite's velocity. The friction should be close to 1 (eg. 0.99) 1: no friction

Default: 1

groups

Array

Defined in lib/p5.play.js:1085

Groups the sprite belongs to, including allSprites

height

Number

Defined in lib/p5.play.js:1011

Height of the sprite's current image. If no images or animations are set it's the height of the placeholder rectangle.

Default: 100

immovable

Boolean

Defined in lib/p5.play.js:872

If set to true the sprite won't bounce or be displaced by collisions Simulates an infinite mass or an anchored object.

Default: false

mass

Number

Defined in lib/p5.play.js:861

The mass determines the velocity transfer when sprites bounce against each other. See Sprite.bounce The higher the mass the least the sprite will be affected by collisions.

Default: 1

maxSpeed

Number

Defined in lib/p5.play.js:802

Set a limit to the sprite's scalar speed regardless of the direction. The value can only be positive. If set to -1, there's no limit.

Default: -1

mouseActive

Boolean

Defined in lib/p5.play.js:967

If set to true sprite will track its mouse state. the properties mouseIsPressed and mouseIsOver will be updated. Note: automatically set to true if the functions onMouseReleased or onMousePressed are set.

Default: false

mouseIsOver

Boolean

Defined in lib/p5.play.js:979

True if mouse is on the sprite's collider. Read only.

mouseIsPressed

Boolean

Defined in lib/p5.play.js:988

True if mouse is pressed on the sprite's collider. Read only.

originalHeight

Number

Defined in lib/p5.play.js:1036

Unscaled height of the sprite If no images or animations are set it's the height of the placeholder rectangle.

Default: 100

originalWidth

Number

Defined in lib/p5.play.js:1025

Unscaled width of the sprite If no images or animations are set it's the width of the placeholder rectangle.

Default: 100

position

p5.Vector

Defined in lib/p5.play.js:768

The sprite's position of the sprite as a vector (x,y).

previousPosition

p5.Vector

Defined in lib/p5.play.js:775

The sprite's position at the beginning of the last update as a vector (x,y).

removed

Boolean

Defined in lib/p5.play.js:1047

True if the sprite has been removed.

removed

Number

Defined in lib/p5.play.js:1055

Cycles before self removal. Set it to initiate a countdown, every draw cycle the property is reduced by 1 unit. At 0 it will call a sprite.remove() Disabled if set to -1.

Default: -1

restitution

Number

Defined in lib/p5.play.js:885

Coefficient of restitution. The velocity lost after bouncing. 1: perfectly elastic, no energy is lost 0: perfectly inelastic, no bouncing less than 1: inelastic, this is the most common in nature greater than 1: hyper elastic, energy is increased like in a pinball bumper

Default: 1

rotateToDirection

Boolean

Defined in lib/p5.play.js:919

Automatically set the rotation of the visual element (image or animation) to the sprite's movement direction.

Default: false

rotation

Number

Defined in lib/p5.play.js:898

Rotation in degrees of the visual element (image or animation) Note: this is not the movement's direction, see getDirection.

Default: 0

rotationSpeed

Number

Defined in lib/p5.play.js:908

Rotation change in degrees per frame of thevisual element (image or animation) Note: this is not the movement's direction, see getDirection.

Default: 0

scale

Number

Defined in lib/p5.play.js:944

Determines the sprite's scale. Example: 2 will be twice the native size of the visuals, 0.5 will be half. Scaling up may make images blurry.

Default: 1

shapeColor

Color

Defined in lib/p5.play.js:1076

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

touching

Object

Defined in lib/p5.play.js:844

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.

velocity

p5.Vector

Defined in lib/p5.play.js:793

The sprite's velocity as a vector (x,y) Velocity is speed broken down to its vertical and horizontal components.

visible

Boolean

Defined in lib/p5.play.js:958

The sprite's visibility.

Default: true

width

Number

Defined in lib/p5.play.js:997

Width of the sprite's current image. If no images or animations are set it's the width of the placeholder rectangle.

Default: 100