Group
In p5play groups are collections of sprites with similar behavior. For example a group may contain all the coin sprites that the player can collect.
Group extends Array. You can use them in for loops just like arrays since they inherit all the properties of standard arrays such as group.length
Since groups contain only references, a sprite can be in multiple groups and deleting a group doesn't affect the sprites themselves.
Sprite.remove() removes the sprite from all the groups it belongs to.
Table of Contents
-
Methods
- _groupCollide(typetargetcallback)
- _rebuildQuadtree()
- add(s)
- addAnimation(labelanimation)
- addImage(labelimg)
- bounce(targetcallback)
- clear()
- collide(targetcallback)
- contains(sprite)
- cull(top|sizebottom|cbleftrightcb)
- displace(targetcallback)
- draw()
- get(i)
- indexOf()
- maxDepth()
- minDepth()
- overlap(targetcallback)
- remove(item)
- removeSprites()
- size()
- toArray()
- Properties
Constructor
Group
()
Methods
_groupCollide
-
type -
target -
callback
Collide each member of group against the target using the given collision type. Return true if any collision occurred. Internal use
Parameters:
Returns:
True if any collision/overlap occurred
_rebuildQuadtree
()
Not for p5play users! This method is used to rebuild quad tree and should only be called on the allSprites group.
add
-
s
Adds a sprite to the group. Returns true if the sprite was added because it was not already in the group.
Parameters:
-
sSpriteThe sprite to be added
addAnimation
-
label -
animation
Adds an animation to the group. 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 group but not necessarily displayed until Sprite.changeAnimation(label) is called.
Usage:
- group.addAnimation(label, animation);
Alternative usages. See SpriteAnimation for more information on file sequences:
- group.addAnimation(label, firstFrame, lastFrame);
- group.addAnimation(label, frame1, frame2, frame3...);
Parameters:
-
labelStringSpriteAnimation identifier
-
animationSpriteAnimationThe preloaded animation
addImage
-
label -
img
Adds an image to the Group. 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 Group but not necessarily displayed until Sprite.changeAnimation(label) is called
Usages:
- group.addImage(label, image);
- group.addImage(image);
If only an image is passed no label is specified
Parameters:
-
labelString | p5.ImageLabel or image
-
[img]p5.Image optionalImage
bounce
-
target -
callback
Checks if the the group is overlapping another group or sprite. 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 overlap occours. The function will be called for each single sprite overlapping. The parameter of the function are respectively the member of the current group and the other sprite passed as parameter.
Parameters:
Returns:
True if overlapping
Example:
group.bounce(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}clear
()
Removes all references to the group. Does not remove the actual sprites.
collide
-
target -
callback
Checks if the the group is overlapping another group or sprite. If the overlap is positive the sprites in the group will be displaced by the colliding one to the closest non-overlapping positions.
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. The function will be called for each single sprite overlapping. The parameter of the function are respectively the member of the current group and the other sprite passed as parameter.
Parameters:
Returns:
True if overlapping
Example:
group.collide(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}contains
-
sprite
Checks if the group contains a sprite.
Parameters:
-
spriteSpriteThe sprite to search
Returns:
Index or -1 if not found
cull
-
top|size -
bottom|cb -
left -
right -
cb
Remove sprites that go outside the culling boundary
Parameters:
-
top|sizeNumberThe distance that sprites can move below the p5.js canvas before they are removed. OR The distance sprites can travel outside the screen on all sides before they get removed.
-
bottom|cbNumberThe distance that sprites can move below the p5.js canvas before they are removed.
-
[left]Number optionalThe distance that sprites can move beyond the left side of the p5.js canvas before they are removed.
-
[right]Number optionalThe distance that sprites can move beyond the right side of the p5.js canvas before they are removed.
-
[cb]Function optionalThe function to be called if any sprites in the group are culled
displace
-
target -
callback
Checks if the the group is overlapping another group or sprite. If the overlap is positive the sprites in the group will displace the colliding ones to the closest non-overlapping positions.
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 occurs. The function will be called for each single sprite overlapping. The parameter of the function are respectively the member of the current group and the other sprite passed as parameter.
Parameters:
Returns:
True if overlapping
Example:
group.displace(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}draw
()
Draws all the sprites in the group.
get
-
i
Gets the member at index i.
Parameters:
-
iNumberThe index of the object to retrieve
indexOf
()
Same as Group.contains
maxDepth
()
Number
Returns the highest depth in a group
Returns:
The depth of the sprite drawn on the top
minDepth
()
Number
Returns the lowest depth in a group
Returns:
The depth of the sprite drawn on the bottom
overlap
-
target -
callback
Checks if the the group is overlapping another group or sprite. 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 occurs. The function will be called for each single sprite overlapping. The parameter of the function are respectively the member of the current group and the other sprite passed as parameter.
Parameters:
Returns:
True if overlapping
Example:
group.overlap(otherSprite, explosion);
function explosion(spriteA, spriteB) {
spriteA.remove();
spriteB.score++;
}remove
-
item
Removes a sprite from the group. Does not remove the actual sprite, only the affiliation (reference).
Parameters:
-
itemSpriteThe sprite to be removed
Returns:
True if sprite was found and removed
removeSprites
()
Removes all the sprites in the group from the scene.
size
()
Same as group.length
toArray
()
This method is deprecated, don't use it! This method is included for backwards compatibility only. Deprecated since v2.
It used to return a copy of the group as standard array but now that Group extends Array you can use groups in for loops just like arrays without using this method.
Properties
animations
Object
Keys are the animation label, values are SpriteAnimation objects.