Learning 16: Timers

This page describes the commands for creating and controlling timers, which allow you to run code periodically.


PS.timerStart ( ticks, exec, ... )

Up to now, you've only been able to run code in direct response to one of Perlenspiel's event calls, such as PS.touch() or PS.keyDown().

The PS.timerStart() command lets you instruct Perlenspiel to run a function periodically, at any time interval you specify.

The required ticks parameter specifies the time interval, expressed in 60ths of a second. It must be an integer greater than or equal to one (1). Non-integral values are floored.

If ticks is PS.DEFAULT, the default delay value (60, one second) is applied.

The required exec parameter must be a valid function reference.

Any parameters supplied to PS.timerStart() after the exec parameter are passed as arguments to the exec function every time it is called.

Usage notes

1. Timer functions must be kept as short and fast as possible. If you try to execute too much code inside a timer function, or run too many timer functions simultaneously, serious performance and synchronization issues are likely to occur.

2. If you intend to stop a timer function you have started, you must save the unique identifier PS.timerStart() returns inside a variable that will be in scope when PS.timerStop() is subsequently called. You can use a global variable for this, although there are other, more elegant methods. See the demo below for an example.

3. Any values returned by timer functions are generally ignored. However, if a timer function returns the value PS.ERROR, PS.timerStop() is immediately called on that timer.


See the description of PS.timerStop() below for example code and a demonstration of how timers work.

Return value

PS.timerStart() returns a string uniquely identifying the newly created timer, or PS.ERROR if an error occurs.


PS.timerStop ( timer )

The PS.timerStop() command stops a timer function previously started by a call to PS.timerStart().

The required timer parameter should be unique string identifier of the type returned by PS.timerStart().

An error occurs if timer is not a valid timer identifier.

Once a timer is stopped with a call to PS.timerStop(), the identifier of the stopped timer becomes invalid, and should not be used again.

// Define a timer function that plays
// a click sound

var myFunc = function () {
 PS.audioPlay( "fx_click" );

// Start a timer that runs the function
// once every second

var myTimer = PS.timerStart( 60, myFunc );

// Stop the previously started timer

PS.timerStop( myTimer );


This demo creates a grid with single bead containing a clock glyph. Touch the bead to initiate a dramatic 5-second countdown.

[Run Demo]

var G; // establish game namespace

// Self-invoking function initializes G
// and encapsulates other data and functions

( function () {
 // Private variables

 var timer = null; // timer id, null if none
 var count = 0; // countdown value

 // Private timer function, called every second

 var tick = function () {
 count -= 1;
 if ( count < 1 ) { // reached zero?
 PS.timerStop( timer );
 timer = null; // allows restart
 PS.audioPlay( "fx_bang" );
 PS.color( 0, 0, PS.COLOR_GRAY ); // flash bead
 G.nuke(); // show nuke
 PS.statusText( "Touch bead to restart timer" );
 else {
 // Set glyph to numeral
 PS.glyph( 0, 0, count.toString() );
 PS.glyphColor( 0, 0, PS.COLOR_YELLOW );
 PS.audioPlay( "fx_click" );

 // Initialize public G object

 G = {
 // Show nuke glyph

 nuke : function () {
 PS.glyph( 0, 0, 0x2622 ); // nuke
 PS.glyphColor( 0, 0, PS.COLOR_RED );

 // Start the timer if not already running

 start : function () {
 if ( !timer ) { // null if not running
 count = 6; // reset count
 timer = PS.timerStart( 60, tick );
 PS.statusText( "Countdown started!" );
 PS.audioPlay( "fx_ding" );
}() )

PS.init = function( system, options ) {
 PS.gridSize( 1, 1 );
 PS.gridColor( PS.COLOR_BLACK );
 PS.color( 0, 0, PS.COLOR_GRAY );
 PS.border( 0, 0, 0 ); // no border
 G.nuke(); // show nuke

 // Use fader to flash bead at
 // end of countdown

 PS.fade( 0, 0, 30, { rgb : PS.COLOR_WHITE } );

 // Preload required sounds

 PS.audioLoad( "fx_ding" );
 PS.audioLoad( "fx_click" );
 PS.audioLoad( "fx_bang" );

 PS.statusColor( PS.COLOR_WHITE );
 PS.statusText( "Touch bead to start timer" );

PS.touch = function( x, y, data, options ) {

Note how much of this demo's code is encapsulated according to the method explained in 13: Coding strategies. Only two functions, G.nuke() and G.start(), are exposed to Perlenspiel.

See 20: Lines and paths for demonstrations of how timers can be used in animation.

Return value

PS.timerStop() returns timer, or PS.ERROR if an error occurs.


Terms to know

Next: Images