Event handling

1. Introduction

A game engine would be of little use if we could only use it to draw something on the screen. To write a full-fledged game, we need it to interact with the user! To be more precise, our program should track user actions and respond to them.

To do this, the CodeGym game engine has special methods that it calls when the user clicks the mouse buttons or keyboard keys.

The point of the class is that you write these methods yourself, and then the CodeGym game engine is responsible for calling them. All you need is to declare these methods in your code. This is easier to do than it sounds.

2. Working with the mouse

The game engine has two methods for working with the mouse:

void onMouseLeftClick(int x, int y)

void onMouseRightClick(int x, int y)

You simply declare these methods in your own class that inherits the Game class. And then write whatever code you want in these methods. The game engine will call these methods when the user clicks the mouse buttons.

onMouseLeftClick(int x, int y) is called by the engine when the left mouse button is clicked. Its parameters are the coordinates of the cell of the playing field where the click occurred. The coordinates of the top left cell are (0,0). To use this method, you need to override it, placing the @Override annotation before the method name.

onMouseRightClick(int x, int y) is called when right mouse button is clicked. It works similar to the onMouseLeftClick(int x, int y) method.

Examples of using these methods:

import com.codegym.engine.cell.Color;
import com.codegym.engine.cell.Game;
import com.codegym.engine.cell.Key;

public class MySuperGame extends Game {
   @Override
   public void initialize() {
      // Set the size of the playing field to 3x3
      setScreenSize(3, 3);

      // Paint the playing field white
      for (int x = 0; x < 3; x++) {
         for (int y = 0; y < 3; y++) {
            setCellColor(x, y, Color.WHITE);
         }
      }
   }

   @Override
   public void onMouseLeftClick(int x, int y) {
      // Put a "X" in the cell that was clicked with the left mouse button
      setCellValue(x, y, "X");
   }

   @Override
   public void onMouseRightClick(int x, int y) {
      // Clear the cell that was clicked with the right mouse button
      setCellValue(x, y, "");
   }
}

In the example above, we declared both methods: onMouseLeftClick() and onMouseRightClick(). The first method will be called when the user clicks the left mouse button on cells of the playing field. The second method will be called when the right mouse button is clicked.

As arguments, the CodeGym game engine will pass the (x, y) coordinates of the cell of the playing field where the mouse was clicked.

3. Working with the keyboard

The game engine has two methods for working with the keyboard:

void onKeyPress(Key key);

void onKeyReleased(Key key);

If you want to do something when the user presses a key, you just need to declare these methods in your class that inherits the Game class.

You write your code in these methods, and the game engine will call them when the user presses (or releases) a key.

onKeyPress(Key key) is called when any key is pressed. The value of the pressed key (or Key.UNKNOWN) is passed to the method as the key parameter. To use this method, you need to override it, placing the @Override annotation before the method name.

onKeyReleased(Key key) is called when any key is released. The value of the corresponding key (or Key.UNKNOWN) gets assigned to the key parameter. To use this method, you need to override it, placing the @Override annotation before the method name.

Examples of using these methods:

import com.codegym.engine.cell.Color;
import com.codegym.engine.cell.Game;
import com.codegym.engine.cell.Key;

public class MySuperGame extends Game {
   @Override
   public void initialize() {
      // Set the size of the playing field to 3x3
      setScreenSize(3, 3);

      // Paint the playing field white
      for (int x = 0; x < 3; x++) {
         for (int y = 0; y < 3; y++) {
            setCellColor(x, y, Color.WHITE);
         }
      }
   }

   @Override
   public void onKeyPress(Key key) {
      // When the spacebar is pressed, the center cell turns yellow
      if (key == Key.SPACE) {
         setCellColor(1, 1, Color.YELLOW);
      }
   }

   @Override
   public void onKeyReleased(Key key) {
      // When the spacebar is released, the center cell returns to white
      if (key == Key.SPACE) {
         setCellColor(1, 1, Color.WHITE);
      }
   }
}

4. List of all supported keys

When the CodeGym engine calls the onKeyPress() and onKeyReleased() methods, it passes information to them about the pressed (released) key. To do this, the CodeGym engine has a special type called Key.

In the current version of the engine, the Key type only supports a limited set of 9 values:

Key.ENTER

Key.ESCAPE

Key.PAUSE

Key.SPACE

Key.LEFT

Key.RIGHT

Key.UP

Key.DOWN

Key.UNKNOWN

If the player presses the space bar, then the onKeyPress() method will be called with Key.SPACE as the parameter. If the user presses the left arrow, then the parameter will be Key.LEFT. If the user presses any key that is not in the list above, then the onKeyPress() method will be called with Key.UNKNOWN as the parameter.

The issue here is that the existing CodeGym games were designed to run on a phone. Instead of the standard keyboard, we have 8 virtual buttons:

5. Working with a timer

Many games take place in real time, i.e. the user might do nothing, but certain events are still occur in the game. To allow you to implement such games, we added a timer to the game engine.

Here's how it works: you turn on the timer and set the time after which it should be triggered. For example, 500 ms. Then, every half second, the CodeGym game engine will call the onTurn() method. An infinite number of times — until the timer is turned off.

How do you use a timer?

1. Turn on the timer

To turn on the timer, we have the void setTurnTimer(int timeMs) method. The method takes as an argument the duration (in milliseconds or 1/1000s of a second) of the interval between callbacks. You just need to call this method once, and the game engine will start calling the onTurn() method every timeMs milliseconds.

2. Override the onTurn(int) method

To do this, you must declare a void onTurn(int step) method in a class that inherits the Game class. The game engine will call this method. With each call, the engine passes the a sequential number that identifies the method call (1, 2, 3, ...).

3. Turn off the timer

If the timer is no longer needed, for example because the user has finished the game, then it can be turned off. To do this, simply call the stopTurnTimer() method.

4 Accelerate/change the timer

In some games, the frequency of events increases regularly, so it would be convenient to be able to speed up our timer, i.e. reduce the time between callbacks. And nothing could be easier — just call setTurnTimer(int timeMs) again with the new value, and the time between calls to onTurn() will change.

Example:

import com.codegym.engine.cell.Color;
import com.codegym.engine.cell.Game;

public class MySuperGame extends Game {
   ...
   @Override
   public void initialize() {
      // Create a 3x3 playing field
      setScreenSize(3, 3);
      showGrid(false);
      setCellValueEx(1, 1, Color.BLUE, "X", Color.ORANGE, 50);

      setTurnTimer(500); // Turn on the timer. The interval between callbacks is 500ms.
   }

   @Override
   public void onTurn(int step) {
      if (step == 100) {
         stopTurnTimer(); // If this is the 100th callback, then turn off the timer
      }

      if (step % 2 == 1) {
         // If this is an odd calllback, then set the cell background to red
         setCellColor(1, 1, Color.RED);
      } else {
         // If this is an even callback, then set the cell background to blue
         setCellColor(1, 1, Color.BLUE);
      }
   }
   ...
}

In this simple example, we created a field that is 3 cells by 3 cells. Then we turned on a timer that will call the onTurn() method every half second.

Here, the color of the central cell will change every half second. The text of the cell will not change. After 50 seconds (100 callbacks), the color will stop changing and the timer will turn off.