Phaser

Class: Group

Phaser. Group

A Group is a container for display objects that allows for fast pooling and object recycling. Groups can be nested within other Groups and have their own local transforms.

new Group(game, parent, name, addToStage, enableBody, physicsBodyType)

Phaser Group constructor.

Parameters:
Name Type Argument Default Description
game Phaser.Game

A reference to the currently running game.
parent Phaser.Group | Phaser.Sprite | null

The parent Group, DisplayObject or DisplayObjectContainer that this Group will be added to. If undefined it will use game.world. If null it won't be added to anything.
name string <optional>
 group

A name for this Group. Not used internally but useful for debugging.
addToStage boolean <optional>
 false

If set to true this Group will be added directly to the Game.Stage instead of Game.World.
enableBody boolean <optional>
 false

If true all Sprites created with Group.create or Group.createMulitple will have a physics body created on them. Change the body type with physicsBodyType.
physicsBodyType number <optional>
 0

If enableBody is true this is the type of physics body that is created on new Sprites. Phaser.Physics.ARCADE, Phaser.Physics.P2, Phaser.Physics.NINJA, etc.
Source:

Members

<static, constant> RETURN_CHILD :number

Type:
  • number
Source:

<static, constant> RETURN_NONE :number

Type:
  • number
Source:

<static, constant> RETURN_TOTAL :number

Type:
  • number
Source:

<static, constant> SORT_ASCENDING :number

Type:
  • number
Source:

<static, constant> SORT_DESCENDING :number

Type:
  • number
Source:

alive

Properties:
Name Type Description
alive boolean

The alive property is useful for Groups that are children of other Groups and need to be included/excluded in checks like forEachAlive.
Default Value:
  • true
Source:

alpha

Properties:
Name Type Description
alpha number

The alpha value of the Group container.
Source:

angle

The angle of rotation of the Group container. This will adjust the Group container itself by modifying its rotation. This will have no impact on the rotation value of its children, but it will update their worldTransform and on-screen position.

Properties:
Name Type Description
angle number

The angle of rotation given in degrees, where 0 degrees = to the right.
Source:

cameraOffset

Properties:
Name Type Description
cameraOffset Phaser.Point

If this object is fixedToCamera then this stores the x/y offset that its drawn at, from the top-left of the camera view.
Source:

cursor

The cursor is a simple way to iterate through the objects in a Group using the Group.next and Group.previous functions. The cursor is set to the first child added to the Group and doesn't change unless you call next, previous or set it directly with Group.cursor.

Properties:
Name Type Description
cursor any

The current display object that the Group cursor is pointing to.
Source:

enableBody

Properties:
Name Type Description
enableBody boolean

If true all Sprites created by, or added to this Group, will have a physics body enabled on them. Change the body type with Group.physicsBodyType.
Source:

enableBodyDebug

Properties:
Name Type Description
enableBodyDebug boolean

If true when a physics body is created (via Group.enableBody) it will create a physics debug object as well. Only works for P2 bodies.
Source:

exists

Properties:
Name Type Description
exists boolean

If exists is true the Group is updated, otherwise it is skipped.
Default Value:
  • true
Source:

fixedToCamera

A Group that is fixed to the camera uses its x/y coordinates as offsets from the top left of the camera. These are stored in Group.cameraOffset. Note that the cameraOffset values are in addition to any parent in the display list. So if this Group was in a Group that has x: 200, then this will be added to the cameraOffset.x

Properties:
Name Type Description
fixedToCamera boolean

Set to true to fix this Group to the Camera at its current world coordinates.
Source:

game

Properties:
Name Type Description
game Phaser.Game

A reference to the currently running Game.
Source:

<readonly> length

Properties:
Name Type Description
length number

The total number of children in this Group, regardless of their exists/alive status.
Source:

name

Properties:
Name Type Description
name string

A name for this Group. Not used internally but useful for debugging.
Source:

physicsBodyType

Properties:
Name Type Description
physicsBodyType number

If Group.enableBody is true this is the type of physics body that is created on new Sprites. Phaser.Physics.ARCADE, Phaser.Physics.P2, Phaser.Physics.NINJA, etc.
Source:

rotation

The angle of rotation of the Group container. This will adjust the Group container itself by modifying its rotation. This will have no impact on the rotation value of its children, but it will update their worldTransform and on-screen position.

Properties:
Name Type Description
rotation number

The angle of rotation given in radians.
Source:

scale

Properties:
Name Type Description
scale Phaser.Point

The scale of the Group container.
Source:

<readonly> total

Properties:
Name Type Description
total number

The total number of children in this Group who have a state of exists = true.
Source:

<protected> type

Properties:
Name Type Description
type number

Internal Phaser Type value.
Source:

visible

Properties:
Name Type Description
visible boolean

The visible state of the Group. Non-visible Groups and all of their children are not rendered.
Source:

x

The x coordinate of the Group container. You can adjust the Group container itself by modifying its coordinates. This will have no impact on the x/y coordinates of its children, but it will update their worldTransform and on-screen position.

Properties:
Name Type Description
x number

The x coordinate of the Group container.
Source:

y

The y coordinate of the Group container. You can adjust the Group container itself by modifying its coordinates. This will have no impact on the x/y coordinates of its children, but it will update their worldTransform and on-screen position.

Properties:
Name Type Description
y number

The y coordinate of the Group container.
Source:

z

Properties:
Name Type Description
z number

The z-depth value of this object within its Group (remember the World is a Group as well). No two objects in a Group can have the same z value.
Source:

Methods

add(child) → {*}

Adds an existing object to this Group. The object can be an instance of Phaser.Sprite, Phaser.Button or any other display object. The child is automatically added to the top of the Group, so renders on-top of everything else within the Group. If you need to control that then see the addAt method.

Parameters:
Name Type Description
child *

An instance of Phaser.Sprite, Phaser.Button or any other display object..
Source:
See:
Returns:

The child that was added to the Group.

Type
*

addAll(property, amount, checkAlive, checkVisible)

Adds the amount to the given property on all children in this Group. Group.addAll('x', 10) will add 10 to the child.x value.

Parameters:
Name Type Description
property string

The property to increment, for example 'body.velocity.x' or 'angle'.
amount number

The amount to increment the property by. If child.x = 10 then addAll('x', 40) would make child.x = 50.
checkAlive boolean

If true the property will only be changed if the child is alive.
checkVisible boolean

If true the property will only be changed if the child is visible.
Source:

addAt(child, index) → {*}

Adds an existing object to this Group. The object can be an instance of Phaser.Sprite, Phaser.Button or any other display object. The child is added to the Group at the location specified by the index value, this allows you to control child ordering.

Parameters:
Name Type Description
child *

An instance of Phaser.Sprite, Phaser.Button or any other display object..
index number

The index within the Group to insert the child to.
Source:
Returns:

The child that was added to the Group.

Type
*

ascendingSortHandler(a, b)

An internal helper function for the sort process.

Parameters:
Name Type Description
a object

The first object being sorted.
b object

The second object being sorted.
Source:

bringToTop(child) → {*}

Brings the given child to the top of this Group so it renders above all other children.

Parameters:
Name Type Description
child *

The child to bring to the top of this Group.
Source:
Returns:

The child that was moved.

Type
*

callAll(method, context, parameter)

Calls a function on all of the children regardless if they are dead or alive (see callAllExists if you need control over that) After the method parameter and context you can add as many extra parameters as you like, which will all be passed to the child.

Parameters:
Name Type Argument Default Description
method string

A string containing the name of the function that will be called. The function must exist on the child.
context string <optional>
 null

A string containing the context under which the method will be executed. Set to null to default to the child.
parameter * <repeatable>

Additional parameters that will be passed to the method.
Source:

callAllExists(callback, existsValue, parameter)

Calls a function on all of the children that have exists=true in this Group. After the existsValue parameter you can add as many parameters as you like, which will all be passed to the child callback.

Parameters:
Name Type Argument Description
callback function

The function that exists on the children that will be called.
existsValue boolean

Only children with exists=existsValue will be called.
parameter * <repeatable>

Additional parameters that will be passed to the callback.
Source:

<protected> callbackFromArray(child, callback, length)

Returns a reference to a function that exists on a child of the Group based on the given callback array.

Parameters:
Name Type Description
child object

The object to inspect.
callback array

The array of function names.
length number

The size of the array (pre-calculated in callAll).
Source:

countDead() → {number}

Call this function to find out how many members of the group are dead.

Source:
Returns:

The number of children flagged as dead.

Type
number

countLiving() → {number}

Call this function to find out how many members of the group are alive.

Source:
Returns:

The number of children flagged as alive.

Type
number

create(x, y, key, frame, exists) → {Phaser.Sprite}

Automatically creates a new Phaser.Sprite object and adds it to the top of this Group. Useful if you don't need to create the Sprite instances before-hand.

Parameters:
Name Type Argument Default Description
x number

The x coordinate to display the newly created Sprite at. The value is in relation to the Group.x point.
y number

The y coordinate to display the newly created Sprite at. The value is in relation to the Group.y point.
key string

The Game.cache key of the image that this Sprite will use.
frame number | string <optional>

If the Sprite image contains multiple frames you can specify which one to use here.
exists boolean <optional>
 true

The default exists state of the Sprite.
Source:
Returns:

The child that was created.

Type
Phaser.Sprite

createMultiple(quantity, key, frame, exists)

Automatically creates multiple Phaser.Sprite objects and adds them to the top of this Group. Useful if you need to quickly generate a pool of identical sprites, such as bullets. By default the sprites will be set to not exist and will be positioned at 0, 0 (relative to the Group.x/y)

Parameters:
Name Type Argument Default Description
quantity number

The number of Sprites to create.
key string

The Game.cache key of the image that this Sprite will use.
frame number | string <optional>

If the Sprite image contains multiple frames you can specify which one to use here.
exists boolean <optional>
 false

The default exists state of the Sprite.
Source:

customSort(sortHandler, context)

This allows you to use your own sort handler function. It will be sent two parameters: the two children involved in the comparison (a and b). It should return -1 if a > b, 1 if a < b or 0 if a === b.

Parameters:
Name Type Description
sortHandler function

Your sort handler function. It will be sent two parameters: the two children involved in the comparison. It must return -1, 1 or 0.
context object

The scope in which the sortHandler is called.
Source:

descendingSortHandler(a, b)

An internal helper function for the sort process.

Parameters:
Name Type Description
a object

The first object being sorted.
b object

The second object being sorted.
Source:

destroy(destroyChildren, soft)

Destroys this Group. Removes all children, then removes the container from the display list and nulls references.

Parameters:
Name Type Argument Default Description
destroyChildren boolean <optional>
 true

Should every child of this Group have its destroy method called?
soft boolean <optional>
 false

A 'soft destroy' (set to true) doesn't remove this Group from its parent or null the game reference. Set to false and it does.
Source:

divideAll(property, amount, checkAlive, checkVisible)

Divides the given property by the amount on all children in this Group. Group.divideAll('x', 2) will half the child.x value.

Parameters:
Name Type Description
property string

The property to divide, for example 'body.velocity.x' or 'angle'.
amount number

The amount to divide the property by. If child.x = 100 then divideAll('x', 2) would make child.x = 50.
checkAlive boolean

If true the property will only be changed if the child is alive.
checkVisible boolean

If true the property will only be changed if the child is visible.
Source:

forEach(callback, callbackContext, checkExists)

Allows you to call your own function on each member of this Group. You must pass the callback and context in which it will run. After the checkExists parameter you can add as many parameters as you like, which will all be passed to the callback along with the child. For example: Group.forEach(awardBonusGold, this, true, 100, 500) Note: Currently this will skip any children which are Groups themselves.

Parameters:
Name Type Argument Default Description
callback function

The function that will be called. Each child of the Group will be passed to it as its first parameter.
callbackContext Object

The context in which the function should be called (usually 'this').
checkExists boolean <optional>
 false

If set only children with exists=true will be passed to the callback, otherwise all children will be passed.
Source:

forEachAlive(callback, callbackContext)

Allows you to call your own function on each alive member of this Group (where child.alive=true). You must pass the callback and context in which it will run. You can add as many parameters as you like, which will all be passed to the callback along with the child. For example: Group.forEachAlive(causeDamage, this, 500)

Parameters:
Name Type Description
callback function

The function that will be called. Each child of the Group will be passed to it as its first parameter.
callbackContext Object

The context in which the function should be called (usually 'this').
Source:

forEachDead(callback, callbackContext)

Allows you to call your own function on each dead member of this Group (where alive=false). You must pass the callback and context in which it will run. You can add as many parameters as you like, which will all be passed to the callback along with the child. For example: Group.forEachDead(bringToLife, this)

Parameters:
Name Type Description
callback function

The function that will be called. Each child of the Group will be passed to it as its first parameter.
callbackContext Object

The context in which the function should be called (usually 'this').
Source:

forEachExists(callback, callbackContext)

Allows you to call your own function on each member of this Group where child.exists=true. You must pass the callback and context in which it will run. You can add as many parameters as you like, which will all be passed to the callback along with the child. For example: Group.forEachExists(causeDamage, this, 500)

Parameters:
Name Type Description
callback function

The function that will be called. Each child of the Group will be passed to it as its first parameter.
callbackContext Object

The context in which the function should be called (usually 'this').
Source:

getAt(index) → {*}

Returns the child found at the given index within this Group.

Parameters:
Name Type Description
index number

The index to return the child from.
Source:
Returns:

The child that was found at the given index. If the index was out of bounds then this will return -1.

Type
*

getBottom() → {Any}

Returns the child at the bottom of this Group. The bottom is the one being displayed (rendered) below every other child.

Source:
Returns:

The child at the bottom of the Group.

Type
Any

getFirstAlive() → {Any}

Call this function to retrieve the first object with alive === true in the group. This is handy for checking if everything has been wiped out, or choosing a squad leader, etc.

Source:
Returns:

The first alive child, or null if none found.

Type
Any

getFirstDead() → {Any}

Call this function to retrieve the first object with alive === false in the group. This is handy for checking if everything has been wiped out, or choosing a squad leader, etc.

Source:
Returns:

The first dead child, or null if none found.

Type
Any

getFirstExists(state) → {Any}

Call this function to retrieve the first object with exists == (the given state) in the Group.

Parameters:
Name Type Description
state boolean

True or false.
Source:
Returns:

The first child, or null if none found.

Type
Any

getIndex(child) → {number}

Get the index position of the given child in this Group. This should always match the childs z property.

Parameters:
Name Type Description
child *

The child to get the index for.
Source:
Returns:

The index of the child or -1 if it's not a member of this Group.

Type
number

getRandom(startIndex, length) → {Any}

Returns a member at random from the group.

Parameters:
Name Type Description
startIndex number

Optional offset off the front of the array. Default value is 0, or the beginning of the array.
length number

Optional restriction on the number of values you want to randomly select from.
Source:
Returns:

A random child of this Group.

Type
Any

getTop() → {Any}

Returns the child at the top of this Group. The top is the one being displayed (rendered) above every other child.

Source:
Returns:

The child at the top of the Group.

Type
Any

iterate(key, value, returnType, callback, callbackContext) → {any}

Iterates over the children of the Group. When a child has a property matching key that equals the given value, it is considered as a match. Matched children can be sent to the optional callback, or simply returned or counted. You can add as many callback parameters as you like, which will all be passed to the callback along with the child, after the callbackContext parameter.

Parameters:
Name Type Argument Default Description
key string

The child property to check, i.e. 'exists', 'alive', 'health'
value any

If child.key === this value it will be considered a match. Note that a strict comparison is used.
returnType number

How to return the data from this method. Either Phaser.Group.RETURN_NONE, Phaser.Group.RETURN_TOTAL or Phaser.Group.RETURN_CHILD.
callback function <optional>
 null

Optional function that will be called on each matching child. Each child of the Group will be passed to it as its first parameter.
callbackContext Object <optional>

The context in which the function should be called (usually 'this').
Source:
Returns:

Returns either a numeric total (if RETURN_TOTAL was specified) or the child object.

Type
any

moveDown(child) → {*}

Moves the given child down one place in this Group unless it's already at the top.

Parameters:
Name Type Description
child *

The child to move down in the Group.
Source:
Returns:

The child that was moved.

Type
*

moveUp(child) → {*}

Moves the given child up one place in this Group unless it's already at the top.

Parameters:
Name Type Description
child *

The child to move up in the Group.
Source:
Returns:

The child that was moved.

Type
*

multiplyAll(property, amount, checkAlive, checkVisible)

Multiplies the given property by the amount on all children in this Group. Group.multiplyAll('x', 2) will x2 the child.x value.

Parameters:
Name Type Description
property string

The property to multiply, for example 'body.velocity.x' or 'angle'.
amount number

The amount to multiply the property by. If child.x = 10 then multiplyAll('x', 2) would make child.x = 20.
checkAlive boolean

If true the property will only be changed if the child is alive.
checkVisible boolean

If true the property will only be changed if the child is visible.
Source:

next() → {*}

Advances the Group cursor to the next object in the Group. If it's at the end of the Group it wraps around to the first object.

Source:
Returns:

The child the cursor now points to.

Type
*

<protected> postUpdate()

The core postUpdate - as called by World.

Source:

<protected> preUpdate()

The core preUpdate - as called by World.

Source:

previous() → {*}

Moves the Group cursor to the previous object in the Group. If it's at the start of the Group it wraps around to the last object.

Source:
Returns:

The child the cursor now points to.

Type
*

remove(child) → {boolean}

Removes the given child from this Group and sets its group property to null.

Parameters:
Name Type Description
child Any

The child to remove.
Source:
Returns:

true if the child was removed from this Group, otherwise false.

Type
boolean

removeAll()

Removes all children from this Group, setting all group properties to null. The Group container remains on the display list.

Source:

removeBetween(startIndex, endIndex)

Removes all children from this Group whos index falls beteen the given startIndex and endIndex values.

Parameters:
Name Type Argument Description
startIndex number

The index to start removing children from.
endIndex number <optional>

The index to stop removing children at. Must be higher than startIndex. If undefined this method will remove all children between startIndex and the end of the Group.
Source:

replace(oldChild, newChild) → {*}

Replaces a child of this Group with the given newChild. The newChild cannot be a member of this Group.

Parameters:
Name Type Description
oldChild *

The child in this Group that will be replaced.
newChild *

The child to be inserted into this Group.
Source:
Returns:

Returns the oldChild that was replaced within this Group.

Type
*

reverse()

Reverses all children in this Group. Note that this does not propagate, only direct children are re-ordered.

Source:

sendToBack(child) → {*}

Sends the given child to the bottom of this Group so it renders below all other children.

Parameters:
Name Type Description
child *

The child to send to the bottom of this Group.
Source:
Returns:

The child that was moved.

Type
*

set(child, key, value, checkAlive, checkVisible, operation)

This function allows you to quickly set a property on a single child of this Group to a new value. The operation parameter controls how the new value is assigned to the property, from simple replacement to addition and multiplication.

Parameters:
Name Type Argument Default Description
child Phaser.Sprite

The child to set the property on.
key string

The property, as a string, to be set. For example: 'body.velocity.x'
value *

The value that will be set.
checkAlive boolean <optional>
 false

If set then the child will only be updated if alive=true.
checkVisible boolean <optional>
 false

If set then the child will only be updated if visible=true.
operation number <optional>
 0

Controls how the value is assigned. A value of 0 replaces the value with the new one. A value of 1 adds it, 2 subtracts it, 3 multiplies it and 4 divides it.
Source:

setAll(key, value, checkAlive, checkVisible, operation)

This function allows you to quickly set the same property across all children of this Group to a new value. This call doesn't descend down children, so if you have a Group inside of this Group, the property will be set on the Group but not its children. If you need that ability please see Group.setAllChildren.

The operation parameter controls how the new value is assigned to the property, from simple replacement to addition and multiplication.

Parameters:
Name Type Argument Default Description
key string

The property, as a string, to be set. For example: 'body.velocity.x'
value *

The value that will be set.
checkAlive boolean <optional>
 false

If set then only children with alive=true will be updated. This includes any Groups that are children.
checkVisible boolean <optional>
 false

If set then only children with visible=true will be updated. This includes any Groups that are children.
operation number <optional>
 0

Controls how the value is assigned. A value of 0 replaces the value with the new one. A value of 1 adds it, 2 subtracts it, 3 multiplies it and 4 divides it.
Source:

setAllChildren(key, value, checkAlive, checkVisible, operation)

This function allows you to quickly set the same property across all children of this Group, and any child Groups, to a new value.

If this Group contains other Groups then the same property is set across their children as well, iterating down until it reaches the bottom. Unlike with Group.setAll the property is NOT set on child Groups itself.

The operation parameter controls how the new value is assigned to the property, from simple replacement to addition and multiplication.

Parameters:
Name Type Argument Default Description
key string

The property, as a string, to be set. For example: 'body.velocity.x'
value *

The value that will be set.
checkAlive boolean <optional>
 false

If set then only children with alive=true will be updated. This includes any Groups that are children.
checkVisible boolean <optional>
 false

If set then only children with visible=true will be updated. This includes any Groups that are children.
operation number <optional>
 0

Controls how the value is assigned. A value of 0 replaces the value with the new one. A value of 1 adds it, 2 subtracts it, 3 multiplies it and 4 divides it.
Source:

setProperty(child, key, value, operation)

Sets the given property to the given value on the child. The operation controls the assignment of the value.

Parameters:
Name Type Argument Default Description
child *

The child to set the property value on.
key array

An array of strings that make up the property that will be set.
value *

The value that will be set.
operation number <optional>
 0

Controls how the value is assigned. A value of 0 replaces the value with the new one. A value of 1 adds it, 2 subtracts it, 3 multiplies it and 4 divides it.
Source:

sort(index, order)

Call this function to sort the group according to a particular value and order. For example to depth sort Sprites for Zelda-style game you might call group.sort('y', Phaser.Group.SORT_ASCENDING) at the bottom of your State.update().

Parameters:
Name Type Argument Default Description
index string <optional>
 'z'

The string name of the property you want to sort on. Defaults to the objects z-depth value.
order number <optional>
 Phaser.Group.SORT_ASCENDING

The Group constant that defines the sort order. Possible values are Phaser.Group.SORT_ASCENDING and Phaser.Group.SORT_DESCENDING.
Source:

subAll(property, amount, checkAlive, checkVisible)

Subtracts the amount from the given property on all children in this Group. Group.subAll('x', 10) will minus 10 from the child.x value.

Parameters:
Name Type Description
property string

The property to decrement, for example 'body.velocity.x' or 'angle'.
amount number

The amount to subtract from the property. If child.x = 50 then subAll('x', 40) would make child.x = 10.
checkAlive boolean

If true the property will only be changed if the child is alive.
checkVisible boolean

If true the property will only be changed if the child is visible.
Source:

swap(child1, child2)

Swaps the position of two children in this Group. Both children must be in this Group. You cannot swap a child with itself, or swap un-parented children, doing so will return false.

Parameters:
Name Type Description
child1 *

The first child to swap.
child2 *

The second child to swap.
Source:

<protected> update()

The core update - as called by World.

Source:

<protected> updateZ()

Internal method that re-applies all of the childrens Z values.

Source:

xy(index, x, y)

Positions the child found at the given index within this Group to the given x and y coordinates.

Parameters:
Name Type Description
index number

The index of the child in the Group to set the position of.
x number

The new x position of the child.
y number

The new y position of the child.
Source: