Moving sprites using the percentage system

Description

In this example we’re going to place a sprite on screen and move it using the approach of the percentage based system.

Overview

The process involved is as follows:

• load an image
• create a sprite
• set the sprite’s size
• move our sprite in the main loop

Load an image

Before creating our sprite we will load in an image, that will later get attached to the sprite:

image = LoadImage ( "blue.png" )

image = agk::LoadImage ( "blue.png" );

This line calls LoadImage passing in the filename "blue.png", it then returns an ID number which gets saved in the variable. This ID number is now treated as a handle to our image and can be used later on when referring to it.

Creating a sprite

Now that we have an image loaded into memory we’re ready to create a sprite and attach this image to it. This is achieved by calling the command CreateSprite.

sprite = CreateSprite ( image )

sprite = agk::CreateSprite ( image );

Here we call CreateSprite passing in an ID number for our image and returning an ID number for the sprite. We’re effectively saying create a sprite, attach this image to it and give us back an ID number for this sprite. This ID number for the sprite can be stored for use later on when dealing with sprite properties, for example.

Set the sprite’s size

As we’re using the percentage based system it’s necessary for us to let AppGameKit Studio know how big this sprite is going to be. This is handled using the function SetSpriteSize. Its parameters are an ID number followed by width and height values as percentages. In this instance we require our sprite to take up 20% of the screen on the X axis and we’ll let AppGameKit Studio calculate the correct proportion on the Y axis, therefore we pass in -1 for the second parameter:

SetSpriteSize ( sprite, 20, -1 )

agk::SetSpriteSize ( iSprite, 20.0f, -1.0f );

If we passed in a value of 20 to the second parameter (the height) then our sprite would look incorrect. This is due to the sprite being of size 54 x 50. It’s not exactly square, therefore if the sprite took up 20% of the screen on both axis then it will not be proportionally correct, so setting one of the parameters to -1 solves this problem for us.

Main loop

Up to this point we have, loaded an image, created a sprite that uses this image and set its size. We’re nearly ready to run our application and see the results. Prior to this we need to ensure one more thing - in our main loop we must call Sync to ensure the screen gets updated and its contents drawn. The function Sync takes no parameters and can be called in your main loop like this:

do
    Sync ( )
loop

void app::Loop ( void )
{
    agk::Sync ( );
}

Move our sprite in the main loop

To move our sprite around the screen we call the command SetSpritePosition. This command takes three parameters - the ID number of the sprite, new X position on screen and the new Y position on screen. As we’re using the percentage based system these coordinates are treated as percentages. For our purposes we want to move our sprite from its initial position (which will be 0, 0 by default) and over towards the right hand side of the screen. This is achieved by setting a variable to 0, incrementing it slowly each frame and then passing it into SetSpritePosition, as shown in this code:

SetSpritePosition ( sprite, x#, 0 )


x# = x# + 0.25

SetSpritePosition ( iSprite, x, 0.0f );


x = x + 0.25f;

This has the effect of moving our sprite by 0.25% of the width of the screen each frame, which is about 0.8 pixels. To move by one pixel would need to increase the percentage to about 0.32%.

Full code listing

Everything is now in place. Here's the final code for our program

backdrop = CreateSprite ( LoadImage ( "background3.jpg" ) )
SetSpriteSize ( backdrop, 100, 100 )


image = LoadImage ( "blue.png" )


sprite = CreateSprite ( image )


SetSpriteSize ( sprite, 20, -1 )


do
    SetSpritePosition ( sprite, x#, 0 )


    x# = x# + 0.25


    sync ( )
loop

void app::Begin ( void )
{
    int backdrop = agk::CreateSprite ( agk::LoadImage ( "background3.jpg" ) );
    agk::SetSpriteSize ( backdrop, 100, 100 );


    image = agk::LoadImage ( "blue.png" );


    sprite = agk::CreateSprite ( image );


    agk::SetSpriteSize ( sprite, 20, -1 );
}
void app::Loop ( void )
{
    agk::SetSpritePosition ( iSprite, x, 0.0f );


    x = x + 0.25f;


    agk::Sync ( );
}

Conclusion

We’re now all set to run our application and see the results on screen.