Learning Perlenspiel

This is a summary of how to set up and begin experimenting with Perlenspiel. The engine has many features not explained here, but this is enough to get you started.

  1. Get the framework files
  2. Get the latest Firefox and Firebug
  3. Get Aptana Studio 3
  4. Organizing and running a project
  5. Basic concepts
  6. How the engine works
  7. Your first script
  8. Using the debugger
  9. Working with color
  10. Adding glyphs

1. Get the framework files

Visit the download page and right-click on the link to download the file named PS2.zip to a convenient place on your computer.

Extract the archive. You should end up with a folder called PS2. Inside it you'll find two files:

These files are the framework upon which all Perlenspiel projects are built.

Nearly all of your time will be spent modifying and extending the game.js file. The game.html file will be changed only a little (if at all).

Before you proceed, make a backup of the PS2 directory! You will need fresh copies of the framework files for every project.

[Firefox]

2. Get the latest Firefox and Firebug

Perlenspiel is a cloud-based HTML5 application, optimized for use with the Firefox browser. It might work with other browsers (Chrome seems to get along perfectly well), but you should use Firefox to develop your projects.

You can get the latest version of Firefox here. It should already be installed on all of the computers in the IMGD Lab.

[Aptana]

3. Get Aptana Studio 3

You can use any text editor to edit your project files. But your productivity will be much improved if you use an integrated development environment (IDE) specifically designed for working with HTML and Javascript.

I recommend the standalone version of Aptana Studio 3 for this purpose. Aptana is based on Eclipse, an open-source IDE that offers many excellent features and is widely used throughout the software industry. Aptana adds dozens of conveniences for editing HTML and Javascript, including a powerful debugger that (when it works) is tightly integrated with Firefox and Firebug.

Perlenspiel 2 and this Web site were themselves developed using Aptana. Try it. Once you find your way around the interface, I think you'll love it. It should already be installed on all the IMGD Lab computers.

You should install Firefox and Firebug before installing Aptana. However, do not use the latest release of Firebug! Visit this page and get Version 1.8.3 instead. This is the last version of Firebug that seems to interact properly with Aptana.

You must also tell Firefox not to automatically upgrade your browser extensions. Otherwise, it will see the old Firebug and cheerfully replace it with the latest release!

While installing Apatana, make sure it is set up to use Firefox for debugging and running Web applications. Instructions for this are provided in the installer and documentation.

A sad note: Firefox is on the decline. I only continue to use it because it works well with Aptana. But the Webkit family of browsers (including Chrome and Safari) are racing ahead of Firefox in terms of functionality. If I locate another free IDE as good as Aptana that interoperates with Chrome, I will leave Aptana and Firefox behind.

4. Organizing and running a project

It's easy to organize and run a basic Perlenspiel project.

  1. Make a project directory. It can be named anything and live anywhere on your hard drive.
  2. Put copies of the two framework files (game.html and game.js) in the directory.
  3. If you're using Aptana, start a new project and specify the project directory you created as the directory Apatana should use.
  4. Modify game.js to create your Perlenspiel applicaton.
  5. To run the application, open game.html with Firefox, or run it with Aptana.

That's all there is to it!

When your application is finished, you can move it to the cloud by copying your entire project directory to a Web server, and run it by linking to game.html.

5. Basic concepts

Begin by checking out a few examples of Perlenspiel toys and games.

Beads and the grid

A Perlenspiel page is divided into three areas.

[Grid]

The center of the page displays the grid, a rectangular matrix of colored squares.

Each square in the grid is called a bead. Yes, I know they look more like boxes than beads. They might look more like real beads in a future version of Perlenspiel, although I've come to rather like the austerity of the squares.

Status and message boxes

There are also two single-line text boxes, one above and one below the grid.

The text box above the grid is the status line. You can use the status line to communicate short messages to your players that would be inconvenient to convey using only the beads in the grid, such as high scores, time limits or simple instructions.

The text box below the grid is the message line. This is used by the Perlenspiel engine to display internal status and error messages. You can't control the text that appears here.

Grid dimensions

The number of rows and columns in the grid is not fixed. You can specify the dimensions of the grid for each game, up to a maximum of 32x32 beads. You can resize the grid anytime, even in the middle of a game.

Referencing beads

The columns and rows on the grid are numbered from zero, starting at the top left corner. Beads are referenced by their column/row position in the grid. So the bead in the top left corner is always bead (0,0), the third bead in the second row is bead (2,1), etc. This convention is used throughout the Perlenspiel engine, so get used to it.

Bead borders

By default, each bead on the grid is enclosed in a border. You can control the width and color of the border on individual beads.

6. How the engine works

Despite its radical simplicity, Perlenspiel actually models the operation of a full-fledged industrial game engine.

By itself, Perlenspiel is dumb. It knows practically nothing about games or interactivity. All it knows how to do is draw beads in the grid, display text in the status line, and read the mouse and keyboard. Without a game script, nothing happens.

Game scripts

Perlenspiel uses the Javascript programming language to control its behavior. Javascript is the most popular and widely-deployed programming language in the world. It is used to control the look and behavior of nearly all of the billions of pages on the World Wide Web. Using the latest HTML5 technology, Javascript is now being used to write complex Web-based applications, including many games. In fact, the Perlenspiel 2 engine is itself written in Javascript!

With Javascript, you can bring Perlenspiel to life.

[Engine]

Whenever the player moves or clicks the mouse, or presses a key on the keyboard, the engine tells Javascript where the mouse is, which bead got clicked, or which key got pressed.

Javascript can respond by commanding the engine to change the color of one or more beads, play sounds, or display a text message in the status line. This event-driven interchange between the Perlenspiel engine and Javascript creates the entire game experience. Change the Javascript, and the behavior of the engine is completely redefined.

7. 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 Aptana, or the editor of your choice, navigate to a copy of the game.js file and open it.

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

PS.Init = function ( options )
{
    "use strict";

    // change to the dimensions you want

    PS.GridSize ( 8, 8 );

    // Put any other init code here
};

This function, PS.Init(), is called whenever the player opens a Perlenspiel page. The function currently contains a call to PS.GridSize(), which tells the engine what the dimensions of the game grid should be.

Note that the function name begins with “PS.” in upper-case letters. All Perlenspiel function names follow this convention. Also note that single-line Javascript comments begin with an adjacent pair of left slashes (//).

Replace the comment below the call to PS.GridSize() with the following line of code:

PS.Init = function ( options )
{
    "use strict";

    // change to the dimensions you want

    PS.GridSize ( 8, 8 );

    PS.StatusText( "Hello, world!" );
};

The PS.StatusText() function puts a text message in the status line. This call will display the classic “Hello, world!” message when the game is initialized.

Scroll down a bit more until you find this code:

PS.Click = function (x, y, data, options)
{
    "use strict";

    // Put code here for bead clicks
};

This important function, PS.Click(), gets called every time the player clicks on a bead. The x and y parameters indicate the column and row of the bead that was clicked. (Ignore the data parameter for now.)

Replace the comment with the following two lines of code:

PS.Click = function (x, y, data, options)
{
    "use strict";

    PS.BeadColor( x, y, PS.COLOR_RED );
    PS.AudioPlay( "fx_click" );
};

The function PS.BeadColor() 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.Click() 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 all 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 file. Open the game.html file with Firefox, or run it in Aptana.

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.

Congratulations. You are now a Perlenspiel engineer.

5. Using the debugger

When writing any type of program, it's very useful to be able to see what's going on in your code as it runs. The Perlenspiel debugger makes this fairly easy.

Go back to the previous script and add the following code in PS.Click():

PS.Click = function (x, y, data, options)
{
    "use strict";

    PS.BeadColor( x, y, PS.COLOR_RED );
    PS.AudioPlay( "fx_click" );
    PS.Debug( "x=" + x + " y=" + y + "\n" );
};

The PS.Debug() command sends a text string to the Perlenspiel debugger, which is a special text box that is normally hidden under the message line. The code in the example uses Javascript's string concatenation syntax (the + sign) to construct a string that reports the x and y position of the bead that was clicked.

Save the file and run game.html again. When you click on a bead, you should now see its coordinates on the grid being reported in the debugger box.

If you are using Firefox and have installed Firebug, you can use it to help debug your scripts as they run. If you are also using Aptana to edit your code, you will have access to a whole range of professional debugging features, including breakpoints, expression evaluation and variable watching. These capabilities can save you many hours of work. Consult the Aptana documentation for details.

A handy little shortcut

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

Return to your editor and change the PS.BeadColor() command so that the third parameter is PS.COLOR_BLUE instead of PS.COLOR_RED. Save the file.

Now switch back to Firefox and click the Reload icon. This 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.

6. Working with color

The Perlenspiel library provides a handful of color constants (PS.COLOR_RED, PS.COLOR_BLUE, etc) that are useful for prototyping. Refer to the Constants page for details.

You can define your own colors by using the PS.MakeRGB() library function. This function takes three arguments (red, green and blue, in that order), each of which indicates how much of that primary color should be included to create the composite hue. The values should be in the range of 0 to 255, inclusive.

For instance, PS.COLOR_RED corresponds to PS.MakeRGB(255,0,0).

PS.COLOR_WHITE is PS.MakeRGB(255,255,255), and PS.COLOR_BLACK is PS.MakeRGB(0,0,0).

You can use the PS.MakeRGB() function wherever a color needs to be specified.

PS.BeadColor( 3, 5, PS.MakeRGB(64,128,64) );

You can also make global variables to hold colors you use frequently.

var MY_DARK_YELLOW = PS.MakeRGB(96,96,0);

7. Adding glyphs

Go back to the game.js script. Remove the call to PS.Debug() and replace it with:

PS.Click = function (x, y, data, options)
{
    "use strict";

    PS.BeadColor( x, y, PS.COLOR_RED );
    PS.AudioPlay( "fx_click" );
    PS.BeadGlyph( x, y, "P" );
};

The PS.BeadGlyph() command tells Perlenspiel to display an alphanumeric 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.

If you prefer, you can pass an integer in the third parameter of PS.BeadGlyph() instead of a string. The integer should be the Unicode value corresponding to the desired glyph.