Gamepad

This topic describes how your application can detect and receive input from a gamepad connected to the TV.


Related Info


A standard gamepad has 4 axes and up to 17 buttons. Other gamepads can have different styles and layouts of axes and buttons.

Figure 1. Standard gamepad axes and buttons

All Samsung TVs since 2016 support gamepads. Gamepads are not supported on the emulator.

The following limitations apply to using gamepads with a Samsung TV:

  • A maximum of 4 gamepads can be connected simultaneously.
  • After the user connects the gamepad, interaction using the gamepad becomes available only after the user presses any button or moves any axis.

Checking for Specific Gamepads

To check that a specific gamepad model is connected to the TV when the application is launched, add the following line to the "config.xml" file:

<tizen:metadata key='http://samsung.com/tv/metadata/gamepad' value='xxx'>
</tizen:metadata> 

The value is the model name of the gamepad. To add multiple gamepad models, separate the model names using "::". For example:

  • 1 model: dualshock4
  • 2 models: usbgamepad::xxx
  • 3 models: xxx::yyy::zzz

The following figure shows the popup that appears if the application checks for a "dualshock4" gamepad when it is launched, and one is not connected.

Figure 2. Correct gamepad not connected popup

Retrieving Gamepad Information

You can use the Web standard Gamepad interface to retrieve information about connected gamepads:

  1. To receive notifications when a gamepad is connected or disconnected, create listeners for the related events:
    • The gamepadconnected event is fired when the gamepad is connected.

      The callback parameter provides access to associated gamepad data.
        var gamepad;
      
        window.addEventListener('gamepadconnected', function(event) {
          gamepad = event.gamepad;
          console.log('event.gamepad : ' + JSON.stringify(event.gamepad));
        });
      
    • The gamepaddisconnected event is fired when the gamepad is disconnected. To remove the gamepad value, set the gamepad variable

      to undefined in the callback.
      window.addEventListener('gamepaddisconnected', function() {
        gamepad = undefined;
      });
      
  2. To retrieve information about the gamepad, such as axis and button values, use the attributes of the Gamepad interface:
    console.log(gamepad.axes[0]); // axes[0]
    console.log(gamepad.buttons[0]); // buttons[0]
    
  3. To retrieve information about the mutiple gamepads, such as axis and button values, use navigator.getGamepads() method:
    var gamepads = navigator.getGamepads();
    if(!gamepads){
        return;
    }
    for(var i = 0; i < gamepads.length(); i++){
        var gp = gamepads[i];
        if(!gp){
    	    continue;
        }
        console.log(gp.axes[0]); // axes[0]
        console.log(gp.buttons[0]); // buttons[0]
        ...
    }
    
  4. To make Gamepad have a vibration effect, use Gamepad.vibrationActuator.playEffect method:
    for(var i = 0 ; i < gamepads.length ; i++){
       var gp = gamepads[i];
       if(!gp){
           continue;
       }
       if (gp.buttons[0]) {//Button A is pressed, start vibration
       if(gp.vibrationActuator){
           gp.vibrationActuator.playEffect("dual-rumble", {duration: 50, strongMagnitude: 1.0, weakMagnitude: 1.0});//duration: 50ms 
           }
       }
    }