API | Events

These functions are called by the Perlenspiel engine when a user event occurs, and when a game is initialized.

By responding to these events, you can make toys and games.

Any values returned by these functions are ignored.

 

PS.init ( system, options )

PS.init() is called once when a game is initialized.

Parameters:

  1. system : object
  2. options : object

Every game should include a PS.init() function. A warning is issued if it is not present.

Your PS.init() function should immediately call PS.gridSize() to establish the dimensions of the grid, followed by any other required game initialization.

If PS.gridSize() is not called, a default 8x8 grid is created.

The system parameter provides information about the Perlenspiel engine, audio engine, host platform and available I/O affordances. It is an object with the following properties:

.engine

The name of the engine running your game code, usually “Perlenspiel.”

.major / .minor / .revision

Three integers indicating the current version of the game engine.

.audio

An object identifying the audio engine and its capabilities. It contains the following properties:

audio.engine

The name of the audio engine, usually “AQ.”

audio.major / audio.minor / audio.revision

Three integers indicating the version of the audio engine.

audio.fileTypes

An array of strings indicating the file types that can be played by the audio engine in the context of the current browser. These will be a combination of "ogg", "mp3" and/or "wav".

.host

An object identifying the host platform. It contains the following properties:

The host.app and host.version strings contain the name and version of the application running the game engine, usually a Web browser.

The host.os string identifies the operating system hosting the application.

.inputs

An object indicating the available input affordances. It can contain any of the following properties:

The input.touch property is true if a touchscreen is available, else false.

The options parameter is currently unused. It is reserved for future expansion.

A startup warning occurs if PS.init() is undefined.

// EXAMPLE:
// Set up a 10 x 10 grid on game initialization
// Saves system info in a global for later reference

var mySystem;

PS.init = function( system, options ) {
   "use strict";

   PS.gridSize( 10, 10 );

   mySystem = system;

   // additional init code goes here
};

 

PS.touch ( x, y, data, options )

PS.touch() is called when the mouse button is clicked on a bead, or when a finger touches a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : a Javascript value
  4. options : object

The x and y parameters contain the zero-based coordinates of the bead.

The data parameter contains a value previously assigned to the bead by PS.data(). If no data has been assigned to the bead, data is set to zero (0).

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if PS.touch() is undefined.

// EXAMPLE:
// Change a clicked or touched bead to red

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

   PS.color( x, y, PS.COLOR_RED );
};

 

PS.release ( x, y, data, options )

PS.release() is called when the mouse button is released over a bead, or when a pressed finger is lifted from a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : a Javascript value
  4. options : object

The x and y parameters contain the zero-based coordinates of the bead.

The data parameter contains a value previously assigned to the bead by PS.data(). If no data has been assigned to the bead, data is set to zero (0).

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if PS.release() is undefined.

// EXAMPLE:
// Change a released bead to white

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

   PS.color( x, y, PS.COLOR_WHITE );
};

 

PS.enter ( x, y, data, options )

PS.enter() is called when the mouse cursor, or a finger touching the screen, enters a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : a Javascript value
  4. options : object

The x and y parameters contain the zero-based coordinates of the bead.

The data parameter contains a value previously assigned to the bead by PS.data(). If no data has been assigned to the bead, data is set to zero (0).

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if PS.enter() is undefined.

// EXAMPLE:
// Change bead to blue on mouse or touch enter

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

   PS.color( x, y, PS.COLOR_BLUE );
};

 

PS.exit ( x, y, data, options )

PS.exit() is called when the mouse cursor, or a finger touching the screen, exits a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : a Javascript value
  4. options : object

The x and y parameters contain the zero-based coordinates of the bead.

The data parameter contains a value previously assigned to the bead by PS.data(). If no data has been assigned to the bead, data is set to zero (0).

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if PS.exit() is undefined.

// EXAMPLE:
// Change bead to green on mouse or touch exit

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

   PS.color( x, y, PS.COLOR_GREEN );
};

 

PS.exitGrid ( options )

PS.exitGrid() is called when the mouse cursor, or a finger touching the screen, exits the perimeter of the grid.

Parameters:

  1. options : object

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if PS.exitGrid() is undefined.

// EXAMPLE:
// Play scream when cursor exits grid

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

   PS.playSound( "fx_wilhelm" );
};

 

PS.keyDown ( key, shift, ctrl, options )

PS.keyDown() is called when a key is pressed on the keyboard.

Parameters:

  1. key : integer
  2. shift : boolean
  3. ctrl : boolean
  4. options : object

PS.keyDown() is called only on platforms with a hardware keyboard.

The key parameter contains an integer indicating which key was pressed.

If the key is one of the standard keyboard keys, (upper-case and lower-case alphabetics, numbers or punctation), the key parameter contains the corresponding ASCII keycode.

If the key is an arrow key, the key parameter contains one of the following constants:

If the key is on the numeric keypad, the key parameter contains one of the following constants:

If the key is function key 1-10, the key parameter contains one of the following constants:

The following auxiliary keys are also recognized:

The shift parameter contains true if the shift key is held down, otherwise false.

The ctrl parameter contains true if the control key is held down, otherwise false.

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if a hardware keyboard is available and PS.keyDown() is undefined.

// EXAMPLE:
// Report pressed keycode in status box

PS.keyDown = function( key, shift, ctrl, options ) {
   "use strict";

   PS.statusText( "Pressed key = " + key );
};

 

PS.keyUp ( key, shift, ctrl, options )

PS.keyUp() is called when a key is released.

Parameters:

  1. key : integer
  2. shift : boolean
  3. ctrl : boolean
  4. options : object

PS.keyUp() is called only on platforms with a hardware keyboard.

The key parameter contains an integer indicating which key was released.

If the key is one of the standard keyboard keys, (upper-case and lower-case alphabetics, numbers or punctation), the key parameter contains the corresponding ASCII keycode.

The special keycodes passed by PS.keyUp() are the same as those used for PS.keyDown().

The shift parameter contains true if the shift key is held down, otherwise false.

The ctrl parameter contains true if the control key is held down, otherwise false.

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if a hardware keyboard is available and PS.keyUp() is undefined.

// EXAMPLE:
// Report released keycode in status box

PS.keyUp = function( key, shift, ctrl, options ) {
   "use strict";

   PS.statusText( "Released key = " + key );
};

 

PS.input ( device, options )

PS.input() is called when a input device event is detected.

Parameters:

  1. device : object
  2. options : object

Perlenspiel games are usually developed and played on a Web browser, using a mouse and/or keyboard for input.

As the engine migrates to other platforms, it will be able to respond to events from a broader range of input devices, including game controllers, tilt sensors, touchpads, and voice commands. PS.input() provides a flexible way to report these events to your game.

The device parameter is an object containing one or more of the following properties:

When an event is detected on an input device, PS.input() is called with the associated device property set to a value identifying the event.

For example: When the mouse wheel is scrolled, PS.input() is called with the .wheel property of device set to either PS.WHEEL_FORWARD or PS.WHEEL_BACKWARD, depending on the direction of the scroll.

As new input devices are supported, the associated device properties and event values will be documented here.

More than one property can potentially be set in a single call to PS.input(), so be sure your code is able to respond to simultaneous events.

The options parameter is currently unused. It is reserved for future expansion.

A startup warning is displayed if a supported special input device is available and PS.input() is undefined.

// EXAMPLE:
// Report mouse wheel movement in status line

PS.input = function( device, options ) {
   "use strict";
   var dir;

   dir = device.wheel;
   if ( dir === PS.WHEEL_FORWARD ) {
      PS.statusText( "Wheel scrolled forward" );
   }
   else if ( dir === PS.WHEEL_BACKWARD ) {
      PS.statusText( "Wheel scrolled backward" );
   }
};