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

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

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

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

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

Adds the sprite to an existing group

Parameters:

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

Defined in lib/p5.play.js:1524

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

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

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

Changes the displayed image/animation. Equivalent to changeAnimation

Parameters:

  • label String

    Image/Animation identifier

collide
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1778

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

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++; }

draw ()

Defined in lib/p5.play.js:1383

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

Returns the label of the current animation

Returns:

String:

label Image/Animation identifier

getDirection () Number

Defined in lib/p5.play.js:1448

Calculates the movement's direction in degrees.

Returns:

Number:

Angle in degrees

limitSpeed
(
  • max
)

Defined in lib/p5.play.js:1476

Limits the scalar speed.

Parameters:

  • max Number

    Max speed: positive number

mirrorX
(
  • dir
)
Number

Defined in lib/p5.play.js:1295

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

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

overlap
(
  • target
  • callback
)
Boolean

Defined in lib/p5.play.js:1747

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

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

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

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

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

setSpeed
(
  • speed
  • angle
)

Defined in lib/p5.play.js:1496

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
(
  • x
  • x
)

Defined in lib/p5.play.js:1426

Sets the velocity vector.

Parameters:

  • x Number

    X component

  • x Number

    Y component

setVelocity () Number

Defined in lib/p5.play.js:1438

Calculates the scalar speed.

Returns:

Number:

Scalar speed

update ()

Defined in lib/p5.play.js:983

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

Properties

animation

Animation

Defined in lib/p5.play.js:975

Reference to the current animation.

camera

Camera

Defined in lib/p5.play.js:2139

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

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

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

Default: false

depth

Number

Defined in lib/p5.play.js:807

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

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

Groups the sprite belongs to, including allSprites

height

Number

Defined in lib/p5.play.js:888

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

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

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

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

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

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

mouseIsPressed

Boolean

Defined in lib/p5.play.js:865

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

originalHeight

Number

Defined in lib/p5.play.js:913

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

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

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

previousPosition

p5.Vector

Defined in lib/p5.play.js:652

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

removed

Boolean

Defined in lib/p5.play.js:924

False if the sprite has been removed.

removed

Number

Defined in lib/p5.play.js:932

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

Coefficient of restitution. The velocity lost after bouncing. 1: perfectly elastic, no energy is lost 0: perfectly inelastic, no bouncing <1: inelastic, this is the most common in nature

1: hyper elastic, energy is increased like in a pinball bumper

Default: 1

rotateToDirection

Boolean

Defined in lib/p5.play.js:796

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

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

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

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

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

touching

Object

Defined in lib/p5.play.js:721

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

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

The sprite's visibility.

Default: true

width

Number

Defined in lib/p5.play.js:874

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

Default: 100