Show:
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.

Sprites are added to the allSprites group and given a depth value that puts it in front of all other sprites by default.

Constructor

Sprite
(
  • x
  • y
  • width|radius
  • height
)

Defined in lib/p5.play.js:42

Parameters:

  • x Number

    Initial x coordinate

  • y Number

    Initial y coordinate

  • [width|radius] 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 radius of the placeholder circle.

  • [height] Number optional

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

Methods

addAnimation
(
  • label
  • animation
)

Defined in lib/p5.play.js:1214

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 SpriteAnimation for more information on file sequences:

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

Parameters:

  • label String

    SpriteAnimation identifier

  • animation SpriteAnimation

    The preloaded animation

addImage
(
  • label
  • img
)

Defined in lib/p5.play.js:1189

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:1155

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:1090

Adds the sprite to an existing group

Parameters:

attractionPoint
(
  • magnitude
  • pointX
  • pointY
)

Defined in lib/p5.play.js:1174

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:1483

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 Sprite | Group

    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:1301

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

Changes the displayed image/animation. Equivalent to changeAnimation

Parameters:

  • label String

    Image/SpriteAnimation identifier

collide
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1420

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 Sprite | Group

    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:1452

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 Sprite | Group

    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:944

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

draw ()

Defined in lib/p5.play.js:1002

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:1291

Returns the label of the current animation

Returns:

String:

label Image/SpriteAnimation identifier

getBoundingBox ()

Defined in lib/p5.play.js:878

Returns a the bounding box of the current image

getDirection () Number

Defined in lib/p5.play.js:1068

Calculates the movement's direction in degrees.

Returns:

Number:

Angle in degrees

getSpeed () Number

Defined in lib/p5.play.js:1058

Calculates the scalar speed.

Returns:

Number:

Scalar speed

limitSpeed
(
  • max
)

Defined in lib/p5.play.js:1103

Limits the scalar speed.

Parameters:

  • max Number

    Max speed: positive number

mirrorX
(
  • dir
)
Number

Defined in lib/p5.play.js:896

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:911

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:752

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

overlap
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1391

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 Sprite | Group

    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:1330

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:1362

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:1026

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:811

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 animated sprites.

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

There are four ways to call this method:

  1. setCollider("rectangle")
  2. setCollider("rectangle", offsetX, offsetY, width, height)
  3. setCollider("circle")
  4. setCollider("circle", offsetX, offsetY, radius)

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:721

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:1121

Set the speed and direction 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

  • [angle] Number optional

    Direction in degrees

setVelocity
(
  • x
  • y
)

Defined in lib/p5.play.js:1046

Sets the velocity vector.

Parameters:

  • x Number

    X component

  • y Number

    Y component

update ()

Defined in lib/p5.play.js:598

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

Properties

_drawnWithCamera

Boolean private

Defined in lib/p5.play.js:555

Internal variable to keep track of whether this sprite is drawn while the camera is active. Used in Sprite.update() to know whether to use camera mouse coordinates.

Default: false

_rotation

Number private

Defined in lib/p5.play.js:219

Internal rotation variable (expressed in degrees). Note: external callers access this through the rotation property above.

Default: 0

animation

SpriteAnimation

Defined in lib/p5.play.js:495

Reference to the current animation.

animations

Object

Defined in lib/p5.play.js:479

Keys are the animation label, values are SpriteAnimation objects.

autoResetAnimations

SpriteAnimation

Defined in lib/p5.play.js:503

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 seperate anim.changeFrame call.

collider

Object

Defined in lib/p5.play.js:123

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 of the sprite or from the image dimension in case of animate sprites

You can set a custom collider with Sprite.setCollider

currentAnimation

String

Defined in lib/p5.play.js:487

The current animation's label.

debug

Boolean

Defined in lib/p5.play.js:453

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

Default: false

depth

Number

Defined in lib/p5.play.js:250

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: One more than the greatest existing sprite depth, when calling createSprite(). When calling new Sprite() directly, depth will initialize to 0 (not recommended).

friction

Number

Defined in lib/p5.play.js:111

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

Default: 0

groups

Array

Defined in lib/p5.play.js:471

Groups the sprite belongs to, including allSprites

height

Number

Defined in lib/p5.play.js:388

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:172

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

Default: false

life

Number

Defined in lib/p5.play.js:441

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

mass

Number

Defined in lib/p5.play.js:161

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:101

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:289

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:301

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

mouseIsPressed

Boolean

Defined in lib/p5.play.js:310

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

onBounce

Function

Defined in lib/p5.play.js:545

Called if the sprite bounced another sprite when checked with the bounce function.

Sub-properties:

  • other Sprite

    Receives the sprite that this sprite bounced.

onCollide

Function

Defined in lib/p5.play.js:525

Called if the sprite collided with another sprite when checked with the collide function.

Sub-properties:

  • other Sprite

    Receives the sprite that this sprite collided with.

onDisplace

Function

Defined in lib/p5.play.js:535

Called if the sprite displaces another sprite when checked with the displace function.

Sub-properties:

  • other Sprite

    Receives the sprite that this sprite displaces.

onOverlap

Function

Defined in lib/p5.play.js:515

Called if the sprite overlaps with another sprite when checked with the overlap function.

Sub-properties:

  • other Sprite

    Receives the sprite that this sprite overlaps with.

originalHeight

Number

Defined in lib/p5.play.js:422

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:411

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:66

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

previousPosition

p5.Vector

Defined in lib/p5.play.js:73

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

removed

Boolean

Defined in lib/p5.play.js:433

True if the sprite has been removed.

restitution

Number

Defined in lib/p5.play.js:185

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:240

Automatically lock the rotation property of the visual element (image or animation) to the sprite's movement direction and vice versa.

Default: false

rotation

Number

Defined in lib/p5.play.js:198

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:230

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:266

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:462

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

touching

Object

Defined in lib/p5.play.js:144

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:92

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:280

The sprite's visibility.

Default: true

width

Number

Defined in lib/p5.play.js:365

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

Default: 100