Getting started

Dependent on the platform, input could be provided by the keyboard, a mouse, touch events, an accelerometer, a joystick or a combination thereof. This example looks at the most basic input available and demonstrates how to respond to a simple touch / click event.

Types of input

The type of input available is dependent on the platform, for example, on Windows you can expect mouse and keyboard input and possibly a joystick, whereas on an iPhone we're limited to touch events and an accelerometer.

Input supported by AppGameKit Studio includes:

• keyboard
• mouse
• touch
• accelerometer
• joystick

Platform dependent input

The choice when dealing with input is to decide whether your game is expected to work on mutiple platforms or if it's targeting a specific platform. For example, if your game is only targeting Windows then you could call commands such as GetRawMouseX and GetRawMouseY to retrieve information about the position of the mouse pointer. Commands such as these are platform dependent. Another example would be a game that is using the accelerometer. This game could call GetAccelX to obtain acceleration data on the X axis, and again this is platform dependent and is only currently supported on iOS and Bada - it would not return any values on Windows or Mac.

When using platform dependent input commands it's important to realise that this restricts the portability of your game. While it wouldn't necessarily stop your game from working, it would mean that you introduce code that only works on certain platforms, and this would result in needing to implement different input routines on each platform. In some cases this could be the desired result, as it may be that your game's input is tailored to each platform. The key point is to consider input early and make a choice as to whether your input will be platform dependent or platform agnostic.

Platform agnostic input

The platform agnostic commands will function on all platforms, for example, the command GetPointerPressed can be used to determine whether there has been a touch event on mobile devices, or if the mouse has been pressed on the likes of Windows and Mac. The objective behind these commands is to ensure that you can write your input routines once and have them behave the same on all platforms.

The usage of any platform agnostic commands may slightly limit the functionality of input handling, but brings the benefit of working on all platforms, thus ensuring your games will run on all platforms supported by AppGameKit Studio without needing to make any changes.

Responding to input

This example will focus on platform agnostic commands, in particular commands that allow us to check whether the user has touched or clicked on the screen. The example will perform the following actions:

• set a virtual resolution
• create a sprite and place it on screen
• whenever the user touches / clicks on the screen the sprite will move to that location

Setup

A virtual resolution is set of 320 x 480, followed by a call to the command CreateSprite where an ID of 1 is specified for the first parameter, while the second parameter involves making a call to LoadImage to load the image "lime.png", which in turn returns an ID number for the image to the CreateSprite command.

The initial set up code is as follows:

SetVirtualResolution ( 320, 480 )


CreateSprite ( 1, LoadImage ( "lime.png" ) )

void app::Begin ( void )
{
    agk::SetVirtualResolution ( 320, 480 );


    agk::CreateSprite ( 1, agk::LoadImage ( "lime.png" ) );
}

Checking for input

The command GetPointerPressed can be used to determine whether the user has touched or clicked on the screen. It takes no parameters and returns a value of 1 when input has occurred. Once input has taken place other information is available such as the location of that input. This is accessible through the commands GetPointerX and GetPointerY. These commands take no parameters and return the location of input on the X and Y axis.

The code to deal with simple input is relatively straightforward, with a call to GetPointerPressed being made, and if it returns 1 then we have some input to deal with:

if ( GetPointerPressed ( ) = 1 )


endif

if ( agk::GetPointerPressed ( ) == 1 )
{


}

The next step is to call GetPointerX and GetPointerY within the if statement:

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

if ( agk::GetPointerPressed ( ) == 1 )
{
    float x = agk::GetPointerX ( );
    float y = agk::GetPointerY ( );
}

We now know that an input event has occurred and we also know the location. The remaining code simply positions our sprite at the location of the input event:

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


    SetSpritePosition ( 1, x#, y# )
endif

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


    agk::SetSpritePosition ( 1, x, y );
}

Full code listing

The final code for our program includes the addition of a background sprite along with some instructions being printed out within the main loop:

SetVirtualResolution ( 320, 480 )


CreateSprite ( LoadImage ( "background5.jpg" ) )


CreateSprite ( 1, LoadImage ( "lime.png" ) )


do
    Print ( "Touch or click the screen" )
    Print ( "to move the sprite" )


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


        SetSpritePosition ( 1, x#, y# )
    endif


    sync ( )
loop

void app::Begin ( void )
{
    agk::SetVirtualResolution ( 320, 480 );


    agk::CreateSprite ( agk::LoadImage ( "background5.jpg" ) );


    agk::CreateSprite ( 1, agk::LoadImage ( "lime.png" ) );
}


void app::Loop ( void )
{
    agk::Print ( "Touch or click the screen" );
    agk::Print ( "to move the sprite" );


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


        agk::SetSpritePosition ( 1, x, y );
    }


    agk::Sync ( );
}

Conclusion

This document has explored some of the important concepts when dealing with input, it has also provided a brief example showing how to handle basic input that will function on all platforms.