Joints - Part 2

Description

In the previous example (Joints - Part 1) we examined the usage of weld joints, where sprites can be attached to each other in a rigid manner. In this example we look at the revolute joint, which is a more complex joint that allows sprites to rotate around an anchor.

Overview

The process to create this example is as follows:

load images to be used by the sprites
create a static physics sprite (the crate)
create a dynamic physics sprite (the chip)
connect both together using a revolute joint
apply an impulse to move the dynamic sprite

Loading images

Two images are loaded, that can later be attached to the sprites:

LoadImage ( 1, "green.png" )
LoadImage ( 2, "small_ball.png" )

agk::LoadImage ( 1, "green.png" );
agk::LoadImage ( 2, "small_ball.png" );

Static sprite

Sprite 1 gets created, it uses the crate image (ID 1), it gets placed near the top of the screen and is set to be a static physics object:

CreateSprite ( 1, 1 )
SetSpritePosition ( 1, 150, 50 )
SetSpritePhysicsOn ( 1, 1 )

agk::CreateSprite ( 1, 1 );
agk::SetSpritePosition ( 1, 150.0f, 50.0f );
agk::SetSpritePhysicsOn ( 1, 1 );

Dynamic sprite

Sprite 2 gets created, it uses the ball image (ID 2), it gets placed directly below sprite 1 and is set to be a dynamic physics object, it also has its physics shape set to be a circle:

CreateSprite ( 2, 2 )
SetSpritePosition ( 2, 150, 150 )
SetSpritePhysicsOn ( 2, 2 )
SetSpriteShape ( 2, 1 )

agk::CreateSprite ( 2, 2 );
agk::SetSpritePosition ( 2, 150.0f, 150.0f );
agk::SetSpritePhysicsOn ( 2, 2 );
agk::SetSpriteShape ( 2, 1 );

Using a revolute joint

A revolute joint connects two sprites and allows for rotation. Within our example the dynamic sprite will be connected to the static sprite using a revolute joint. This has the effect of allowing the dynamic sprite to rotate around the static sprite.

To create a revolute joint call the CreateRevoluteJoint command. This command takes several parameters:

sprite A
sprite B
x
y
colConnected

The first two parameters of this command refer to the sprites that are being joined together. The X and Y parameters control the anchor point of the joint. The anchor point is responsible for controlling at which point the sprites can rotate around. The final parameter ColConnected sets if the two sprites will collide, 0=not, 1=they will.

When our sprites are connected with the revolute joint the anchor is set to 182, 82:

CreateRevoluteJoint ( 1, 2, 182, 82, 0 )

agk::CreateRevoluteJoint ( 1, 2, 182.0f, 82.0f, 0 );

This means the anchor point, or point of rotation for these sprites is the centre of the static sprite. The end result is that our dynamic sprite could rotate all around the static sprite if it had enough force applied to it.

Applying an impulse

If at this point the example was launched, then the result would be two sprites on screen that are connected, but not moving. In order to bring our scene to life we'll need to apply an impulse to our dynamic sprite. This has the effect of pushing our dynamic sprite in a certain direction. By doing this we'll provide our sprite with some force and it will start moving within the limits of the revolute joint.

The command SetSpritePhysicsImpulse takes several parameters:

sprite ID
x
y
x impulse
y impulse

The ID refers to the ID of the sprite that you want to apply an impulse to. The x and y parameters refer to the location at which point the impulse will be applied. Finally the last two parameters x impulse and y impulse are responsible for the amount of impulse on each axis.

For our example we're effectively wanting to give our dynamic sprite a push and help it on its way. Therefore an impulse is applied at the sprites position on the X axis:

SetSpritePhysicsImpulse ( 2, 150, 150, 10000, 0 );

agk::SetSpritePhysicsImpulse ( 2, 150.0f, 150.0f, 10000.0f, 0.0f );

Physics debug mode

The final part before moving onto the main loop is a call to the command SetPhysicsDebugOn. After calling this command overlays will be placed on our sprites, which will help us to understand how the physics simulation represents our sprites:

SetPhysicsDebugOn ( )

agk::SetPhysicsDebugOn ( );

Main loop

The only code required within our main loop is a call to Sync that will ensure the screen is updated. Nothing else needs to happen. We'll let the simulation play itself out and view the results on screen:

do
    Sync ( )
loop

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

Full code listing

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

SetVirtualResolution ( 320, 480 )


CreateSprite ( LoadImage ( "background1.jpg" ) )


LoadImage ( 1, "green.png" )
LoadImage ( 2, "small_ball.png" )


CreateSprite ( 1, 1 )
SetSpritePosition ( 1, 150, 50 )
SetSpritePhysicsOn ( 1, 1 )


CreateSprite ( 2, 2 )
SetSpritePosition ( 2, 150, 150 )
SetSpritePhysicsOn ( 2, 2 )
SetSpriteShape ( 2, 1 )


CreateRevoluteJoint ( 1, 2, 182, 82, 0 )


SetSpritePhysicsImpulse ( 2, 150, 150, 10000, 0 )


SetPhysicsDebugOn ( )


do
    Sync ( )
loop

void app::Begin ( void )
{
    agk::CreateSprite ( agk::LoadImage ( "background1.jpg" ) );
    

    agk::LoadImage ( 1, "green.png" );
    agk::LoadImage ( 2, "small_ball.png" );
    

    agk::CreateSprite ( 1, 1 );
    agk::SetSpritePosition ( 1, 150.0f, 50.0f );
    agk::SetSpritePhysicsOn ( 1, 1 );
    

    agk::CreateSprite ( 2, 2 );
    agk::SetSpritePosition ( 2, 150.0f, 150.0f );
    agk::SetSpritePhysicsOn ( 2, 2 );
    agk::SetSpriteShape ( 2, 1 );
    

    agk::CreateRevoluteJoint ( 1, 2, 182.0f, 82.0f, 0 );
    

    agk::SetSpritePhysicsImpulse ( 2, 150.0f, 150.0f, 10000.0f, 0.0f );
    

    agk::SetPhysicsDebugOn ( );
}


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

Conclusion

With a few simple lines of code it's been possible to create a relationship between two sprites, where one is able to rotate around another. Whilst this example is relatively simple, it should help in understanding how joints can be used to attach sprites together.