3D Game Builder SDK

SDK Functions

gamePadButtonDown( int n, int button )

Description

Check if a button on a game pad / controller is down (either pressed or held down).

You need to call gamePadRead( void ) function before you call this function.

Specification

int gamePadButtonDown( int n, int button )

int n

= the controller number (1 or 2)

int button

= a button value (refer below)

return value

= 1 (true) or 0 (false)

Notes

Use this function to check if a button is pressed or held down on your game pad / controller.

You need to call the gamePadRead( void ) function before you call this gamePadButtonDown( int n, int button ) function. This is because gamePadRead( void ) needs to read the current state of the buttons for each attached game pad / controller.

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.

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 status of button A
    		if (gamePadButtonDown(1,PAD_BUTTON_A)) 
    			gameMessage( "You are holding PAD_BUTTON_A" );
    		else
    			gameMessage( "You are NOT holding PAD_BUTTON_A" );
    
    		// display the status of button B
    		if (gamePadButtonPressed(1,PAD_BUTTON_B)) 
    			gameMessage( "You pressed PAD_BUTTON_B" );
    
    		// 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