Phaser Class: Group

new Group(game, parent, name, useStage)

Phaser Group constructor.

Parameters:

Name	Type	Argument	Default	Description
`game`	Phaser.Game			A reference to the currently running game.
`parent`	*			The parent Group or DisplayObjectContainer that will hold this group, if any.
`name`	string	<optional>	group	A name for this Group. Not used internally but useful for debugging.
`useStage`	boolean	<optional>	false	Should the DisplayObjectContainer this Group creates be added to the World (default, false) or direct to the Stage (true).

Source:

core/Group.js, line 17

Members

alpha

Properties:

Name	Type	Description
`alpha`	number	The alpha value of the Group container.

Source:

core/Group.js, line 1228

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:

core/Group.js, line 1176

exists

Properties:

Name	Type	Description
`exists`	boolean	If exists is true the the Group is updated, otherwise it is skipped.

Default Value:

true

Source:

core/Group.js, line 75

game

Properties:

Name	Type	Description
`game`	Phaser.Game	A reference to the currently running Game.

Source:

core/Group.js, line 32

<readonly> length

Properties:

Name	Type	Description
`length`	number	The number of children in this Group.

Source:

core/Group.js, line 1127

name

Properties:

Name	Type	Description
`name`	string	A name for this Group. Not used internally but useful for debugging.

Source:

core/Group.js, line 37

rotation

Properties:

Name	Type	Description
`rotation`	number	The angle of rotation given in radians.

Source:

core/Group.js, line 1194

scale

Properties:

Name	Type	Description
`scale`	Phaser.Point	Replaces the PIXI.Point with a slightly more flexible one.

Source:

core/Group.js, line 80

<readonly> total

Properties:

Name	Type	Description
`total`	number	The total number of children in this Group, regardless of their alive state.

Source:

core/Group.js, line 1114

<protected> type

Properties:

Name	Type	Description
`type`	number	Internal Phaser Type value.

Source:

core/Group.js, line 69

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:

core/Group.js, line 1212

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:

core/Group.js, line 1140

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:

core/Group.js, line 1158

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:

core/Group.js, line 86

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:

core/Group.js, line 515

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:

core/Group.js, line 115

Returns:

The child that was added to the Group.

Type: *

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:

core/Group.js, line 352

Returns:

The child that was moved.

Type: *

callAll(callback, 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 callback parameter you can add as many extra parameters as you like, which will all be passed to the child.

Parameters:

Name	Type	Argument	Description
`callback`	function		The function that exists on the children that will be called.
`parameter`	*	<repeatable>	Additional parameters that will be passed to the callback.

Source:

core/Group.js, line 611

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:

core/Group.js, line 579

countDead() → {number}

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

Source:

core/Group.js, line 875

Returns:

The number of children flagged as dead. Returns -1 if Group is empty.

Type: number

countLiving() → {number}

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

Source:

core/Group.js, line 841

Returns:

The number of children flagged as alive. Returns -1 if Group is empty.

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:

core/Group.js, line 156

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:

core/Group.js, line 190

destroy()

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

Source:

core/Group.js, line 1003

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:

core/Group.js, line 563

dump(full)

Dumps out a list of Group children and their index positions to the browser console. Useful for group debugging.

Parameters:

Name	Type	Argument	Default	Description
`full`	boolean	<optional>	false	If full the dump will include the entire display list, start from the Stage. Otherwise it will only include this container.

Source:

core/Group.js, line 1022

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)

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').
`checkExists`	boolean	If set only children with exists=true will be passed to the callback, otherwise all children will be passed.

Source:

core/Group.js, line 642

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:

core/Group.js, line 682

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:

core/Group.js, line 716

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:

core/Group.js, line 142

Returns:

The child that was found at the given index.

Type: *

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:

core/Group.js, line 783

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:

core/Group.js, line 812

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:

core/Group.js, line 749

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.

Parameters:

Name	Type	Description
`child`	*	The child to get the index for.

Source:

core/Group.js, line 371

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:

core/Group.js, line 909

Returns:

A random child of this Group.

Type: Any

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:

core/Group.js, line 547

remove(child)

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:

core/Group.js, line 931

removeAll()

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

Source:

core/Group.js, line 950

removeBetween(startIndex, endIndex)

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

Parameters:

Name	Type	Description
`startIndex`	number	The index to start removing children from.
`endIndex`	number	The index to stop removing children from. Must be higher than startIndex and less than the length of the Group.

Source:

core/Group.js, line 975

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:

core/Group.js, line 384

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. 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.
`checkVisible`	boolean	<optional>	false	If set then only children with visible=true will be updated.
`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:

core/Group.js, line 477

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:

core/Group.js, line 415

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:

core/Group.js, line 531

swap(child1, child2) → {boolean}

Swaps the position of two children in this Group.

Parameters:

Name	Type	Description
`child1`	*	The first child to swap.
`child2`	*	The second child to swap.

Source:

core/Group.js, line 224

Returns:

True if the swap was successful, otherwise false.

Type: boolean