Games section on CodeGym: Event handling

"Games" from CodeGym is a new section with large interesting tasks where you create your own versions of popular games. It's simple: each game project is divided into subtasks. Complete them one by one and the game is done. You can share it on social networks and invite your friends to play. In this article, we'll describe in detail the event handling methods used to write games.

1. 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 class that inherits Game, and add any code you want to them. The game engine will call them when the user clicks mouse buttons.

1. onMouseLeftClick(int x, int y) — 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 top left cell has coordinates (0, 0). You need to override this method to use it.

2. onMouseRightClick(int x, int y) — called when the right mouse button is clicked. This method works like the onMouseLeftClick(int x, int y) method.

Here's an example 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) {
        // Set "X" in the cell where the left mouse click occurred
        setCellValue(x, y, "X");
    }

    @Override
    public void onMouseRightClick(int x, int y) {
        // Clear the cell where the right mouse click occurred
        setCellValue(x, y, "");
    }
}

2. 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 something to happen when the user presses a key, declare these methods in your class that inherits Game, and add your code to them. The game engine will call them when the user presses or releases a key.

1. onKeyPress(Key key) — called when any key is pressed. The key parameter is the pressed key (or Key.UNKNOWN).

2. onKeyReleased(Key key) — called when any key is released. The key parameter is the corresponding key (or Key.UNKNOWN).

Here's an example 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 space bar is pressed, the center cell turns yellow
        if (key == Key.SPACE) {
            setCellColor(1, 1, Color.YELLOW);
        }
    }

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

Important! In the current version of the game engine, the Key type has a limited set of nine values:

3. Working with the timer

Many games happen in real time, i.e. even if the user does nothing, events still occur in the game. To enable you to implement such games, we added a timer to the game engine. It works something like this: you turn on the timer and set the timer interval. For example, 500 milliseconds. Then, every half second the game engine calls the onTurnTimer() method. Again and again forever — until the timer is turned off. So how do you use the timer?

1. Turn on the timer.

   To do this, there is a special void setTurnTimer(int timeMs) method. The method takes as an argument the interval between calls in milliseconds (1 millisecond = 1/1000 second). You only need to call it once, and the game engine will start calling the onTurn() method every timeMs milliseconds.

2. Override the onTurn(int) method.

   To do this, you need to declare a void onTurn(int step) method in the class that inherits Game. This method will be called by the game engine. What's more, with each call the game engine will pass to the method a sequential identifier for the call (1, 2, 3, …).

3. Turn off the timer.

   If the timer is no longer needed, for example, when the user completes the game, you can turn it off. To do this, you simply need to call the stopTurnTimer() method.

4. Accelerate or change the timer.

   In some games, the rate at which events occur is constantly accelerating, so it would be convenient to speed up our timer (reduce the time between calls). Nothing could be easier: call setTurnTimer(int timeMs) once again with a new value, and the time between onTurn() calls will change.

For example:

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

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

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

    @Override
    public void onTurn(int step) {
        if(step == 100) {
            stopTurnTimer();  // If 100 calls have been made, turn off the timer
        }

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

        }
    }
    …
}

In this simple example, we created a field that is 3 cells x 3 cells. Then we started a timer that will call the onTurn() method every half second. Every half second, the cell color will change, but its content will not change. After 50 seconds, the color will no longer change. That's all for now! If you want to learn more about the "Games" section, here is some useful documentation that can help: