3D Game Builder SDK

SDK Functions

gamePadRead( void )

Description

Read the current state of the game pad / controller(s).

Specification

void gamePadRead( void )

return value

= void (nothing)

Notes

You need to read the state of the game pad / controller every frame to catch the button activity from the player. You can then use the other functions to detect the state of each button.

You can check if a game pad / controller is successfully attached by using the gamePadAttached( int n ) function.

You can have up to 2 connected game pad / controllers plugged in at any time. You can refer to each controller independently by passing the controller number (1 or 2) to the game pad function. For example, gamePadAttached(1) and gamePadAttached(2) will tell you the status of each controller.

You can check if a button is down by using the gamePadButtonDown( int n, int button ) function. This will return 1 (true) if the button is down.

To check if a button has been pressed use the gamePadButtonPressed( int n, int button ) function. This checks for a button press only so it is useful for things like menu navigation.

The button argument in these functions can be any of the following values (as defined in 3dgamebuilder.h)

  • PAD_ANY_BUTTON

  • PAD_BUTTON_RIGHT

  • PAD_BUTTON_LEFT

  • PAD_BUTTON_UP

  • PAD_BUTTON_DOWN

  • PAD_BUTTON_START

  • PAD_BUTTON_SELECT

  • PAD_BUTTON_A

  • PAD_BUTTON_B

  • PAD_BUTTON_C

  • PAD_BUTTON_D

  • PAD_BUTTON_LEFT_1

  • PAD_BUTTON_LEFT_2

  • PAD_BUTTON_RIGHT_1

  • PAD_BUTTON_RIGHT_2

  • Here are the button assignments on the game pad / controller:

    You can check for a combination of buttons using logical OR. For example, to test if both buttons PAD_BUTTON_A and PAD_BUTTON_B are down on controller 1 use these function arguments:

    gamePadButtonDown( 1, (PAD_BUTTON_A | PAD_BUTTON_B) )

    This will return 1 (true) if either of these buttons are held down or both.

    As a shortcut feature, you can quickly exit 3D Game Builder immediately at any time by pressing and holding down both the PAD_BUTTON_START and PAD_BUTTON_SELECT buttons simultaneously.

    The special value PAD_ANY_BUTTON means "any button". For example, gamePadButtonDown( 1, PAD_ANY_BUTTON ) will return 1 (true) if any button is pressed or held down.

    If you do not have a game pad / controller attached before the 3D Game Builder starts and then you plug it in, you will need to restart 3D Game Builder to detect the new controller.

    For Example

    #include "3dgamebuilder.h"
    
    // exported game function
    DLL_EXPORT int gameLoop(void)
    {
    	while(1)
    	{
    		// read the controller input
    		gamePadRead();
    					
    		// display the buttons pressed on the game pad
    		if (gamePadButtonDown(1,PAD_BUTTON_RIGHT)) 
    			gameMessage( "PAD_BUTTON_RIGHT" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_LEFT)) 
    			gameMessage( "PAD_BUTTON_LEFT" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_UP)) 
    			gameMessage( "PAD_BUTTON_UP" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_DOWN)) 
    			gameMessage( "PAD_BUTTON_DOWN" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_START)) 
    			gameMessage( "PAD_BUTTON_START" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_SELECT)) 
    			gameMessage( "PAD_BUTTON_SELECT" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_A)) 
    			gameMessage( "PAD_BUTTON_A" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_B)) 
    			gameMessage( "PAD_BUTTON_B" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_C)) 
    			gameMessage( "PAD_BUTTON_C" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_D)) 
    			gameMessage( "PAD_BUTTON_D" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_LEFT_1)) 
    			gameMessage( "PAD_BUTTON_LEFT_1" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_LEFT_2)) 
    			gameMessage( "PAD_BUTTON_LEFT_2" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_RIGHT_1)) 
    			gameMessage( "PAD_BUTTON_RIGHT_1" );
    
    		if (gamePadButtonDown(1,PAD_BUTTON_RIGHT_2)) 
    			gameMessage( "PAD_BUTTON_RIGHT_2" );
    
    		// draw a frame
    		gameStartRender();
    		// (nothing to draw)
    		gameEndRender();
    	}
    
    	return 0;
    }
    

    See Also

      gamePadRead( void )
      gamePadAttached( int n )
      gamePadButtonDown( int n, int button )
      gamePadButtonPressed( int n, int button )

    Go Back

    SDK Functions