Steamworks-dokumentaatio
Pelinsisäisten toimintojen (IGA) -tiedosto

Yleiskatsaus


Kehittäjien tulee toimittaa pelinsisäisten toimintojen tiedosto (IGA-tiedosto), joka määrittää toiminnot, toimintosarjat ja pelin syötemäärityksen perusrakenteen. Tässä artikkelissa kerrotaan tiedoston kokonaisrakenteesta ja annetaan useita konkreettisia esimerkkejä erilaisista peleistä.

Esimerkkitiedostot


Pelinsisäisten toimintojen tiedoston (IGA-tiedosto) manuaalinen luonti

Aloita lataamalla yllä olevista esimerkkilinkeistä pelinsisäisten toimintojen aloitustiedosto (IGA). Luo seuraavaksi "controller_config"-hakemisto Steam-kansioon, yleensä: C:/Program Files (x86)/Steam/controller_config ja siirrä tiedosto hakemistoon. Steam-kansiosta löytyy valmiiksi kansio, jolla on samanlainen nimi. Ole siis tarkkana, että siirrät tiedoston controller_config -kansioon, etkä controller_base -kansioon. Nimeä tiedosto uudelleen seuraavasti: game_actions_X.vdf. Korvaa tiedoston nimessä oleva X pelisi sovellustunnuksella (AppID). Jos et tiedä pelisi Steam-sovellustunnusta, näet sen kirjautumalla sisään Steamin kumppanisivustoon.

Avaa tiedosto valitsemassasi tekstieditorissa. Tiedosto on Valven KeyValues-standardimuodossa, joka on yksinkertainen ja helppolukuinen. Voi olla myös hyödyllistä ladata yksi pelinsisäisten toimintojen tiedostojen (IGA) malleista tai Portal 2 -pelin IGA-tiedosto vertailun vuoksi.

IGA-tiedoston luonti pelistä, joka käyttää Steam-syötteen ohjelmointirajapintaa


Jos tallennat määritykset mille tahansa pelille Steamiin paikallisina määrityksinä, vastaava tiedosto löytyy täältä:
[Steam-hakemisto]\UserData\[käyttäjätunnus]\241100\remote\controller_config\[appid]\[tallennusnimi].vdf

Tässä on esimerkki siitä, minne Defender's Questin paikalliset määritykset on tallennettu tyypillisessä Windows 10 -koneessa:

whereisvgf.png

Huomaa, etteivät tiedostot ole täydellisiä kopioita kehittäjän lähettämästä IGA-päätiedostosta, mutta saat käsityksen alkuperäisestä rakenteesta tarkastelemalla "actions"- ja "localization"-lohkoja, jotka ovat peräisin suoraan päätiedostosta.

Tässä on edellisessä kuvakaappauksessa näkyvän tiedoston latauslinkki: #library_controllersavedefaulttitle_0.vdf. Sitä kannattaa verrata Defender's Questin IGA-päätiedostoon.

IGA-tiedostomuoto


IGA-tiedosto on muodoltaan VDF-dokumentti, joka on Valven oma tiedon tallennusmuoto rakenteisten objektitietojen luomiseen avain-/arvomerkkijonoparien avulla.

Runko


Tiedoston perusrakenne koostuu paketoijaobjektista, jonka nimi on "In Game Actions", ja kahdesta aliobjektista, joiden nimet ovat "actions" ja "localization":

"Pelinaikaiset toiminnot" { "toiminnot" { } "lokalisointi" { } }

Toimintosarjat

Tarkastellaan seuraavaksi lähemmin "actions"-objektia. Tämä objekti sisältää toimintosarjat. "Actions"-objektin rakenne näyttää tältä.
"actions" { "ActionSetNameGoesHere" { "title" "#TitleGoesHere" "StickPadGyro" { } "AnalogTrigger" { } "Button" { } } }

Merkkijonot "ActionSetNameGoesHere" ja "#TitleGoesHere" ovat ainoat edellä olevan esimerkin merkkijonoista, jotka käyttäjän tulisi korvata. Loput on varattu avainsanoille.

Arvo, jolla "ActionSetNameGoesHere" korvataan, on Steam-syötteen ohjelmointirajapinnassa käytetyn toimintojoukon nimi. Merkkijonon "#TitleGoesHere" korvaavasta arvosta tulee lokalisointitunniste, jota käytät myöhemmin tiedoston "localization"-osiossa. Huomaa, että tässä on käytettävä #-merkkiä.

Jokaisella toimintosarjalla on oltava yksilöllinen merkkijonon nimi, ja niitä voidaan lisätä luomalla lisää objekteja "actions"-säilöobjektin alueella. Pilkkuja tai hakasulkeita ei tarvita, sillä kyseessä on VDF-, ei JSON-tiedosto.

Kullekin toimintosarjan objektille on kolme mahdollista aliobjektia. Ne ovat "StickPadGyro", "AnalogTrigger" ja "Button". Nämä ovat ainoat objektit, jotka voit määrittää, ja ne ovat säilöjä, jonne yksittäiset toimintomääritykset sijoitetaan. Sinun ei kuitenkaan tarvitse tarjota kaikkia kolmea kategoriaa.

Esimerkiksi tämä rakenne on täysin kelvollinen:
"actions" { "ActionSetName1" { "title" "#Title1" "AnalogTrigger" { } "Button" { } } "ActionSetName2" { "title" "#Title2" "StickPadGyro" { } } "ActionSetName3" { "title" "#Title3" "Button" { } } }

StickPadGyro

Tämä toimintosarjalohko on tarkoitettu analogisille toiminnoille, joilla on kaksi liikeakselia. Ne kannattaa määrittää ohjainsauvaan, kosketuslevyyn tai gyroskooppiin. Lisäksi se sopii mille tahansa muille toiminnoille, joita haluat ohjata hiirellä tai muulla vastaavalla.

AnalogTrigger

Tämä toimintosarjalohko on tarkoitettu analogisille toiminnoille, joilla on vain yksi liikeakseli, eli sellaisille, jotka kannattaa määrittää analogiliipaisimeen.

Painike

Tämä toimintosarjalohko on tarkoitettu täysin digitaalisille toiminnoille, jotka palauttavat vain päälle/pois-tilan. Vaikka lohkon nimi on "button" (painike), digitaaliset toiminnot voidaan määrittää melkein mihin tahansa fyysiseen syötteeseen – myös sellaisiin, jotka oli alun perin suunniteltu tuottamaan analogista dataa (ohjainsauvat ja kosketuslevyt jne.).

Toiminnot


IGA-tiedosto ei tee mitään, ennen kuin siihen on määritetty toimintoja, joten lisätään niitä.

StickPadGyro-toiminnot

Aloitetaan lisäämällä StickPadGyro-toimintoja (2-akselinen, analoginen). Lisätään vaikka toiminto, jolla hahmoa voi liikuttaa – kutsutaan sitä nimellä "Move". Lisätään myös toiminto, jolla voi ohjata kameraa – kutsutaan sitä nimellä "Camera".

"actions" { "FPSControls" { "Otsikko" "#Set_FPSControls" "StickPadGyro" { "Move" { "Otsikko" "#Action_Move" "input_mode" "joystick_move" } "Camera" { "Otsikko" "#Action_Camera" "input_mode" "absolute_mouse" } } } }

Kuten näet, StickPadGyro-toiminnon abstrakti rakenne on seuraava:
"ActionNameHere" { "title" "#ActionTitleHere" "input_mode" "<analog_mode>" }

Tämän rakenteen ainoat käyttäjän muokattavissa olevat arvot on merkitty seuraavasti: "ActionNameHere", "#ActionTitleHere" ja "<analog_mode>". Ne vastaavat Steam-syötteen ohjelmointirajapinnassa käytettävää toiminnon merkkijonon nimeä, tiedoston lokalisointiosiossa käytettävää lokalisointiavainta ja syötelähdetilaa, joka määrittää, miten analogista tietoa käsitellään ja tulkitaan.

"input_mode"-ominaisuudella on kaksi mahdollista arvoa StickPadGyro-toiminnoille:

  • "joystick_move"
  • "absolute_mouse"

Käytä "joystick_move"-arvoa toiminnoissa, joiden arvot tulkitaan ohjainsauvana (vakiopoikkeama keskipisteestä), ja "absolute_mouse"-arvoa joustavassa, yleisessä analogisessa toiminnossa. Jos et tiedä, kumpaa käyttäisit, käytä "absolute_mouse"-arvoa.

"joystick_move" vs. "absolute_mouse"

Kun luot kamerasyötettä ensimmäisen tai kolmannen persoonan peliin tai mihin tahansa hiiren osoittimella pelattavaan peliin, on erittäin tärkeää käyttää "absolute_mouse"-tyyppiä ja reagoida muutoksiin niin kuin se olisi hiiri.

Ohjelmointirajapinta toimii automaattisesti oikein sauvapohjaisen syötteen tapauksessa. Voit siis edelleen käyttää säädettävää sauvapalautetta, jos kamerasi määritetään (PS4/Xbox-tyyliseen) analogiseen sauvaan täysimittaisilla kuolleilla alueilla, vastauskäyrillä jne. Voit määrittää nämä oletusmäärityksissä. Sama syöte toimii myös ohjainsauvoissa, kosketuslevyissä tai gyroskoopeissa (Steam Controller / PS4-ohjain) sekä hiiren tulevaisuuden tuessa.

Älä käytä "joystick_move"-pohjaista syötetapaa kamerallesi, koska hyödyllisen 1:1-tiedon saamiseksi ei ole mahdollista yhdistää vastakkaista suuntaa kosketuslevylle/gyrolle/hiirelle/liikkeenohjaukselle.

Tämä koskee myös kohdistinpohjaista syötettä: "absolute_mouse". Kohdistin toimii hyvin ohjaussauvapohjaisissa syötteissä, joten sinun ei tarvitse luoda omaa ohjaussauvapohjaista osoitinta.

Vaihtoehtoisesti voit lähettää matalan tason hiiritapahtumia analogisten tietojen mukana. Pelisi ei pysty erottamaan näitä hiiritapahtumia niistä, jotka käyttöjärjestelmäsi on luonut. Tämä tehdään lisäämällä arvo "os_mouse" ja määrittämällä sille arvo 1.

Tässä on esimerkki:
"StickPadGyro" { "Mouse" { "title" "#Action_Mouse" "input_mode" "absolute_mouse" "os_mouse" "1" } }


Analogiliipaisin-toiminnot
AnalogTrigger-toiminnot ovat yksiulotteisia analogitoimintoja, jotka voidaan määrittää liipaisinpainikkeille. Jos käytät liipaisinpainikkeen raja-arvoa aseen ampumiseen tai tähtäämiseen, kannattaa käyttää Button-toimintoa AnalogTrigger-toiminnon sijaan, sillä se antaa käyttäjille enemmän joustavuutta ohjaimen uudelleenmääritykseen.

AnalogTrigger-toiminnoilla on määritettävä kuollut alue, jota pystyy säätämään uudelleenmäärityksen käyttöliittymässä. Skaalaavan arvon vaihteluväli on 0–1,0f. Nintendo Switch Pro -tyyliset ohjaimet, joissa on digitaaliset liipaisinpainikkeet, lähettävät joko arvon 0 tai 1,0. Kannattaa siis tarkistaa, ettei pelisi koodi vaadi liipaisimen hidasta painallusta.

AnalogTrigger-toimintojen formaatti on yksinkertainen. Toiminnon nimi on tunnus ja lokalisointitunnus on arvo. Eli näin:
"AnalogTrigger" { "AccelerationAxis" "#Action_Accelerate" "BreakingAxis" "#Action_Brake" }

Button-toiminnot

Button-toimintojen formaatti on samanlainen. Myös niissä käytetään toiminnon nimeä ja lokalisointitunnusta:
"Button" { "digital_action_1_name_here" "#DigitalAction1TitleHere" "digital_action_2_name_here" "#DigitalAction2TitleHere" }

Tarvittaessa voit määrittää natiivin matalan tason syötteen laitteistotapahtuman (kuten natiivin hiiren klikkauksen), joka käynnistyy yhdessä toiminnon kanssa. Tästä on hyötyä joissakin rajatapauksissa, joissa pelisi edellyttää esimerkiksi seitsemän kerrosta syvää pikkutarkkaa syötepinoa, joka ei koskaan kohtele sovelluskerroksesi simuloituja hiiritapahtumia aivan samalla tavalla kuin niitä, jotka käyttöjärjestelmä on luonut suoraan.

"Button" { "simple_click" "#simple_click" "fancy_click" "#fancy_click, mouse_button LEFT" }

Tämän vuoksi pelisi lähettää todellisen käyttöjärjestelmätasoisen vasemman hiiren painikkeen tapahtuman joka kerta, kun fancy_click-toiminto käynnistyy.

Huomaa!

Älä koskaan käytä tätä keinoa helppona ratkaisuna, jolla pakotat toiminnoille tiettyjä kiinteitä syötemäärityksiä. Tällöin "toimintoja eikä syötteitä" -paradigman tavoite ei toteudu eikä käyttäjä voi täysin hallita määrityksiään. Jos käytät tätä ominaisuutta muuhunkin kuin muutamien harvinaisten rajatapausten korjaamiseen, käytät sitä todennäköisesti liikaa.

Toimintosarjan kerrokset

Aktiiviseen toimintosarjaan pystyy lisäämään pieniä muutoksia toimintosarjan kerroksella. Tämän ansiosta voit luoda erikoistiloja perustilan lisäksi. Esimerkiksi tarkkuuskivääritilan voi asettaa kävelytilan ohjauksen päälle. Kerrokset toimivat myös tilanteissa, jossa pelin käyttöliittymä tulee esille normaalin pelaamisen aikana (esimerkiksi äänestysikkunat). Kerrokset esitellään niiden omassa osiossa:
"action_layers" { "IngameModalLayer" { "title" "#Layer_IngameModal" "legacy_set" "0" "set_layer" "1" "parent_set_name" "InGame" "AnalogTrigger" { } "Button" { "Modal_Accept" "#Action_Modal_Accept" "Modal_Decline" "#Action_Modal_Decline" } } }

Lokalisointi


IGA-päätiedostossa on oltava lokalisointiosio ja toimintosarjan määritelmät. Lokalisointiobjektin yksittäisiä aliobjekteja ovat mitkä tahansa Steamin tukemat kielimerkkijonot. Varmista, että sisällytät vähintään yhden lohkon, joka sisältää englanninkieliset toimintojen nimet.

"localization" { "english" { "move" "Move" "camera" "Camera" } }

Huomaa, että ominaisuuksien nimien on vastattava aiemmissa osioissa määrittämiäsi lokalisointiavaimia, mutta ilman #-merkkiä.

Voit lisätä kieliä lisäämällä kielilohkoja, joiden jokaisessa merkinnässä on lokalisoitu teksti:

"localization" { "english" { "move" "Move" "camera" "Camera" } "spanish" { "move" "Mover" "camera" "Cámara" } "norwegian" { "move" "Bevege" "camera" "Kamera" } }
Kunkin kielen tunnuksen tulee vastata ohjelmointirajapinnan kielikoodia. Esimerkiksi yksinkertaistetun kiinan kielikoodi on schinese. Koko tuettujen kielten luettelo löytyy tästä.

Miten Steam käyttää IGA-tiedostoasi


Luomasi IGA-päätiedosto on olemassa vain kehitysvaiheen ajan. Se on silti tallennettava ja sitä on ylläpidettävä ja säilytettävä versionhallinnassa. Kun luot viralliset syötemääritykset pelillesi kehitysvaiheen aikana, Steam-asiakasohjelma käyttää IGA-päätiedostoasi aloitusmallin luomiseen.