GamePad API: Põhjalik juhend mängupuldi sisendi käsitlemiseks

GamePad API pakub standardiseeritud viisi mängupultidele otse veebibrauseritest juurdepääsemiseks. See avab põnevaid võimalusi kaasahaaravate ja interaktiivsete veebipõhiste mängude ja rakenduste loomiseks. See põhjalik juhend juhatab teid läbi kõige, mida peate teadma GamePad API tõhusaks kasutamiseks, alates põhisätetest kuni täiustatud tehnikateni.

Mis on GamePad API?

GamePad API on JavaScripti API, mis võimaldab veebirakendustel tuvastada ja reageerida mängupultide (mängupuldid, juhtkangid jne) sisendile. See võimaldab arendajatel luua mänge ja interaktiivseid kogemusi, mida saab juhtida standardsete mängupuldi sisenditega, nagu nupud, teljed (analoogkangid) ja päästikud.

Enne GamePad API-d oli mängupuldi sisendi käsitlemine veebibrauserites killustatud ja ebausaldusväärne kogemus, mis nõudis sageli brauserispetsiifilisi pistikprogramme või keerukaid lahendusi. GamePad API pakub ühtset ja brauseriülest lahendust, lihtsustades mängupuldi toe integreerimist veebirakendustesse.

Brauseri ühilduvus

GamePad API on laialdaselt toetatud kaasaegsetes brauserites, sealhulgas:

• Chrome (arvutis ja mobiilis)
• Firefox (arvutis ja mobiilis)
• Safari (arvutis ja mobiilis, mõningate piirangutega)
• Edge
• Opera

Kuigi brauserite tugi on üldiselt hea, võib eri brauserites esineda peeneid erinevusi rakenduses ja funktsioonide saadavuses. Alati on hea tava testida oma rakendust mitmes brauseris, et tagada ühtlane käitumine.

GamePad API-ga alustamine

Siin on samm-sammuline juhend GamePad API-ga alustamiseks:

1. Mängupuldi ühenduse tuvastamine

Meetod navigator.getGamepads() tagastab Gamepad objektide massiivi, mis esindavad hetkel ühendatud mängupulte. Brauser käivitab sündmused gamepadconnected ja gamepaddisconnected vastavalt siis, kui mängupuldid ühendatakse või lahti ühendatakse. Saate neid sündmusi kuulata, et oma rakenduse olekut värskendada.

            window.addEventListener("gamepadconnected", function(e) {
  console.log("Mängupult ühendatud indeksil %d: %s. %d nuppu, %d telge.",
    e.gamepad.index, e.gamepad.id, e.gamepad.buttons.length, e.gamepad.axes.length);
  gamepadHandler(e, true);
});

window.addEventListener("gamepaddisconnected", function(e) {
  console.log("Mängupult lahti ühendatud indeksilt %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
              
            
          

See koodilõik seab sündmuste kuulajad sündmustele gamepadconnected ja gamepaddisconnected. Funktsioon gamepadHandler värskendab objekti gamepads, et pidada arvet ühendatud mängupultide üle.

2. Mängupuldi oleku küsimine

GamePad API on peamiselt sündmustepõhine, kuid pideva sisendi (nagu analoogkangi liikumine) jaoks peate mängupuldi olekut küsima requestAnimationFrame tsüklis. See hõlmab navigator.getGamepads() korduvat kutsumist ja Gamepad objektide omaduste buttons ja axes uurimist.

            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) {
      // Töötle mängupuldi sisendit siin
      for (var j = 0; j < gp.buttons.length; j++) {
        if (gp.buttons[j].pressed) {
          console.log("Nupp " + j + " vajutatud");
        }
      }
      for (var j = 0; j < gp.axes.length; j++) {
        console.log("Telg " + j + ": " + gp.axes[j]);
      }
    }
  }
  requestAnimationFrame(update);
}

requestAnimationFrame(update);

            

              
                Copy
              
            
          

See koodilõik uuendab pidevalt mängupuldi olekut, kasutades requestAnimationFrame. See itereerib läbi ühendatud mängupultide ja kontrollib nende nuppude ja telgede olekut.

3. Mängupuldi omaduste mõistmine

Igal Gamepad objektil on järgmised põhiomadused:

• id: String, mis tuvastab mängupuldi (nt "Xbox Controller (XInput STANDARD GAMEPAD)").
• index: Mängupuldi indeks navigator.getGamepads() massiivis.
• connected: Kahendmuutuja, mis näitab, kas mängupult on hetkel ühendatud.
• buttons: GamepadButton objektide massiiv, mis esindab mängupuldi nuppe.
• axes: Numbrite massiiv, mis esindab mängupuldi telgi (analoogkangid ja päästikud).
• mapping: String, mis näitab mängupuldi nupukaardistust (kas "standard" või "").

4. Mängupuldi nuppudega töötamine

Igal GamepadButton objektil on järgmised omadused:

• pressed: Kahendmuutuja, mis näitab, kas nupp on hetkel vajutatud.
• value: Number vahemikus 0 kuni 1, mis esindab nupule rakendatavat survet (survetundlike nuppude, näiteks päästikute puhul).

Nupu olekule pääseb juurde selle indeksi kaudu buttons massiivis. Näiteks gamepad.buttons[0].pressed tagastaks true, kui esimene nupp on vajutatud.

5. Mängupuldi telgedega töötamine

Massiiv axes sisaldab numbreid, mis esindavad mängupuldi analoogkangide ja päästikute väärtusi. Väärtused on tavaliselt vahemikus -1 kuni 1, kus -1 esindab vasakpoolseimat/ülemist asendit ja 1 parempoolseimat/alumist asendit.

Telje väärtusele pääseb juurde selle indeksi kaudu axes massiivis. Näiteks gamepad.axes[0] tagastaks vasaku analoogkangi horisontaalse asendi.

Standardne mängupuldi kaardistus

GamePad API määratleb "standardse" mängupuldi kaardistuse, mis pakub ühtset viisi levinud mängupuldi nuppudele ja telgedele juurdepääsemiseks, sõltumata konkreetsest mängupuldi mudelist. See kaardistus on tuvastatav omaduse mapping väärtusega "standard".

Standardne mängupuldi kaardistus sisaldab järgmisi nuppe:

• Nupp 0: A (tavaliselt parempoolne alumine nupp)
• Nupp 1: B (tavaliselt parempoolne nupp)
• Nupp 2: X (tavaliselt vasakpoolne nupp)
• Nupp 3: Y (tavaliselt ülemine nupp)
• Nupp 4: Vasak õlanupp (LB)
• Nupp 5: Parem õlanupp (RB)
• Nupp 6: Vasak päästik (LT)
• Nupp 7: Parem päästik (RT)
• Nupp 8: Select (või Back)
• Nupp 9: Start
• Nupp 10: Vasaku kangi nupp (LS)
• Nupp 11: Parema kangi nupp (RS)
• Nupp 12: D-pad Üles
• Nupp 13: D-pad Alla
• Nupp 14: D-pad Vasakule
• Nupp 15: D-pad Paremale
• Nupp 16: Guide (või Home)

Standardne mängupuldi kaardistus sisaldab järgmisi telgi:

• Telg 0: Vasak kang, horisontaaltelg (-1 = vasakule, 1 = paremale)
• Telg 1: Vasak kang, vertikaaltelg (-1 = üles, 1 = alla)
• Telg 2: Parem kang, horisontaaltelg (-1 = vasakule, 1 = paremale)
• Telg 3: Parem kang, vertikaaltelg (-1 = üles, 1 = alla)

On oluline märkida, et mitte kõik mängupuldid ei toeta standardset kaardistust. Mängupultidel, mis ei toeta standardset kaardistust, on omaduse mapping väärtuseks tühi string ja teil tuleb mängupuldi tuvastamiseks ja selle nuppude ning telgede kaardistamiseks kasutada omadust id.

Mittestandardsete mängupultide käsitlemine

Mittestandardsete mängupultidega tegeledes peate mängupuldi tuvastama selle id omaduse põhjal ja looma selle nuppudele ja telgedele kohandatud kaardistuse. See võib olla keeruline ülesanne, kuna saadaval on palju erinevaid mängupuldi mudeleid, millest igaühel on oma unikaalne nupu- ja teljepaigutus.

Siin on mõned strateegiad mittestandardsete mängupultide käsitlemiseks:

• Mängupultide andmebaas: Looge andmebaas mängupultide id stringidest ja nende vastavatest nupu- ja teljekaardistustest. See võimaldab teil automaatselt kaardistada tuntud mängupultide nuppe ja telgi.
• Kasutaja seadistamine: Lubage kasutajatel seadistada oma mängupultide nupu- ja teljekaardistusi. See pakub paindlikkust kasutajatele, kellel on haruldased mängupuldid.
• Heuristiline kaardistamine: Kasutage heuristikat, et arvata nupu- ja teljekaardistusi nuppude ja telgede arvu ning nende tüüpiliste kasutusmustrite põhjal.

Laia valiku mängupultide toe implementeerimine võib olla märkimisväärne ettevõtmine. Kaaluge esmalt kõige populaarsemate mängupuldi mudelite toetamisele keskendumist ja lisage vajadusel järk-järgult tuge rohkemate mängupultide jaoks.

Täiustatud tehnikad

1. Tundetsoonid (Dead Zones)

Analoogkangidel on sageli keskasendi ümber "tundetsoon", kus teatatud väärtus ei ole null, isegi kui kangi ei puudutata. See võib põhjustada teie mängus soovimatut liikumist või värinat. Selle lahendamiseks saate rakendada tundetsooni, seades telje väärtuseks nulli, kui see jääb teatud vahemikku nulli ümber.

            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
              
            
          

See koodilõik rakendab telje väärtusele tundetsooni. Kui telje absoluutväärtus on väiksem kui deadZoneThreshold, on kohandatud väärtus null. Vastasel juhul skaleeritakse kohandatud väärtus vahemikku 0-1, säilitades algse väärtuse märgi.

2. Eksponentsiaalne silumine

Analoogkangi sisend võib mõnikord olla mürarikas, põhjustades hüplikku või ettearvamatut liikumist. Sisendi silumiseks saate rakendada eksponentsiaalset silumist. See hõlmab praeguse sisendväärtuse keskmistamist eelmise silutud väärtusega, andes suurema kaalu eelmisele väärtusele.

            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
              
            
          

See koodilõik rakendab telje väärtusele eksponentsiaalset silumist. smoothingFactor määrab praegusele väärtusele antava kaalu. Väiksem silumisfaktor annab sujuvama, kuid viivitusega sisendi.

3. Nupu põrke eemaldamine (Debouncing)

Nupud võivad mõnikord mehaanilise põrke tõttu vajutamisel või vabastamisel käivitada mitu sündmust. See võib põhjustada teie mängus soovimatut käitumist. Selle lahendamiseks saate rakendada nupu põrke eemaldamist. See hõlmab nupusündmuste ignoreerimist, mis toimuvad lühikese aja jooksul pärast eelmist sündmust.

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

function handleButtonPress(buttonIndex) {
  if (!buttonStates[buttonIndex] || Date.now() - buttonStates[buttonIndex].lastPress > debounceDelay) {
    console.log("Nupp " + buttonIndex + " vajutatud (põrke eemaldamisega)");
    buttonStates[buttonIndex] = { lastPress: Date.now() };
    // Teosta toiming siin
  }
}

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

            

              
                Copy
              
            
          

See koodilõik rakendab nupu põrke eemaldamist. See peab arvet selle üle, millal iga nuppu viimati vajutati. Kui nuppu vajutatakse uuesti debounceDelay aja jooksul, ignoreeritakse sündmust.

Ligipääsetavuse kaalutlused

Mängupuldi toega mänge arendades on oluline arvestada puuetega mängijate ligipääsetavusega. Siin on mõned näpunäited oma mängu ligipääsetavamaks muutmiseks:

• Seadistatavad juhtnupud: Lubage mängijatel kohandada nupu- ja teljekaardistusi vastavalt oma individuaalsetele vajadustele.
• Alternatiivsed sisestusmeetodid: Pakkuge alternatiivseid sisestusmeetodeid, nagu klaviatuur ja hiir, mängijatele, kes ei saa mängupulti kasutada.
• Selge visuaalne tagasiside: Pakkuge selget visuaalset tagasisidet kõigi toimingute kohta, et mängijad saaksid hõlpsasti aru, mis mängus toimub.
• Reguleeritav raskusaste: Pakkuge reguleeritavaid raskusastmeid, et sobida erineva oskustasemega mängijatele.

Neid juhiseid järgides saate luua mänge, mis on nauditavad ja kättesaadavad laiemale mängijaskonnale.

GamePad API ja virtuaalreaalsus

GamePad API on asjakohane ka WebVR-i (virtuaalreaalsus veebis) kontekstis. VR-kontrollerid, mida sageli kasutatakse koos VR-peakomplektidega, on sageli kättesaadavad GamePad API kaudu. See võimaldab arendajatel luua VR-kogemusi, mis kasutavad neid kontrollereid interaktsiooniks.

VR-rakenduste arendamisel võib Gamepad objektil olla täiendavaid omadusi, mis on seotud selle asendi (positsiooni ja orientatsiooniga) 3D-ruumis. Nendele omadustele pääseb juurde omaduse pose kaudu, mis tagastab GamePadPose objekti. GamePadPose objekt annab teavet kontrolleri asukoha, orientatsiooni (kvaternioonina), lineaarkiiruse ja nurkkiiruse kohta.

GamePad API kasutamine koos WebVR-iga võimaldab arendajatel luua kaasahaaravaid ja interaktiivseid VR-kogemusi, mis reageerivad kasutaja liikumistele ja interaktsioonidele VR-kontrolleritega.

Näide: Lihtne mängupuldi testija

Siin on lihtne näide mängupuldi testijast, mis kuvab ühendatud mängupultide oleku:

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

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

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

          gamepadsDiv.appendChild(gamepadDiv);
        }
      }
    }

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

    window.addEventListener("gamepadconnected", function(e) {
      console.log("Mängupult ühendatud indeksil %d: %s. %d nuppu, %d telge.",
        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("Mängupult lahti ühendatud indeksilt %d: %s",
        e.gamepad.index, e.gamepad.id);
      delete gamepads[e.gamepad.index];
    });

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

            

              
                Copy
              
            
          

See näide loob lihtsa veebilehe, mis kuvab teavet ühendatud mängupultide kohta, sealhulgas nende ID, nupuolekud ja teljeväärtused. Saate seda näidet kasutada oma GamePad API rakenduste testimise ja silumise lähtepunktina.

Parimad praktikad

• Küsige mängupuldi olekut: Kasutage requestAnimationFrame, et regulaarselt küsida mängupuldi olekut, tagades sujuva ja reageeriva sisendi.
• Käsitlege lahtiühendamisi: Kuulake sündmust gamepaddisconnected ja käsitlege mängupuldi lahtiühendamisi sujuvalt, et vältida vigu.
• Kasutage standardset kaardistust: Kasutage võimaluse korral standardset mängupuldi kaardistust, et pakkuda ühtlast kogemust erinevate mängupultidega.
• Pakkuge seadistamisvõimalusi: Lubage kasutajatel seadistada nupu- ja teljekaardistusi vastavalt oma individuaalsetele vajadustele.
• Testige mitmes brauseris: Testige oma rakendust mitmes brauseris, et tagada ühtlane käitumine.
• Arvestage ligipääsetavusega: Kujundage oma mäng ligipääsetavust silmas pidades, et sobida puuetega mängijatele.

Kokkuvõte

GamePad API pakub võimsat ja standardiseeritud viisi mängupultidele veebibrauseritest juurdepääsemiseks. GamePad API valdamisega saate luua kaasahaaravaid ja interaktiivseid veebipõhiseid mänge ja rakendusi, mis reageerivad kasutaja sisendile erinevatelt mängupultidelt.

See juhend on andnud põhjaliku ülevaate GamePad API-st, hõlmates kõike alates põhisätetest kuni täiustatud tehnikateni. Järgides selles juhendis toodud näpunäiteid ja parimaid praktikaid, saate tõhusalt integreerida mängupuldi toe oma veebirakendustesse ja luua oma kasutajatele kaasahaaravaid kogemusi.

Ärge unustage oma rakendust põhjalikult testida erinevates brauserites ja mängupultides, et tagada ühtlane käitumine. Arvestage puuetega mängijate ligipääsetavusega ja pakkuge seadistamisvõimalusi, et kasutajad saaksid juhtnuppe oma maitse järgi kohandada. Väikese vaevaga saate luua mänge, mis on nauditavad ja kättesaadavad laiale mängijaskonnale.

Lisamaterjalid

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