Group.align is a new method that allows you to layout all the children of the Group in a grid formation. You can specify the dimensions of the grid, including the width, height and cell size. You can also control where children are positioned within each grid cell. The grid width and height values can also be set to -1, making them fluid, so the grid expands until all children are aligned. Finally an optional child index argument can be set. This is a great way to quickly and comprehensively align Group children, and has lots of use cases.

Author: photonstorm

README.md

@@ -369,6 +369,7 @@ You can read all about the philosophy behind Lazer [here](http://phaser.io/news/
 * Rectangle.getPoint is a new method that returns a point based on the given location constant, such as `Phaser.BOTTOM_LEFT`. It returns the same result as calling `Rectangle.bottomLeft` (etc) but unlike those getters you are able to provide your own Point object.
 * The Game Object Bounds component has been updated to include two new properties: `centerX` and `centerY`. This means you can, for example, now get the horizontal center of a Sprite by called `Sprite.centerX`. These properties are also setters, so you can position the Game Objects, and it will take scale and anchor into consideration.
 * All Game Objects with the Bounds component; which includes Sprites, Images, Text, BitmapText, TileSprites and anything that extend these, now have a new method `alignTo`. It allows you to align the Game Object to another Game Object, or a Rectangle. You can specify one of 9 positions which are the new constants: `Phaser.TOP_LEFT`, `Phaser.TOP_CENTER` and so on (see above for the complete list). The Game Objects are positioned based on their Bounds, which takes rotation, scaling and anchor into consideration. You can easily place Sprites into the corners or the screen or game world, or align them against other Sprites, using this method.
+* Group.align is a new method that allows you to layout all the children of the Group in a grid formation. You can specify the dimensions of the grid, including the width, height and cell size. You can also control where children are positioned within each grid cell. The grid width and height values can also be set to -1, making them fluid, so the grid expands until all children are aligned. Finally an optional child index argument can be set. This is a great way to quickly and comprehensively align Group children, and has lots of use cases.
 
 ### Updates
 

src/core/Group.js

@@ -674,29 +674,59 @@ Phaser.Group.prototype.updateZ = function () {
 
 /**
 * This method iterates through all children in the Group (regardless if they are visible or exist)
-* and then changes their position properties so they are arranged in a Grid formation.
+* and then changes their position so they are arranged in a Grid formation. Children must have
+* the `alignTo` method in order to be positioned by this call. All default Phaser Game Objects have
+* this.
 *
-* The grid dimensions are determined by the first four arguments. The rows and columns arguments
+* The grid dimensions are determined by the first four arguments. The `rows` and `columns` arguments
 * relate 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 per
+* grid cell. If you want a wider grid, you could do:
 * 
-* You can choose to set 'columns' to -1.
-* If you do this it means it will continue aligning all of the children of the Group
+* `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 `rows` or `columns` value to -1. Doing so tells the method
+* to keep on aligning children until there are no children left. For example if this Group had
+* 48 children in it, the following:
+*
+* `Group.align(-1, 8, 32, 32)`
+*
+* ... will align the children so that there are 8 columns 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:
 * 
-*   This is the number of grid cells that exist
-* in total.
+* `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 fit
+* all of the children in.
+*
+* The `position` property allows you to control where in each grid cell the child is positioned.
+* This is a constant, such as `Phaser.TOP_RIGHT` or `Phaser.MIDDLE_CENTER`.
+*
+* The final argument; `offset` lets you start the alignment from a specific child index.
 *
 * @method Phaser.Group#align
-* @param {integer} rows - The number of rows to use in the grid alignment.
-* @param {integer} columns - The number of columns to use in the grid alignment.
+* @param {integer} rows - The number of rows, or width, of the grid. Set to -1 for a dynamic width.
+* @param {integer} columns - The number of columns, or height, of the grid. Set to -1 for a dynamic height.
 * @param {integer} cellWidth - The width of each grid cell, in pixels.
 * @param {integer} cellHeight - The height of each grid cell, in pixels.
 * @param {integer} [position] - The position constant. One of `Phaser.TOP_LEFT` (default), `Phaser.TOP_CENTER`, `Phaser.TOP_RIGHT`, `Phaser.MIDDLE_LEFT`, `Phaser.MIDDLE_CENTER`, `Phaser.MIDDLE_RIGHT`, `Phaser.BOTTOM_LEFT`, `Phaser.BOTTOM_CENTER` or `Phaser.BOTTOM_RIGHT`.
+* @param {integer} [offset=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.
 */
-Phaser.Group.prototype.align = function (rows, columns, cellWidth, cellHeight, position) {
+Phaser.Group.prototype.align = function (rows, columns, cellWidth, cellHeight, position, offset) {
 
     if (position === undefined) { position = Phaser.TOP_LEFT; }
+    if (offset === undefined) { offset = 0; }
 
-    if (this.children.length === 0 || (rows === -1 && columns === -1))
+    if (this.children.length === 0 || offset > this.children.length || (rows === -1 && columns === -1))
     {
         return;
     }
@@ -705,7 +735,7 @@ Phaser.Group.prototype.align = function (rows, columns, cellWidth, cellHeight, p
     var w = (rows * cellWidth);
     var h = (columns * cellHeight);
 
-    for (var i = 0; i < this.children.length; i++)
+    for (var i = offset; i < this.children.length; i++)
     {
         var child = this.children[i];
 

typescript/phaser.d.ts

@@ -1730,6 +1730,7 @@ declare module "phaser" {
             addAt(child: any, index: number, silent?: boolean): any;
             addMultiple(children: any[], silent?: boolean): any[];
             addToHash(child: PIXI.DisplayObject): boolean;
+            align(rows: number, columns: number, cellWidth: number, cellHeight: number, position?: number, offset?: number): void;
             bringToTop(child: any): any;
             callAll(method: string, context: any, ...parameters: any[]): void;
             callAllExists(callback: string, existsValue: boolean, ...parameters: any[]): void;