Class: Group

Phaser.GameObjects. Group

A Group is a way for you to create, manipulate, or recycle similar Game Objects.

Group membership is non-exclusive. A Game Object can belong to several groups, one group, or none.

Groups themselves aren't displayable, and can't be positioned, rotated, scaled, or hidden.


new Group(scene [, children] [, config])

Parameters:
Name Type Argument Description
scene Phaser.Scene

The scene this group belongs to.

children Array.<Phaser.GameObjects.GameObject> | Phaser.Types.GameObjects.Group.GroupConfig | Phaser.Types.GameObjects.Group.GroupCreateConfig <optional>

Game Objects to add to this group; or the config argument.

config Phaser.Types.GameObjects.Group.GroupConfig | Phaser.Types.GameObjects.Group.GroupCreateConfig <optional>

Settings for this group. If key is set, Phaser.GameObjects.Group#createMultiple is also called with these settings.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 17)
See:

Members


active :boolean

Whether this group runs its Phaser.GameObjects.Group#preUpdate method (which may update any members).

Type:
  • boolean
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 116)

children :Phaser.Structs.Set.<Phaser.GameObjects.GameObject>

Members of this group.

Type:
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 87)

classType :Phaser.Types.GameObjects.Group.GroupClassTypeConstructor

The class to create new group members from.

Type:
Since: 3.0.0
Default Value:
  • Phaser.GameObjects.Sprite
Source: src/gameobjects/group/Group.js (Line 106)

<nullable> createCallback :Phaser.Types.GameObjects.Group.GroupCallback

A function to be called when adding or creating group members.

Type:
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 168)

<nullable> createMultipleCallback :Phaser.Types.GameObjects.Group.GroupMultipleCreateCallback

A function to be called when creating several group members at once.

Type:
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 186)

defaultFrame :string|integer

A default texture frame to use when creating new group members.

Type:
  • string | integer
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 148)

defaultKey :string

A default texture key to use when creating new group members.

This is used in Phaser.GameObjects.Group#create but not in Phaser.GameObjects.Group#createMultiple.

Type:
  • string
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 136)

isParent :boolean

A flag identifying this object as a group.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • true
Source: src/gameobjects/group/Group.js (Line 96)

maxSize :integer

The maximum size of this group, if used as a pool. -1 is no limit.

Type:
  • integer
Since: 3.0.0
Default Value:
  • -1
Source: src/gameobjects/group/Group.js (Line 126)

<nullable> removeCallback :Phaser.Types.GameObjects.Group.GroupCallback

A function to be called when removing group members.

Type:
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 177)

runChildUpdate :boolean

Whether to call the update method of any members.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/gameobjects/group/Group.js (Line 157)
See:

scene :Phaser.Scene

This scene this group belongs to.

Type:
Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 78)

Methods


add(child [, addToScene])

Adds a Game Object to this group.

Calls Phaser.GameObjects.Group#createCallback.

Parameters:
Name Type Argument Default Description
child Phaser.GameObjects.GameObject

The Game Object to add.

addToScene boolean <optional>
false

Also add the Game Object to the scene.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 456)
Returns:

This Group object.

Type
Phaser.GameObjects.Group

addMultiple(children [, addToScene])

Adds several Game Objects to this group.

Calls Phaser.GameObjects.Group#createCallback.

Parameters:
Name Type Argument Default Description
children Array.<Phaser.GameObjects.GameObject>

The Game Objects to add.

addToScene boolean <optional>
false

Also add the Game Objects to the scene.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 500)
Returns:

This group.

Type
Phaser.GameObjects.Group

clear( [removeFromScene] [, destroyChild])

Removes all members of this Group and optionally removes them from the Scene and / or destroys them.

Does not call Phaser.GameObjects.Group#removeCallback.

Parameters:
Name Type Argument Default Description
removeFromScene boolean <optional>
false

Optionally remove each Group member from the Scene.

destroyChild boolean <optional>
false

Optionally call destroy on the removed Group members.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 578)
Returns:

This group.

Type
Phaser.GameObjects.Group

contains(child)

Tests if a Game Object is a member of this group.

Parameters:
Name Type Description
child Phaser.GameObjects.GameObject

A Game Object.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 624)
Returns:

True if the Game Object is a member of this group.

Type
boolean

countActive( [value])

Counts the number of active (or inactive) group members.

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

Count active (true) or inactive (false) group members.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 981)
Returns:

The number of group members with an active state matching the active argument.

Type
integer

create( [x] [, y] [, key] [, frame] [, visible] [, active])

Creates a new Game Object and adds it to this group, unless the group is full.

Calls Phaser.GameObjects.Group#createCallback.

Parameters:
Name Type Argument Default Description
x number <optional>
0

The horizontal position of the new Game Object in the world.

y number <optional>
0

The vertical position of the new Game Object in the world.

key string <optional>
defaultKey

The texture key of the new Game Object.

frame string | integer <optional>
defaultFrame

The texture frame of the new Game Object.

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of the new Game Object.

active boolean <optional>
true

The Phaser.GameObjects.GameObject#active state of the new Game Object.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 201)
Returns:

The new Game Object (usually a Sprite, etc.).

Type
any

createFromConfig(options)

Parameters:
Name Type Description
options Phaser.Types.GameObjects.Group.GroupCreateConfig

Creation settings.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 291)
Returns:

The newly created Game Objects.

Type
Array.<any>

createMultiple(config)

Creates several Game Objects and adds them to this group.

If the group becomes Phaser.GameObjects.Group#isFull, no further Game Objects are created.

Calls Phaser.GameObjects.Group#createMultipleCallback and Phaser.GameObjects.Group#createCallback.

Parameters:
Name Type Description
config Phaser.Types.GameObjects.Group.GroupCreateConfig | Array.<Phaser.Types.GameObjects.Group.GroupCreateConfig>

Creation settings. This can be a single configuration object or an array of such objects, which will be applied in turn.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 250)
Returns:

The newly created Game Objects.

Type
Array.<any>

destroy( [destroyChildren])

Empties this group and removes it from the Scene.

Does not call Phaser.GameObjects.Group#removeCallback.

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

Also Phaser.GameObjects.GameObject#destroy each group member.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1105)

get( [x] [, y] [, key] [, frame] [, visible])

Scans the group for the first member that has an Phaser.GameObjects.GameObject#active state set to false, assigns x and y, and returns the member.

If no inactive member is found and the group isn't full then it will create a new Game Object using x, y, key, frame, and visible. The new Game Object will have its active state set to true. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 870)
Returns:

The first inactive group member, or a newly created member, or null.

Type
any

getChildren()

All members of the group.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 639)
Returns:

The group members.

Type
Array.<Phaser.GameObjects.GameObject>

getFirst( [state] [, createIfNull] [, x] [, y] [, key] [, frame] [, visible])

Scans the Group, from top to bottom, for the first member that has an Phaser.GameObjects.GameObject#active state matching the argument, assigns x and y, and returns the member.

If no matching member is found and createIfNull is true and the group isn't full then it will create a new Game Object using x, y, key, frame, and visible. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
state boolean <optional>
false

The Phaser.GameObjects.GameObject#active value to match.

createIfNull boolean <optional>
false

Create a new Game Object if no matching members are found, using the following arguments.

x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 665)
Returns:

The first matching group member, or a newly created member, or null.

Type
any

getFirstAlive( [createIfNull] [, x] [, y] [, key] [, frame] [, visible])

Scans the group for the first member that has an Phaser.GameObjects.GameObject#active state set to true, assigns x and y, and returns the member.

If no active member is found and createIfNull is true and the group isn't full then it will create a new one using x, y, key, frame, and visible. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
createIfNull boolean <optional>
false

Create a new Game Object if no matching members are found, using the following arguments.

x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 894)
Returns:

The first active group member, or a newly created member, or null.

Type
any

getFirstDead( [createIfNull] [, x] [, y] [, key] [, frame] [, visible])

Scans the group for the first member that has an Phaser.GameObjects.GameObject#active state set to false, assigns x and y, and returns the member.

If no inactive member is found and createIfNull is true and the group isn't full then it will create a new one using x, y, key, frame, and visible. The new Game Object will have an active state set to true. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
createIfNull boolean <optional>
false

Create a new Game Object if no matching members are found, using the following arguments.

x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 918)
Returns:

The first inactive group member, or a newly created member, or null.

Type
any

getFirstNth(nth [, state] [, createIfNull] [, x] [, y] [, key] [, frame] [, visible])

Scans the Group, from top to bottom, for the nth member that has an Phaser.GameObjects.GameObject#active state matching the argument, assigns x and y, and returns the member.

If no matching member is found and createIfNull is true and the group isn't full then it will create a new Game Object using x, y, key, frame, and visible. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
nth integer

The nth matching Group member to search for.

state boolean <optional>
false

The Phaser.GameObjects.GameObject#active value to match.

createIfNull boolean <optional>
false

Create a new Game Object if no matching members are found, using the following arguments.

x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.6.0
Source: src/gameobjects/group/Group.js (Line 690)
Returns:

The first matching group member, or a newly created member, or null.

Type
any

getLast( [state] [, createIfNull] [, x] [, y] [, key] [, frame] [, visible])

Scans the Group for the last member that has an Phaser.GameObjects.GameObject#active state matching the argument, assigns x and y, and returns the member.

If no matching member is found and createIfNull is true and the group isn't full then it will create a new Game Object using x, y, key, frame, and visible. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
state boolean <optional>
false

The Phaser.GameObjects.GameObject#active value to match.

createIfNull boolean <optional>
false

Create a new Game Object if no matching members are found, using the following arguments.

x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.6.0
Source: src/gameobjects/group/Group.js (Line 716)
Returns:

The first matching group member, or a newly created member, or null.

Type
any

getLastNth(nth [, state] [, createIfNull] [, x] [, y] [, key] [, frame] [, visible])

Scans the Group for the last nth member that has an Phaser.GameObjects.GameObject#active state matching the argument, assigns x and y, and returns the member.

If no matching member is found and createIfNull is true and the group isn't full then it will create a new Game Object using x, y, key, frame, and visible. Unless a new member is created, key, frame, and visible are ignored.

Parameters:
Name Type Argument Default Description
nth integer

The nth matching Group member to search for.

state boolean <optional>
false

The Phaser.GameObjects.GameObject#active value to match.

createIfNull boolean <optional>
false

Create a new Game Object if no matching members are found, using the following arguments.

x number <optional>

The horizontal position of the Game Object in the world.

y number <optional>

The vertical position of the Game Object in the world.

key string <optional>
defaultKey

The texture key assigned to a new Game Object (if one is created).

frame string | integer <optional>
defaultFrame

A texture frame assigned to a new Game Object (if one is created).

visible boolean <optional>
true

The Phaser.GameObjects.Components.Visible#visible state of a new Game Object (if one is created).

Since: 3.6.0
Source: src/gameobjects/group/Group.js (Line 741)
Returns:

The first matching group member, or a newly created member, or null.

Type
any

getLength()

The number of members of the group.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 652)
Returns:
Type
integer

getTotalFree()

The difference of Phaser.GameObjects.Group#maxSize and the number of active group members.

This represents the number of group members that could be created or reactivated before reaching the size limit.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1021)
Returns:

maxSize minus the number of active group numbers; or a large number (if maxSize is -1).

Type
integer

getTotalUsed()

Counts the number of in-use (active) group members.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1008)
Returns:

The number of group members with an active state of true.

Type
integer

isFull()

Whether this group's size at its maximum.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 961)
Returns:

True if the number of members equals Phaser.GameObjects.Group#maxSize.

Type
boolean

kill(gameObject)

Deactivates a member of this group.

Parameters:
Name Type Description
gameObject Phaser.GameObjects.GameObject

A member of this group.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1057)

killAndHide(gameObject)

Deactivates and hides a member of this group.

Parameters:
Name Type Description
gameObject Phaser.GameObjects.GameObject

A member of this group.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1073)

playAnimation(key [, startFrame])

Plays an animation for all members of this group.

Parameters:
Name Type Argument Default Description
key string

The string-based key of the animation to play.

startFrame string <optional>
0

Optionally start the animation playing from this frame index.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 943)
Returns:

This Group object.

Type
Phaser.GameObjects.Group

preUpdate(time, delta)

Updates any group members, if Phaser.GameObjects.Group#runChildUpdate is enabled.

Parameters:
Name Type Description
time number

The current timestamp.

delta number

The delta time elapsed since the last frame.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 426)

remove(child [, removeFromScene] [, destroyChild])

Removes a member of this Group and optionally removes it from the Scene and / or destroys it.

Calls Phaser.GameObjects.Group#removeCallback.

Parameters:
Name Type Argument Default Description
child Phaser.GameObjects.GameObject

The Game Object to remove.

removeFromScene boolean <optional>
false

Optionally remove the Group member from the Scene it belongs to.

destroyChild boolean <optional>
false

Optionally call destroy on the removed Group member.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 528)
Returns:

This Group object.

Type
Phaser.GameObjects.Group

setDepth(value, step)

Sets the depth of each group member.

Parameters:
Name Type Description
value number

The amount to set the property to.

step number

This is added to the value amount, multiplied by the iteration counter.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1039)
Returns:

This Group object.

Type
Phaser.GameObjects.Group

toggleVisible()

Toggles (flips) the visible state of each member of this group.

Since: 3.0.0
Source: src/gameobjects/group/Group.js (Line 1090)
Returns:

This Group object.

Type
Phaser.GameObjects.Group