Input

Overview

The input commands provide the ability to deal with a variety of different inputs for example, joysticks, buttons and the accelerometer. The commands are divided up into two main categories - Universal and Raw, and it's important to understand the distinction between these categories.

Universal Input

The universal input commands will function on all platforms. Here's an example demonstrating the process:

if ( GetPointerPressed ( ) = 1 )
    // do something
endif

if ( agk::GetPointerPressed ( ) == 1 )
{
    // do something
}

This particular command will adapt its behaviour dependent on the platform. When running on a platform that uses a mouse it will return a value of 1 when the left mouse button has been pressed. When running on a platform that uses a touch screen it will return a value of 1 when the user taps the screen.

All the other universal commands operate in a similar fashion. As another example here's a line showing the usage for a command named GetDirectionX:

x# = GetDirectionX ( )

x = GetDirectionY ( );

When running this code on a device that supports an accelerometer the data being returned will come directly from the accelerometer. When running on a platform such as Windows, where no accelerometer is pressent, AppGameKit Studio will provide a fallback mechanism and emulate the functionality by using the arrow keys on the keyboard.

What we end up with is a set of generic commands that will behave the same way regardless of the platform being used. If you want to maintain the philosophy of AppGameKit Studio to write once and deploy everywhere then you must ensure you use the universal input commands.

Raw Input

In some circumstances a game may only be directed at a specific platform or a subset rather than all the platforms that AppGameKit Studio supports. In cases like this, it might be more convenient to handle all of the input functionality provided by those devices. For example, on mobile devices it would be possible to pick up much more information relating to touch input, whereas when targeting all platforms and using the universal commands a more limited set of data is provided.

This example highlights the differences between universal and raw commands:

x# = GetRawAccelX ( )
y# = GetRawAccelY ( )
z# = GetRawAccelZ ( )

x = agk::GetRawAccelX ( );
y = agk::GetRawAccelY ( );
z = agk::GetRawAccelZ ( );

In this instance the code is extracting data from an accelerometer on the X, Y and Z axis. Data will only be returned when an accelerometer is present on the platform e.g. on Samsung Bada. Obtaining this level of data is not possible when using the universal commands.

How can I respond to basic input?

Some of the universal commands to deal with basic input are:

• GetPointerPressed
• GetPointerX
• GetPointerY

These three commands can be used to respond to mouse or touch input. The initial command to use is GetPointerPressed. This command returns a value of 1 upon input and after this point you can determine the X and Y position of the input:

if ( GetPointerPressed ( ) = 1 )
    x# = GetPointerX ( )
    y# = GetPointerY ( )
endif

if ( agk::GetPointerPressed ( ) == 1 )
    x = agk::GetPointerX ( );
    y = agk::GetPointerY ( );
endif

How can I use a virtual joystick on one platform and keyboard input on another?

This might be a common scenario for many games, whereby a virtual joystick controller is displayed on screen for mobile devices and keyboard input is preferred for platforms that support it. AppGameKit Studio will automatically take care of this transition if you use the following commands:

• SetJoystickScreenPosition
• GetJoystickX
• GetJoystickY

The command SetJoystickScreenPosition is used to place a virtual joystick on screen when appropriate. It takes 3 parameters:

• x
• y
• size

The x and y parameters control the position of the on screen joystick, while the size parameter controls the diameter of the joystick. This command has no effect when your game is running on a platform that has a real joystick or keyboard available, but it's still important to call it if you require this transition so that a virtual joystick will be displayed when necessary.

The commands GetJoystickX and GetJoystickY will return data either when the W, A, S and D keys are pressed or a real joystick is being used or when a virtual joystick is being used.

For an example of this process in action please check out the Space Game example provided with AppGameKit Studio.