Debugging Physics

Description

Internally AGK represents physics objects by providing a bounding box, a circle or a convex hull around sprites. By switching the physics debug mode on you can get to see how AGK is representing your sprites in the physics simulation. Switching this mode on will force AGK to draw the physics representations of your sprites on top of all sprites. This is great for debugging. Being able to see this on screen can help make a big difference to understanding how and why the physics simulation provides results.

This example creates four dynamic sprites that are placed alongside each other. A fifth sprite is created, that is positioned slightly below the other sprites and is static. Finally debug mode is switched on for physics.

Overview

The steps involved in this example are:

create our sprites and set their dynamic or static states
turn physics on for the sprites
turn physics debug on
within the main loop simply update the contents of the screen

Creating the sprites

One image is loaded, which is then used by five sprites, which are laid out in a row, except for sprite three that is slightly lower down the screen:

LoadImage ( 1, "small_silver.png" )


CreateSprite ( 1, 1 )
CreateSprite ( 2, 1 )
CreateSprite ( 3, 1 )
CreateSprite ( 4, 1 )
CreateSprite ( 5, 1 )


SetSpritePosition ( 1,  50,   0 )
SetSpritePosition ( 2, 100,   0 )
SetSpritePosition ( 3, 140, 200 )
SetSpritePosition ( 4, 170,   0 )
SetSpritePosition ( 5, 220,   0 )

agk::LoadImage ( 1, "small_silver.png" );


agk::CreateSprite ( 1, 1 );
agk::CreateSprite ( 2, 1 );
agk::CreateSprite ( 3, 1 );
agk::CreateSprite ( 4, 1 );
agk::CreateSprite ( 5, 1 );


agk::SetSpritePosition ( 1,  50,   0 );
agk::SetSpritePosition ( 2, 100,   0 );
agk::SetSpritePosition ( 3, 140, 200 );
agk::SetSpritePosition ( 4, 170,   0 );
agk::SetSpritePosition ( 5, 220,   0 );

Switching physics on

Four of the sprites are enabled as dynamic objects, while one is set up as a static object.

SetSpritePhysicsOn ( 1, 2 )
SetSpritePhysicsOn ( 2, 2 )
SetSpritePhysicsOn ( 3, 1 )
SetSpritePhysicsOn ( 4, 2 )
SetSpritePhysicsOn ( 5, 2 )

agk::SetSpritePhysicsOn ( 1, 2 );
agk::SetSpritePhysicsOn ( 2, 2 );
agk::SetSpritePhysicsOn ( 3, 1 );
agk::SetSpritePhysicsOn ( 4, 2 );
agk::SetSpritePhysicsOn ( 5, 2 );

Debug mode

To switch debug mode on for physics it’s simply a case of calling the command SetPhysicsDebugOn. This function takes no parameters. To switch it off call SetPhysicsDebugOff. Please note that switching debug mode on is likely to negatively impact the frame rate of your game. Once switched on the overlaid shapes will be drawn with the following colours, in order to help you identify the kind of object they are:

cream - used for dynamic objects
green - used for static objects
blue - used for kinematic objects
grey - displays sleeping dynamic objects

Prior to our main loop the function SetPhysicsDebugOn is called:

SetPhysicsDebugOn ( )

agk::SetPhysicsDebugOn ( );

Main loop

The main loop in this example does not take any action. All it needs to do is make a call to Sync to ensure the screen is updated.

do
    Sync ( )
loop

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

Full code listing

The only alteration for the final program is the addition of a background image, which has its alpha level reduced to 100. Here's the final listing:

SetVirtualResolution ( 320, 480 )


backdrop = CreateSprite ( LoadImage ( "background2.jpg" ) )
SetSpriteColorAlpha ( backdrop, 100 )


LoadImage ( 1, "small_silver.png" )


CreateSprite ( 1, 1 )
CreateSprite ( 2, 1 )
CreateSprite ( 3, 1 )
CreateSprite ( 4, 1 )
CreateSprite ( 5, 1 )


SetSpritePosition ( 1,  50,   0 )
SetSpritePosition ( 2, 100,   0 )
SetSpritePosition ( 3, 140, 200 )
SetSpritePosition ( 4, 170,   0 )
SetSpritePosition ( 5, 220,   0 )


SetSpritePhysicsOn ( 1, 2 )
SetSpritePhysicsOn ( 2, 2 )
SetSpritePhysicsOn ( 3, 1 )
SetSpritePhysicsOn ( 4, 2 )
SetSpritePhysicsOn ( 5, 2 )


SetPhysicsDebugOn ( )


do
    Sync ( )
loop

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


    int backdrop = agk::CreateSprite ( agk::LoadImage ( "background2.jpg" ) );
    agk::SetSpriteColorAlpha ( backdrop, 100 );


    agk::LoadImage ( 1, "small_silver.png" );


    agk::CreateSprite ( 1, 1 );
    agk::CreateSprite ( 2, 1 );
    agk::CreateSprite ( 3, 1 );
    agk::CreateSprite ( 4, 1 );
    agk::CreateSprite ( 5, 1 );


    agk::SetSpritePosition ( 1,  50,   0 );
    agk::SetSpritePosition ( 2, 100,   0 );
    agk::SetSpritePosition ( 3, 140, 200 );
    agk::SetSpritePosition ( 4, 170,   0 );
    agk::SetSpritePosition ( 5, 220,   0 );


    agk::SetSpritePhysicsOn ( 1, 2 );
    agk::SetSpritePhysicsOn ( 2, 2 );
    agk::SetSpritePhysicsOn ( 3, 1 );
    agk::SetSpritePhysicsOn ( 4, 2 );
    agk::SetSpritePhysicsOn ( 5, 2 );


    agk::SetPhysicsDebugOn ( ); 
}


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

Conclusion

This simple command is a great way of understanding how your sprites are represented in the physics simulation. It can be used to determine such things as whether a bounding box isn’t providing a tight fit around a sprite, and whether it’s better to use an alternative.