API | Events

These event-handling functions, normally defined in the devkit’s game.js file, are called when the engine is initialized or shut down, and when user activity is detected.

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.

The .host.mobile property will be true on mobile devices, else false.

.inputs

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

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

.date

An object indicating the date and time the Perlenspiel engine was initialized, in the same format returned by a call to PS.date().

The options parameter is an object with the following properties:

A startup warning is displayed if PS.init() is defined as anything other than a function.

// 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 ) {
 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 an object with the following properties:

A startup warning is displayed if PS.touch() is defined as anything other than a function.

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

PS.touch = function( x, y, data, options ) {
 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 an object with the following properties:

The .time integer indicates the moment PS.release() was called, expressed in the number of ticks elapsed since engine startup.

A startup warning is displayed if PS.release() is defined as anything other than a function.

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

PS.release = function( x, y, data, options ) {
 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 an object with the following properties:

A startup warning is displayed if PS.enter() is defined as anything other than a function.

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

PS.enter = function( x, y, data, options ) {
 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 an object with the following properties:

A startup warning is displayed if PS.exit() is defined as anything other than a function.

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

PS.exit = function( x, y, data, options ) {
 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 an object with the following properties:

A startup warning is displayed if PS.exitGrid() is defined as anything other than a function.

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

PS.exitGrid = function( options ) {
 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 an object with the following properties:

A startup warning is displayed if PS.keyDown() is defined as anything other than a function.

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

PS.keyDown = function( key, shift, ctrl, options ) {
 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 an object with the following properties:

A startup warning is displayed if PS.keyUp() is defined as anything other than a function.

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

PS.keyUp = function( key, shift, ctrl, options ) {
 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 upgraded to respond to events from a broader range of input devices, including touch screens, game controllers, tilt sensors and voice commands. PS.input() provides a flexible way to report these events to your game.

When an event is detected on an input device other than the mouse, touchscreen or keyboard, PS.input() is called with the device argument set to an object containing one or more of the following properties:

The specific values returned by different input devices are described below.

[Mouse]

Mouse wheel events

When the mouse wheel is scrolled forward or backward, PS.input() is called with the .wheel property of device set to the string constant PS.WHEEL_FORWARD or PS.WHEEL_BACKWARD, depending on the direction of the scroll.

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

PS.input = function( device, options ) {
 var event;

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

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 multiple simultaneous events.

The options parameter is an object with the following properties:

A startup warning is displayed if PS.input() is defined as anything other than a function.

 

PS.shutdown ( options )

PS.shutdown() is called when the browser page running Perlenspiel is about to close.

Parameters:

  1. options : object

The options parameter is an object with the following properties:

A startup warning is displayed if PS.shutdown() is defined as anything other than a function.

// EXAMPLE:
// Announce engine shutdown in status line

PS.shutdown = function( options ) {
 PS.statusText( "Dave. My mind is going." );
};