Sprite
A Sprite is the main building block of p5play: 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.
Table of Contents
-
Methods
- addAnimation(labelanimation)
- addImage(labelimg)
- addSpeed(speedangle)
- addToGroup(group)
- attractionPoint(magnitudepointXpointY)
- bounce(targetcallback)
- changeAnimation(label)
- changeImage(label)
- collide(targetcallback)
- displace(targetcallback)
- display()
- draw()
- getAnimationLabel()
- getBoundingBox()
- getDirection()
- getSpeed()
- limitSpeed(max)
- mirrorX(dir)
- mirrorY(dir)
- mouseUpdate()
- overlap(targetcallback)
- overlapPixel(pointXpointY)
- overlapPoint(pointXpointY)
- remove()
- setCollider(typeoffsetXoffsetYwidthheight)
- setDefaultCollider()
- setSpeed(speedangle)
- setVelocity(xy)
- update()
-
Properties
- _drawnWithCamera
- _rotation
- animation
- animations
- autoResetAnimations
- collider
- currentAnimation
- debug
- depth
- friction
- groups
- height
- immovable
- life
- mass
- maxSpeed
- mouseActive
- mouseIsOver
- mouseIsPressed
- onBounce
- onCollide
- onDisplace
- onOverlap
- originalHeight
- originalWidth
- position
- previousPosition
- removed
- restitution
- rotateToDirection
- rotation
- rotationSpeed
- scale
- shapeColor
- touching
- velocity
- visible
- width
Constructor
Sprite
-
x -
y -
width|radius -
height
Parameters:
-
xNumberInitial x coordinate
-
yNumberInitial y coordinate
-
[width|radius]Number optionalWidth 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 optionalHeight of the placeholder rectangle and of the collider until an image or new collider are set createVector
Methods
addAnimation
-
label -
animation
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:
-
labelStringSpriteAnimation identifier
-
animationSpriteAnimationThe preloaded animation
addImage
-
label -
img
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:
-
labelString | p5.ImageLabel or image
-
[img]p5.Image optionalImage
addSpeed
-
speed -
angle
Pushes the sprite in a direction defined by an angle. The force is added to the current velocity.
Parameters:
-
speedNumberScalar speed to add
-
angleNumberDirection in degrees
attractionPoint
-
magnitude -
pointX -
pointY
Pushes the sprite toward a point. The force is added to the current velocity.
Parameters:
-
magnitudeNumberScalar speed to add
-
pointXNumberDirection x coordinate
-
pointYNumberDirection y coordinate
bounce
-
target -
callback
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:
Returns:
True if overlapping
Example:
sprite.bounce(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}changeAnimation
-
label
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:
-
labelStringSpriteAnimation identifier
changeImage
-
label
Changes the displayed image/animation. Equivalent to changeAnimation
Parameters:
-
labelStringImage/SpriteAnimation identifier
collide
-
target -
callback
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:
Returns:
True if overlapping
Example:
sprite.collide(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}displace
-
target -
callback
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:
Returns:
True if overlapping
Example:
sprite.displace(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}display
()
Manages the positioning, scale and rotation of the sprite Called automatically, it should not be overridden
draw
()
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
Returns the label of the current animation
Returns:
label Image/SpriteAnimation identifier
getBoundingBox
()
Returns a the bounding box of the current image
getDirection
()
Number
Calculates the movement's direction in degrees.
Returns:
Angle in degrees
getSpeed
()
Number
Calculates the scalar speed.
Returns:
Scalar speed
limitSpeed
-
max
Limits the scalar speed.
Parameters:
-
maxNumberMax speed: positive number
mirrorX
-
dir
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:
-
dirNumberEither 1 or -1
Returns:
Current mirroring if no parameter is specified
mirrorY
-
dir
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:
-
dirNumberEither 1 or -1
Returns:
Current mirroring if no parameter is specified
mouseUpdate
()
Updates the sprite mouse states and triggers the mouse events: onMouseOver, onMouseOut, onMousePressed, onMouseReleased
overlap
-
target -
callback
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:
Returns:
True if overlapping
Example:
sprite.overlap(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}overlapPixel
-
pointX -
pointY
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:
-
pointXNumberx coordinate of the point to check
-
pointYNumbery coordinate of the point to check
Returns:
result True if non-transparent
overlapPoint
-
pointX -
pointY
Checks if the given point is inside the sprite's collider.
Parameters:
-
pointXNumberx coordinate of the point to check
-
pointYNumbery coordinate of the point to check
Returns:
result True if inside
remove
()
Removes the Sprite from the sketch. The removed Sprite won't be drawn or updated anymore.
setCollider
-
type -
offsetX -
offsetY -
width -
height
Sets a collider for the sprite.
In p5play 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:
- setCollider("rectangle")
- setCollider("rectangle", offsetX, offsetY, width, height)
- setCollider("circle")
- setCollider("circle", offsetX, offsetY, radius)
Parameters:
-
typeStringEither "rectangle" or "circle"
-
offsetXNumberCollider x position from the center of the sprite
-
offsetYNumberCollider y position from the center of the sprite
-
widthNumberCollider width or radius
-
heightNumberCollider height
setDefaultCollider
()
Creates a default collider matching the size of the placeholder rectangle or the bounding box of the image.
setSpeed
-
speed -
angle
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:
-
speedNumberScalar speed
-
[angle]Number optionalDirection in degrees
setVelocity
-
x -
y
Sets the velocity vector.
Parameters:
-
xNumberX component
-
yNumberY component
update
()
Updates the sprite. Called automatically at the beginning of the draw cycle.
Properties
_drawnWithCamera
Boolean
private
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
Internal rotation variable (expressed in degrees). Note: external callers access this through the rotation property above.
Default: 0
animations
Object
Keys are the animation label, values are SpriteAnimation objects.
autoResetAnimations
SpriteAnimation
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
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
The current animation's label.
debug
Boolean
If set to true, draws an outline of the collider, the depth, and center.
Default: false
depth
Number
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
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
Groups the sprite belongs to, including allSprites
height
Number
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
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
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
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
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
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
True if mouse is on the sprite's collider. Read only.
mouseIsPressed
Boolean
True if mouse is pressed on the sprite's collider. Read only.
onBounce
Function
Called if the sprite bounced another sprite when checked with the bounce function.
Sub-properties:
-
otherSpriteReceives the sprite that this sprite bounced.
onCollide
Function
Called if the sprite collided with another sprite when checked with the collide function.
Sub-properties:
-
otherSpriteReceives the sprite that this sprite collided with.
onDisplace
Function
Called if the sprite displaces another sprite when checked with the displace function.
Sub-properties:
-
otherSpriteReceives the sprite that this sprite displaces.
onOverlap
Function
Called if the sprite overlaps with another sprite when checked with the overlap function.
Sub-properties:
-
otherSpriteReceives the sprite that this sprite overlaps with.
originalHeight
Number
Unscaled height of the sprite If no images or animations are set it's the height of the placeholder rectangle.
Default: 100
originalWidth
Number
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
The sprite's position of the sprite as a vector (x,y).
previousPosition
p5.Vector
The sprite's position at the beginning of the last update as a vector (x,y).
removed
Boolean
True if the sprite has been removed.
restitution
Number
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
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
Rotation in degrees of the visual element (image or animation) Note: this is not the movement's direction, see getDirection.
Default: 0
rotationSpeed
Number
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
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
If no image or animations are set this is color of the placeholder rectangle
touching
Object
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
The sprite's velocity as a vector (x,y) Velocity is speed broken down to its vertical and horizontal components.
visible
Boolean
The sprite's visibility.
Default: true
width
Number
Width of the sprite's current image. If no images or animations are set it's the width of the placeholder rectangle.
Default: 100