GamePad API: Een Uitgebreide Gids voor het Beheren van Gamecontroller-invoer

De GamePad API biedt een gestandaardiseerde manier om gamecontrollers rechtstreeks vanuit webbrowsers te benaderen. Dit opent spannende mogelijkheden voor het creëren van meeslepende en interactieve webgebaseerde games en applicaties. Deze uitgebreide gids leidt u door alles wat u moet weten om de GamePad API effectief te gebruiken, van de basisinstallatie tot geavanceerde technieken.

Wat is de GamePad API?

De GamePad API is een JavaScript API die webapplicaties in staat stelt om invoer van gamecontrollers (gamepads, joysticks, etc.) te detecteren en hierop te reageren. Het stelt ontwikkelaars in staat om games en interactieve ervaringen te bouwen die kunnen worden bestuurd met standaard gamepad-invoer, zoals knoppen, assen (analoge sticks) en triggers.

Vóór de GamePad API was het verwerken van gamecontroller-invoer in webbrowsers een gefragmenteerde en onbetrouwbare ervaring, die vaak browserspecifieke plug-ins of complexe oplossingen vereiste. De GamePad API biedt een consistente en cross-browser oplossing, waardoor het proces van het integreren van gamecontroller-ondersteuning in webapplicaties wordt vereenvoudigd.

Browsercompatibiliteit

De GamePad API wordt breed ondersteund in moderne browsers, waaronder:

• Chrome (desktop en mobiel)
• Firefox (desktop en mobiel)
• Safari (desktop en mobiel, met enkele beperkingen)
• Edge
• Opera

Hoewel de browserondersteuning over het algemeen goed is, kunnen er subtiele verschillen zijn in implementatie en de beschikbaarheid van functies tussen verschillende browsers. Het is altijd een goede gewoonte om uw applicatie op meerdere browsers te testen om een consistent gedrag te garanderen.

Aan de slag met de GamePad API

Hier is een stapsgewijze handleiding om aan de slag te gaan met de GamePad API:

1. Gamepad-verbinding Detecteren

De navigator.getGamepads()-methode retourneert een array van Gamepad-objecten, die de momenteel verbonden gamepads vertegenwoordigen. De browser zal gamepadconnected- en gamepaddisconnected-evenementen activeren wanneer gamepads respectievelijk worden aangesloten of losgekoppeld. U kunt naar deze evenementen luisteren om de status van uw applicatie bij te werken.

            window.addEventListener("gamepadconnected", function(e) {
  console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
    e.gamepad.index, e.gamepad.id, e.gamepad.buttons.length, e.gamepad.axes.length);
  gamepadHandler(e, true);
});

window.addEventListener("gamepaddisconnected", function(e) {
  console.log("Gamepad disconnected from index %d: %s",
    e.gamepad.index, e.gamepad.id);
  gamepadHandler(e, false);
});

function gamepadHandler(event, connecting) {
  var gamepad = event.gamepad;
  if (connecting) {
    gamepads[gamepad.index] = gamepad;
  } else {
    delete gamepads[gamepad.index];
  }
}

var gamepads = {};

            

              
                Copy
              
            
          

Dit codefragment stelt event listeners in voor gamepadconnected- en gamepaddisconnected-evenementen. De gamepadHandler-functie werkt een gamepads-object bij om de verbonden gamepads bij te houden.

2. De Gamepad-status Pollen

De GamePad API is voornamelijk event-driven, maar voor continue invoer (zoals de beweging van een analoge stick), moet u de gamepad-status pollen in een requestAnimationFrame-lus. Dit houdt in dat u navigator.getGamepads() herhaaldelijk aanroept en de buttons- en axes-eigenschappen van de Gamepad-objecten onderzoekt.

            function update() {
  var gamepads = navigator.getGamepads ? navigator.getGamepads() : (navigator.webkitGetGamepads ? navigator.webkitGetGamepads() : []);
  for (var i = 0; i < gamepads.length; i++) {
    var gp = gamepads[i];
    if (gp) {
      // Process gamepad input here
      for (var j = 0; j < gp.buttons.length; j++) {
        if (gp.buttons[j].pressed) {
          console.log("Button " + j + " pressed");
        }
      }
      for (var j = 0; j < gp.axes.length; j++) {
        console.log("Axis " + j + ": " + gp.axes[j]);
      }
    }
  }
  requestAnimationFrame(update);
}

requestAnimationFrame(update);

            

              
                Copy
              
            
          

Dit codefragment werkt de gamepad-status continu bij met behulp van requestAnimationFrame. Het itereert door de verbonden gamepads en controleert de status van hun knoppen en assen.

3. Gamepad-eigenschappen Begrijpen

Elk Gamepad-object heeft de volgende belangrijke eigenschappen:

• id: Een string die de gamepad identificeert (bijv. "Xbox Controller (XInput STANDARD GAMEPAD)").
• index: De index van de gamepad in de navigator.getGamepads()-array.
• connected: Een boolean die aangeeft of de gamepad momenteel is verbonden.
• buttons: Een array van GamepadButton-objecten, die de knoppen van de gamepad vertegenwoordigen.
• axes: Een array van getallen, die de assen van de gamepad vertegenwoordigen (analoge sticks en triggers).
• mapping: Een string die de knoptoewijzing van de gamepad aangeeft (ofwel "standard" of "").

4. Werken met Gamepad-knoppen

Elk GamepadButton-object heeft de volgende eigenschappen:

• pressed: Een boolean die aangeeft of de knop momenteel is ingedrukt.
• value: Een getal tussen 0 en 1 dat de druk op de knop weergeeft (voor drukgevoelige knoppen zoals triggers).

U kunt de status van een knop benaderen via de index in de buttons-array. Bijvoorbeeld, gamepad.buttons[0].pressed zou true retourneren als de eerste knop is ingedrukt.

5. Werken met Gamepad-assen

De axes-array bevat getallen die de waarden van de analoge sticks en triggers van de gamepad vertegenwoordigen. De waarden variëren doorgaans van -1 tot 1, waarbij -1 de meest linkse/bovenste positie vertegenwoordigt en 1 de meest rechtse/onderste positie.

U kunt de waarde van een as benaderen via de index in de axes-array. Bijvoorbeeld, gamepad.axes[0] zou de horizontale positie van de linker analoge stick retourneren.

Standaard Gamepad-mapping

De GamePad API definieert een 'standard' gamepad-mapping die een consistente manier biedt om toegang te krijgen tot veelvoorkomende gamepad-knoppen en -assen, ongeacht het specifieke gamepad-model. Deze mapping wordt geïdentificeerd doordat de mapping-eigenschap is ingesteld op 'standard'.

De standaard gamepad-mapping omvat de volgende knoppen:

• Knop 0: A (meestal de knop rechtsonder)
• Knop 1: B (meestal de rechterknop)
• Knop 2: X (meestal de linkerknop)
• Knop 3: Y (meestal de bovenste knop)
• Knop 4: Linker bumper (LB)
• Knop 5: Rechter bumper (RB)
• Knop 6: Linker trigger (LT)
• Knop 7: Rechter trigger (RT)
• Knop 8: Select (of Back)
• Knop 9: Start
• Knop 10: Linker stick-knop (LS)
• Knop 11: Rechter stick-knop (RS)
• Knop 12: D-pad Omhoog
• Knop 13: D-pad Omlaag
• Knop 14: D-pad Links
• Knop 15: D-pad Rechts
• Knop 16: Guide (of Home)

De standaard gamepad-mapping omvat de volgende assen:

• As 0: Linker stick, horizontale as (-1 = links, 1 = rechts)
• As 1: Linker stick, verticale as (-1 = omhoog, 1 = omlaag)
• As 2: Rechter stick, horizontale as (-1 = links, 1 = rechts)
• As 3: Rechter stick, verticale as (-1 = omhoog, 1 = omlaag)

Het is belangrijk op te merken dat niet alle gamepads de standaard mapping ondersteunen. Gamepads die de standaard mapping niet ondersteunen, hebben een lege string voor de mapping-eigenschap, en u zult de id-eigenschap moeten gebruiken om de gamepad te identificeren en de knoppen en assen dienovereenkomstig toe te wijzen.

Omgaan met niet-standaard Gamepads

Bij het omgaan met niet-standaard gamepads moet u de gamepad identificeren op basis van de id-eigenschap en een aangepaste toewijzing voor de knoppen en assen maken. Dit kan een uitdagende taak zijn, omdat er veel verschillende gamepad-modellen beschikbaar zijn, elk met zijn eigen unieke knop- en as-lay-out.

Hier zijn enkele strategieën voor het omgaan met niet-standaard gamepads:

• Gamepad-database: Maak een database van id-strings van gamepads en hun overeenkomstige knop- en as-toewijzingen. Hiermee kunt u de knoppen en assen voor bekende gamepads automatisch toewijzen.
• Gebruikersconfiguratie: Sta gebruikers toe de knop- en as-toewijzingen voor hun gamepads te configureren. Dit biedt flexibiliteit voor gebruikers met ongebruikelijke gamepads.
• Heuristische Toewijzing: Gebruik heuristieken om de knop- en as-toewijzingen te raden op basis van het aantal knoppen en assen en hun typische gebruikspatronen.

Het implementeren van ondersteuning voor een breed scala aan gamepads kan een aanzienlijke onderneming zijn. Overweeg om u eerst te concentreren op de ondersteuning van de meest populaire gamepad-modellen en geleidelijk ondersteuning voor meer gamepads toe te voegen als dat nodig is.

Geavanceerde Technieken

1. Dode Zones

Analoge sticks hebben vaak een 'dode zone' rond de middenpositie waar de gerapporteerde waarde niet nul is, zelfs als de stick niet wordt aangeraakt. Dit kan ongewenste beweging of trillingen in uw spel veroorzaken. Om dit aan te pakken, kunt u een dode zone implementeren door de aswaarde op nul in te stellen als deze binnen een bepaald bereik rond nul valt.

            function applyDeadZone(value, threshold) {
  var percentage = (Math.abs(value) - threshold) / (1 - threshold);
  if (percentage < 0) {
    percentage = 0;
  }
  return percentage * (value > 0 ? 1 : -1);
}

var axisValue = gamepad.axes[0];
var deadZoneThreshold = 0.1;
var adjustedAxisValue = applyDeadZone(axisValue, deadZoneThreshold);

            

              
                Copy
              
            
          

Dit codefragment past een dode zone toe op de aswaarde. Als de absolute waarde van de as kleiner is dan de deadZoneThreshold, is de aangepaste waarde nul. Anders wordt de aangepaste waarde geschaald naar het bereik 0-1, met behoud van het teken van de oorspronkelijke waarde.

2. Exponentiële Afvlakking

De invoer van analoge sticks kan soms ruis bevatten, wat schokkerige of onvoorspelbare bewegingen veroorzaakt. Om de invoer af te vlakken, kunt u exponentiële afvlakking toepassen. Dit houdt in dat de huidige invoerwaarde wordt gemiddeld met de vorige afgevlakte waarde, waarbij meer gewicht wordt gegeven aan de vorige waarde.

            var smoothedAxisValue = 0;
var smoothingFactor = 0.1;

function smoothAxisValue(axisValue) {
  smoothedAxisValue = smoothingFactor * axisValue + (1 - smoothingFactor) * smoothedAxisValue;
  return smoothedAxisValue;
}

var axisValue = gamepad.axes[0];
var smoothedValue = smoothAxisValue(axisValue);

            

              
                Copy
              
            
          

Dit codefragment past exponentiële afvlakking toe op de aswaarde. De smoothingFactor bepaalt het gewicht dat aan de huidige waarde wordt gegeven. Een kleinere afvlakkingsfactor resulteert in een vloeiendere maar meer vertraagde invoer.

3. Knop-debouncing

Knoppen kunnen soms meerdere evenementen activeren wanneer ze worden ingedrukt of losgelaten vanwege mechanische 'bouncing'. Dit kan onbedoeld gedrag in uw spel veroorzaken. Om dit aan te pakken, kunt u knop-debouncing implementeren. Dit houdt in dat knopevenementen die kort na een vorig evenement plaatsvinden, worden genegeerd.

            var buttonStates = {};
var debounceDelay = 100; // milliseconds

function handleButtonPress(buttonIndex) {
  if (!buttonStates[buttonIndex] || Date.now() - buttonStates[buttonIndex].lastPress > debounceDelay) {
    console.log("Button " + buttonIndex + " pressed (debounced)");
    buttonStates[buttonIndex] = { lastPress: Date.now() };
    // Perform action here
  }
}

for (var j = 0; j < gp.buttons.length; j++) {
  if (gp.buttons[j].pressed) {
    handleButtonPress(j);
  }
}

            

              
                Copy
              
            
          

Dit codefragment implementeert knop-debouncing. Het houdt bij wanneer elke knop voor het laatst is ingedrukt. Als een knop opnieuw wordt ingedrukt binnen de debounceDelay, wordt het evenement genegeerd.

Toegankelijkheidsoverwegingen

Bij het ontwikkelen van games met gamepad-ondersteuning is het belangrijk om rekening te houden met de toegankelijkheid voor spelers met een handicap. Hier zijn enkele tips om uw game toegankelijker te maken:

• Configureerbare Besturing: Sta spelers toe de knop- en as-toewijzingen aan te passen aan hun individuele behoeften.
• Alternatieve Invoermethoden: Bied alternatieve invoermethoden, zoals toetsenbord en muis, voor spelers die geen gamepad kunnen gebruiken.
• Duidelijke Visuele Feedback: Geef duidelijke visuele feedback voor alle acties, zodat spelers gemakkelijk kunnen begrijpen wat er in het spel gebeurt.
• Aanpasbare Moeilijkheidsgraad: Bied aanpasbare moeilijkheidsgraden om spelers van verschillende vaardigheidsniveaus tegemoet te komen.

Door deze richtlijnen te volgen, kunt u games maken die plezierig en toegankelijk zijn voor een breder scala aan spelers.

GamePad API en Virtual Reality

De GamePad API is ook relevant in de context van WebVR (Virtual Reality op het web). VR-controllers, die vaak in combinatie met VR-headsets worden gebruikt, worden regelmatig via de GamePad API beschikbaar gesteld. Dit stelt ontwikkelaars in staat om VR-ervaringen te bouwen die deze controllers gebruiken voor interactie.

Bij het ontwikkelen van VR-applicaties kan het Gamepad-object extra eigenschappen hebben die verband houden met zijn pose (positie en oriëntatie) in de 3D-ruimte. Deze eigenschappen worden benaderd via de pose-eigenschap, die een GamePadPose-object retourneert. Het GamePadPose-object biedt informatie over de positie van de controller, de oriëntatie (als een quaternion), de lineaire snelheid en de hoeksnelheid.

Het gebruik van de GamePad API met WebVR stelt ontwikkelaars in staat om meeslepende en interactieve VR-ervaringen te creëren die reageren op de bewegingen en interacties van de gebruiker met de VR-controllers.

Voorbeeld: Eenvoudige Gamecontroller-tester

Hier is een eenvoudig voorbeeld van een gamecontroller-tester die de status van de verbonden gamepads weergeeft:

            <!DOCTYPE html>
<html>
<head>
  <title>Gamepad-tester</title>
  <style>
    body {
      font-family: sans-serif;
    }
  </style>
</head>
<body>
  <h1>Gamepad-tester</h1>
  <div id="gamepads"></div>

  <script>
    var gamepadsDiv = document.getElementById("gamepads");
    var gamepads = {};

    function updateGamepads() {
      var gamepadList = navigator.getGamepads ? navigator.getGamepads() : (navigator.webkitGetGamepads ? navigator.webkitGetGamepads() : []);

      gamepadsDiv.innerHTML = "";

      for (var i = 0; i < gamepadList.length; i++) {
        var gamepad = gamepadList[i];
        if (gamepad) {
          var gamepadDiv = document.createElement("div");
          gamepadDiv.innerHTML = "<h2>Gamepad " + i + ": " + gamepad.id + "</h2>";

          var buttonsDiv = document.createElement("div");
          buttonsDiv.innerHTML = "<h3>Knoppen</h3>";
          for (var j = 0; j < gamepad.buttons.length; j++) {
            var button = gamepad.buttons[j];
            var buttonDiv = document.createElement("div");
            buttonDiv.innerHTML = "Knop " + j + ": Ingedrukt = " + button.pressed + ", Waarde = " + button.value;
            buttonsDiv.appendChild(buttonDiv);
          }
          gamepadDiv.appendChild(buttonsDiv);

          var axesDiv = document.createElement("div");
          axesDiv.innerHTML = "<h3>Assen</h3>";
          for (var j = 0; j < gamepad.axes.length; j++) {
            var axisValue = gamepad.axes[j];
            var axisDiv = document.createElement("div");
            axisDiv.innerHTML = "As " + j + ": " + axisValue;
            axesDiv.appendChild(axisDiv);
          }
          gamepadDiv.appendChild(axesDiv);

          gamepadsDiv.appendChild(gamepadDiv);
        }
      }
    }

    function update() {
      updateGamepads();
      requestAnimationFrame(update);
    }

    window.addEventListener("gamepadconnected", function(e) {
      console.log("Gamepad connected at index %d: %s. %d buttons, %d axes.",
        e.gamepad.index, e.gamepad.id, e.gamepad.buttons.length, e.gamepad.axes.length);
      gamepads[e.gamepad.index] = e.gamepad;
    });

    window.addEventListener("gamepaddisconnected", function(e) {
      console.log("Gamepad disconnected from index %d: %s",
        e.gamepad.index, e.gamepad.id);
      delete gamepads[e.gamepad.index];
    });

    requestAnimationFrame(update);
  </script>
</body>
</html>

            

              
                Copy
              
            
          

Dit voorbeeld creëert een eenvoudige webpagina die informatie weergeeft over de verbonden gamepads, inclusief hun ID, knopstatussen en aswaarden. U kunt dit voorbeeld gebruiken als uitgangspunt voor het testen en debuggen van uw eigen GamePad API-applicaties.

Best Practices

• Poll de Gamepad-status: Gebruik requestAnimationFrame om de gamepad-status regelmatig te pollen om een vloeiende en responsieve invoer te garanderen.
• Behandel Verbindingsverbrekingen: Luister naar het gamepaddisconnected-evenement en behandel het verbreken van de verbinding met de gamepad correct om fouten te voorkomen.
• Gebruik de Standaard Mapping: Gebruik waar mogelijk de standaard gamepad-mapping om een consistente ervaring te bieden op verschillende gamepads.
• Bied Configuratieopties: Sta gebruikers toe om de knop- en as-toewijzingen te configureren om aan hun individuele behoeften te voldoen.
• Test op Meerdere Browsers: Test uw applicatie op meerdere browsers om een consistent gedrag te garanderen.
• Houd Rekening met Toegankelijkheid: Ontwerp uw game met toegankelijkheid in gedachten om spelers met een handicap tegemoet te komen.

Conclusie

De GamePad API biedt een krachtige en gestandaardiseerde manier om toegang te krijgen tot gamecontrollers vanuit webbrowsers. Door de GamePad API te beheersen, kunt u meeslepende en interactieve webgebaseerde games en applicaties creëren die reageren op gebruikersinvoer van verschillende gamecontrollers.

Deze gids heeft een uitgebreid overzicht gegeven van de GamePad API, van de basisinstallatie tot geavanceerde technieken. Door de tips en best practices in deze gids te volgen, kunt u gamecontroller-ondersteuning effectief integreren in uw webapplicaties en boeiende ervaringen voor uw gebruikers creëren.

Vergeet niet uw applicatie grondig te testen op verschillende browsers en gamepads om een consistent gedrag te garanderen. Houd rekening met de toegankelijkheid voor spelers met een handicap en bied configuratieopties zodat gebruikers de besturing naar wens kunnen aanpassen. Met een beetje inspanning kunt u games maken die plezierig en toegankelijk zijn voor een breed scala aan spelers.

Verdere Bronnen

• MDN Web Docs: Gamepad API
• W3C Gamepad-specificatie
• Gamepad Test: Online gamepad-tester