Introduction to Keyboard Events in Quorum
In this tutorial, we will learn about using player input and the game engine's event system. With these tools, our games will be able to react to keyboard input.
Handling Input with EventsThe second method for getting player input is known as event handling. Event handling is a technique in which we designate code blocks that run whenever a specific event occurs, such as the mouse being clicked or a key being pressed. When we use event handling, we rely on the game engine to notify us when an event occurs by automatically calling certain predefined actions.
The Difference Between Polling and Event Handling
Most games, especially large games, use event handling instead of polling to detect input. To understand why, it’s helpful to think of an analogy for how the two approaches work.
Consider the situation where you want to get a book from the library, but it is currently checked out. One approach (polling) is to call the library once every hour and ask the librarian if the book has been returned yet. The other approach (event handling) is to register your request with the librarian and respond when you are notified that the book is available.
From this example, you can see that event handling is much more efficient than input polling, because it doesn’t waste time repeatedly checking. There are cases where it isn't noticeable which approach you use and others where it is necessary to poll, but the event handling approach should generally be preferred.
To see how events can be used for keyboard input, we will use another sample program. This program will play a sound when the space bar is pressed, and a different sound when it is released. We will use the same audio files in the previous sample, or you can use your own.
Our code for this sample uses two classes, which are each in a separate file. Let's start by looking at the Soundboard class.
use Libraries.Interface.Events.KeyboardListener use Libraries.Interface.Events.KeyboardEvent use Libraries.Sound.Audio class Soundboard is KeyboardListener Audio pressedSound Audio releasedSound on create // We load our sounds when this object is created. pressedSound:Load("AudioFiles/lightSound.wav") releasedSound:Load("AudioFiles/heavySound.wav") end // This action will be called when any keyboard key is pressed. action PressedKey(KeyboardEvent event) if event:keyCode = event:SPACE pressedSound:Play() end end // This action will be called when any keyboard key is released. action ReleasedKey(KeyboardEvent event) if event:keyCode = event:SPACE releasedSound:Play() end end end
An important thing to note about this code is in the first line (the class definition) where we specify that the class is a KeyboardListener (
class Soundboard is KeyboardListener ). By inheriting from the KeyboardListener class, our class gets special actions that can "listen" for KeyboardEvents. This gives us certain action definitions that the engine will automatically call when a keyboard event occurs. If we choose to listen and respond to an event we simply put our actions inside these actions.
In any class that inherits from KeyboardListener, the PressedKey action will be called automatically by the engine when the user presses a key on the keyboard. The PressedKey action must take a KeyboardEvent as a parameter which is passed by the engine. This KeyboardEvent contains a field
keyCode that represents what key was pressed. A KeyboardEvent also contains values representing all possible supported keys on a keyboard, which we use in our example to make sure that the key that was pressed is the space bar. We can choose to listen to whichever events we want to and respond to whichever keys we specify. If a key is pressed that we don't respond to, the event is ignored by our code.
action PressedKey(KeyboardEvent event) if event:keyCode = event:SPACE pressedSound:Play() end end
In any class that inherits from KeyboardListener, the ReleasedKey action will be called automatically by the engine when the user releases a key on the keyboard. Let’s start by looking at the Soundboard class.Like the PressedKey action, this action must take a KeyboardEvent as a parameter which will provide the information on which key was released.
action ReleasedKey(KeyboardEvent event) if event:keyCode = event:SPACE releasedSound:Play() end end
With this class ready to receive KeyboardEvents, we can set up our Main class as follows:
use Libraries.Game.Game class Main is Game // We create a object using our Soundboard listener class. Soundboard board action Main StartGame() end action CreateGame // We add the listener to our game. This has the effect of letting the engine know //that the Soundboard object should be notified of keyboard events. AddKeyboardListener(board) end action Update(number seconds) end end
The most important addition to the Main class is
AddKeyboardListener(board) . This action tells the game engine that our Soundboard object is ready to start receiving KeyboardEvents. Now our program will "get"events from the keyboard (meaning that the engine will call the actions we specified in the Soundboard class when events occur).
In the next tutorial, we will discuss Mouse Events in Quorum, which describes How to use mouse events events in our games..