Learning 04: Your first script

This section is not going to teach you how to program, or the details of JavaScript. It's just a quick demonstration of how to edit and run Perlenspiel scripts.

Using Webstorm, or the IDE of your choice, navigate to your project's game.js file and open it.

Scroll down and take a look at this short file. Much of it is commented out using one of JavaScript's two commenting formats:

/*
Blocks of text (like this) are commented out
by enclosing them inside slash-asterix and
asterix-slash character pairs.
*/

// Individual lines (or ends of lines) are
// commented out (like these) by preceding them
// with a pair of forward slashes.

Amid all the comments you'll find ten JavaScript function definitions, one for each of Perlenspiel's ten event calls. These are the functions that are executed in response to the associated events.

In the default game.js file, none of these function definitions contain any active code, so nothing happens when they are called.

Scroll down a bit until you find some code that looks like this:

/*

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( 8, 8 );

 // 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.
};

*/

This function, PS.init(), is called only once, when a Perlenspiel game starts running. By default, this function contains a call to PS.gridSize(), a command which tells Perlenspiel what the dimensions of the grid should be. The grid created by the default command is 8 beads wide and 8 high, but you can change either value to anything between 1 and 32 inclusive.

Note that the function name begins with PS. in upper-case letters. All Perlenspiel event and command names follow this convention.

Important!

JavaScript is a case-sensitive language. Upper and lower case characters must be typed exactly as expected, or errors will occur.

Remove the /* and */ characters enclosing the PS.init() function definition to expose it to the compiler. Then uncomment the code lines containing the calls to PS.gridSize() and PS.statusText() to make them active. Change the x and y parameters of PS.gridSize() to any dimensions you want between 1 and 32, and change the PS.statusText() parameter to the string "Hello, world!"

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

Scroll down a bit more until you find this code:

/*

PS.touch = function( x, y, data, options ) {
 // Uncomment the following code line
 // to inspect x/y parameters:

 // PS.debug( "PS.touch() @ " + x + ", " + y + "\n" );

 // Add code here for mouse clicks/touches
 // over a bead.
 };

*/

This important event function, PS.touch(), is called every time the player clicks on or touches a bead. The x and y parameters indicate the column and row of the bead that was pressed. (Ignore the other parameters for now. We'll explore them later.)

Remove the /* and */ characters enclosing the PS.touch() function definition. Then add these two lines of code to the bottom of the function:

PS.touch = function( x, y, data, options ) {
 // Uncomment the following code line
 // to inspect x/y parameters:

 // PS.debug( "PS.touch() @ " + x + ", " + y + "\n" );

 // Add code here for mouse clicks/touches
 // over a bead.

 PS.color( x, y, PS.COLOR_RED );
 PS.audioPlay( "fx_click" );
};

The PS.color() call commands the engine to change the color of a particular bead. The first and second parameters indicate the column and row of the bead to change. In this case, we are specifying the same row and column that was sent to the PS.touch() function, so it will affect the bead that was just clicked.

The third parameter, PS.COLOR_RED, is the desired color (in this case, red). Note that the color constant begins with PS. and is in upper-case letters. All Perlenspiel constant names follow this convention.

The function PS.audioPlay() commands the engine to play a sound file.

Once you have made these changes, save the game.js file. Then open thegame.html file and run it.

The message Hello, world! should now be visible in the status line.

Click on any bead on the grid. It should change to red and play a “click” sound.

A handy little shortcut

It would be very tedious to open and close the browser running Perlenspiel every time you made a change in a script. Luckily, you don't have to.

Leave your browser open. Return to the game.js file in your editor, find the PS.touch() function you edited earlier and change the PS.color() command so that the third parameter is PS.COLOR_BLUE instead of PS.COLOR_RED. Save game.js again.

Now switch back to your browser and click its reload button. (Ask someone if you don't know where it is or what it looks like.) This button reloads the last page that was opened. The grid will clear as the engine is reset.

Click on a few beads to verify that they are now turning blue.

Adding glyphs

Go back to your game.js file. Add a new line to the bottom of the PS.touch() function:

PS.touch = function( x, y, data, options ) {
 // Uncomment the following code line
 // to inspect x/y parameters:

 // PS.debug( "PS.touch() @ " + x + ", " + y + "\n" );

 // Add code here for mouse clicks/touches
 // over a bead.

 PS.color( x, y, PS.COLOR_RED );
 PS.audioPlay( "fx_click" );
 PS.glyph( x, y, "P" );
};

The PS.glyph() call commands Perlenspiel to display a text character inside the specified bead. The first two arguments are the x and y coordinates of the bead on the grid. The third argument is a string with the character you want to display. In this example, we use the capital letter P.

Save the script and run it. When you click on the grid, each blue bead should now contain a capital P.

Congratulations. You are now a Perlenspiel engineer.

 

Terms to know

Next: Using the debugger