GamePad API: Kattava opas peliohjainten syötteenkäsittelyyn

GamePad API tarjoaa standardoidun tavan käyttää peliohjaimia suoraan verkkoselaimista. Tämä avaa jännittäviä mahdollisuuksia luoda mukaansatempaavia ja interaktiivisia verkkopohjaisia pelejä ja sovelluksia. Tämä kattava opas käy läpi kaiken, mitä sinun tarvitsee tietää hyödyntääksesi GamePad API:a tehokkaasti, perusasetuksista edistyneisiin tekniikoihin.

Mikä on GamePad API?

GamePad API on JavaScript-ohjelmointirajapinta (API), joka antaa verkkosovelluksille mahdollisuuden tunnistaa ja reagoida peliohjainten (peliohjaimet, joystickit jne.) syötteisiin. Se mahdollistaa kehittäjille pelien ja interaktiivisten kokemusten rakentamisen, joita voidaan ohjata tavallisilla peliohjainsyötteillä, kuten painikkeilla, akseleilla (analogiset sauvat) ja liipaisimilla.

Ennen GamePad API:a peliohjainten syötteen käsittely verkkoselaimissa oli hajanaista ja epäluotettavaa, vaatien usein selainkohtaisia lisäosia tai monimutkaisia kiertoteitä. GamePad API tarjoaa yhtenäisen ja selainriippumattoman ratkaisun, joka yksinkertaistaa peliohjaintuen integrointia verkkosovelluksiin.

Selainyhteensopivuus

GamePad API on laajalti tuettu nykyaikaisissa selaimissa, mukaan lukien:

• Chrome (työpöytä ja mobiili)
• Firefox (työpöytä ja mobiili)
• Safari (työpöytä ja mobiili, joitakin rajoituksia)
• Edge
• Opera

Vaikka selaintuki on yleisesti ottaen hyvä, toteutuksessa ja ominaisuuksien saatavuudessa voi olla pieniä eroja eri selainten välillä. On aina hyvä käytäntö testata sovellusta useilla selaimilla yhtenäisen toiminnan varmistamiseksi.

GamePad API:n käytön aloittaminen

Tässä on vaiheittainen opas GamePad API:n käytön aloittamiseen:

1. Peliohjaimen yhteyden tunnistaminen

Metodi navigator.getGamepads() palauttaa taulukon Gamepad-olioita, jotka edustavat tällä hetkellä yhdistettyjä peliohjaimia. Selain laukaisee gamepadconnected- ja gamepaddisconnected-tapahtumat, kun peliohjaimia yhdistetään tai irrotetaan. Voit kuunnella näitä tapahtumia päivittääksesi sovelluksesi tilaa.

            window.addEventListener("gamepadconnected", function(e) {
  console.log("Peliohjain yhdistetty indeksissä %d: %s. %d painiketta, %d akselia.",
    e.gamepad.index, e.gamepad.id, e.gamepad.buttons.length, e.gamepad.axes.length);
  gamepadHandler(e, true);
});

window.addEventListener("gamepaddisconnected", function(e) {
  console.log("Peliohjain irrotettu indeksistä %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
              
            
          

Tämä koodinpätkä asettaa tapahtumakuuntelijat gamepadconnected- ja gamepaddisconnected-tapahtumille. Funktio gamepadHandler päivittää gamepads-oliota pitääkseen kirjaa yhdistetyistä peliohjaimista.

2. Peliohjaimen tilan kysely (polling)

GamePad API on pääasiassa tapahtumapohjainen, mutta jatkuvaa syötettä varten (kuten analogisen sauvan liike) sinun tulee kysellä peliohjaimen tilaa requestAnimationFrame-silmukassa. Tämä tarkoittaa navigator.getGamepads()-metodin kutsumista toistuvasti ja Gamepad-olioiden buttons- ja axes-ominaisuuksien tutkimista.

            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) {
      // Käsittele peliohjaimen syöte tässä
      for (var j = 0; j < gp.buttons.length; j++) {
        if (gp.buttons[j].pressed) {
          console.log("Painike " + j + " painettu");
        }
      }
      for (var j = 0; j < gp.axes.length; j++) {
        console.log("Akseli " + j + ": " + gp.axes[j]);
      }
    }
  }
  requestAnimationFrame(update);
}

requestAnimationFrame(update);

            

              
                Copy
              
            
          

Tämä koodinpätkä päivittää jatkuvasti peliohjaimen tilaa käyttäen requestAnimationFrame-metodia. Se käy läpi yhdistetyt peliohjaimet ja tarkistaa niiden painikkeiden ja akselien tilan.

3. Gamepad-ominaisuuksien ymmärtäminen

Jokaisella Gamepad-oliolla on seuraavat keskeiset ominaisuudet:

• id: Merkkijono, joka tunnistaa peliohjaimen (esim. "Xbox Controller (XInput STANDARD GAMEPAD)").
• index: Peliohjaimen indeksi navigator.getGamepads()-taulukossa.
• connected: Boolean-arvo, joka ilmaisee, onko peliohjain tällä hetkellä yhdistetty.
• buttons: Taulukko GamepadButton-olioita, jotka edustavat peliohjaimen painikkeita.
• axes: Taulukko numeroita, jotka edustavat peliohjaimen akseleita (analogiset sauvat ja liipaisimet).
• mapping: Merkkijono, joka ilmaisee peliohjaimen painikekartoituksen (joko "standard" tai "").

4. Peliohjaimen painikkeiden käsittely

Jokaisella GamepadButton-oliolla on seuraavat ominaisuudet:

• pressed: Boolean-arvo, joka ilmaisee, onko painiketta painettu tällä hetkellä.
• value: Numero välillä 0 ja 1, joka edustaa painikkeeseen kohdistuvaa painetta (paineherkille painikkeille, kuten liipaisimille).

Voit tarkistaa painikkeen tilan sen indeksin avulla buttons-taulukossa. Esimerkiksi gamepad.buttons[0].pressed palauttaisi true, jos ensimmäistä painiketta painetaan.

5. Peliohjaimen akselien käsittely

axes-taulukko sisältää numeroita, jotka edustavat peliohjaimen analogisten sauvojen ja liipaisimien arvoja. Arvot ovat tyypillisesti välillä -1 ja 1, joista -1 edustaa äärimmäistä vasenta/ylintä asentoa ja 1 äärimmäistä oikeaa/alinta asentoa.

Voit tarkistaa akselin arvon sen indeksin avulla axes-taulukossa. Esimerkiksi gamepad.axes[0] palauttaisi vasemman analogisen sauvan vaaka-asennon.

Standardi peliohjainkartoitus

GamePad API määrittelee "standard"-peliohjainkartoituksen, joka tarjoaa yhtenäisen tavan käyttää yleisimpiä peliohjaimen painikkeita ja akseleita riippumatta ohjainmallista. Tämä kartoitus tunnistetaan siitä, että mapping-ominaisuuden arvona on "standard".

Standardi peliohjainkartoitus sisältää seuraavat painikkeet:

• Painike 0: A (tyypillisesti oikeanpuoleinen alapainike)
• Painike 1: B (tyypillisesti oikeanpuoleinen painike)
• Painike 2: X (tyypillisesti vasemmanpuoleinen painike)
• Painike 3: Y (tyypillisesti ylin painike)
• Painike 4: Vasen olkapainike (LB)
• Painike 5: Oikea olkapainike (RB)
• Painike 6: Vasen liipaisin (LT)
• Painike 7: Oikea liipaisin (RT)
• Painike 8: Select (tai Back)
• Painike 9: Start
• Painike 10: Vasemman sauvan painike (LS)
• Painike 11: Oikean sauvan painike (RS)
• Painike 12: D-pad Ylös
• Painike 13: D-pad Alas
• Painike 14: D-pad Vasen
• Painike 15: D-pad Oikea
• Painike 16: Guide (tai Home)

Standardi peliohjainkartoitus sisältää seuraavat akselit:

• Akseli 0: Vasen sauva, vaaka-akseli (-1 = vasen, 1 = oikea)
• Akseli 1: Vasen sauva, pystyakseli (-1 = ylös, 1 = alas)
• Akseli 2: Oikea sauva, vaaka-akseli (-1 = vasen, 1 = oikea)
• Akseli 3: Oikea sauva, pystyakseli (-1 = ylös, 1 = alas)

On tärkeää huomata, että kaikki peliohjaimet eivät tue standardikartoitusta. Peliohjaimilla, jotka eivät tue standardikartoitusta, mapping-ominaisuuden arvo on tyhjä merkkijono, ja sinun on käytettävä id-ominaisuutta peliohjaimen tunnistamiseen ja sen painikkeiden ja akselien kartoittamiseen vastaavasti.

Ei-standardien peliohjainten käsittely

Käsitellessäsi ei-standardeja peliohjaimia sinun on tunnistettava peliohjain sen id-ominaisuuden perusteella ja luotava mukautettu kartoitus sen painikkeille ja akseleille. Tämä voi olla haastava tehtävä, koska saatavilla on monia erilaisia ohjainmalleja, joilla kaikilla on oma ainutlaatuinen painike- ja akseliasettelunsa.

Tässä on joitakin strategioita ei-standardien peliohjainten käsittelyyn:

• Peliohjaintietokanta: Luo tietokanta peliohjainten id-merkkijonoista ja niiden vastaavista painike- ja akselikartoituksista. Tämä mahdollistaa tunnettujen peliohjainten painikkeiden ja akselien automaattisen kartoittamisen.
• Käyttäjän määritykset: Anna käyttäjien määrittää painike- ja akselikartoitukset omille peliohjaimilleen. Tämä tarjoaa joustavuutta käyttäjille, joilla on harvinaisempia peliohjaimia.
• Heuristinen kartoitus: Päättele painike- ja akselikartoitukset heuristiikan avulla perustuen painikkeiden ja akselien lukumäärään ja niiden tyypillisiin käyttömalleihin.

Tuen toteuttaminen laajalle valikoimalle peliohjaimia voi olla merkittävä urakka. Harkitse keskittymistä ensin suosituimpien peliohjainmallien tukemiseen ja lisää tukea muille ohjaimille vähitellen tarpeen mukaan.

Edistyneet tekniikat

1. Katvealueet (Dead Zones)

Analogisilla sauvoilla on usein "katvealue" keskikohdan ympärillä, jossa ilmoitettu arvo ei ole nolla, vaikka sauvaan ei koskettaisikaan. Tämä voi aiheuttaa ei-toivottua liikettä tai tärinää pelissäsi. Voit korjata tämän toteuttamalla katvealueen asettamalla akselin arvon nollaksi, jos se on tietyllä alueella nollan ympärillä.

            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
              
            
          

Tämä koodinpätkä soveltaa katvealueen akselin arvoon. Jos akselin itseisarvo on pienempi kuin deadZoneThreshold, säädetty arvo on nolla. Muussa tapauksessa säädetty arvo skaalataan välille 0-1 säilyttäen alkuperäisen arvon etumerkin.

2. Eksponentiaalinen tasoitus

Analogisen sauvan syöte voi joskus olla kohinaista, aiheuttaen nykivää tai arvaamatonta liikettä. Syötteen tasoittamiseksi voit käyttää eksponentiaalista tasoitusta. Tämä tarkoittaa nykyisen syötearvon keskiarvon laskemista edellisen tasoitetun arvon kanssa, antaen enemmän painoarvoa edelliselle arvolle.

            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
              
            
          

Tämä koodinpätkä soveltaa eksponentiaalista tasoitusta akselin arvoon. smoothingFactor määrittää nykyiselle arvolle annetun painoarvon. Pienempi tasoituskerroin johtaa tasaisempaan mutta viivästetympään syötteeseen.

3. Painikkeen tärinänesto (Debouncing)

Painikkeet voivat joskus laukaista useita tapahtumia painettaessa tai vapautettaessa mekaanisen tärinän vuoksi. Tämä voi aiheuttaa tahatonta toimintaa pelissäsi. Voit korjata tämän toteuttamalla painikkeen tärinäneston. Tämä tarkoittaa painiketapahtumien ohittamista, jotka tapahtuvat lyhyen ajan sisällä edellisestä tapahtumasta.

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

function handleButtonPress(buttonIndex) {
  if (!buttonStates[buttonIndex] || Date.now() - buttonStates[buttonIndex].lastPress > debounceDelay) {
    console.log("Painike " + buttonIndex + " painettu (tärinänesto)");
    buttonStates[buttonIndex] = { lastPress: Date.now() };
    // Suorita toiminto tässä
  }
}

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

            

              
                Copy
              
            
          

Tämä koodinpätkä toteuttaa painikkeen tärinäneston. Se pitää kirjaa siitä, milloin kutakin painiketta on viimeksi painettu. Jos painiketta painetaan uudelleen debounceDelay-ajan sisällä, tapahtuma ohitetaan.

Saavutettavuusnäkökohdat

Kehitettäessä pelejä, joissa on peliohjaintuki, on tärkeää ottaa huomioon saavutettavuus vammaisille pelaajille. Tässä muutamia vinkkejä pelisi saavutettavuuden parantamiseksi:

• Muokattavat ohjaimet: Anna pelaajien mukauttaa painike- ja akselikartoituksia omien tarpeidensa mukaan.
• Vaihtoehtoiset syötetavat: Tarjoa vaihtoehtoisia syötetapoja, kuten näppäimistö ja hiiri, pelaajille, jotka eivät voi käyttää peliohjainta.
• Selkeä visuaalinen palaute: Anna selkeää visuaalista palautetta kaikista toiminnoista, jotta pelaajat ymmärtävät helposti, mitä pelissä tapahtuu.
• Säädettävä vaikeustaso: Tarjoa säädettäviä vaikeustasoja, jotka sopivat eri taitotason pelaajille.

Noudattamalla näitä ohjeita voit luoda pelejä, jotka ovat nautinnollisia ja saavutettavia laajemmalle pelaajakunnalle.

GamePad API ja virtuaalitodellisuus

GamePad API on relevantti myös WebVR:n (virtuaalitodellisuus verkossa) yhteydessä. VR-ohjaimet, joita usein käytetään VR-lasien kanssa, paljastetaan usein GamePad API:n kautta. Tämä antaa kehittäjille mahdollisuuden rakentaa VR-kokemuksia, jotka käyttävät näitä ohjaimia vuorovaikutukseen.

VR-sovelluksia kehitettäessä Gamepad-oliolla voi olla lisäominaisuuksia, jotka liittyvät sen asentoon (sijainti ja suunta) 3D-avaruudessa. Näihin ominaisuuksiin pääsee käsiksi pose-ominaisuuden kautta, joka palauttaa GamePadPose-olion. GamePadPose-olio tarjoaa tietoa ohjaimen sijainnista, suunnasta (kvaternionina), lineaarisesta nopeudesta ja kulmanopeudesta.

GamePad API:n käyttäminen WebVR:n kanssa mahdollistaa kehittäjille mukaansatempaavien ja interaktiivisten VR-kokemusten luomisen, jotka reagoivat käyttäjän liikkeisiin ja vuorovaikutukseen VR-ohjainten kanssa.

Esimerkki: Yksinkertainen peliohjaintestaaja

Tässä on yksinkertainen esimerkki peliohjaintestaajasta, joka näyttää yhdistettyjen peliohjainten tilan:

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

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

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

          gamepadsDiv.appendChild(gamepadDiv);
        }
      }
    }

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

    window.addEventListener("gamepadconnected", function(e) {
      console.log("Peliohjain yhdistetty indeksissä %d: %s. %d painiketta, %d akselia.",
        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("Peliohjain irrotettu indeksistä %d: %s",
        e.gamepad.index, e.gamepad.id);
      delete gamepads[e.gamepad.index];
    });

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

            

              
                Copy
              
            
          

Tämä esimerkki luo yksinkertaisen verkkosivun, joka näyttää tietoja yhdistetyistä peliohjaimista, mukaan lukien niiden ID, painikkeiden tilat ja akselien arvot. Voit käyttää tätä esimerkkiä lähtökohtana omien GamePad API -sovellustesi testaamiseen ja virheenkorjaukseen.

Parhaat käytännöt

• Kysele peliohjaimen tilaa: Käytä requestAnimationFrame-metodia peliohjaimen tilan säännölliseen kyselyyn varmistaaksesi sulavan ja reagoivan syötteen.
• Käsittele yhteyden katkeamiset: Kuuntele gamepaddisconnected-tapahtumaa ja käsittele peliohjaimen yhteyden katkeamiset sulavasti virheiden välttämiseksi.
• Käytä standardikartoitusta: Käytä standardia peliohjainkartoitusta aina kun mahdollista tarjotaksesi yhtenäisen kokemuksen eri peliohjaimilla.
• Tarjoa määritysasetuksia: Anna käyttäjien määrittää painike- ja akselikartoitukset omien tarpeidensa mukaan.
• Testaa useilla selaimilla: Testaa sovellustasi useilla selaimilla varmistaaksesi yhtenäisen toiminnan.
• Ota saavutettavuus huomioon: Suunnittele pelisi saavutettavuus mielessä pitäen, jotta se soveltuu myös vammaisille pelaajille.

Yhteenveto

GamePad API tarjoaa tehokkaan ja standardoidun tavan käyttää peliohjaimia verkkoselaimista. Hallitsemalla GamePad API:n voit luoda mukaansatempaavia ja interaktiivisia verkkopohjaisia pelejä ja sovelluksia, jotka reagoivat käyttäjän syötteisiin monenlaisilta peliohjaimilta.

Tämä opas on tarjonnut kattavan yleiskatsauksen GamePad API:sta, kattaen kaiken perusasetuksista edistyneisiin tekniikoihin. Noudattamalla tässä oppaassa esitettyjä vinkkejä ja parhaita käytäntöjä voit tehokkaasti integroida peliohjaintuen verkkosovelluksiisi ja luoda mukaansatempaavia kokemuksia käyttäjillesi.

Muista testata sovelluksesi perusteellisesti eri selaimilla ja peliohjaimilla yhtenäisen toiminnan varmistamiseksi. Ota huomioon saavutettavuus vammaisille pelaajille ja tarjoa määritysasetuksia, joiden avulla käyttäjät voivat mukauttaa ohjaimia mieleisekseen. Pienellä vaivalla voit luoda pelejä, jotka ovat nautinnollisia ja saavutettavia laajalle pelaajakunnalle.

Lisäresurssit

• MDN Web Docs: Gamepad API
• W3C Gamepad -määritys
• Gamepad Test: online-peliohjaintestaaja