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.
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.
Type:
-
Boolean
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.
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.
Type:
-
Boolean
bounciness :Number
The bounciness of the sprite's physics body.
Type:
-
Number
centerOfMass :Number
The center of mass of the sprite's physics body.
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'.
Type:
-
String
color :p5.Color
The sprite's current color. By default sprites get a random color.
Type:
-
p5.Color
colour :p5.Color
Alias for color. colour is the British English spelling.
Type:
-
p5.Color
direction :Number
The angle of the sprite's movement or it's rotation angle if the
sprite is not moving.
Type:
-
Number
drag :Number
The amount of resistance a sprite has to being moved.
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).
Example
sprite.draw = function() {
// an oval
ellipse(0,0,20,10);
}
dynamic :Boolean
True if the sprite's physics body is dynamic.
Type:
-
Boolean
fill :p5.Color
Alias for sprite.fillColor
Type:
-
p5.Color
fillColor :p5.Color
Alias for sprite.color
Type:
-
p5.Color
fixture
Returns the first node in a linked list of the planck physics
body's fixtures.
fixtureList
Returns the first node in a linked list of the planck physics
body's fixtures.
friction :Number
The amount the sprite's physics body resists moving
when rubbing against another physics body.
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.
Type:
-
String
image :p5.Image
A reference to the sprite's current image.
Type:
-
p5.Image
img :p5.Image
A reference to the sprite's current image.
Type:
-
p5.Image
(readonly) isMoving :Boolean
True if the sprite is moving.
Type:
-
Boolean
isSuperFast :Boolean
Set this to true if the sprite goes really fast to prevent
inaccurate physics simulation.
Type:
-
Boolean
kinematic :Boolean
True if the sprite's physics body is kinematic.
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.
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!
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. |
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.
Type:
-
object
pixelPerfect :Boolean
Set to true to display the sprite pixel perfect.
This is useful when using pixel art.
Type:
-
Boolean
rotation :Number
The angle of the sprite's rotation, not the direction it is moving.
Type:
-
Number
rotationDrag :Number
The amount the sprite resists rotating.
Type:
-
Number
rotationLock :Boolean
If true the sprite can not rotate.
Type:
-
Boolean
rotationSpeed :Number
The speed of the sprite's rotation.
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.
Type:
-
Number
|Object
shape :String
The kind of shape: 'box', 'circle', 'chain', or 'polygon'.
Type:
-
String
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.
Type:
-
Boolean
static :Boolean
Is the sprite's physics collider static?
Type:
-
Boolean
strokeColor :p5.Color
The sprite's stroke color. By default the stroke of a sprite
is determined by its collider type.
Type:
-
p5.Color
strokeWeight :Number
The sprite's stroke weight.
Type:
-
Number
textColor :p5.Color
The sprite's current text color. Black by default.
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.
visible :Boolean
If true the sprite is shown, if false the sprite is hidden.
Type:
-
Boolean
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.
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.
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.
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.
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`.
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`.
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.
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.
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.
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.
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`.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
rotate(angle, speed) → {Promise}
Rotates the sprite by an amount at a specified angles per frame speed.
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.
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.
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.
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.
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;