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.

.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:

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

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

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

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

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

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

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

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

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

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.swipe ( data, options )

PS.swipe() is called when the player swipes a held-down mouse or finger across or around the grid.

Parameters:

  1. data : object
  2. options : object

The PS.swipe event is a gestural detector. It is fired once after the following sequence of events:

  1. The player presses the mouse button, or touches the screen.
  2. The held-down mouse or finger is moved across the grid.
  3. The mouse button is released, or the finger is raised.

Complete mouse/finger tracking data is provided, with timing.

All of the usual mouse/finger events continue to fire as usual. PS.swipe() fires after the final PS.release() event that ends the gesture.

The data parameter is an object with the following properties:

The .start integer indicates the moment the mouse button or finger was initially pressed, expressed in the number of ticks elapsed since engine startup.

The .end integer indicates the moment the mouse button or finger was finally released, expressed in the number of ticks elapsed since engine startup.

The .duration integer indicates the total duration of the swipe gesture, expressed in ticks.

The .events array contains a chronological sequence of objects that describe the motion of the held-down mouse or finger over the course of the swipe. Each object has the following properties:

The .x and .y integers indicate the zero-based coordinates of a bead which the held-down mouse or finger passed through during the swipe.

The .start integer indicates the moment the mouse button or finger entered or touched the bead, expressed in the number of ticks elapsed since engine startup.

The .end integer indicates the moment the mouse button or finger exited or was released from the bead, expressed in the number of ticks elapsed since engine startup.

The .duration integer indicates the total period of the time spent within the bead, expressed in ticks.

NOTE: If the .x / .y properties of an object in the .events array are set to -1, it indicates a segment of the swipe which occurred outside the perimeter of the grid. The timing parameters of the object are interpreted the same way.

The options parameter is an object with the following properties:

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

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

 

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:

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

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

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

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

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

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" );
   }
};