GamePad API: En Omfattende Guide til Håndtering af Spilcontroller-Input

GamePad API'et giver en standardiseret måde at tilgå spilcontrollere direkte fra webbrowsere. Dette åbner op for spændende muligheder for at skabe medrivende og interaktive webbaserede spil og applikationer. Denne omfattende guide vil gennemgå alt, hvad du behøver at vide for at udnytte GamePad API'et effektivt, fra grundlæggende opsætning til avancerede teknikker.

Hvad er GamePad API'et?

GamePad API'et er et JavaScript API, der giver webapplikationer mulighed for at registrere og reagere på input fra spilcontrollere (gamepads, joysticks osv.). Det gør det muligt for udviklere at bygge spil og interaktive oplevelser, der kan styres ved hjælp af standard gamepad-input, såsom knapper, akser (analoge pinde) og aftrækkere.

Før GamePad API'et var håndtering af spilcontroller-input i webbrowsere en fragmenteret og upålidelig oplevelse, der ofte krævede browserspecifikke plugins eller komplekse løsninger. GamePad API'et giver en konsistent løsning på tværs af browsere, hvilket forenkler processen med at integrere understøttelse af spilcontrollere i webapplikationer.

Browserkompatibilitet

GamePad API'et er bredt understøttet på tværs af moderne browsere, herunder:

• Chrome (desktop og mobil)
• Firefox (desktop og mobil)
• Safari (desktop og mobil, med visse begrænsninger)
• Edge
• Opera

Selvom browserunderstøttelsen generelt er god, kan der være små forskelle i implementering og tilgængelighed af funktioner på tværs af forskellige browsere. Det er altid en god praksis at teste din applikation på flere browsere for at sikre en ensartet opførsel.

Kom Godt i Gang med GamePad API'et

Her er en trin-for-trin guide til at komme i gang med GamePad API'et:

1. Registrering af Gamepad-tilslutning

Metoden navigator.getGamepads() returnerer et array af Gamepad-objekter, der repræsenterer de aktuelt tilsluttede gamepads. Browseren vil udløse gamepadconnected og gamepaddisconnected hændelser, når gamepads henholdsvis tilsluttes eller frakobles. Du kan lytte efter disse hændelser for at opdatere din applikations tilstand.

            window.addEventListener("gamepadconnected", function(e) {
  console.log("Gamepad tilsluttet ved indeks %d: %s. %d knapper, %d akser.",
    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 frakoblet fra indeks %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
              
            
          

Dette kodestykke opsætter hændelseslyttere for gamepadconnected og gamepaddisconnected hændelser. Funktionen gamepadHandler opdaterer et gamepads-objekt for at holde styr på tilsluttede gamepads.

2. Polling af Gamepad-tilstand

GamePad API'et er primært hændelsesdrevet, men for kontinuerligt input (som bevægelse af analoge pinde), skal du polle gamepad-tilstanden i en requestAnimationFrame-løkke. Dette indebærer at kalde navigator.getGamepads() gentagne gange og undersøge buttons- og axes-egenskaberne for Gamepad-objekterne.

            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) {
      // Behandl gamepad-input her
      for (var j = 0; j < gp.buttons.length; j++) {
        if (gp.buttons[j].pressed) {
          console.log("Knap " + j + " trykket ned");
        }
      }
      for (var j = 0; j < gp.axes.length; j++) {
        console.log("Akse " + j + ": " + gp.axes[j]);
      }
    }
  }
  requestAnimationFrame(update);
}

requestAnimationFrame(update);

            

              
                Copy
              
            
          

Dette kodestykke opdaterer løbende gamepad-tilstanden ved hjælp af requestAnimationFrame. Det itererer gennem de tilsluttede gamepads og kontrollerer tilstanden af deres knapper og akser.

3. Forståelse af Gamepad-egenskaber

Hvert Gamepad-objekt har følgende nøgleegenskaber:

• id: En streng, der identificerer gamepad'en (f.eks. "Xbox Controller (XInput STANDARD GAMEPAD)").
• index: Indekset for gamepad'en i navigator.getGamepads()-arrayet.
• connected: En boolean, der angiver, om gamepad'en er tilsluttet.
• buttons: Et array af GamepadButton-objekter, der repræsenterer gamepad'ens knapper.
• axes: Et array af tal, der repræsenterer gamepad'ens akser (analoge pinde og aftrækkere).
• mapping: En streng, der angiver gamepad'ens knaptildeling (enten "standard" eller "").

4. Arbejde med Gamepad-knapper

Hvert GamepadButton-objekt har følgende egenskaber:

• pressed: En boolean, der angiver, om knappen er trykket ned.
• value: Et tal mellem 0 og 1, der repræsenterer det tryk, der anvendes på knappen (for trykfølsomme knapper som aftrækkere).

Du kan tilgå en knaps tilstand ved hjælp af dens indeks i buttons-arrayet. For eksempel vil gamepad.buttons[0].pressed returnere true, hvis den første knap er trykket ned.

5. Arbejde med Gamepad-akser

axes-arrayet indeholder tal, der repræsenterer værdierne for gamepad'ens analoge pinde og aftrækkere. Værdierne ligger typisk fra -1 til 1, hvor -1 repræsenterer den yderste venstre/øverste position, og 1 repræsenterer den yderste højre/nederste position.

Du kan tilgå værdien af en akse ved hjælp af dens indeks i axes-arrayet. For eksempel vil gamepad.axes[0] returnere den horisontale position af den venstre analoge pind.

Standard Gamepad-mapping

GamePad API'et definerer en "standard" gamepad-mapping, der giver en ensartet måde at tilgå almindelige gamepad-knapper og -akser på, uanset den specifikke gamepad-model. Denne mapping identificeres ved, at mapping-egenskaben er sat til "standard".

Standard gamepad-mappingen inkluderer følgende knapper:

• Knap 0: A (typisk den nederste højre knap)
• Knap 1: B (typisk den højre knap)
• Knap 2: X (typisk den venstre knap)
• Knap 3: Y (typisk den øverste knap)
• Knap 4: Venstre skulderknap (LB)
• Knap 5: Højre skulderknap (RB)
• Knap 6: Venstre aftrækker (LT)
• Knap 7: Højre aftrækker (RT)
• Knap 8: Select (eller Back)
• Knap 9: Start
• Knap 10: Venstre pind-knap (LS)
• Knap 11: Højre pind-knap (RS)
• Knap 12: D-pad Op
• Knap 13: D-pad Ned
• Knap 14: D-pad Venstre
• Knap 15: D-pad Højre
• Knap 16: Guide (eller Home)

Standard gamepad-mappingen inkluderer følgende akser:

• Akse 0: Venstre pind, horisontal akse (-1 = venstre, 1 = højre)
• Akse 1: Venstre pind, vertikal akse (-1 = op, 1 = ned)
• Akse 2: Højre pind, horisontal akse (-1 = venstre, 1 = højre)
• Akse 3: Højre pind, vertikal akse (-1 = op, 1 = ned)

Det er vigtigt at bemærke, at ikke alle gamepads understøtter standard-mappingen. Gamepads, der ikke understøtter standard-mappingen, vil have en tom streng for mapping-egenskaben, og du bliver nødt til at bruge id-egenskaben til at identificere gamepad'en og tildele dens knapper og akser i overensstemmelse hermed.

Håndtering af Ikke-standard Gamepads

Når du arbejder med ikke-standard gamepads, skal du identificere gamepad'en baseret på dens id-egenskab og oprette en brugerdefineret mapping for dens knapper og akser. Dette kan være en udfordrende opgave, da der findes mange forskellige gamepad-modeller, hver med sit eget unikke layout af knapper og akser.

Her er nogle strategier til håndtering af ikke-standard gamepads:

• Gamepad-database: Opret en database med gamepad id-strenge og deres tilsvarende knap- og akse-mappings. Dette giver dig mulighed for automatisk at tildele knapper og akser for kendte gamepads.
• Brugerkonfiguration: Tillad brugere at konfigurere knap- og akse-mappings for deres gamepads. Dette giver fleksibilitet for brugere med ualmindelige gamepads.
• Heuristisk mapping: Brug heuristik til at gætte knap- og akse-mappings baseret på antallet af knapper og akser og deres typiske brugsmønstre.

Implementering af understøttelse for et bredt udvalg af gamepads kan være en betydelig opgave. Overvej at fokusere på at understøtte de mest populære gamepad-modeller først og gradvist tilføje understøttelse for flere gamepads efter behov.

Avancerede Teknikker

1. Dødzoner

Analoge pinde har ofte en "dødzone" omkring centerpositionen, hvor den rapporterede værdi er forskellig fra nul, selv når pinden ikke berøres. Dette kan forårsage uønsket bevægelse eller rysten i dit spil. For at løse dette kan du implementere en dødzone ved at sætte akseværdien til nul, hvis den falder inden for et bestemt interval omkring nul.

            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
              
            
          

Dette kodestykke anvender en dødzone på akseværdien. Hvis den absolutte værdi af aksen er mindre end deadZoneThreshold, vil den justerede værdi være nul. Ellers vil den justerede værdi blive skaleret til intervallet 0-1, mens fortegnet for den oprindelige værdi bevares.

2. Eksponentiel Udjævning

Input fra analoge pinde kan undertiden være støjende, hvilket forårsager hakkende eller uforudsigelig bevægelse. For at udjævne inputtet kan du anvende eksponentiel udjævning. Dette indebærer at tage et gennemsnit af den aktuelle inputværdi og den tidligere udjævnede værdi, hvor der lægges mere vægt på den tidligere værdi.

            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
              
            
          

Dette kodestykke anvender eksponentiel udjævning på akseværdien. smoothingFactor bestemmer den vægt, der gives til den aktuelle værdi. En mindre udjævningsfaktor vil resultere i et glattere, men mere forsinket input.

3. Knap-debouncing

Knapper kan undertiden udløse flere hændelser, når de trykkes ned eller slippes på grund af mekanisk 'bouncing'. Dette kan forårsage utilsigtet adfærd i dit spil. For at løse dette kan du implementere knap-debouncing. Dette indebærer at ignorere knaphændelser, der opstår inden for en kort periode efter en tidligere hændelse.

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

function handleButtonPress(buttonIndex) {
  if (!buttonStates[buttonIndex] || Date.now() - buttonStates[buttonIndex].lastPress > debounceDelay) {
    console.log("Knap " + buttonIndex + " trykket ned (debounced)");
    buttonStates[buttonIndex] = { lastPress: Date.now() };
    // Udfør handling her
  }
}

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

            

              
                Copy
              
            
          

Dette kodestykke implementerer knap-debouncing. Det holder styr på, hvornår hver knap sidst blev trykket ned. Hvis en knap trykkes ned igen inden for debounceDelay, ignoreres hændelsen.

Tilgængelighedsovervejelser

Når du udvikler spil med gamepad-understøttelse, er det vigtigt at overveje tilgængelighed for spillere med handicap. Her er nogle tips til at gøre dit spil mere tilgængeligt:

• Konfigurerbare kontroller: Tillad spillere at tilpasse knap- og akse-mappings, så de passer til deres individuelle behov.
• Alternative inputmetoder: Tilbyd alternative inputmetoder, såsom tastatur og mus, for spillere, der ikke kan bruge en gamepad.
• Tydelig visuel feedback: Giv tydelig visuel feedback for alle handlinger, så spillere let kan forstå, hvad der sker i spillet.
• Justerbar sværhedsgrad: Tilbyd justerbare sværhedsgrader for at imødekomme spillere med forskellige færdighedsniveauer.

Ved at følge disse retningslinjer kan du skabe spil, der er underholdende og tilgængelige for en bredere vifte af spillere.

GamePad API og Virtual Reality

GamePad API'et er også relevant i forbindelse med WebVR (Virtual Reality på nettet). VR-controllere, der ofte bruges sammen med VR-headsets, eksponeres hyppigt gennem GamePad API'et. Dette giver udviklere mulighed for at bygge VR-oplevelser, der bruger disse controllere til interaktion.

Når man udvikler VR-applikationer, kan Gamepad-objektet have yderligere egenskaber relateret til dets 'pose' (position og orientering) i 3D-rummet. Disse egenskaber tilgås ved hjælp af pose-egenskaben, som returnerer et GamePadPose-objekt. GamePadPose-objektet giver information om controllerens position, orientering (som en quaternion), lineær hastighed og vinkelhastighed.

Brug af GamePad API'et med WebVR giver udviklere mulighed for at skabe medrivende og interaktive VR-oplevelser, der reagerer på brugerens bevægelser og interaktioner med VR-controllerne.

Eksempel: Simpel Spilcontroller-Tester

Her er et simpelt eksempel på en spilcontroller-tester, der viser tilstanden for de tilsluttede gamepads:

            <!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>Knapper</h3>";
          for (var j = 0; j < gamepad.buttons.length; j++) {
            var button = gamepad.buttons[j];
            var buttonDiv = document.createElement("div");
            buttonDiv.innerHTML = "Knap " + j + ": Trykket = " + button.pressed + ", Værdi = " + button.value;
            buttonsDiv.appendChild(buttonDiv);
          }
          gamepadDiv.appendChild(buttonsDiv);

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

          gamepadsDiv.appendChild(gamepadDiv);
        }
      }
    }

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

    window.addEventListener("gamepadconnected", function(e) {
      console.log("Gamepad tilsluttet ved indeks %d: %s. %d knapper, %d akser.",
        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 frakoblet fra indeks %d: %s",
        e.gamepad.index, e.gamepad.id);
      delete gamepads[e.gamepad.index];
    });

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

            

              
                Copy
              
            
          

Dette eksempel skaber en simpel webside, der viser information om de tilsluttede gamepads, herunder deres ID, knappernes tilstand og aksernes værdier. Du kan bruge dette eksempel som udgangspunkt for at teste og fejlsøge dine egne GamePad API-applikationer.

Bedste Praksis

• Poll for Gamepad-tilstand: Brug requestAnimationFrame til regelmæssigt at polle for gamepad-tilstanden for at sikre jævn og responsiv input.
• Håndter frakoblinger: Lyt efter gamepaddisconnected-hændelsen og håndter frakoblinger af gamepads elegant for at undgå fejl.
• Brug Standard-mapping: Brug standard gamepad-mappingen, når det er muligt, for at give en ensartet oplevelse på tværs af forskellige gamepads.
• Tilbyd konfigurationsmuligheder: Tillad brugere at konfigurere knap- og akse-mappings, så de passer til deres individuelle behov.
• Test på flere browsere: Test din applikation på flere browsere for at sikre ensartet opførsel.
• Overvej tilgængelighed: Design dit spil med tilgængelighed i tankerne for at imødekomme spillere med handicap.

Konklusion

GamePad API'et giver en kraftfuld og standardiseret måde at tilgå spilcontrollere fra webbrowsere. Ved at mestre GamePad API'et kan du skabe medrivende og interaktive webbaserede spil og applikationer, der reagerer på brugerinput fra en række forskellige spilcontrollere.

Denne guide har givet en omfattende oversigt over GamePad API'et, der dækker alt fra grundlæggende opsætning til avancerede teknikker. Ved at følge de tips og bedste praksis, der er beskrevet i denne guide, kan du effektivt integrere understøttelse af spilcontrollere i dine webapplikationer og skabe engagerende oplevelser for dine brugere.

Husk at teste din applikation grundigt på forskellige browsere og gamepads for at sikre ensartet opførsel. Overvej tilgængelighed for spillere med handicap, og tilbyd konfigurationsmuligheder, så brugerne kan tilpasse kontrollerne efter deres smag. Med en lille indsats kan du skabe spil, der er underholdende og tilgængelige for en bred vifte af spillere.

Yderligere Ressourcer

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