Group Class
Look at the Group reference pages before reading these docs.
https://p5play.org/learn/group.html
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 functions and properties of standard arrays such as group.length
Since groups just contain references to sprites, a sprite can be in multiple groups.
sprite.remove() removes the sprite from all the groups
it belongs to. group.removeAll() removes all the sprites from
a group.
The top level group is a p5 instance level variable named
allSprites that contains all the sprites added to the sketch.
Constructor
Group
()
Item Index
Methods
Methods
add
()
Alias for group.push
Its better to use the group Sprite constructor instead.
new group.Sprite() which both creates a group sprite
using
soft inheritance and adds it to the group.
addAni
-
name -
animation
Adds an animation to the sprite. Use this function in the preload p5.js function. You don't need to name the animation if the sprite will only use one animation. See SpriteAnimation for more information.
Parameters:
-
nameStringSpriteAnimation identifier
-
animationSpriteAnimationThe preloaded animation
Example:
sprite.addAni(name, animation); sprite.addAni(name, frame1, frame2, frame3...); sprite.addAni(name, atlas);
addAnis
()
Add multiple animations
applyForce
-
forceVector -
[forceOrigin]
Apply a force that is scaled to the sprite's mass.
Parameters:
-
forceVectorp5.Vector | Arrayforce vector
-
[forceOrigin]p5.Vector | Array optionalforce origin
collided
-
target -
[callback]
Returns true on the first frame that the group no longer overlaps with the target sprite or group.
Returns:
collides
-
target -
[callback]
Returns true on the first frame that the group 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.
colliding
-
target -
[callback]
Returns a truthy value while the group is colliding with the target sprite or group. The value is the number of frames that the group has been colliding with the target.
Returns:
frames
contains
()
Alias for group.includes
cull
-
top|size -
bottom|cb -
[left] -
[right] -
[cb(sprite)]
Remove sprites that go outside the given culling boundary relative to the camera.
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(sprite)]Function optionalThe callback is given the sprite that passed the cull boundary, if no callback is given the sprite is removed by default
Returns:
The number of sprites culled
draw
()
Draws all the sprites in the group.
includes
-
sprite
Check if a sprite is in the group.
Parameters:
-
spriteSprite
Returns:
index of the sprite or -1 if not found
move
()
moveAway
()
moveTo
()
moveTowards
()
orbit
-
amount
EXPERIMENTAL! Subject to change in the future!
Rotates the group around its centroid.
Parameters:
-
amountNumberAmount of rotation
overlapped
-
target -
[callback]
Returns true on the first frame that the group no longer overlaps with the target sprite or group.
Returns:
overlapping
-
target -
[callback]
Returns a truthy value while the group is overlapping with the target sprite or group. The value returned is the number of frames the group has been overlapping with the target.
Returns:
frames
overlaps
-
target -
[callback]
Returns true on the first frame that the group 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.
push
-
sprites
Its better to use the group Sprite constructor instead.
new group.Sprite() which both creates a group sprite
using
soft inheritance and adds it to the group.
Adds a sprite or multiple sprites to the group, whether they were already in the group or not, just like with the Array.push() method. Only sprites can be added to a group.
Parameters:
-
spritesSpriteThe sprite or sprites to be added
Returns:
the new length of the group
remove
-
item
If no input is given all sprites in the group are removed.
If a sprite or index is given, that sprite is removed from the group, but not from the sketch or any other groups it may be in.
Parameters:
-
itemSpriteThe sprite to be removed
Returns:
the removed sprite
removeAll
()
Removes all sprites from the group and destroys the group.
update
()
Updates all the sprites in the group. See sprite.update for more information.
By default, allSprites.update is called after every draw call.
Properties
amount
Number
Depending on the value that the amount property is set to, the group will either add or remove sprites.
animations
SpriteAnimations
Keys are the animation label, values are SpriteAnimation objects.
anis
SpriteAnimations
The group's animations.
autoCull
Boolean
autoCull is a property of the allSprites group only, that controls whether sprites are automatically removed when they are 10,000 pixels away from the camera.
It only needs to be set to false once and then it will remain false for the rest of the sketch, unless changed.
idNum
Number
Each group has a unique id number. Don't change it! Its useful for debugging.
length
Unknown
parent
Number
The parent group's uid number.
Default: undefined
subgroups
Array
Groups can have subgroups, which inherit the properties of their parent groups.
Default: []