A utility class for organizing objects within a Phaser scene into a grid layout. The grid allows you to arrange elements with customizable row and column configurations, as well as optional aspect ratio handling and debugging capabilities.

• 1. Usage
  • 1.1. Installation
  • 1.2. Example Usage
    • 1.2.1. Basic Grid Example
    • 1.2.2. Aspect Ratio Specific Grid Example
    • 1.2.3. Placing Items Throughout the Grid
• 2. API Reference
  • 2.1. Constructor
  • 2.2. Properties
    • 2.2.1. width
    • 2.2.2. height
  • 2.3. Methods
    • 2.3.1. cell
    • 2.3.2. enableDebug
    • 2.3.3. widthOf
    • 2.3.4. heightOf

1. Usage

1.1. Installation

Install the package via npm.

npm install @phaserquick/grid

1.2. Example Usage

1.2.1. Basic Grid Example

See below for a default grid tht will fill the entire canvas with the specified number of rows and cols.

import { Grid } from '@phaserquick/grid';

// Create a new grid with 9 rows and 9 columns
const grid = new Grid(scene, 9, 9);

// Enable debugging to visualize the grid
grid.enableDebug();

Output:

1.2.2. Aspect Ratio Specific Grid Example

In this example, the grid is created with an aspect ratio of 16:9. The grid is aligned in the center of the screen.

import { Grid } from '@phaserquick/grid';

/**
 * Create a 9x9 grid with an aspect ratio of 9:16, and align
 * it to the bottom of the canvas.
 */
const grid = new Grid(this, 9, 9, {
  aspectRatio: {
    height: 9,
    width: 16,
    align: 'bottom'
  }
});

// Enable debugging to visualize the aspect ratio-based grid
grid.enableDebug();

Output:

1.2.3. Placing Items Throughout the Grid

This example demonstrates how to place items in specific cells of the grid. You can use the cell() method to retrieve the position of any cell and customize its alignment within the cell.

import { Grid } from '@phaserquick/grid';

const gem1 = this.add.image(0, 0, 'gem').setAlpha(0.4);
const gem2 = this.add.image(0, 0, 'gem').setAlpha(0.4);

const grid = new Grid(this, 9, 9);

// Enable debugging to visualize the aspect ratio-based grid
grid.enableDebug();

// Get cell 41 x & y. Center of the cell by default.
const cell29 = grid.cell(29);

// Place gem1 at cell 29.
gem1.setPosition(cell29.x, cell29.y);

// Get cell 52 x & y. Bottom right of the cell.
const cell52 = grid.cell(52, { x: 'right', y: 'bottom' });

// Place gem2 at the bottom right of cell 52.
gem2.setPosition(cell52.x, cell52.y);

Output:

2. API Reference

2.1. Constructor

new Grid(scene: Phaser.Scene, rows: number, cols: number, options?: GridOptions)

Creates a new instance of the Grid class.

• scene: The Phaser scene to which the grid belongs.
• rows: The number of rows in the grid.
• cols: The number of columns in the grid.
• options (optional): Additional options for configuring the grid, including:
  • cellColor: The color of the grid cell outlines (default is red).
  • aspectRatio: Defines the width, height, and alignment of the grid based on a specified aspect ratio. This option can be omitted if you want the grid to automatically adjust to fit the canvas.

2.2. Properties

2.2.1. width

Retrieves the full width of the grid.

2.2.2. height

Retrieves the full height of the grid.

2.3. Methods

2.3.1. cell

cell(cellID: number, options?: { x?: 'left' | 'right' | 'center', y?: 'top' | 'bottom' | 'center' }): { x: number, y: number }

Retrieves the coordinates of the center of the specified cell in the grid.

• cellID: The ID of the cell for which to retrieve the coordinates.
• options (optional): Additional options for specifying the alignment of the cell coordinates.
  • x: Specifies horizontal alignment. Can be 'left', 'right', or 'center' (default).
  • y: Specifies vertical alignment. Can be 'top', 'bottom', or 'center' (default).

2.3.2. enableDebug

enableDebug()

Enables debugging for the grid by drawing rectangles with outlines and adding text to represent the cell IDs. This method is useful for visualizing and debugging the grid layout.

No parameters are required.

Example:

grid.enableDebug();

2.3.3. widthOf

widthOf(cells: number): number

Returns the total width of a specified number of cells. This is useful for calculating how much horizontal space a given number of cells will take up.

• cells: The number of cells for which to calculate the width.

Example:

const totalWidth = grid.widthOf(3); // Gets the width of 3 cells

2.3.4. heightOf

heightOf(cells: number): number

Returns the total height of a specified number of cells. This is useful for calculating how much vertical space a given number of cells will take up.

• cells: The number of cells for which to calculate the height.

Example:

const totalHeight = grid.heightOf(4); // Gets the height of 4 cells