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.
Demonstration
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.
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.
// EXAMPLE
// 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 );
Demonstration
This demo creates a grid with single bead containing a clock glyph. Touch the bead to initiate a dramatic 5-second countdown.
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 ) {
G.start();
};
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.
Next: Images