Access Keys:
Skip to content (Access Key - 0)

Kobold2D™ Documentation

The All-In-One, Ready-To-Go development solution for cocos2d-iphone developers. Open source, ARC enabled, for iOS & Mac OS.

Switch to: Japanese Documentation

Level Up!

The Learn Cocos2D Book

Line-Drawing Game Starterkit

Excellent template code for creating your own Line-Drawing game, similar to popular titles such as Flight Control, Harbor Master, and Pirate Bay.

The iPhone RPG Engine

Rapidly create your own RPG or action-adventure game with this complete starter kit. Includes an ebook, game source code and a royalty-free art package.

KKInput supports testing the state of the Keyboard keys. The keyboard is accessed with virtual key codes in a locale-independent manner.

About Locale Independent Keyboard Input

It is a common mistake among beginning game developers to assume that testing for the key character "/" will work correctly on all keyboards. Assume the following (bad) example code:

This works fine on a US Keyboard. You press the key that's left to the Right Shift key. However, most european players would have to press Shift+7 in order to shoot. That's because the key to the left of the Right Shift key prints a different character, for example on German keyboards it will print the "-" character. Clearly you'll want to avoid that!

Any keyboard character can be mapped to a different key or key combination depending on the user's locale. Just about every nationality has its own keyboard layout! That's why you don't want to test for the characters the keyboard sends to the operating system, you'll want to test specifically for a key's KeyCode that uniquely identifies each key on all keyboards.

Games rely on these so-called virtual keycodes to treat the Keyboard as an input device where each key has a unique key code that's the same for all keyboards and all locale settings. Games don't care what's printed on the key to the left of the Right Shift key, a game wants to ensure that they keyboard to game actions mapping is the same for all locales.

Any Key Down or Up

The simplest way to check for Keyboard input is obviously the "any" key. You know, that particular key one always has to press to continue, but that's never been on any keyboard.

Joking aside, if all you need to test if a key is pressed, either for simple menus or for a "pre-screening" if it's worthwhile to perform more thorough keyboard input checks, use one of these methods (properties actually):

In case you're wondering why there's no isAnyKeyUp, that's because it's not very meaningful. Think about it. A common keyboard has around and often times over 100 keys. One of those keys is very likely going to be "up" (as in: not pressed) until the day humans developed tentacle limbs.

Testing for a particular Key press

KKInput has these methods to test for key down/up states by providing a virtual keycode for the desired key:

If you want to test for a combination of keys simply && (logical AND) the queries together. Likewise, if you need to respond to alternate keys doing the same thing use || (logical OR):

Adding key combos and alternate keys as an array of keycodes may be available in the future, please refer to the status of this task.

Key presses with modifiers

Modifiers are those "special" keys like Command, Control, Shift and others, defined in the KKModifierFlag enum.

You have two ways of checking whether a key and one or more modifier keys have been pressed down. The Modifier keys have also virtual key codes, so you can just and them together as in the first part of the following code example. The other way is to use the modifier flags enum. I'll explain the major issue with the first approach after the code - maybe you can already guess it?

The problem with #1) is in particular related to the "ThisFrame" check. What you want to achieve is to test whether the modifier keys (Control, Command and Shift) are held down when the "C" key is pressed "ThisFrame". The first method is prone to human error introducing a subtle, hard to notice but fatal bug: if you also checked one of the modifiers or a second key to be pressed down "ThisFrame" the user would have to press both these keys down in the same frame. It is almost impossible to press down two or more keys down at the same time with a time span of 0.1667 seconds (one 60th of a second).

That's why the #2) approach is preferred, it assures that the test (key down/up, this frame or not) is performed only on the defining key and not one of the modifier keys. It also requires fewer method calls and is a bit shorter to write because you can | (bitwise OR) the modifier key masks together. Approach #2) will check if the "C" key was pressed down "ThisFrame", and then verifies if the modifier keys have also been held down at the same time.

Keyboard Input References

Kobold2D Virtual KeyCodes Reference with KeyCode values printed in hex.

For more details about Mac Keyboard Input processing please refer to this blog post.

Here's a handy KeyCodes App that prints out all the information about the character when you press it.

Image of Mac Keyboard with virtual KeyCodes printed on each key. Click image for high-res version. Image courtesy of Peter Hosey.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
Adaptavist Theme Builder Powered by Atlassian Confluence