Joints - Part 1

Description

Joints are used as a way of making connections between sprites. At the most basic level this could mean attaching two sprites through the use of a weld joint. AppGameKit Studio provides support for several different kinds of joints including a distance joint, revolute joint, prismatic joint, pulley joint, mouse joint, line joint and weld joint.

This example demonstrates the use of a simple weld joint and the impact this makes on two sprites.

Overview

The process involved is as follows:

• loading images
• create two sprites, align them next to each other and turn physics on
• weld the sprites together
• repeat the process with another two sprites, placing them lower down the screen
• make an obstacle so that when the sprites fall (due to gravity) we can see the impact of a collision

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" );

First set of sprites

The first set of sprites will be created alongside each other at the top of the screen. Both of them will use the crate texture (ID 1) and have physics turned on (as dynamic objects):

CreateSprite ( 1, 1 )
SetSpritePosition ( 1, 100, 0 )
SetSpritePhysicsOn ( 1, 2 )


CreateSprite ( 2, 1 )
SetSpritePosition ( 2, 164, 0 )
SetSpritePhysicsOn ( 2, 2 )

agk::CreateSprite ( 1, 1 )
agk::SetSpritePosition ( 1, 100.0f, 0.0f );
agk::SetSpritePhysicsOn ( 1, 2 );


agk::CreateSprite ( 2, 1 );
agk::SetSpritePosition ( 2, 164.0f, 0.0f );
agk::SetSpritePhysicsOn ( 2, 2 );

Welding two sprites together

By welding two sprites together we create a solid, invisible link that effectively transforms the two sprites into one single entity. The creation of a weld joint is handled with the command CreateWeldJoint. 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 welded together. The X and Y parameters control the anchor point of the weld. For most cases setting the anchor point to the centre point of both sprites makes sense. The final parameter colConnected sets wheather the two sprites can collide (0=no, 1=yes).

For our example the previously created sprites with ID numbers of 1 and 2 will be connected, with the anchor point being the centre point of both sprites:

CreateWeldJoint ( 1, 2, 164, 32, 0 )

agk::CreateWeldJoint ( 1, 2, 164.0f, 32.0f, 0 );

Both sprite 1 and sprite 2 use image 1 (the crate) which has dimensions of 64 x 64. These sprites are positioned directly alongside each other at 100, 0 and 164, 0. Therefore setting the X parameter to 164 results in the central point on the X axis between both sprites. Setting the Y paramter to 32 means the anchor point is halfway down and in the centre point on the Y axis. After calling CreateWeldJoint with the above parameters our sprites are connected at the anchor point.

The command CreateWeldJoint returns an ID number for the joint. This ID number can be used to edit properties of joints and also deleting the joint. For the purpose of this example it's not necessary to know and retain the ID, so the return value is ignored.

More sprites

Another two sprites will be created. These sprites will be placed further down the screen and below our previous sprites, they will not be connected by any joints:

CreateSprite ( 3, 1 )
SetSpritePosition ( 3, 100, 140 )
SetSpritePhysicsOn ( 3, 2 )


CreateSprite ( 4, 1 )
SetSpritePosition ( 4, 164, 140 )
SetSpritePhysicsOn ( 4, 2 )

agk::CreateSprite ( 3, 1 );
agk::SetSpritePosition ( 3, 100.0f, 140.0f );
agk::SetSpritePhysicsOn ( 3, 2 );


agk::CreateSprite ( 4, 1 );
agk::SetSpritePosition ( 4, 164.0f, 140.0f );
agk::SetSpritePhysicsOn ( 4, 2 )

By creating these two sprites without a joint we can examine the difference between collisions on individual sprites and those attached with joints.

An obstacle

A static physics sprite will be created directly below both sets of sprites. This sprite is placed here so that the dynamically created sprites will collide with this obstacle. The sprite uses image 2 (the chip) and has its shape set to 1 so it's represented as a circle within the simulation. It is also set to be a static object. Here's the code:

CreateSprite ( 5, 2 )
SetSpritePosition ( 5, 132, 250 )
SetSpritePhysicsOn ( 5, 1 )
SetSpriteShape ( 5, 1 )

agk::CreateSprite ( 5, 2 );
agk::SetSpritePosition ( 5, 132.0f, 250.0f );
agk::SetSpritePhysicsOn ( 5, 1 );
agk::SetSpriteShape ( 5, 1 );

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

The final code for our program is as follows:

SetVirtualResolution ( 320, 480 )


CreateSprite ( LoadImage ( "background3.jpg" ) )


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


CreateSprite ( 1, 1 )
SetSpritePosition ( 1, 100, 0 )
SetSpritePhysicsOn ( 1, 2 )


CreateSprite ( 2, 1 )
SetSpritePosition ( 2, 164, 0 )
SetSpritePhysicsOn ( 2, 2 )


CreateWeldJoint ( 1, 2, 164, 32, 0 )


CreateSprite ( 3, 1 )
SetSpritePosition ( 3, 100, 140 )
SetSpritePhysicsOn ( 3, 2 )


CreateSprite ( 4, 1 )
SetSpritePosition ( 4, 164, 140 )
SetSpritePhysicsOn ( 4, 2 )


CreateSprite ( 5, 2 )
SetSpritePosition ( 5, 132, 250 )
SetSpritePhysicsOn ( 5, 1 )
SetSpriteShape ( 5, 1 )


SetPhysicsDebugOn ( )


do
    Sync ( )
loop

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

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

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

    agk::CreateSprite ( 1, 1 )
    agk::SetSpritePosition ( 1, 100.0f, 0.0f );
    agk::SetSpritePhysicsOn ( 1, 2 );
    

    agk::CreateSprite ( 2, 1 );
    agk::SetSpritePosition ( 2, 164.0f, 0.0f );
    agk::SetSpritePhysicsOn ( 2, 2 );
    

    agk::CreateWeldJoint ( 1, 2, 164.0f, 32.0f, 0 );
    

    agk::CreateSprite ( 3, 1 );
    agk::SetSpritePosition ( 3, 100.0f, 140.0f );
    agk::SetSpritePhysicsOn ( 3, 2 );
    

    agk::CreateSprite ( 4, 1 );
    agk::SetSpritePosition ( 4, 164.0f, 140.0f );
    agk::SetSpritePhysicsOn ( 4, 2 )
    

    agk::CreateSprite ( 5, 2 );
    agk::SetSpritePosition ( 5, 132.0f, 250.0f );
    agk::SetSpritePhysicsOn ( 5, 1 );
    agk::SetSpriteShape ( 5, 1 );
    

    agk::SetPhysicsDebugOn ( );
}


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

Conclusion

When you run the program notice how the sprites collision response is different. The two sprites connected with a weld joint act as one, whereas the second set of sprites act individually. Through the use of joints it's possible to create all kinds of interesting scenarios. While this particular example is simple it should give you some kind of insight into what might be possible with joints.