Keeping Time
Some games, perhaps the one you are developing, are time based. This could mean that a specific challenge in a game has a time limit in which it needs to be completed, or that the entire game itself can only be played for a predetermined amount of time.
The solutions in this chapter will help you create a timer within your game. You will then use that timer to write to the screen, and to exit the game action after expiration. The key component for tracking time within a game is the Android class CountDownTimer(). The CountDownTimer() is a very powerful, yet easy to implement, tool.
17.1 Track Time Within the Game
Problem
The user should only have a set amount of time to complete a task.
How It Works
The key behind establishing a timer is to instantiate a CountDownTimer(). The CountDownTimer() class is a core Android class, and is not dependent upon OpenGL ES. This means that regardless of whether your game is using OpenGL ES 1, 2, or 3, you can easily use the CountDownTimer() in your game. Therefore, the examples in this chapter are OpenGL ES version independent.
The first step is to instantiate the class.
newCountDownTimer(millisecondsInFuture, countDownInterval) {
}
The constructor of the CountDownTime() takes two parameters. The first parameter, millisecondsInFuture, is the overall duration of the timer, in milliseconds. If you want the timer to last for 30 seconds, you would set the millisecondsInFuture to 30000.
new CountDownTimer(30000, countDownInterval) {
}
The second parameter, countDownInterval, specifies when an interval or tickwill be fired. Let’s say you want to perform an action, such as updating a screen or checking the progress of an in-game task periodically. You would set the countDownInterval to something less than the millisecondsInFuture, like so:
new CountDownTimer(30000, 1000) {
}
This code sets up a new CountDownTimer() that will expire in 30 seconds and fire off a tick every 1 second. However, there is a little more coding to do before the timer is complete. You need to override two methods (see Listing 17-1).
Listing 17-1. CountDownTimer()
new CountDownTimer(30000,1000) {
@Override
public void onTick(long millisUntilFinished) {
//perform any interval-based calls here
}
@Override
public void onFinish() {
//perform any clean up or ending of tasks here
};
}
The first method, onTick(), is called after the expiration of every countDownInterval. The second method that you need to override is onFinish(). The onFinish() method is called after the CountDownTimer() has fully expired.
Finally, use the start() method to start the timer. The start() method is called from CountDownTimer() to activate the timer and begin the countdown (see Listing 17-2).
Listing 17-2. start()
newCountDownTimer(30000,1000) {
@Override
public void onTick(long millisUntilFinished) {
}
@Override
public void onFinish() {
};
}.start();
One great use for the onTick() method is to write the time to the screen. For example, using the solutions in Chapter 16, you can set up a sprite sheet with the digits 0 through 9. However, rather than keep score, it can be used to count down the time (see Listing 17-3).
Listing 17-3. Displaying time
new CountDownTimer(30000,1000) {
@Override
public void onTick(long millisUntilFinished) {
switch(millisUntilFinished){
case(29000):
scoreTile.x = 0; //set the x and y to the location of the
scoreTile.y = 0; //correct sprite sheet image for the time digit
break;
...
}
}
@Override
public void onFinish() {
};
}.start();
17.2 Stop the Action When the Time Expires
Solution
Use the onFinish() method of the CountDownTimer() to stop the game when the time expires.
How It Works
To stop the game when the time expires, use the onFinish() method to call your closing routine. Looking back at the recipes in Chapter 4, you most likely have an exit routine that is called from the exit button on the game’s menu.
You can call this same routine from the onFinish() method when the timer expires (see Listing 17-4).
Listing 17-4. Game Exit
new CountDownTimer(30000,1000) {
@Override
public void onTick(long millisUntilFinished) {
}
@Override
public void onFinish() {
gameView.exit(); //call the method that you established for exiting the game
};
}.start();
17.3 Stop the Timer When a Task Completes
Problem
The game timer continues to run after the player has completed the required task.
Solution
Use the cancel() method of the CountDownTimer() to stop the timer when the player finishes a task.
How It Works
Your game might be set up in such a way that the player is required to complete a task, or series of tasks, within a given amount of time. The question then is, how do you stop the timer when the tasks are complete?
The CountDownTimer contains a cancel() method that can be called when you need to stop the timer. The key to using this method effectively is to instantiate a CountDownTimer and scope it so it can be called from other methods in your game. Listing 17-5 shows you how to instantiate the CountDownTimer (slightly different from how it was done in Recipe 17.1) and then stop the timer using cancel().
Listing 17-5. Cancel CountDownTimer
private CountDownTimer cdt;
...
cdt = new CountDownTimer(30000,1000) {
@Override
public void onTick(long millisUntilFinished) {
}
@Override
public void onFinish() {
//something bad happens to the player for failing
};
}.start();
... //rest of your game code
private checkTask(){
//this is a method that you create to check if the player
//has finished the required task
if(taskCompleted){
cdt.cancel();
}
}