3D Game Builder SDK

SDK Functions

gamePadButtonPressed( int n, int button )

Description

Check if a button on a game pad / controller has just been pressed down. It only detects the button when you press it down. It does not detect if you are holding the button down.

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

Specification

int gamePadButtonPressed( 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 has just been pressed down on your game pad / controller.

This function will return 1 (true) once only when you press down on a button. This, for example, allows you to use a button to step through a menu, up or down, using a single button press.

The other function gamePadButtonDown( int n, int button ) will continuously return 1 (true) while the button is down.

You need to call the gamePadRead( void ) function before you call this gamePadButtonPressed( 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.

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.

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