API Docs for: 3
Show:

Sprite Class

Defined in: v3/p5play.js:138

Look at the Sprite reference pages before reading these docs. The Sprite constructor can be used in many different ways.

https://p5play.org/learn/sprite.html

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

Constructor

Sprite

(
  • [x]
  • [y]
  • [width]
  • [height]
  • [colliderType]
)

Defined in v3/p5play.js:138

Parameters:

  • [x] Number optional
    • horizontal position of the sprite
  • [y] Number optional
    • vertical position of the sprite
  • [width] 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
  • [colliderType] String optional
    • collider type is 'dynamic' by default, can be 'static', 'kinematic', or 'none'

Example:

let sprite = new Sprite();

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

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

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

Methods

addCollider

(
  • offsetX
  • offsetY
  • w
  • h
)

Defined in v3/p5play.js:700

EXPERIMENTAL method! Subject to change!

Adds a collider (fixture) to the sprite's physics body.

It accepts parameters in a similar format to the Sprite constructor except the first two parameters are x and y offsets, the distance new collider should be from the center of the sprite.

One limitation of the current implementation is that the collider type can't be changed without losing every collider added to the sprite besides the first. This will be fixed in a future release.

Parameters:

  • offsetX Number

    distance from the center of the sprite

  • offsetY Number

    distance from the center of the sprite

  • w Number

    width of the collider

  • h Number

    height of the collider

addDefaultSensors

()

Defined in v3/p5play.js:3411

This function is used automatically if a sprite overlap detection function is called but the sprite has no overlap sensors.

It creates sensor fixtures that are the same size as the sprite's colliders. If you'd like to add more sensors to a sprite, use the addSensor function.

addSensor

(
  • offsetX
  • offsetY
  • w
  • h
)

Defined in v3/p5play.js:740

EXPERIMENTAL method! Subject to change!

Adds a sensor to the sprite's physics body that's used to detect overlaps with other sprites.

It accepts parameters in a similar format to the Sprite constructor except the first two parameters are x and y offsets, the relative distance the new sensor should be from the center of the sprite.

Parameters:

  • offsetX Number

    distance from the center of the sprite

  • offsetY Number

    distance from the center of the sprite

  • w Number

    width of the collider

  • h Number

    height of the collider

addSpeed

(
  • speed
  • [angle]
)

Defined in v3/p5play.js:2638

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

angleTo

(
  • x
  • y
)
Number

Defined in v3/p5play.js:2899

Finds the angle from this sprite to the given position or object with x and y properties.

Can be used to change the direction of a sprite so it moves to a position or object.

Used internally by moveTo and moveTowards.

Parameters:

  • x Number
  • y Number

Returns:

Number:

angle

Example:

spriteA.direction = spriteA.angleTo(spriteB);

angleToFace

(
  • x
  • y
  • facing
)
Number

Defined in v3/p5play.js:2932

Finds the minimium amount the sprite would have to rotate to "face" a position at a specified "facing" rotation.

Used internally by rotateTo and rotateTowards.

Parameters:

  • x Number
  • y Number
  • facing Number
    • rotation angle the sprite should be at when "facing" the position, default is 0

Returns:

Number:

minimum angle of rotation to face the position

applyForce

(
  • x
  • y
  • [originX]
  • [originY]
)

Defined in v3/p5play.js:2522

Apply a force that is scaled to the sprite's mass.

Parameters:

  • x Number
  • y Number
  • [originX] Number optional
  • [originY] Number optional

Example:

sprite.applyForce(x, y); sprite.applyForce(x, y, originX, originY); sprite.applyForce(x, y, {x: originX, y: originY}); sprite.applyForce({x, y}, {x: originX, y: originY});

applyImpulse

(
  • x
  • y
  • [originX]
  • [originY]
)

Defined in v3/p5play.js:2552

Apply an impulse to the sprite's physics collider.

Parameters:

  • x Number
  • y Number
  • [originX] Number optional
  • [originY] Number optional

Example:

sprite.applyImpulse(x, y); sprite.applyImpulse(x, y, originX, originY); sprite.applyImpulse(x, y, {x: originX, y: originY}); sprite.applyImpulse({x, y}, {x: originX, y: originY});

applyTorque

(
  • torque
)

Defined in v3/p5play.js:2582

Apply a torque on the sprite's physics body. Torque is the force that causes rotation. A positive torque will rotate the sprite clockwise. A negative torque will rotate the sprite counter-clockwise.

Parameters:

  • torque Number

    The amount of torque to apply.

changeAni

(
  • anis
)

Defined in v3/p5play.js:3038

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

changeAnimation

(
  • anis
)

Defined in v3/p5play.js:3133

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

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

changeAnimation

(
  • label
)

Defined in v3/p5play.js:3147

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

collided

(
  • target
  • [callback]
)
Boolean

Defined in v3/p5play.js:3287

Returns true on the first frame that the sprite no longer overlaps with the target sprite or group.

Parameters:

Returns:

Boolean:

collides

(
  • target
  • [callback]
)

Defined in v3/p5play.js:3253

Returns true on the first frame that the sprite collides with the target sprite or group.

Custom collision event handling can be done by using this function in an if statement or adding a callback as the second parameter.

Parameters:

colliding

(
  • target
  • [callback]
)
Number

Defined in v3/p5play.js:3270

Returns a truthy value while the sprite is colliding with the target sprite or group. The value is the number of frames that the sprite has been colliding with the target.

Parameters:

Returns:

Number:

frames

draw

()

Defined in v3/p5play.js:1541

Displays the sprite.

This function is called automatically at the end of each p5.js draw function call but it can also be run separately to customize the order sprites are drawn in relation to other stuff drawn to the p5.js canvas. Also see the sprite.layer property.

A sprite's draw function can be overridden with a custom draw function, in which the center of the sprite is at (0, 0).

Example:

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

move

(
  • distance
  • direction
  • speed
)
Promise

Defined in v3/p5play.js:2705

Move the sprite a certain distance from its current position.

Parameters:

  • distance Number

    [optional]

  • direction Number | String

    [optional]

  • speed Number

    [optional]

Returns:

Promise:

resolves when the movement is complete or cancelled

Example:

sprite.move(distance); sprite.move(distance, direction); sprite.move(distance, direction, speed);

sprite.move(directionName); sprite.move(directionName, speed); sprite.move(directionName, speed, distance); // deprecated usage

moveAway

(
  • x|position
  • y
  • repel
)

Defined in v3/p5play.js:2691

Move a sprite away from a position.

Parameters:

  • x|position Number | Object

    x or any object with x and y properties

  • y Number
  • repel Number

    [optional] the higher the value, the faster the sprite moves away. Default is 0.1 (10% repel).

moveTo

(
  • x|position
  • y
  • speed
)
Promise

Defined in v3/p5play.js:2751

Move the sprite to a position.

Parameters:

  • x|position Number | Object

    destination x or any object with x and y properties

  • y Number

    destination y

  • speed Number

    [optional]

Returns:

Promise:

resolves when the movement is complete or cancelled

moveTowards

(
  • x|position
  • y
  • tracking
)

Defined in v3/p5play.js:2654

Move a sprite towards a position.

Parameters:

  • x|position Number | Object

    destination x or any object with x and y properties

  • y Number

    destination y

  • tracking Number

    [optional] 1 represents 1:1 tracking, the mouse moves to the destination immediately, 0 represents no tracking. Default is 0.1 (10% tracking).

overlapped

(
  • target
  • [callback]
)
Boolean

Defined in v3/p5play.js:3396

Returns true on the first frame that the sprite no longer overlaps with the target sprite or group.

Parameters:

Returns:

Boolean:

overlapping

(
  • target
  • [callback]
)
Number

Defined in v3/p5play.js:3379

Returns a truthy value while the sprite is overlapping with the target sprite or group. The value returned is the number of frames the sprite has been overlapping with the target.

Parameters:

Returns:

Number:

frames

overlaps

(
  • target
  • [callback]
)

Defined in v3/p5play.js:3362

Returns true on the first frame that the sprite overlaps with the target sprite or group.

Custom overlap event handling can be done by using this function in an if statement or adding a callback as the second parameter.

Parameters:

remove

()

Defined in v3/p5play.js:3182

Removes the Sprite from the sketch and all the groups it belongs to.

When a sprite is removed it will not be drawn or updated anymore. If it has a physics body, it will be removed from the physics world simulation.

There's no way to undo this operation. If you want to hide a sprite use sprite.visible = false instead.

removeColliders

()

Defined in v3/p5play.js:989

Removes the physics body colliders from the sprite but not overlap sensors.

Only use this method if you never want to use the sprite's colliders again. If you want to disable colliders without removing them, use the overlaps, overlapping, or overlapped functions instead.

removeSensors

()

Defined in v3/p5play.js:1106

Removes overlap sensors from the sprite.

Only use this method if you never want to use the sprite's overlap sensors again. To disable overlap sensors without removing them, use the collides, colliding, or collided functions instead.

rotate

(
  • angle
  • speed
)
Promise

Defined in v3/p5play.js:2987

Rotates the sprite by an amount at a specified angles per frame speed.

Parameters:

  • angle Number

    the amount to rotate the sprite

  • speed Number

    the amount of rotation per frame, default is 1

Returns:

Promise:

a promise that resolves when the rotation is complete

rotateTo

(
  • x|position
  • y
  • speed
  • facing
)
Promise

Defined in v3/p5play.js:2963

Rotates the sprite to a position at a rotation.

Parameters:

  • x|position Number | Object
  • y Number
  • speed Number

    the amount of rotation per frame, default is 1

  • facing Number

    rotation angle the sprite should be at when "facing" the position, default is 0

Returns:

Promise:

a promise that resolves when the rotation is complete

rotateTowards

(
  • x
  • y
  • tracking
  • facing
)

Defined in v3/p5play.js:2880

Parameters:

  • x

    position to rotate towards

  • y

    position to rotate towards

  • tracking

    percent of the distance to rotate on each frame towards the target angle, default is 0.1 (10%)

  • facing

    rotation angle the sprite should be at when "facing" the position, default is 0

toString

()

Defined in v3/p5play.js:3213

Warning: This function might be changed in a future release.

Returns the sprite's unique identifier

Returns:

the sprite's id

update

()

Defined in v3/p5play.js:2295

You can set the sprite's update function to a custom update function which by default, will be run after every p5.js draw call.

This function updates the sprite's animation, mouse, and

There's no way to individually update a sprite or group of sprites in the physics simulation though.

Properties

allowSleeping

Boolean

Defined in v3/p5play.js:1188

This property disables the ability for a sprite to "sleep".

"Sleeping" sprites are not included in the physics simulation, a sprite starts "sleeping" when it stops moving and doesn't collide with anything that it wasn't already _touching.

Default: true

animation

SpriteAnimation

Defined in v3/p5play.js:1207

Reference to the sprite's current animation.

animations

SpriteAnimations

Defined in v3/p5play.js:258

Keys are the animation label, values are SpriteAnimation objects.

autoDraw

Boolean

Defined in v3/p5play.js:576

autoDraw is a property of all groups that controls whether a group is automatically drawn to the screen after the end of each draw cycle.

It only needs to be set to false once and then it will remain false for the rest of the sketch, unless changed.

Default: true

autoUpdate

Boolean

Defined in v3/p5play.js:588

autoUpdate is a property of all groups that controls whether a group is automatically updated after the end of each draw cycle.

It only needs to be set to false once and then it will remain false for the rest of the sketch, unless changed.

Default: true

bounciness

Number

Defined in v3/p5play.js:1231

The bounciness of the sprite's physics body.

Default: 0.2

centerOfMass

Number

Defined in v3/p5play.js:1248

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

collider

String

Defined in v3/p5play.js:1259

The sprite's collider type. Default is 'dynamic'.

The collider type can be one of the following strings: 'dynamic', 'static', 'kinematic', 'none'.

Default: 'dynamic'

color

p5.Color

Defined in v3/p5play.js:1346

The sprite's current color. By default sprites get a random color.

Default: random color

colour

p5.Color

Defined in v3/p5play.js:1359

Alias for color. colour is the British English spelling.

Default: random color

d

Number

Defined in v3/p5play.js:2125

The diameter of a circular sprite.

debug

Boolean | String

Defined in v3/p5play.js:553

When the sprite.debug property is set to true, the collider shapes will be drawn as bright green outlines with crosshairs at the center of the sprite.

When the sprite.debug property is set to 'colliders', only the collider shapes will be drawn.

Default: false

density

Number

Defined in v3/p5play.js:1451

The density of the sprite's physics body.

diameter

Number

Defined in v3/p5play.js:2169

The diameter of a circular sprite.

direction

Number

Defined in v3/p5play.js:1481

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

Default: 0 ("right")

drag

Number

Defined in v3/p5play.js:1526

The amount of resistance a sprite has to being moved.

Default: 0

dynamic

Boolean

Defined in v3/p5play.js:1570

True if the sprite's physics body is dynamic.

Default: true

fill

p5.Color

Defined in v3/p5play.js:1382

Alias for sprite.fillColor

Default: random color

fillColor

p5.Color

Defined in v3/p5play.js:1396

Alias for sprite.color

Default: random color

friction

Number

Defined in v3/p5play.js:1617

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

Default: 0.5

groups

Array

Defined in v3/p5play.js:248

Groups the sprite belongs to, including allSprites

Default: [allSprites]

h

Number

Defined in v3/p5play.js:2070

The height of the sprite.

halfHeight

Number

Defined in v3/p5play.js:2114

Half the height of the sprite.

halfWidth

Number

Defined in v3/p5play.js:2059

Half the width of the sprite.

heading

String

Defined in v3/p5play.js:1635

The sprite's heading. This is a string that can be set to "up", "down", "left", "right", "upRight", "upLeft", "downRight"

It ignores cardinal direction word order, capitalization, spaces, underscores, and dashes.

Default: undefined

height

Number

Defined in v3/p5play.js:2103

The height of the sprite.

hh

Number

Defined in v3/p5play.js:2092

Half the height of the sprite.

hw

Number

Defined in v3/p5play.js:2037

Half the width of the sprite.

idNum

Number

Defined in v3/p5play.js:173

Each sprite has a unique id number. Don't change it! Its useful for debugging. Sprite id numbers start at 1000.

image

SpriteAnimation

Defined in v3/p5play.js:1683

A reference to the sprite's current image.

img

SpriteAnimation

Defined in v3/p5play.js:1670

A reference to the sprite's current image.

isMoving

Boolean

Defined in v3/p5play.js:1696

True if the sprite is moving.

isSuperFast

Boolean

Defined in v3/p5play.js:1707

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

Default: false

kinematic

Boolean

Defined in v3/p5play.js:1730

True if the sprite's physics body is kinematic.

Default: false

life

Number

Defined in v3/p5play.js:294

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

mass

Number

Defined in v3/p5play.js:1745

The mass of the sprite's physics body.

pos

p5.Vector

Defined in v3/p5play.js:1991

The position vector {x, y}

position

p5.Vector

Defined in v3/p5play.js:2008

The position vector {x, y}

previousPosition

Object

Defined in v3/p5play.js:1770

Verbose alias for sprite.prevPos

prevPos

Object

Defined in v3/p5play.js:541

The sprite's position on the previous frame.

r

Number

Defined in v3/p5play.js:2181

The radius of a circular sprite.

radius

Number

Defined in v3/p5play.js:2193

The radius of a circular sprite.

removed

Boolean

Defined in v3/p5play.js:266

True if the sprite was removed from the world

Default: false

resetAnimationsOnChange

SpriteAnimation

Defined in v3/p5play.js:600

If false, animations will always start playing from the frame they were stopped at. If true, when the sprite changes the animation its currently displaying, it will start playing from frame 0.

Default: false

rotation

Number

Defined in v3/p5play.js:1783

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

Default: 0

rotationDrag

Number

Defined in v3/p5play.js:1808

The amount the sprite resists rotating.

Default: 0

rotationLock

Boolean

Defined in v3/p5play.js:1586

If true the sprite can not rotate.

Default: false

rotationSpeed

Number

Defined in v3/p5play.js:1822

The speed of the sprite's rotation.

Default: 0

scale

Number | Object

Defined in v3/p5play.js:1838

Scale of the sprite's physics body. Default is {x: 1, y: 1}

The getter for sprite.scale returns the scale as an object with x and y properties.

The valueOf function for sprite.scale returns the scale as a number. This enables users to do things like sprite.scale *= 2 to double the sprite's scale.

Default: 1

shape

String

Defined in v3/p5play.js:2266

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

Default: box

sleeping

Boolean

Defined in v3/p5play.js:1880

Wake a sprite up or put it to sleep.

"Sleeping" sprites are not included in the physics simulation, a sprite starts "sleeping" when it stops moving and doesn't collide with anything that it wasn't already _touching.

Default: true

speed

Number

Defined in v3/p5play.js:1908

The sprite's speed.

Default: 0

static

Boolean

Defined in v3/p5play.js:1924

Is the sprite's physics collider static?

Default: false

stroke

p5.Color

Defined in v3/p5play.js:1410

Alias for sprite.strokeColor

strokeColor

p5.Color

Defined in v3/p5play.js:1423

The sprite's stroke current color. By default the stroke of a sprite indicates its collider type.

strokeWeight

Number

Defined in v3/p5play.js:673

Default: undefined

textColor

p5.Color

Defined in v3/p5play.js:1437

The sprite's current text color. Black by default.

Default: black (#000000)

tileSize

Number

Defined in v3/p5play.js:336

The tile size is used to change the size of one unit of measurement for the sprite.

For example, if the tile size is 16, then a sprite with x=1 and y=1 will be drawn at position (16, 16) on the canvas.

Default: 1

vertices

Array An array of p5.Vector objects.

Defined in v3/p5play.js:1940

The sprite's vertices.

visible

Boolean

Defined in v3/p5play.js:305

The sprite's visibility.

Default: true

w

Number

Defined in v3/p5play.js:2020

The width of the sprite.

width

Number

Defined in v3/p5play.js:2048

The width of the sprite.

x

Number

Defined in v3/p5play.js:1969

The horizontal position of the sprite.

y

Number

Defined in v3/p5play.js:1980

The vertical position of the sprite.