Mirrors/phaser
2
0
Fork 0
mirror of https://github.com/photonstorm/phaser synced 2024-11-24 05:33:35 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #3554 from samme/docs/group

Browse source 
Add descriptions for Phaser.GameObjects.Group
This commit is contained in:
Richard Davey 2018-04-13 12:12:01 +01:00 committed by GitHub
commit 8000f9298d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 211 additions and 160 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

365
src/gameobjects/group/Group.js
View file

@ -15,79 +15,100 @@ var Sprite = require('../sprite/Sprite');
/**
* @callback GroupCallback
*
* @param {Phaser.GameObjects.GameObject} item - [description]
* @param {Phaser.GameObjects.GameObject} item - A group member
*/
/**
* @callback GroupMultipleCreateCallback
*
* @param {Phaser.GameObjects.GameObject[]} items - [description]
* @param {Phaser.GameObjects.GameObject[]} items - The newly created group members
*/
/**
* @typedef {object} GroupConfig
*
* @property {object} [classType=Sprite] - [description]
* @property {boolean} [active=true] - [description]
* @property {number} [maxSize=-1] - [description]
* @property {?string} [defaultKey=null] - [description]
* @property {?(string|integer)} [defaultFrame=null] - [description]
* @property {boolean} [runChildUpdate=false] - [description]
* @property {?GroupCallback} [createCallback=null] - [description]
* @property {?GroupCallback} [removeCallback=null] - [description]
* @property {?GroupMultipleCreateCallback} [createMultipleCallback=null] - [description]
* @property {?object} [classType=Sprite] - Sets {@link Phaser.GameObjects.Group#classType}.
* @property {?boolean} [active=true] - Sets {@link Phaser.GameObjects.Group#active}.
* @property {?number} [maxSize=-1] - Sets {@link Phaser.GameObjects.Group#maxSize}.
* @property {?string} [defaultKey=null] - Sets {@link Phaser.GameObjects.Group#defaultKey}.
* @property {?(string|integer)} [defaultFrame=null] - Sets {@link Phaser.GameObjects.Group#defaultFrame}.
* @property {?boolean} [runChildUpdate=false] - Sets {@link Phaser.GameObjects.Group#runChildUpdate}.
* @property {?GroupCallback} [createCallback=null] - Sets {@link Phaser.GameObjects.Group#createCallback}.
* @property {?GroupCallback} [removeCallback=null] - Sets {@link Phaser.GameObjects.Group#removeCallback}.
* @property {?GroupMultipleCreateCallback} [createMultipleCallback=null] - Sets {@link Phaser.GameObjects.Group#createMultipleCallback}.
*/
/**
* @typedef {object} GroupCreateConfig
*
* @property {object} [classType] - [description]
* @property {string} [key] - [description]
* @property {?(string|integer)} [frame=null] - [description]
* @property {boolean} [visible=true] - [description]
* @property {boolean} [active=true] - [description]
* @property {number} [repeat=0] - [description]
* @property {boolean} [randomKey=false] - [description]
* @property {boolean} [randomFrame=false] - [description]
* @property {boolean} [yoyo=false] - [description]
* @property {number} [frameQuantity=1] - [description]
* @property {number} [max=1] - [description]
* @property {object} [setXY] - [description]
* @property {number} [setXY.x=0] - [description]
* @property {number} [setXY.y=0] - [description]
* @property {number} [setXY.stepX=0] - [description]
* @property {number} [setXY.stepY=0] - [description]
* @property {object} [setRotation] - [description]
* @property {number} [setRotation.value=0] - [description]
* @property {number} [setRotation.step=0] - [description]
* @property {object} [setScale] - [description]
* @property {number} [setScale.x=0] - [description]
* @property {number} [setScale.y=0] - [description]
* @property {number} [setScale.stepX=0] - [description]
* @property {number} [setScale.stepY=0] - [description]
* @property {object} [setAlpha] - [description]
* @property {number} [setAlpha.value=0] - [description]
* @property {number} [setAlpha.step=0] - [description]
* @property {*} [hitArea] - [description]
* @property {HitAreaCallback} [hitAreaCallback] - [description]
* @property {(false|GridAlignConfig)} [gridAlign=false] - [description]
* The total number of objects created will be
*
* key.length * frame.length * frameQuantity * (yoyo ? 2 : 1) * (1 + repeat)
*
* In the simplest case, 1 + `repeat` objects will be created.
*
* If `max` is positive, then the total created will not exceed `max`.
*
* `key` is required.
*
* @property {?object} [classType] - The class of each new Game Object.
* @property {string} [key] - The texture key of each new Game Object.
* @property {?(string|integer)} [frame=null] - The texture frame of each new Game Object.
* @property {?boolean} [visible=true] - The visible state of each new Game Object.
* @property {?boolean} [active=true] - The active state of each new Game Object.
* @property {?number} [repeat=0] - The number of times each `key` × `frame` combination will be *repeated* (after the first combination).
* @property {?boolean} [randomKey=false] - Select a `key` at random.
* @property {?boolean} [randomFrame=false] - Select a `frame` at random.
* @property {?boolean} [yoyo=false] - Select keys and frames by moving forward then backward through `key` and `frame`.
* @property {?number} [frameQuantity=1] - The number of times each `frame` should be combined with one `key`.
* @property {?number} [max=0] - The maximum number of new Game Objects to create. 0 is no maximum.
* @property {?object} [setXY]
* @property {?number} [setXY.x=0] - The horizontal position of each new Game Object.
* @property {?number} [setXY.y=0] - The vertical position of each new Game Object.
* @property {?number} [setXY.stepX=0] - Increment each Game Object's horizontal position from the previous by this amount, starting from `setXY.x`.
* @property {?number} [setXY.stepY=0] - Increment each Game Object's vertical position from the previous by this amount, starting from `setXY.y`.
* @property {?object} [setRotation]
* @property {?number} [setRotation.value=0] - Rotation of each new Game Object.
* @property {?number} [setRotation.step=0] - Increment each Game Object's rotation from the previous by this amount, starting at `setRotation.value`.
* @property {?object} [setScale]
* @property {?number} [setScale.x=0] - The horizontal scale of each new Game Object.
* @property {?number} [setScale.y=0] - The vertical scale of each new Game Object.
* @property {?number} [setScale.stepX=0] - Increment each Game Object's horizontal scale from the previous by this amount, starting from `setScale.x`.
* @property {?number} [setScale.stepY=0] - Increment each Game object's vertical scale from the previous by this amount, starting from `setScale.y`.
* @property {?object} [setAlpha]
* @property {?number} [setAlpha.value=0] - The alpha value of each new Game Object.
* @property {?number} [setAlpha.step=0] - Increment each Game Object's alpha from the previous by this amount, starting from `setAlpha.value`.
* @property {?*} [hitArea] - A geometric shape that defines the hit area for the Game Object.
* @property {?HitAreaCallback} [hitAreaCallback] - A callback to be invoked when the Game Object is interacted with.
* @property {?(false|GridAlignConfig)} [gridAlign=false] - Align the new Game Objects in a grid using these settings.
*
* @see Phaser.Actions.GridAlign
* @see Phaser.Actions.SetAlpha
* @see Phaser.Actions.SetHitArea
* @see Phaser.Actions.SetRotation
* @see Phaser.Actions.SetScale
* @see Phaser.Actions.SetXY
* @see Phaser.GameObjects.Group#createFromConfig
* @see Phaser.Utils.Array.Range
*/
/**
* @classdesc
* [description]
* @classdesc A Group is a way for you to create, manipulate, or recycle similar Game Objects.
*
* children can be either an array of children, or a config object
* config can be either a config object, or undefined if passed as the children argument instead
* 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.
*
* @class Group
* @memberOf Phaser.GameObjects
* @constructor
* @since 3.0.0
* @param {Phaser.Scene} scene - The scene this group belongs to.
* @param {?(Phaser.GameObjects.GameObject[]|GroupConfig)} [children] - Game objects to add to this group; or the `config` argument.
* @param {GroupConfig} [config] - Settings for this group.
*
* @param {Phaser.Scene} scene - [description]
* @param {?(Phaser.GameObjects.GameObject[]|GroupConfig)} children - [description]
* @param {GroupConfig} [config] - [description]
* @see Phaser.Physics.Arcade.Group
* @see Phaser.Physics.Arcade.StaticGroup
*/
var Group = new Class({
@ -102,7 +123,7 @@ var Group = new Class({
}
/**
* [description]
* This scene this group belongs to.
*
* @name Phaser.GameObjects.Group#scene
* @type {Phaser.Scene}
@ -111,7 +132,7 @@ var Group = new Class({
this.scene = scene;
/**
* [description]
* Members of this group.
*
* @name Phaser.GameObjects.Group#children
* @type {Phaser.Structs.Set.<Phaser.GameObjects.GameObject>}
@ -120,7 +141,7 @@ var Group = new Class({
this.children = new Set(children);
/**
* [description]
* A flag identifying this object as a group.
*
* @name Phaser.GameObjects.Group#isParent
* @type {boolean}
@ -130,16 +151,18 @@ var Group = new Class({
this.isParent = true;
/**
* [description]
* The class to create new group members from.
*
* @name Phaser.GameObjects.Group#classType
* @type {object}
* @since 3.0.0
* @default Phaser.GameObjects.Sprite
*/
this.classType = GetFastValue(config, 'classType', Sprite);
/**
* [description]
* Whether this group runs its {@link Phaser.GameObjects.Group#preUpdate} method
* (which may update any members).
*
* @name Phaser.GameObjects.Group#active
* @type {boolean}
@ -148,16 +171,17 @@ var Group = new Class({
this.active = GetFastValue(config, 'active', true);
/**
* [description]
* The maximum size of this group, if used as a pool. -1 is no limit.
*
* @name Phaser.GameObjects.Group#maxSize
* @type {integer}
* @since 3.0.0
* @default -1
*/
this.maxSize = GetFastValue(config, 'maxSize', -1);
/**
* [description]
* A default texture key to use when creating new group members.
*
* @name Phaser.GameObjects.Group#defaultKey
* @type {string}
@ -166,7 +190,7 @@ var Group = new Class({
this.defaultKey = GetFastValue(config, 'defaultKey', null);
/**
* [description]
* A default texture frame to use when creating new group members.
*
* @name Phaser.GameObjects.Group#defaultFrame
* @type {(string|integer)}
@ -175,17 +199,18 @@ var Group = new Class({
this.defaultFrame = GetFastValue(config, 'defaultFrame', null);
/**
* [description]
* Whether to call the update method of any members.
*
* @name Phaser.GameObjects.Group#runChildUpdate
* @type {boolean}
* @default false
* @since 3.0.0
* @see Phaser.GameObjects.Group#preUpdate
*/
this.runChildUpdate = GetFastValue(config, 'runChildUpdate', false);
/**
* [description]
* A function to be called when adding or creating group members.
*
* @name Phaser.GameObjects.Group#createCallback
* @type {?GroupCallback}
@ -194,7 +219,7 @@ var Group = new Class({
this.createCallback = GetFastValue(config, 'createCallback', null);
/**
* [description]
* A function to be called when removing group members.
*
* @name Phaser.GameObjects.Group#removeCallback
* @type {?GroupCallback}
@ -203,7 +228,7 @@ var Group = new Class({
this.removeCallback = GetFastValue(config, 'removeCallback', null);
/**
* [description]
* A function to be called when creating several group members at once.
*
* @name Phaser.GameObjects.Group#createMultipleCallback
* @type {?GroupMultipleCreateCallback}
@ -218,19 +243,21 @@ var Group = new Class({
},
/**
* [description]
* Creates a new Game Object and adds it to this group, unless the group {@link Phaser.GameObjects.Group#isFull is full}.
*
* Calls {@link Phaser.GameObjects.Group#createCallback}.
*
* @method Phaser.GameObjects.Group#create
* @since 3.0.0
*
* @param {number} [x=0] - The horizontal position of this Game Object in the world.
* @param {number} [y=0] - The vertical position of this Game Object in the world.
* @param {string} [key=defaultKey] - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager.
* @param {(string|integer)} [frame=defaultFrame] - An optional frame from the Texture this Game Object is rendering with.
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of this Game Object.
* @param {boolean} [active=true] - The {@link Phaser.GameObjects.GameObject#active} state of this Game Object.
* @param {number} [x=0] - The horizontal position of the new Game Object in the world.
* @param {number} [y=0] - The vertical position of the new Game Object in the world.
* @param {string} [key=defaultKey] - The texture key of the new Game Object.
* @param {(string|integer)} [frame=defaultFrame] - The texture frame of the new Game Object.
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of the new Game Object.
* @param {boolean} [active=true] - The {@link Phaser.GameObjects.GameObject#active} state of the new Game Object.
*
* @return {Phaser.GameObjects.GameObject} [description]
* @return {Phaser.GameObjects.GameObject} The new Game Object.
*/
create: function (x, y, key, frame, visible, active)
{
@ -265,14 +292,17 @@ var Group = new Class({
},
/**
* [description]
* Creates several Game Objects and adds them to this group.
*
* Calls {@link Phaser.GameObjects.Group#createMultipleCallback}
* and {@link Phaser.GameObjects.Group#createCallback}.
*
* @method Phaser.GameObjects.Group#createMultiple
* @since 3.0.0
*
* @param {GroupCreateConfig} config - [description]
* @param {GroupCreateConfig|GroupCreateConfig[]} config - Creation settings. This can be a single configuration object or an array of such objects, which will be applied in turn.
*
* @return {Phaser.GameObjects.GameObject[]} [description]
* @return {Phaser.GameObjects.GameObject[]} The newly created Game Objects.
*/
createMultiple: function (config)
{
@ -294,14 +324,14 @@ var Group = new Class({
},
/**
* [description]
* A helper for {@link Phaser.GameObjects.Group#createMultiple}.
*
* @method Phaser.GameObjects.Group#createFromConfig
* @since 3.0.0
*
* @param {GroupCreateConfig} options - [description]
* @param {GroupCreateConfig} options - Creation settings.
*
* @return {Phaser.GameObjects.GameObject[]} [description]
* @return {Phaser.GameObjects.GameObject[]} The newly created Game Objects.
*/
createFromConfig: function (options)
{
@ -407,13 +437,13 @@ var Group = new Class({
},
/**
* [description]
* Updates any group members, if {@link Phaser.GameObjects.Group#runChildUpdate} is enabled.
*
* @method Phaser.GameObjects.Group#preUpdate
* @since 3.0.0
*
* @param {number} time - [description]
* @param {number} delta - [description]
* @param {number} time - The current timestamp.
* @param {number} delta - The delta time elapsed since the last frame.
*/
preUpdate: function (time, delta)
{
@ -437,13 +467,15 @@ var Group = new Class({
},
/**
* [description]
* Adds a Game Object to this group.
*
* Calls {@link Phaser.GameObjects.Group#createCallback}.
*
* @method Phaser.GameObjects.Group#add
* @since 3.0.0
*
* @param {Phaser.GameObjects.GameObject} child - [description]
* @param {boolean} [addToScene=false] - [description]
* @param {Phaser.GameObjects.GameObject} child - The Game Object to add.
* @param {boolean} [addToScene=false] - Also add the Game Object to the scene.
*
* @return {Phaser.GameObjects.Group} This Group object.
*/
@ -474,15 +506,17 @@ var Group = new Class({
},
/**
* [description]
* Adds several Game Objects to this group.
*
* Calls {@link Phaser.GameObjects.Group#createCallback}.
*
* @method Phaser.GameObjects.Group#addMultiple
* @since 3.0.0
*
* @param {Phaser.GameObjects.GameObject[]} children - [description]
* @param {boolean} [addToScene=false] - [description]
* @param {Phaser.GameObjects.GameObject[]} children - The Game Objects to add.
* @param {boolean} [addToScene=false] - Also add the Game Objects to the scene.
*
* @return {Phaser.GameObjects.Group} This Group object.
* @return {Phaser.GameObjects.Group} This group.
*/
addMultiple: function (children, addToScene)
{
@ -500,13 +534,15 @@ var Group = new Class({
},
/**
* [description]
* Removes a member of this group.
*
* Calls {@link Phaser.GameObjects.Group#removeCallback}.
*
* @method Phaser.GameObjects.Group#remove
* @since 3.0.0
*
* @param {Phaser.GameObjects.GameObject} child - [description]
* @param {boolean} [removeFromScene=false] - [description]
* @param {Phaser.GameObjects.GameObject} child - The Game Object to remove.
* @param {boolean} [removeFromScene=false] - Also remove the group member from the scene.
*
* @return {Phaser.GameObjects.Group} This Group object.
*/
@ -537,14 +573,16 @@ var Group = new Class({
},
/**
* [description]
* Removes all members of this group.
*
* Does not call {@link Phaser.GameObjects.Group#removeCallback}.
*
* @method Phaser.GameObjects.Group#clear
* @since 3.0.0
*
* @param {boolean} [removeFromScene=false] - [description]
* @param {boolean} [removeFromScene=false] - Also remove each group member from the scene.
*
* @return {Phaser.GameObjects.Group} This Group object.
* @return {Phaser.GameObjects.Group} This group.
*/
clear: function (removeFromScene)
{
@ -575,14 +613,14 @@ var Group = new Class({
},
/**
* [description]
* Tests if a Game Object is a member of this group.
*
* @method Phaser.GameObjects.Group#contains
* @since 3.0.0
*
* @param {Phaser.GameObjects.GameObject} child - [description]
* @param {Phaser.GameObjects.GameObject} child - A Game Object.
*
* @return {boolean} [description]
* @return {boolean} True if the Game Object is a member of this group.
*/
contains: function (child)
{
@ -590,12 +628,12 @@ var Group = new Class({
},
/**
* [description]
* All members of the group.
*
* @method Phaser.GameObjects.Group#getChildren
* @since 3.0.0
*
* @return {Phaser.GameObjects.GameObject[]} [description]
* @return {Phaser.GameObjects.GameObject[]} The group members.
*/
getChildren: function ()
{
@ -603,12 +641,12 @@ var Group = new Class({
},
/**
* [description]
* The number of members of the group.
*
* @method Phaser.GameObjects.Group#getLength
* @since 3.0.0
*
* @return {integer} [description]
* @return {integer}
*/
getLength: function ()
{
@ -616,20 +654,24 @@ var Group = new Class({
},
/**
* [description]
* Scans the group for the first member that has an {@link 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.
*
* @method Phaser.GameObjects.Group#getFirst
* @since 3.0.0
*
* @param {boolean} [state=false] - [description]
* @param {boolean} [createIfNull=false] - [description]
* @param {number} [x=0] - The horizontal position of this Game Object in the world.
* @param {number} [y=0] - The vertical position of this Game Object in the world.
* @param {string} [key=defaultKey] - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager.
* @param {(string|integer)} [frame=defaultFrame] - An optional frame from the Texture this Game Object is rendering with.
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of this Game Object.
* @param {boolean} [state=false] - The {@link Phaser.GameObjects.GameObject#active} value to match.
* @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
* @param {number} [x] - The horizontal position of the Game Object in the world.
* @param {number} [y] - The vertical position of the Game Object in the world.
* @param {string} [key=defaultKey] - The texture key assigned to a new Game Object (if one is created).
* @param {(string|integer)} [frame=defaultFrame] - A texture frame assigned to a new Game Object (if one is created).
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of a new Game Object (if one is created).
*
* @return {?Phaser.GameObjects.GameObject} [description]
* @return {?Phaser.GameObjects.GameObject} The first matching group member, or a newly created member, or null.
*/
getFirst: function (state, createIfNull, x, y, key, frame, visible)
{
@ -672,21 +714,23 @@ var Group = new Class({
},
/**
* Scans the Group for the first child that has an `active` state set to `false` and returns it.
* Scans the group for the first member that has an {@link Phaser.GameObjects.GameObject#active} state set to `false`,
* assigns `x` and `y`, and returns the member.
*
* If no child is found then it will create a new one using the arguments given to this method.
* Unless a new child is being created the arguments are ignored.
* 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.
*
* @method Phaser.GameObjects.Group#get
* @since 3.0.0
*
* @param {number} [x=0] - The horizontal position of this Game Object in the world.
* @param {number} [y=0] - The vertical position of this Game Object in the world.
* @param {string} [key=defaultKey] - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager.
* @param {(string|integer)} [frame=defaultFrame] - An optional frame from the Texture this Game Object is rendering with.
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of this Game Object.
* @param {number} [x] - The horizontal position of the Game Object in the world.
* @param {number} [y] - The vertical position of the Game Object in the world.
* @param {string} [key=defaultKey] - The texture key assigned to a new Game Object (if one is created).
* @param {(string|integer)} [frame=defaultFrame] - A texture frame assigned to a new Game Object (if one is created).
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of a new Game Object (if one is created).
*
* @return {Phaser.GameObjects.GameObject} [description]
* @return {?Phaser.GameObjects.GameObject} The first inactive group member, or a newly created member, or null.
*/
get: function (x, y, key, frame, visible)
{
@ -694,22 +738,23 @@ var Group = new Class({
},
/**
* Scans the Group for the first child that has an `active` state set to `true` and returns it.
* Scans the group for the first member that has an {@link Phaser.GameObjects.GameObject#active} state set to `true`,
* assigns `x` and `y`, and returns the member.
*
* If no child is found, and `createIfNull` is `true`, then it will create a new one using the arguments given to this method.
* Unless a new child is being created the arguments are ignored.
* 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.
*
* @method Phaser.GameObjects.Group#getFirstAlive
* @since 3.0.0
*
* @param {boolean} createIfNull - [description]
* @param {number} [x=0] - The horizontal position of this Game Object in the world.
* @param {number} [y=0] - The vertical position of this Game Object in the world.
* @param {string} [key=defaultKey] - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager.
* @param {(string|integer)} [frame=defaultFrame] - An optional frame from the Texture this Game Object is rendering with.
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of this Game Object.
* @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
* @param {number} [x] - The horizontal position of the Game Object in the world.
* @param {number} [y] - The vertical position of the Game Object in the world.
* @param {string} [key=defaultKey] - The texture key assigned to a new Game Object (if one is created).
* @param {(string|integer)} [frame=defaultFrame] - A texture frame assigned to a new Game Object (if one is created).
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of a new Game Object (if one is created).
*
* @return {Phaser.GameObjects.GameObject} [description]
* @return {Phaser.GameObjects.GameObject} The first active group member, or a newly created member, or null.
*/
getFirstAlive: function (createIfNull, x, y, key, frame, visible)
{
@ -717,22 +762,24 @@ var Group = new Class({
},
/**
* Scans the Group for the first child that has an `active` state set to `false` and returns it.
* Scans the group for the first member that has an {@link Phaser.GameObjects.GameObject#active} state set to `false`,
* assigns `x` and `y`, and returns the member.
*
* If no child is found, and `createIfNull` is `true`, then it will create a new one using the arguments given to this method.
* Unless a new child is being created the arguments are ignored.
* 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.
*
* @method Phaser.GameObjects.Group#getFirstDead
* @since 3.0.0
*
* @param {boolean} createIfNull - [description]
* @param {number} [x=0] - The horizontal position of this Game Object in the world.
* @param {number} [y=0] - The vertical position of this Game Object in the world.
* @param {string} [key=defaultKey] - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager.
* @param {(string|integer)} [frame=defaultFrame] - An optional frame from the Texture this Game Object is rendering with.
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of this Game Object.
* @param {boolean} [createIfNull=false] - Create a new Game Object if no matching members are found, using the following arguments.
* @param {number} [x] - The horizontal position of the Game Object in the world.
* @param {number} [y] - The vertical position of the Game Object in the world.
* @param {string} [key=defaultKey] - The texture key assigned to a new Game Object (if one is created).
* @param {(string|integer)} [frame=defaultFrame] - A texture frame assigned to a new Game Object (if one is created).
* @param {boolean} [visible=true] - The {@link Phaser.GameObjects.Components.Visible#visible} state of a new Game Object (if one is created).
*
* @return {Phaser.GameObjects.GameObject} [description]
* @return {Phaser.GameObjects.GameObject} The first inactive group member, or a newly created member, or null.
*/
getFirstDead: function (createIfNull, x, y, key, frame, visible)
{
@ -740,13 +787,13 @@ var Group = new Class({
},
/**
* [description]
* {@link Phaser.GameObjects.Components.Animation#play Plays} an animation for all members of this group.
*
* @method Phaser.GameObjects.Group#playAnimation
* @since 3.0.0
*
* @param {string} key - [description]
* @param {string} startFrame - [description]
* @param {string} key - The string-based key of the animation to play.
* @param {string} [startFrame=0] - Optionally start the animation playing from this frame index.
*
* @return {Phaser.GameObjects.Group} This Group object.
*/
@ -758,12 +805,12 @@ var Group = new Class({
},
/**
* [description]
* Whether this group's size at its {@link Phaser.GameObjects.Group#maxSize maximum}.
*
* @method Phaser.GameObjects.Group#isFull
* @since 3.0.0
*
* @return {boolean} [description]
* @return {boolean} True if the number of members equals {@link Phaser.GameObjects.Group#maxSize}.
*/
isFull: function ()
{
@ -778,14 +825,14 @@ var Group = new Class({
},
/**
* [description]
* Counts the number of active (or inactive) group members.
*
* @method Phaser.GameObjects.Group#countActive
* @since 3.0.0
*
* @param {boolean} [value=true] - [description]
* @param {boolean} [value=true] - Count active (true) or inactive (false) group members.
*
* @return {integer} [description]
* @return {integer} The number of group members with an active state matching the `active` argument.
*/
countActive: function (value)
{
@ -805,12 +852,12 @@ var Group = new Class({
},
/**
* [description]
* Counts the number of in-use (active) group members.
*
* @method Phaser.GameObjects.Group#getTotalUsed
* @since 3.0.0
*
* @return {integer} [description]
* @return {integer} The number of group members with an active state of true.
*/
getTotalUsed: function ()
{
@ -818,12 +865,14 @@ var Group = new Class({
},
/**
* [description]
* The difference of {@link 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.
*
* @method Phaser.GameObjects.Group#getTotalFree
* @since 3.0.0
*
* @return {integer} [description]
* @return {integer} maxSize minus the number of active group numbers; or a large number (if maxSize is -1).
*/
getTotalFree: function ()
{
@ -834,13 +883,13 @@ var Group = new Class({
},
/**
* [description]
* Sets the depth of each group member.
*
* @method Phaser.GameObjects.Group#setDepth
* @since 3.0.0
*
* @param {number} value - [description]
* @param {number} step - [description]
* @param {number} value - The amount to set the property to.
* @param {number} step - This is added to the `value` amount, multiplied by the iteration counter.
*
* @return {Phaser.GameObjects.Group} This Group object.
*/
@ -852,12 +901,12 @@ var Group = new Class({
},
/**
* [description]
* Deactivates a member of this group.
*
* @method Phaser.GameObjects.Group#kill
* @since 3.0.0
*
* @param {Phaser.GameObjects.GameObject} gameObject - [description]
* @param {Phaser.GameObjects.GameObject} gameObject - A member of this group.
*/
kill: function (gameObject)
{
@ -868,12 +917,12 @@ var Group = new Class({
},
/**
* [description]
* Deactivates and hides a member of this group.
*
* @method Phaser.GameObjects.Group#killAndHide
* @since 3.0.0
*
* @param {Phaser.GameObjects.GameObject} gameObject - [description]
* @param {Phaser.GameObjects.GameObject} gameObject - A member of this group.
*/
killAndHide: function (gameObject)
{
@ -885,7 +934,7 @@ var Group = new Class({
},
/**
* [description]
* Toggles (flips) the visible state of each member of this group.
*
* @method Phaser.GameObjects.Group#toggleVisible
* @since 3.0.0
@ -900,12 +949,14 @@ var Group = new Class({
},
/**
* [description]
* Empties this group and removes it from the scene.
*
* Does not call {@link Phaser.GameObjects.Group#removeCallback}.
*
* @method Phaser.GameObjects.Group#destroy
* @since 3.0.0
*
* @param {boolean} [destroyChildren=false] - Call `GameObject.destroy` on all children of this Group?
* @param {boolean} [destroyChildren=false] - Also {@link Phaser.GameObjects.GameObject#destroy} each group member.
*/
destroy: function (destroyChildren)
{