Perlenspiel 3.3 | Learning 07

PS.gridSize ( width, height )

The grid is, figuratively and literally, the framework of all Perlenspiel games. Establishing the dimensions of your grid(s) is one of the first concrete decisions you'll make when beginning a new design.

The PS.gridSize() command lets you specify the width and height of the grid. It should usually be the first command included in your game's PS.init() function. To remind you of this, the default game.js file includes the expected call to PS.gridSize() inside PS.init(), specifying the default 8x8 grid.

Uncomment the PS.init() function block and the example call to PS.gridSize(), and change those placeholder values to whatever your game initially requires.

PS.init = function( system, options ) {
// Uncomment the following code line
// to verify operation:

// PS.debug( "PS.init() called\n" );

// This function should normally begin
// with a call to PS.gridSize( x, y )
// where x and y are the desired initial
// dimensions of the grid.
// Call PS.gridSize() FIRST to avoid problems!
// The sample call below sets the grid to the
// default dimensions (8 x 8).
// Uncomment the following code line and change
// the x and y parameters as needed.

PS.gridSize( 7, 17 );

// This is also a good place to display
// your game title or a welcome message
// in the status line above the grid.
// Uncomment the following code line and
// change the string parameter as needed.

// PS.statusText( "Game" );

// Add any other initialization code you need here.
};

The required width and height parameters must be integers between 1 and 32 inclusive. Any values outside this range are clamped. Non-integral values are floored.

Specifying the Perlenspiel constant PS.CURRENT in either parameter causes that dimension of the grid to maintain its current value. Specifying the constant PS.DEFAULT changes that dimension to its default value (8).

Changing the grid size mid-game

As noted above, it's important to establish your initial grid dimensions at the beginning of your game's PS.init() function. However, you can also change the size of the grid anytime, even in the middle of a game.

If you want to do this, here's an important thing you need to know:

Changing the size of the grid completely resets the grid.

All attributes of any previously established grid and its beads are returned to their default values. All running faders and timers are stopped. All z-planes above plane 0 are deleted.

The API documentation for PS.gridSize() has a complete description of what gets reset, and how.

Be prepared to completely re-initialize your game if you change the dimensions of your grid!

Demonstration

This demo starts with a 32x32 white grid, and generates a new randomly-sized grid every time you click or touch any bead. The color of each bead is also random.

NOTE: Commented-out blocks and lines included in the default game.js file have been removed from this and all subsequent example code.

PS.init = function( system, options ) {
PS.gridSize( 32, 32 );
PS.statusText( "PS.gridSize() Demo" );
};

PS.touch = function( x, y, data, options ) {
var w, h, x, y, r, g, b;

w = PS.random( 32 ); // random width 1-32
h = PS.random( 32 ); // random height
PS.gridSize( w, h ); // create new grid

// Report new size in status line

PS.statusText( "Width = " + w + ", Height = " + h );

// Nested loops set the bead colors

for ( y = 0; y < h; y += 1 ) {
for ( x = 0; x < w; x += 1 ) {
r = PS.random(256) - 1; // random red 0-255
g = PS.random(256) - 1; // random green
b = PS.random(256) - 1; // random blue
PS.color( x, y, r, g, b ); // set bead color
}
}
};

Return value

PS.gridSize() returns an object containing the following properties:

.width : integer
.height : integer

These properties indicate the current width and height of the grid.

The Perlenspiel constant PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Inspecting the size of the grid

var result = PS.gridSize( 12, 18 );
PS.debug( "Width = " + result.width + ", height = " +
result.height + "\n" );

PS.gridColor ( color )

By default, the background color of the grid, and the web page surrounding it, is plain white. The PS.gridColor() command lets you specify any background color for the grid you want.

The optional color parameter can be supplied in any of the four Perlenspiel color expression formats.

If color is PS.DEFAULT, the default color (PS.COLOR_WHITE) is applied. If color is PS.CURRENT or not supplied, the grid color is not changed.

Keep an eye on the status line!

Changing the grid color doesn't affect the color of any text that may be present in the status line.

If the status line color is close to or identical to the new grid color, the text may become difficult or impossible to read.

If necessary, you can keep the status line legible with a tasteful call to PS.statusColor().

Demonstration

This demo starts with a white grid background, and generates a random background color when you click or touch any bead.

PS.init = function( system, options ) {
PS.gridSize( 8, 8 ); // set initial size
PS.statusText( "PS.gridColor() Demo" );
};

PS.touch = function( x, y, data, options ) {
var r, g, b;

r = PS.random(256) - 1; // random red 0-255
g = PS.random(256) - 1; // random green
b = PS.random(256) - 1; // random blue
PS.gridColor( r, g, b ); // set grid color

// Report grid color in status line

PS.statusText( "r = " + r + ", g = " + g +
", b = " + b + "\n" );
};

Return value

PS.gridColor() returns an RGB triplet integer indicating the current background color of the grid.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Inspecting the grid background color
// PS.unmakeRGB() is used to extract the r, g & b values
// from the RGB triplet returned by PS.gridColor()

var result = PS.unmakeRGB( PS.gridColor(), {} );
PS.debug( "r = " + result.r + ", g = " + result.g +
", b = " + result.b + "\n" );

PS.gridShadow ( show, color )

You can add a decorative shadow around the grid with the PS.gridShadow() command. By default, no shadow is displayed.

The show parameter expects a Boolean (true/false) value. If you specify true, the grid shadow is turned on. Specifying false or PS.DEFAULT turns it off.

The optional color parameter can be supplied in any of the four Perlenspiel color expression formats.

If color is PS.DEFAULT, the default color (PS.COLOR_GRAY_LIGHT) is applied. If color is PS.CURRENT or not supplied, the shadow color is not changed.

Demonstration

This demo starts with no grid shadow, and turns the shadow on and off alternately when you click or touch any bead. The color of the shadow is random each time.

// This variable remembers the shadow status

var shadowStatus = false;

PS.init = function( system, options ) {
PS.gridSize( 8, 8 );
PS.statusText( "PS.gridShadow() Demo" );
};

PS.touch = function( x, y, data, options ) {
var r, g, b;

// If shadow is visible, hide it

if ( shadowStatus ) {
shadowStatus = false;
PS.gridShadow( false );
PS.statusText( "Grid shadow disabled" );
}

// Otherwise show with random color
// Max color value is 127 to insure
// visibility against white grid

else {
shadowStatus = true;
r = PS.random(128) - 1; // random red 0-127
g = PS.random(128) - 1; // random green
b = PS.random(128) - 1; // random blue
PS.gridShadow( true, r, g, b );

// Report shadow color in status line

PS.statusText( "r = " + r + ", g = " + g +
", b = " + b + "\n" );
}
};

Return value

PS.gridShadow() returns an object with the following properties:

.show : boolean
.rgb : integer

The .show property is true if the grid shadow is currently enabled, else false.

The .rgb property is an RGB triplet integer indicating the color currently assigned to the grid shadow.

PS.ERROR is returned if an error occurs.

Terms to know

PS.gridSize()
PS.gridColor()
PS.gridShadow()
PS.DEFAULT
PS.CURRENT
PS.ERROR
Boolean