GamePad API: En omfattande guide till hantering av indata från spelkontroller

GamePad API erbjuder ett standardiserat sätt att komma åt spelkontroller direkt från webbläsare. Detta öppnar upp spännande möjligheter för att skapa uppslukande och interaktiva webbaserade spel och applikationer. Denna omfattande guide kommer att gå igenom allt du behöver veta för att utnyttja GamePad API effektivt, från grundläggande installation till avancerade tekniker.

Vad är GamePad API?

GamePad API är ett JavaScript-API som låter webbapplikationer upptäcka och svara på indata från spelkontroller (gamepads, joysticks, etc.). Det gör det möjligt för utvecklare att bygga spel och interaktiva upplevelser som kan styras med vanliga spelkontrollsinmatningar, såsom knappar, axlar (analoga spakar) och avtryckare.

Innan GamePad API var hanteringen av indata från spelkontroller i webbläsare en fragmenterad och opålitlig upplevelse, som ofta krävde webbläsarspecifika insticksprogram eller komplexa lösningar. GamePad API erbjuder en konsekvent och webbläsaröverskridande lösning, vilket förenklar processen att integrera stöd för spelkontroller i webbapplikationer.

Webbläsarkompatibilitet

GamePad API stöds brett i moderna webbläsare, inklusive:

• Chrome (dator och mobil)
• Firefox (dator och mobil)
• Safari (dator och mobil, med vissa begränsningar)
• Edge
• Opera

Även om stödet i webbläsare generellt är bra kan det finnas subtila skillnader i implementation och funktionstillgänglighet mellan olika webbläsare. Det är alltid en god praxis att testa din applikation i flera webbläsare för att säkerställa ett konsekvent beteende.

Komma igång med GamePad API

Här är en steg-för-steg-guide för att komma igång med GamePad API:

1. Upptäcka anslutning av spelkontroll

Metoden navigator.getGamepads() returnerar en array av Gamepad-objekt, som representerar de för närvarande anslutna spelkontrollerna. Webbläsaren kommer att avfyra gamepadconnected- och gamepaddisconnected-händelser när spelkontroller ansluts eller kopplas från. Du kan lyssna efter dessa händelser för att uppdatera din applikations tillstånd.

            window.addEventListener("gamepadconnected", function(e) {
  console.log("Spelkontroll ansluten vid index %d: %s. %d knappar, %d axlar.",
    e.gamepad.index, e.gamepad.id, e.gamepad.buttons.length, e.gamepad.axes.length);
  gamepadHandler(e, true);
});

window.addEventListener("gamepaddisconnected", function(e) {
  console.log("Spelkontroll frånkopplad från 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
              
            
          

Detta kodstycke sätter upp händelselyssnare för gamepadconnected- och gamepaddisconnected-händelser. Funktionen gamepadHandler uppdaterar ett gamepads-objekt för att hålla reda på anslutna spelkontroller.

2. Avfrågning av spelkontrollens status

GamePad API är primärt händelsestyrt, men för kontinuerlig inmatning (som rörelse med analog spak) måste du avfråga spelkontrollens status i en requestAnimationFrame-loop. Detta innebär att anropa navigator.getGamepads() upprepade gånger och undersöka egenskaperna buttons och axes hos Gamepad-objekten.

            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) {
      // Bearbeta spelkontrollens indata här
      for (var j = 0; j < gp.buttons.length; j++) {
        if (gp.buttons[j].pressed) {
          console.log("Knapp " + j + " nedtryckt");
        }
      }
      for (var j = 0; j < gp.axes.length; j++) {
        console.log("Axel " + j + ": " + gp.axes[j]);
      }
    }
  }
  requestAnimationFrame(update);
}

requestAnimationFrame(update);

            

              
                Copy
              
            
          

Detta kodstycke uppdaterar kontinuerligt spelkontrollens status med hjälp av requestAnimationFrame. Det itererar genom de anslutna spelkontrollerna och kontrollerar statusen på deras knappar och axlar.

3. Förstå spelkontrollens egenskaper

Varje Gamepad-objekt har följande nyckelegenskaper:

• id: En sträng som identifierar spelkontrollen (t.ex. "Xbox Controller (XInput STANDARD GAMEPAD)").
• index: Indexet för spelkontrollen i navigator.getGamepads()-arrayen.
• connected: Ett booleskt värde som anger om spelkontrollen är ansluten.
• buttons: En array av GamepadButton-objekt, som representerar spelkontrollens knappar.
• axes: En array av tal, som representerar spelkontrollens axlar (analoga spakar och avtryckare).
• mapping: En sträng som anger spelkontrollens knappmappning (antingen "standard" eller "").

4. Arbeta med spelkontrollens knappar

Varje GamepadButton-objekt har följande egenskaper:

• pressed: Ett booleskt värde som anger om knappen är nedtryckt.
• value: Ett tal mellan 0 och 1 som representerar trycket som appliceras på knappen (för tryckkänsliga knappar som avtryckare).

Du kan komma åt en knapps status med hjälp av dess index i buttons-arrayen. Till exempel skulle gamepad.buttons[0].pressed returnera true om den första knappen är nedtryckt.

5. Arbeta med spelkontrollens axlar

axes-arrayen innehåller tal som representerar värdena från spelkontrollens analoga spakar och avtryckare. Värdena varierar vanligtvis från -1 till 1, där -1 representerar den vänstra/översta positionen och 1 representerar den högra/nedersta positionen.

Du kan komma åt en axels värde med hjälp av dess index i axes-arrayen. Till exempel skulle gamepad.axes[0] returnera den horisontella positionen för den vänstra analoga spaken.

Standardmappning för spelkontroller

GamePad API definierar en "standard"-mappning för spelkontroller som erbjuder ett konsekvent sätt att komma åt vanliga knappar och axlar, oavsett specifik spelkontrollsmodell. Denna mappning identifieras genom att egenskapen mapping är satt till "standard".

Standardmappningen för spelkontroller inkluderar följande knappar:

• Knapp 0: A (vanligtvis den nedre högra knappen)
• Knapp 1: B (vanligtvis den högra knappen)
• Knapp 2: X (vanligtvis den vänstra knappen)
• Knapp 3: Y (vanligtvis den övre knappen)
• Knapp 4: Vänster bumper (LB)
• Knapp 5: Höger bumper (RB)
• Knapp 6: Vänster avtryckare (LT)
• Knapp 7: Höger avtryckare (RT)
• Knapp 8: Select (eller Back)
• Knapp 9: Start
• Knapp 10: Vänster spak-knapp (LS)
• Knapp 11: Höger spak-knapp (RS)
• Knapp 12: Styrkors Upp
• Knapp 13: Styrkors Ner
• Knapp 14: Styrkors Vänster
• Knapp 15: Styrkors Höger
• Knapp 16: Guide (eller Home)

Standardmappningen för spelkontroller inkluderar följande axlar:

• Axel 0: Vänster spak, horisontell axel (-1 = vänster, 1 = höger)
• Axel 1: Vänster spak, vertikal axel (-1 = upp, 1 = ner)
• Axel 2: Höger spak, horisontell axel (-1 = vänster, 1 = höger)
• Axel 3: Höger spak, vertikal axel (-1 = upp, 1 = ner)

Det är viktigt att notera att inte alla spelkontroller stöder standardmappningen. Spelkontroller som inte stöder standardmappningen kommer att ha en tom sträng för egenskapen mapping, och du måste använda egenskapen id för att identifiera spelkontrollen och mappa dess knappar och axlar därefter.

Hantering av icke-standardiserade spelkontroller

När du hanterar icke-standardiserade spelkontroller måste du identifiera spelkontrollen baserat på dess id-egenskap och skapa en anpassad mappning för dess knappar och axlar. Detta kan vara en utmanande uppgift, eftersom det finns många olika modeller av spelkontroller tillgängliga, var och en med sin egen unika layout för knappar och axlar.

Här är några strategier för att hantera icke-standardiserade spelkontroller:

• Spelkontrollsdatabas: Skapa en databas med id-strängar för spelkontroller och deras motsvarande knapp- och axelmappningar. Detta gör att du automatiskt kan mappa knappar och axlar för kända spelkontroller.
• Användarkonfiguration: Låt användare konfigurera knapp- och axelmappningarna för sina spelkontroller. Detta ger flexibilitet för användare med ovanliga spelkontroller.
• Heuristisk mappning: Använd heuristik för att gissa knapp- och axelmappningar baserat på antalet knappar och axlar och deras typiska användningsmönster.

Att implementera stöd för ett brett utbud av spelkontroller kan vara ett betydande åtagande. Överväg att först fokusera på att stödja de mest populära spelkontrollsmodellerna och gradvis lägga till stöd för fler spelkontroller vid behov.

Avancerade tekniker

1. Dödzoner

Analoga spakar har ofta en "dödzon" runt mittpositionen där det rapporterade värdet inte är noll även när spaken inte rörs. Detta kan orsaka oönskad rörelse eller darrningar i ditt spel. För att åtgärda detta kan du implementera en dödzon genom att sätta axelvärdet till noll om det faller inom ett visst intervall runt noll.

            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
              
            
          

Detta kodstycke tillämpar en dödzon på axelvärdet. Om det absoluta värdet av axeln är mindre än deadZoneThreshold, kommer det justerade värdet att vara noll. Annars kommer det justerade värdet att skalas till intervallet 0-1, med bibehållet tecken från det ursprungliga värdet.

2. Exponentiell utjämning

Indata från analoga spakar kan ibland vara brusig, vilket orsakar ryckiga eller oförutsägbara rörelser. För att jämna ut indatan kan du tillämpa exponentiell utjämning. Detta innebär att man beräknar ett medelvärde av det aktuella inmatningsvärdet och det föregående utjämnade värdet, med mer vikt på det föregående värdet.

            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
              
            
          

Detta kodstycke tillämpar exponentiell utjämning på axelvärdet. smoothingFactor bestämmer vikten som ges till det aktuella värdet. En mindre utjämningsfaktor resulterar i en jämnare men mer fördröjd inmatning.

3. Knapp-avstudsning (Debouncing)

Knappar kan ibland utlösa flera händelser när de trycks ner eller släpps på grund av mekanisk studs. Detta kan orsaka oavsiktligt beteende i ditt spel. För att åtgärda detta kan du implementera knapp-avstudsning. Detta innebär att man ignorerar knapphändelser som inträffar inom en kort tidsperiod efter en föregående händelse.

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

function handleButtonPress(buttonIndex) {
  if (!buttonStates[buttonIndex] || Date.now() - buttonStates[buttonIndex].lastPress > debounceDelay) {
    console.log("Knapp " + buttonIndex + " nedtryckt (avstudsad)");
    buttonStates[buttonIndex] = { lastPress: Date.now() };
    // Utför åtgärd här
  }
}

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

            

              
                Copy
              
            
          

Detta kodstycke implementerar knapp-avstudsning. Det håller reda på när varje knapp senast trycktes ner. Om en knapp trycks ner igen inom debounceDelay, ignoreras händelsen.

Tillgänglighetsaspekter

När man utvecklar spel med stöd för spelkontroller är det viktigt att ta hänsyn till tillgänglighet för spelare med funktionsnedsättningar. Här är några tips för att göra ditt spel mer tillgängligt:

• Konfigurerbara kontroller: Låt spelare anpassa knapp- och axelmappningarna för att passa deras individuella behov.
• Alternativa inmatningsmetoder: Tillhandahåll alternativa inmatningsmetoder, såsom tangentbord och mus, för spelare som inte kan använda en spelkontroll.
• Tydlig visuell återkoppling: Ge tydlig visuell återkoppling för alla åtgärder, så att spelare enkelt kan förstå vad som händer i spelet.
• Justerbar svårighetsgrad: Erbjud justerbara svårighetsgrader för att tillgodose spelare med olika färdighetsnivåer.

Genom att följa dessa riktlinjer kan du skapa spel som är roliga och tillgängliga för ett bredare spektrum av spelare.

GamePad API och virtuell verklighet (VR)

GamePad API är också relevant i samband med WebVR (Virtual Reality på webben). VR-kontroller, som ofta används tillsammans med VR-headset, exponeras ofta via GamePad API. Detta gör det möjligt för utvecklare att bygga VR-upplevelser som använder dessa kontroller för interaktion.

När man utvecklar VR-applikationer kan Gamepad-objektet ha ytterligare egenskaper relaterade till dess pose (position och orientering) i 3D-rymden. Dessa egenskaper nås med hjälp av egenskapen pose, som returnerar ett GamePadPose-objekt. GamePadPose-objektet ger information om kontrollens position, orientering (som en kvaternion), linjär hastighet och vinkelhastighet.

Att använda GamePad API med WebVR gör det möjligt för utvecklare att skapa uppslukande och interaktiva VR-upplevelser som svarar på användarens rörelser och interaktioner med VR-kontrollerna.

Exempel: Enkel testare för spelkontroller

Här är ett enkelt exempel på en testare för spelkontroller som visar statusen för anslutna spelkontroller:

            <!DOCTYPE html>
<html>
<head>
  <title>Spelkontrollstestare</title>
  <style>
    body {
      font-family: sans-serif;
    }
  </style>
</head>
<body>
  <h1>Spelkontrollstestare</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>Spelkontroll " + i + ": " + gamepad.id + "</h2>";

          var buttonsDiv = document.createElement("div");
          buttonsDiv.innerHTML = "<h3>Knappar</h3>";
          for (var j = 0; j < gamepad.buttons.length; j++) {
            var button = gamepad.buttons[j];
            var buttonDiv = document.createElement("div");
            buttonDiv.innerHTML = "Knapp " + j + ": Nedtryckt = " + button.pressed + ", Värde = " + button.value;
            buttonsDiv.appendChild(buttonDiv);
          }
          gamepadDiv.appendChild(buttonsDiv);

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

          gamepadsDiv.appendChild(gamepadDiv);
        }
      }
    }

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

    window.addEventListener("gamepadconnected", function(e) {
      console.log("Spelkontroll ansluten vid index %d: %s. %d knappar, %d axlar.",
        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("Spelkontroll frånkopplad från index %d: %s",
        e.gamepad.index, e.gamepad.id);
      delete gamepads[e.gamepad.index];
    });

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

            

              
                Copy
              
            
          

Detta exempel skapar en enkel webbsida som visar information om anslutna spelkontroller, inklusive deras ID, knappstatus och axelvärden. Du kan använda detta exempel som en utgångspunkt för att testa och felsöka dina egna GamePad API-applikationer.

Bästa praxis

• Avfråga spelkontrollens status: Använd requestAnimationFrame för att regelbundet avfråga spelkontrollens status för att säkerställa smidig och responsiv inmatning.
• Hantera frånkopplingar: Lyssna efter gamepaddisconnected-händelsen och hantera frånkopplingar av spelkontroller på ett elegant sätt för att undvika fel.
• Använd standardmappning: Använd standardmappningen för spelkontroller när det är möjligt för att ge en konsekvent upplevelse över olika spelkontroller.
• Erbjud konfigurationsalternativ: Låt användare konfigurera knapp- och axelmappningar för att passa deras individuella behov.
• Testa i flera webbläsare: Testa din applikation i flera webbläsare för att säkerställa ett konsekvent beteende.
• Tänk på tillgänglighet: Utforma ditt spel med tillgänglighet i åtanke för att tillgodose spelare med funktionsnedsättningar.

Slutsats

GamePad API erbjuder ett kraftfullt och standardiserat sätt att komma åt spelkontroller från webbläsare. Genom att bemästra GamePad API kan du skapa uppslukande och interaktiva webbaserade spel och applikationer som svarar på användarens indata från en mängd olika spelkontroller.

Denna guide har gett en omfattande översikt över GamePad API, och täcker allt från grundläggande installation till avancerade tekniker. Genom att följa tipsen och bästa praxis som beskrivs i denna guide kan du effektivt integrera stöd för spelkontroller i dina webbapplikationer och skapa engagerande upplevelser för dina användare.

Kom ihåg att testa din applikation noggrant i olika webbläsare och med olika spelkontroller för att säkerställa ett konsekvent beteende. Tänk på tillgänglighet för spelare med funktionsnedsättningar, och erbjud konfigurationsalternativ för att låta användare anpassa kontrollerna efter eget tycke. Med lite ansträngning kan du skapa spel som är roliga och tillgängliga för ett brett spektrum av spelare.

Ytterligare resurser

• MDN Web Docs: Gamepad API
• W3C Gamepad-specifikation
• Gamepad Test: Onlinetestare för spelkontroller