Reference | Events

These functions are called by the Perlenspiel engine when a mouse, keyboard or clock event occurs, and when a game is initialized.

Any values returned by these functions are ignored.

PS.Init ( options )

Called once when a game is initialized.

Parameters:

  1. options : object

Every game normally includes a PS.Init() function, which calls PS.GridSize() to establish the dimensions of the grid, together with any other required game initialization.

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

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

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

Example:

PS.Init = function ( options )
{
    // set up a 10 x 10 grid

    PS.GridSize( 10, 10 );

    // additional init code goes here
};

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

Called when a mouse button is clicked over an active bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : value

The x and y parameters contain the zero-based x and y position of the bead on the grid.

The data parameter contains the data value previously assigned to the bead. If no data value has been assigned to the bead, the data parameter will contain zero (0).

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

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

Example:

PS.Click = function ( x, y, data, options )
{
    // change the clicked bead to red

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

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

Called when a mouse button is released over a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : value

The x and y parameters contain the zero-based x and y position of the bead on the grid.

The data parameter contains the data value previously assigned to the bead. If no data value has been assigned to the bead, the data parameter will contain 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:

PS.Release = function ( x, y, data, options )
{
    // change bead to white on button release

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

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

Called when the mouse cursor enters a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : value

The x and y parameters contain the zero-based x and y position of the bead on the grid.

The data parameter contains the data value previously assigned to the bead. If no data value has been assigned to the bead, the data parameter will contain 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:

PS.Enter = function ( x, y, data, options )
{
    // change bead to blue on mouse enter

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

PS.Leave ( x, y, alpha, options )

Called when the mouse cursor leaves a bead.

Parameters:

  1. x : integer
  2. y : integer
  3. data : value

The x and y parameters contain the zero-based x and y position of the bead on the grid.

The data parameter contains the data value previously assigned to the bead. If no data value has been assigned to the bead, the data parameter will contain zero (0).

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

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

Example:

PS.Leave = function ( x, y, data, options )
{
    // change bead to green on mouse leave

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

PS.Wheel ( delta, options )

Called when the mouse wheel is moved forward or backward.

Parameters:

  1. delta : integer

PS.Wheel() is called only when the mouse cursor is positioned over the grid.

The delta parameter contains the constant PS.FORWARD if the mouse wheel was moved forward, or PS.BACKWARD if it was moved backward.

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

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

Example:

PS.Wheel = function ( delta, options )
{
    // report wheel motion in status line

    if ( delta === PS.FORWARD )
    {
        PS.StatusText( "Forward" );
    }
    else
    {
        PS.StatusText( "Backward" );
    }
};

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

Called when a key is pressed on the keyboard.

Parameters:

  1. key : integer
  2. shift : boolean
  3. ctrl : boolean

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 escape key (Esc) is pressed, the key parameter contains the constant PS.ESCAPE.

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:

NOTE: Function keys 11 and 12 are not supported.

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 PS.KeyDown() is undefined.

Example:

PS.KeyDown = function ( key, shift, ctrl )
{
    // report keycode in status box

    PS.StatusText( "Key = " + key );
};

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

Called when a key is released on the keyboard.

Parameters:

  1. key : integer
  2. shift : boolean
  3. ctrl : boolean

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() above.

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 PS.KeyUp() is undefined.

PS.Tick ( options )

Called on every clock pulse.

Parameters:

  1. options : object

If the system clock has been activated with a previous call to PS.Clock(), this function will be called at the frequency specified by the PS.Clock() call.

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

A PS.Tick() function should be kept as short and fast as possible to avoid slowing the engine.

Example:

PS.Init = function ( options )
{
    // set up 10x10 grid

    PS.GridSize( 10, 10 );

    // preload a tick sound

    PS.AudioLoad( "fx_tick" );

    // start a once-per-second clock

    PS.Clock( 60 );
};

// Here is the PS.Tick() function
// that will respond to the clock

PS.Tick = function ( options )
{
    // play the tick sound

    PS.AudioPlay( "fx_tick" );
};