Constructor

new BodyDebug(game, body, settings)

Draws a P2 Body to a Graphics instance for visual debugging.Needless to say, for every body you enable debug drawing on, you are adding processor and graphical overhead.So use sparingly and rarely (if ever) in production code.

Also be aware that the Debug body is only updated when the Sprite it is connected to changes position. If youmanipulate the sprite in any other way (such as moving it to another Group or bringToTop, etc) then you willneed to manually adjust its BodyDebug as well.

If this object is fixedToCamera then this stores the x/y position offset relative to the top-left of the camera view.If the parent of this Group is also fixedToCamera then the offset here is in addition to that and should typically be disabled.

classType : Object

Any object may be used but it should extend either Sprite or Image and accept the same constructor arguments:when a new object is created it is passed the following parameters to its constructor: (game, x, y, key, frame).

hash :array

The hash array is an array belonging to this Group into which you can add any of its children via Group.addToHash and Group.removeFromHash.

Only children of this Group can be added to and removed from the hash.

This hash is used automatically by Phaser Arcade Physics in order to perform non z-index based destructive sorting.However if you don't use Arcade Physics, or this isn't a physics enabled Group, then you can use the hash to perform your ownsorting and filtering of Group children without touching their z-index (and therefore display draw order)

name : string

This Signal is dispatched whenever a child of this Group emits an onInputDown signal as a resultof having been interacted with by a Pointer. You can bind functions to this Signal instead of toevery child Sprite.

This Signal is sent 2 arguments: A reference to the Sprite that triggered the signal, anda reference to the Pointer that caused it.

This Signal is dispatched whenever a child of this Group emits an onInputOut signal as a resultof having been interacted with by a Pointer. You can bind functions to this Signal instead of toevery child Sprite.

This Signal is sent 2 arguments: A reference to the Sprite that triggered the signal, anda reference to the Pointer that caused it.

This Signal is dispatched whenever a child of this Group emits an onInputOver signal as a resultof having been interacted with by a Pointer. You can bind functions to this Signal instead of toevery child Sprite.

This Signal is sent 2 arguments: A reference to the Sprite that triggered the signal, anda reference to the Pointer that caused it.

This Signal is dispatched whenever a child of this Group emits an onInputUp signal as a resultof having been interacted with by a Pointer. You can bind functions to this Signal instead of toevery child Sprite.

This Signal is sent 3 arguments: A reference to the Sprite that triggered the signal,a reference to the Pointer that caused it, and a boolean value isOver that tells you if the Pointeris still over the Sprite or not.

This method iterates through all children in the Group (regardless if they are visible or exist)and then changes their position so they are arranged in a Grid formation. Children must havethe alignTo method in order to be positioned by this call. All default Phaser Game Objects havethis.

The grid dimensions are determined by the first four arguments. The width and height argumentsrelate to the width and height of the grid respectively.

For example if the Group had 100 children in it:

Group.align(10, 10, 32, 32)

This will align all of the children into a grid formation of 10x10, using 32 pixels pergrid cell. If you want a wider grid, you could do:

Group.align(25, 4, 32, 32)

This will align the children into a grid of 25x4, again using 32 pixels per grid cell.

You can choose to set either the width or height value to -1. Doing so tells the methodto keep on aligning children until there are no children left. For example if this Group had48 children in it, the following:

Group.align(-1, 8, 32, 32)

... will align the children so that there are 8 children vertically (the second argument),and each row will contain 6 sprites, except the last one, which will contain 5 (totaling 48)

You can also do:

Group.align(10, -1, 32, 32)

In this case it will create a grid 10 wide, and as tall as it needs to be in order to fitall of the children in.

The position property allows you to control where in each grid cell the child is positioned.This is a constant and can be one of Phaser.TOP_LEFT (default), Phaser.TOP_CENTER,Phaser.TOP_RIGHT, Phaser.LEFT_CENTER, Phaser.CENTER, Phaser.RIGHT_CENTER,Phaser.BOTTOM_LEFT, Phaser.BOTTOM_CENTER or Phaser.BOTTOM_RIGHT.

The final argument; offset lets you start the alignment from a specific child index.

Parameters

Name

Type

Argument

Default

Description

width

integer

The width of the grid in items (not pixels). Set to -1 for a dynamic width. If -1 then you must set an explicit height value.

height

integer

The height of the grid in items (not pixels). Set to -1 for a dynamic height. If -1 then you must set an explicit width value.

cellWidth

integer

The width of each grid cell, in pixels.

cellHeight

integer

The height of each grid cell, in pixels.

position

integer

<optional>

The position constant. One of Phaser.TOP_LEFT (default), Phaser.TOP_CENTER, Phaser.TOP_RIGHT, Phaser.LEFT_CENTER, Phaser.CENTER, Phaser.RIGHT_CENTER, Phaser.BOTTOM_LEFT, Phaser.BOTTOM_CENTER or Phaser.BOTTOM_RIGHT.

offset

integer

<optional>

0

Optional index to start the alignment from. Defaults to zero, the first child in the Group, but can be set to any valid child index value.

Returns

Aligns this Group within another Game Object, or Rectangle, known as the'container', to one of 9 possible positions.

The container must be a Game Object, or Phaser.Rectangle object. This can include propertiessuch as World.bounds or Camera.view, for aligning Groups within the worldand camera bounds. Or it can include other Sprites, Images, Text objects, BitmapText,TileSprites or Buttons.

Please note that aligning a Group to another Game Object does not make it a child ofthe container. It simply modifies its position coordinates so it aligns with it.

Groups are placed in such a way that their bounds align with thecontainer, taking into consideration rotation and scale of its children.This allows you to neatly align Groups, irrespective of their position value.

The optional offsetX and offsetY arguments allow you to apply extra spacing to the finalaligned position of the Group. For example:

group.alignIn(background, Phaser.BOTTOM_RIGHT, -20, -20)

Would align the group to the bottom-right, but moved 20 pixels in from the corner.Think of the offsets as applying an adjustment to the containers bounds before the alignment takes place.So providing a negative offset will 'shrink' the container bounds by that amount, and providing a positiveone expands it.

Returns

Aligns this Group to the side of another Game Object, or Rectangle, known as the'parent', in one of 11 possible positions.

The parent must be a Game Object, or Phaser.Rectangle object. This can include propertiessuch as World.bounds or Camera.view, for aligning Groups within the worldand camera bounds. Or it can include other Sprites, Images, Text objects, BitmapText,TileSprites or Buttons.

Please note that aligning a Group to another Game Object does not make it a child ofthe parent. It simply modifies its position coordinates so it aligns with it.

Groups are placed in such a way that their bounds align with theparent, taking into consideration rotation and scale of the children.This allows you to neatly align Groups, irrespective of their position value.

The optional offsetX and offsetY arguments allow you to apply extra spacing to the finalaligned position of the Group. For example:

group.alignTo(background, Phaser.BOTTOM_RIGHT, -20, -20)

Would align the group to the bottom-right, but moved 20 pixels in from the corner.Think of the offsets as applying an adjustment to the parents bounds before the alignment takes place.So providing a negative offset will 'shrink' the parent bounds by that amount, and providing a positiveone expands it.

Parameters

Returns

callAll(method, context, args)

Calls a function, specified by name, on all on children.

The function is called for all children regardless if they are dead or alive (see callAllExists for different options).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

Name of the function on the child to call. Deep property lookup is supported.

context

string

<optional>

null

A string containing the context under which the method will be executed. Set to null to default to the child.

This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache Image entry, or an instance of a RenderTexture, BitmapData, Video or PIXI.Texture.

frame

string
|
number

<optional>

If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

exists

boolean

<optional>

true

The default exists state of the Sprite.

index

integer

<optional>

The index within the group to insert the child to. Where 0 is the bottom of the Group.

You can provide an array as the key and / or frame arguments. When you do thisit will create quantity Sprites for every key (and frame) in the arrays.

For example:

createMultiple(25, ['ball', 'carrot'])

In the above code there are 2 keys (ball and carrot) which means that 50 sprites will becreated in total, 25 of each. You can also have the frame as an array:

createMultiple(5, 'bricks', [0, 1, 2, 3])

In the above there is one key (bricks), which is a sprite sheet. The frames array tellsthis method to use frames 0, 1, 2 and 3. So in total it will create 20 sprites, becausethe quantity was set to 5, so that is 5 brick sprites of frame 0, 5 brick sprites withframe 1, and so on.

If you set both the key and frame arguments to be arrays then understand it will createa total quantity of sprites equal to the size of both arrays times each other. I.e.:

createMultiple(20, ['diamonds', 'balls'], [0, 1, 2])

The above will create 20 'diamonds' of frame 0, 20 with frame 1 and 20 with frame 2.It will then create 20 'balls' of frame 0, 20 with frame 1 and 20 with frame 2.In total it will have created 120 sprites.

By default the Sprites will have their exists property set to false, and they will bepositioned at 0x0, relative to the Group.x / y values.

If Group.enableBody is set, then a physics body will be created on the objects, so long as one does not already exist.

If Group.inputEnableChildren is set, then an Input Handler will be created on the objects, so long as one does not already exist.

Parameters

Name

Type

Argument

Default

Description

quantity

integer

The number of Sprites to create.

key

string
|
array

The Cache key of the image that the Sprites will use. Or an Array of keys. See the description for details on how the quantity applies when arrays are used.

frame

integer
|
string
|
array

<optional>

0

If the Sprite image contains multiple frames you can specify which one to use here. Or an Array of frames. See the description for details on how the quantity applies when arrays are used.

getAll(property, value, startIndex, endIndex) → {any}

You can optionally specify a matching criteria using the property and value arguments.

For example: getAll('exists', true) would return only children that have their exists property set.

Optionally you can specify a start and end index. For example if this Group had 100 children,and you set startIndex to 0 and endIndex to 50, it would return a random child from onlythe first 50 children in the Group.

Parameters

Name

Type

Argument

Default

Description

property

string

<optional>

An optional property to test against the value argument.

value

any

<optional>

If property is set then Child.property must strictly equal this value to be included in the results.

getClosestTo(object, callback, callbackContext) → {any}

Get the closest child to given Object, with optional callback to filter children.

This can be a Sprite, Group, Image or any object with public x and y properties.

'close' is determined by the distance from the objects x and y properties compared to the childs x and y properties.

You can use the optional callback argument to apply your own filter to the distance checks.If the child is closer then the previous child, it will be sent to callback as the first argument,with the distance as the second. The callback should return true if it passes yourfiltering criteria, otherwise it should return false.

Parameters

Name

Type

Argument

Description

object

any

The object used to determine the distance. This can be a Sprite, Group, Image or any object with public x and y properties.

callback

function

<optional>

The function that each child will be evaluated against. Each child of the group will be passed to it as its first parameter, with the distance as the second. It should return true if the child passes the matching criteria.

This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache Image entry, or an instance of a RenderTexture, BitmapData, Video or PIXI.Texture.

frame

string
|
number

<optional>

If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache Image entry, or an instance of a RenderTexture, BitmapData, Video or PIXI.Texture.

frame

string
|
number

<optional>

If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache Image entry, or an instance of a RenderTexture, BitmapData, Video or PIXI.Texture.

frame

string
|
number

<optional>

If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

getFurthestFrom(object, callback, callbackContext) → {any}

Get the child furthest away from the given Object, with optional callback to filter children.

This can be a Sprite, Group, Image or any object with public x and y properties.

'furthest away' is determined by the distance from the objects x and y properties compared to the childs x and y properties.

You can use the optional callback argument to apply your own filter to the distance checks.If the child is closer then the previous child, it will be sent to callback as the first argument,with the distance as the second. The callback should return true if it passes yourfiltering criteria, otherwise it should return false.

Parameters

Name

Type

Argument

Description

object

any

The object used to determine the distance. This can be a Sprite, Group, Image or any object with public x and y properties.

callback

function

<optional>

The function that each child will be evaluated against. Each child of the group will be passed to it as its first parameter, with the distance as the second. It should return true if the child passes the matching criteria.

callbackContext

object

<optional>

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

Returns

any
-

The child furthest from the given object, or null if no child was found.

Returns

getRandomExists(startIndex, endIndex) → {any}

Returns a random child from the Group that has exists set to true.

Optionally you can specify a start and end index. For example if this Group had 100 children,and you set startIndex to 0 and endIndex to 50, it would return a random child from onlythe first 50 children in the Group.

This is the image or texture used by the Sprite during rendering. It can be a string which is a reference to the Cache Image entry, or an instance of a RenderTexture, BitmapData, Video or PIXI.Texture.

frame

string
|
number

<optional>

If this Sprite is using part of a sprite sheet or texture atlas you can specify the exact frame to use by giving a string or numeric index.

Returns

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

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

any

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

integer

<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.

force

boolean

<optional>

false

If force is true then the property will be set on the child regardless if it already exists or not. If false and the property doesn't exist, nothing will be set.

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 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

any

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

integer

<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.

force

boolean

<optional>

false

If force is true then the property will be set on the child regardless if it already exists or not. If false and the property doesn't exist, nothing will be set.

Returns

sort(key, order)

Sort the children in the group according to a particular key and ordering.

Call this function to sort the group according to a particular key 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().

Internally this uses a standard JavaScript Array sort, so everything that applies there also applies here, includingalphabetical sorting, mixing strings and numbers, and Unicode sorting. See MDN for more details.

Parameters

Name

Type

Argument

Default

Description

key

string

<optional>

'z'

The name of the property to sort on. Defaults to the objects z-depth value.