Version notes

Report suspected bugs, ideas and comments to Professor Moriarty (bmoriarty [at] wpi [dot] edu).

Version 2.3.9 (Released 01.08.13)

Mark Diehr tracked down another bug, this time in PS.ImageBlit(). Fixed.

He also noticed a new audio bug, introduced in the previous version. Fixed.

Version 2.3.8 (Released 01.07.13)

Mark Diehr tracked down a bug in the key repeat code. Fixed.

Version 2.3.7 (Released 01.02.13)

Bugs in some of the keycodes returned by PS.KeyDown() and PS.KeyUp() have been fixed.

Several new keys now have system constants. Also, the actual values of many existing key constants have been changed. This will have no effect on your games if you wisely used the constants. But if you substituted hardcoded values for certain keys, expect trouble.

Version 2.3.6 (Released 12.10.12)

1. The flakiness in the audio engine's error handling has finally been tracked down and fixed! You should now get a clear error message if you try to load an invalid sound file.

2. The path parameters in PS.AudioPath(), PS.AudioLoad() and PS.AudioPlay() now accept PS.CURRENT (which specifies the current path) or an empty string (""). This lets you load and play sound files located in the same directory as your source files by specifying "" as the path.

Version 2.3.5 (Released 12.07.12)

1. PS.AudioPlay() now accepts an additional data parameter that lets you pass any type of Javascript data through the parameter of the on-end function specified by the func parameter. This should be backwards compatible.

2. The status line text was not being cleared at the end of a fade-out. Fixed.

Version 2.3.4 (Released 12.03.12)

1. A bug in PS.ImageBlit() was causing glyph size problems. Fixed.

Version 2.3.3 (Released 11.30.12)

1. A bug in key repeating has been fixed. I have also added an initial delay of 1/2 second before the repeats start to fire at 10 per second.

Version 2.3.2 (Released 11.29.12)

1. PS.StatusColor() now accepts the same color parameters as all other color-setting functions.

2. PS.StatusFade() has been replaced by two new calls, PS.StatusFadeUp() and PS.StatusFadeDown(). These allow precise control over the appearance and disappearance of status line text.

PS.StatusFade() still works as usual to ensure backwards compatibility. It will be deprecated in the next major version.

3. The status line is now empty by default.

4. The message line that displays the engine version number under the grid now disappears five seconds after startup. It only reappears if an error occurs. The text color of this line is now controlled by the engine, and is no longer tied to PS.StatusColor().

5. If a key is held down, your PS.KeyDown() function will now be called no more than 10 times per second. Also, there is never more than 1/10th second delay between the first keypress event and the repeat events.

Version 2.3.1 (Released 11.20.12)

1. A bug in PS.ImageBlit() has been fixed, and extra bulletproofing has been added.

2. PS.ImageLoad() now returns a unique string identifier for the image. The same identifier is assigned to a new id element in the ImageData object passed to the loader function. This provides a solution to the problem of knowing which ImageData object is associated with which image, as there is no guarantee that the loader calls (which are asynchronous) will fire in the same order that they were loaded.

Another new ImageData element named file provides the filename that was passed to PS.ImageLoad(). You can also use this element to identify the image if you prefer.

NOTE: A new identifier is generated by each call to PS.ImageLoad(). If you load the same image more than once for some reason, each ImageData instance will have the same filename but a different identifier.

Version 2.3.0 (Released 11.19.12)

1. The game.html template has been simplified to make the engine layout more flexible. You must use this template for all games written with Perlenspiel 2.3. You can get it using the download link above.

The game.js template is also slightly different, but existing code should work fine after you adapt your image loading code (see below).

2. An audio problem when opening games from a local file with Webkit browsers (Chrome and Safari) has been addressed.

3. The image loading and blitting functions have been significantly changed.

PS.ImageData() has been deprecated. Its functionality is now wrapped inside PS.ImageLoad(), making the process of loading and showing image files even easier. And you're no longer limited to loading 32x32 images!

The loader function parameter in PS.ImageLoad() is no longer optional. There is also a new, optional format parameter that lets you specify the format of the image data.

Best of all, PS.ImageBlit() has been completely rewritten for much better performance, and enhanced with new optional parameters that let you specify a region within the source image. A simple example of image scrolling using the new blitter can be seen here.

Refer to the Images documentation for complete details on these changes and an updated example.

5. The debugger now intercepts keyboard events when it is in focus. This means you can use ctrl+c to copy text out of it. To direct the key events back to Perlenspiel, click anywhere on the browser window outside the debugger.

Version 2.2.6 (Released 11.15.12)

1. The audio system has been completely rewritten. I believe you will find the performance and stability substantially improved. In particular, you should now be able to have many more sounds playing at the same time, including several instances of the same sound.

Here is a demonstration of the new tech.

Webkit-based browsers (Chrome and Safari desk/laptop) now use the advanced Web Audio API to handle sound. Firefox still uses standard HTML5 audio, but subjectively the two seem to function identically. However, Web Audio provides a wide range of advanced audio effects (spatialization, filters, etc) that will be added to Perlenspiel when Web Audio becomes part of the HTML5 standard.

Running out of audio channels is still possible with the new audio system, but far less likely. When it does happen, you will no longer see an error message. The added sounds just won't play. If a call to PS.AudioPlay() caused the overflow, it will silently return PS.ERROR.

3. The default audio volume is now 0.5 (50%) instead of 1.0 (100%). This will help prevent clipping when many audio files are being played at the same time.

4. The documentation of PS.AudioPlay() has been expanded to more precisely explain the behavior of stop functions.

5. The documentation incorrectly stated the range of the volume parameter for PS.BeadAudio(). Fixed.

Version 2.2.5 (Released 11.12.12)

1. The mouse wheel fix in the last release caused the space bar to scroll down the window. Fixed.

2. PS.AudioPlay() now accepts PS.DEFAULT (no function) for the optional function parameter.

2. The documentation for PS.AudioLoad() and PS.AudioPlay() has been updated to make it clearer that the path parameter should specify the pathname of the directory containing the sound file, not the pathname of the file itself.

3. PS.Debug() now plays the correct error sound even if the default audio path has been changed.

4. Various parameter checks here and there have been improved to make them more bulletproof.

Version 2.2.4 (Released 11.09.12)

1. The mouse wheel now sends messages to Perlenspiel only when the mouse cursor is over the grid. Otherwise, messages are sent to the browser window, allowing pages to be scrolled up and down.

2. The maximum border width is no longer fixed at 8 pixels. It is now calculated based on the current dimensions of the grid, ensuring that the area of the bead visible inside the border is at least 8x8 pixels.

3. The previous version of the audio system has been re-installed while I figure out why the new, “improved” version doesn't work as well.

4. A .zip archive of the audio library files is now available for those who prefer a local copy for development. You'll find a link in the Audio Library documentation.

Version 2.2.3 (Released 11.06.12)

1. The five calls that expected a multiplexed rgb color value — PS.BeadColor(), PS.BeadBorderColor(), PS.BeadGlyphColor(), PS.BeadFlashColor() and PS.GridBGColor() — will now accept a color specification expressed in any of four parameter formats:

• rgb : integer (single multiplexed rgb value)
• r, g, b: integer (separate r, g and b values)
• [ r, g, b: integer ] (3-element r, g, b array)
• { r, g, b: integer } (table with named r, g, b elements)

These examples show how to use the different parameter formats. They all specify exactly the same color (a dark, autumnal orange).

// a multiplexed rgb value

PS.BeadColor( x, y, 0xFFC040 );

// separate red, green and blue values

PS.BeadColor( x y, 255, 192, 64 );

// three-element array

PS.BeadColor( x, y, [ 255, 192, 64 ] );

// table with named r, g and b elements

PS.BeadColor( x, y, { r: 255, g: 192, b: 64 } );

This change is backwards compatible. Refer to the documentation for the individual calls for more information.

2. Mouse coordinates are now reported correctly when the page is scrolled under Webkit browsers (Chrome, Safari) and Internet Explorer. (It was already working okay in Firefox.)

Version 2.2.2 (Released 11.01.12)

1. Eliminated redundant graphics calls to improve performance.

Version 2.2.1 (Released 10.26.12)

1. PS.ImageData() now assumes its default behavior (no alpha) if PS.DEFAULT is supplied for the alpha parameter.

2. PS.ImageBlit() now accepts an imageData structure with a pixelSize value of 1. In this case, the data array is assumed to contain (width * height) multiplexed RGB values (one per pixel). NOTE: This type of imageData structure is not created by PS.ImageData(), but if you create one yourself, PS.ImageBlit() will display it correctly.

3. A bug (now fixed) prevented copying highlighted text out of the debugger window. (Ctrl+C still doesn't work, but the Copy item in the Edit menu will.)

Version 2.2.0 (Released 10.25.12)

1. The animation system now uses the HTML5 requestAnimationFrame() facility for smoother operation. As a result of this change, the maximum frame rate is now clamped at 60 fps, and the PS.Clock() ticks parameter represents 1/60ths of a second.

2. Beads that have not been explicitly assigned a color now contain the value PS.EMPTY. They appear as fully transparent, showing the current background color. You can assign the value PS.EMPTY to a bead using PS.Color() to make it transparent. The appearance of the border and glyph (if any) are not affected when a bead is set to PS.EMPTY.

3. The audio system has been substantially overhauled.

The Fine Print