Sprite

Sprite

new Sprite(xopt, yopt, wopt, hopt, collideropt)

Look at the Sprite reference pages before reading these docs. The Sprite constructor can be used in many different ways. Every sprite you create is added to the `allSprites` group and put on the top layer, in front of all previously created sprites.
Source:
Parameters:
Name Type Attributes Description
x Number <optional>
 horizontal position of the sprite
y Number <optional>
 vertical position of the sprite
w 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.
h Number <optional>
 height of the placeholder rectangle and of the collider until an image or new collider are set
collider 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]);

Members

allowSleeping :Boolean

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 Value:
  • true
Source:
Type:
  • Boolean

animation :SpriteAnimation

Reference to the sprite's current animation.
Source:
Type:

autoDraw :Boolean

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 Value:
  • true
Source:
Type:
  • Boolean

autoUpdate :Boolean

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 Value:
  • true
Source:
Type:
  • Boolean

bounciness :Number

The bounciness of the sprite's physics body.
Default Value:
  • 0.2
Source:
Type:
  • Number

centerOfMass :Number

The center of mass of the sprite's physics body.
Source:
Type:
  • Number

collider :String

The sprite's collider type. Default is 'dynamic'. The collider type can be one of the following strings: 'dynamic', 'static', 'kinematic', 'none'.
Default Value:
  • 'dynamic'
Source:
Type:
  • String

color :p5.Color

The sprite's current color. By default sprites get a random color.
Default Value:
  • random color
Source:
Type:
  • p5.Color

colour :p5.Color

Alias for color. colour is the British English spelling.
Default Value:
  • random color
Source:
Type:
  • p5.Color

d :Number

The diameter of a circular sprite.
Source:
Type:
  • Number

density :Number

The density of the sprite's physics body.
Source:
Type:
  • Number

depth

Use .layer instead.
Deprecated:
  • depth
Source:

diameter :Number

The diameter of a circular sprite.
Source:
Type:
  • Number

direction :Number

The angle of the sprite's movement or it's rotation angle if the sprite is not moving.
Default Value:
  • 0 ("right")
Source:
Type:
  • Number

drag :Number

The amount of resistance a sprite has to being moved.
Default Value:
  • 0
Source:
Type:
  • Number

draw

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).
Source:
Example
sprite.draw = function() {
  // an oval
  ellipse(0,0,20,10);
}

dynamic :Boolean

True if the sprite's physics body is dynamic.
Default Value:
  • true
Source:
Type:
  • Boolean

fill :p5.Color

Alias for sprite.fillColor
Default Value:
  • random color
Source:
Type:
  • p5.Color

fillColor :p5.Color

Alias for sprite.color
Default Value:
  • random color
Source:
Type:
  • p5.Color

fixture

Returns the first node in a linked list of the planck physics body's fixtures.
Source:

fixtureList

Returns the first node in a linked list of the planck physics body's fixtures.
Source:

friction :Number

The amount the sprite's physics body resists moving when rubbing against another physics body.
Default Value:
  • 0.5
Source:
Type:
  • Number

h :Number

The height of the sprite.
Source:
Type:
  • Number

halfHeight :Number

Half the height of the sprite.
Source:
Type:
  • Number

halfWidth :Number

Half the width of the sprite.
Source:
Type:
  • Number

heading :String

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 Value:
  • undefined
Source:
Type:
  • String

height :Number

The height of the sprite.
Source:
Type:
  • Number

hh :Number

Half the height of the sprite.
Source:
Type:
  • Number

hw :Number

Half the width of the sprite.
Source:
Type:
  • Number

image :p5.Image

A reference to the sprite's current image.
Source:
Type:
  • p5.Image

img :p5.Image

A reference to the sprite's current image.
Source:
Type:
  • p5.Image

immovable

Use .static instead.
Deprecated:
  • immovable
Source:

(readonly) isMoving :Boolean

True if the sprite is moving.
Source:
Type:
  • Boolean

isSuperFast :Boolean

Set this to true if the sprite goes really fast to prevent inaccurate physics simulation.
Default Value:
  • false
Source:
Type:
  • Boolean

kinematic :Boolean

True if the sprite's physics body is kinematic.
Default Value:
  • false
Source:
Type:
  • Boolean

layer :Number

By default sprites are drawn in the order they were created in. You can change the draw order by editing sprite's layer property. Sprites with the highest layer value get drawn first.
Source:
Type:
  • Number

life :Number

The number of frame cycles before the sprite is removed. Set it to initiate a countdown, every draw cycle the value is reduced by 1 unit. If it becomes less than or equal to 0, the sprite will be removed. It must be set to a positive integer lower than the max value of a 32 bit signed integer, 2147483647, which is the default value representing infinite life. This limitation makes sprite netcode smaller. But don't worry, at 60 fps this gives users a definable sprite life range between 1 frame and ~411 days!
Default Value:
  • 2147483647
Source:
Type:
  • Number

mass :Number

The mass of the sprite's physics body.
Source:
Type:
  • Number

mirror :Object

The sprite's mirror states.
Properties:
Name Type Description
x Boolean The sprite's horizontal mirror state.
y Boolean The sprite's vertical mirror state.
Default Value:
  • {x: false, y: false}
Source:
Type:
  • Object

offset :object

Offsetting the sprite moves the sprite's physics body relative to its center. The sprite's x and y properties represent its center in world coordinates. This point is also the sprite's center of rotation.
Source:
Type:
  • object

pixelPerfect :Boolean

Set to true to display the sprite pixel perfect. This is useful when using pixel art.
Default Value:
  • false
Source:
Type:
  • Boolean

pos :p5.Vector

The position vector {x, y}
Source:
Type:
  • p5.Vector

position :p5.Vector

The position vector {x, y}
Source:
Type:
  • p5.Vector

previousPosition :object

Verbose alias for sprite.prevPos
Source:
Type:
  • object

r :Number

The radius of a circular sprite.
Source:
Type:
  • Number

radius :Number

The radius of a circular sprite.
Source:
Type:
  • Number

rotation :Number

The angle of the sprite's rotation, not the direction it is moving.
Default Value:
  • 0
Source:
Type:
  • Number

rotationDrag :Number

The amount the sprite resists rotating.
Default Value:
  • 0
Source:
Type:
  • Number

rotationLock :Boolean

If true the sprite can not rotate.
Default Value:
  • false
Source:
Type:
  • Boolean

rotationSpeed :Number

The speed of the sprite's rotation.
Default Value:
  • 0
Source:
Type:
  • Number

scale :Number|Object

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 Value:
  • 1
Source:
Type:
  • Number | Object

shape :String

The kind of shape: 'box', 'circle', 'chain', or 'polygon'.
Default Value:
  • box
Source:
Type:
  • String

shapeColor

Deprecated:
  • Yes
Source:

sleeping :Boolean

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 Value:
  • true
Source:
Type:
  • Boolean

speed :Number

The sprite's speed.
Default Value:
  • 0
Source:
Type:
  • Number

static :Boolean

Is the sprite's physics collider static?
Default Value:
  • false
Source:
Type:
  • Boolean

stroke :p5.Color

Alias for sprite.strokeColor
Source:
Type:
  • p5.Color

strokeColor :p5.Color

The sprite's stroke color. By default the stroke of a sprite is determined by its collider type.
Source:
Type:
  • p5.Color

strokeWeight :Number

The sprite's stroke weight.
Default Value:
  • undefined
Source:
Type:
  • Number

textColor :p5.Color

The sprite's current text color. Black by default.
Default Value:
  • black (#000000)
Source:
Type:
  • p5.Color

update

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

(readonly) vertices :Array

The sprite's vertices.
Source:
Type:
  • Array

visible :Boolean

If true the sprite is shown, if false the sprite is hidden.
Default Value:
  • true
Source:
Type:
  • Boolean

w :Number

The width of the sprite.
Source:
Type:
  • Number

width :Number

The width of the sprite.
Source:
Type:
  • Number

x :Number

The horizontal position of the sprite.
Source:
Type:
  • Number

y :Number

The vertical position of the sprite.
Source:
Type:
  • Number

Methods

addCollider(offsetX, offsetY, w, h)

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.
Source:
Parameters:
Name Type Description
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()

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

addSensor(offsetX, offsetY, w, h)

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.
Source:
Parameters:
Name Type Description
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, angleopt)

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.
Source:
Parameters:
Name Type Attributes Description
speed Number Scalar speed
angle Number <optional>
 Direction in degrees

angleTo(x, y) → {Number}

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`.
Source:
Parameters:
Name Type Description
x Number
y Number
Returns:
Type:
Number
angle
Example
spriteA.direction = spriteA.angleTo(spriteB);

angleToFace(x, y, facing) → {Number}

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`.
Source:
Parameters:
Name Type Description
x Number
y Number
facing Number rotation angle the sprite should be at when "facing" the position, default is 0
Returns:
Type:
Number
minimum angle of rotation to face the position

applyForce(x, y, originXopt, originYopt)

Apply a force that is scaled to the sprite's mass.
Source:
Parameters:
Name Type Attributes Description
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, originXopt, originYopt)

Apply an impulse to the sprite's physics collider.
Source:
Parameters:
Name Type Attributes Description
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)

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.
Source:
Parameters:
Name Type Description
torque Number The amount of torque to apply.

(async) changeAni(…anis)

Changes the sprite's animation. Use `addAni` to define the animation(s) first.
Source:
Parameters:
Name Type Attributes Description
anis String <repeatable>
 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)

Changes the sprite's animation. Use `addAni` to define the animation(s) first. Alt for `changeAni`.
Source:
Parameters:
Name Type Attributes Description
anis String <repeatable>
 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

collided(target, callbackopt) → {Boolean}

Returns true on the first frame that the sprite no longer overlaps with the target sprite or group.
Source:
Parameters:
Name Type Attributes Description
target Sprite | Group
callback function <optional>
Returns:
Type:
Boolean

collides(target, callbackopt)

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.
Source:
Parameters:
Name Type Attributes Description
target Sprite | Group
callback function <optional>

colliding(target, callbackopt) → {Number}

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.
Source:
Parameters:
Name Type Attributes Description
target Sprite | Group
callback function <optional>
Returns:
Type:
Number
frames

move(distance, direction, speed) → {Promise}

Move the sprite a certain distance from its current position.
Source:
Parameters:
Name Type Description
distance Number [optional]
direction Number | String [optional]
speed Number [optional]
Returns:
Type:
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)

Move a sprite away from a position.
Source:
Parameters:
Name Type Description
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}

Move the sprite to a position.
Source:
Parameters:
Name Type Description
x|position Number | Object destination x or any object with x and y properties
y Number destination y
speed Number [optional]
Returns:
Type:
Promise
resolves to true when the movement is complete or to false if the sprite will not reach its destination

moveTowards(x|position, y, tracking)

Move a sprite towards a position.
Source:
Parameters:
Name Type Description
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, callbackopt) → {Boolean}

Returns true on the first frame that the sprite no longer overlaps with the target sprite or group.
Source:
Parameters:
Name Type Attributes Description
target Sprite | Group
callback function <optional>
Returns:
Type:
Boolean

overlapping(target, callbackopt) → {Number}

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.
Source:
Parameters:
Name Type Attributes Description
target Sprite | Group
callback function <optional>
Returns:
Type:
Number
frames

overlaps(target, callbackopt)

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.
Source:
Parameters:
Name Type Attributes Description
target Sprite | Group
callback function <optional>

remove()

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

removeColliders()

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

removeSensors()

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

rotate(angle, speed) → {Promise}

Rotates the sprite by an amount at a specified angles per frame speed.
Source:
Parameters:
Name Type Description
angle Number the amount to rotate the sprite
speed Number the amount of rotation per frame, default is 1
Returns:
Type:
Promise
a promise that resolves when the rotation is complete

rotateTo(angle|position, speed, facing) → {Promise}

Rotates the sprite to an angle or to face a position.
Source:
Parameters:
Name Type Description
angle|position Number | Object
speed Number the amount of rotation per frame, default is 1
facing Number (only if position is given) the rotation angle the sprite should be at when "facing" the position, default is 0
Returns:
Type:
Promise
a promise that resolves when the rotation is complete

rotateTowards(angle|position, tracking, facing)

Rotates the sprite towards an angle or position with x and y properties.
Source:
Parameters:
Name Type Description
angle|position Number | Object angle in degrees or an object with x and y properties
tracking Number percent of the distance to rotate on each frame towards the target angle, default is 0.1 (10%)
facing Number (only if position is given) rotation angle the sprite should be at when "facing" the position, default is 0

setSpeed(speed, directionopt)

Deprecated: set direction and set speed separately Sets 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.
Deprecated:
  • setSpeed
Source:
Parameters:
Name Type Attributes Description
speed Number Scalar speed
direction Number <optional>
 angle

setVelocity(vector|x, y)

Deprecated: set sprite.vel instead. Sets the velocity vector.
Deprecated:
  • setVelocity
Source:
Parameters:
Name Type Description
vector|x Number vector or horizontal velocity
y Number vertical velocity
Example
sprite.vel = createVector(1, 2);
// OR
sprite.vel.x = 1;
sprite.vel.y = 2;

toString()

Warning: This function might be changed in a future release. Returns the sprite's unique identifier
Source:
Returns:
the sprite's id