Steamworks-dokumentaatio
Peli-ilmoitukset

Yleiskatsaus

Steamin peli-ilmoitukset on järjestelmä, jonka avulla toimitetaan käyttäjille offline-ilmoituksia peleistä, joissa pelataan asynkronista moninpeliä, kuten shakissa.

Tämän APIn tarkoituksena on ilmoittaa käyttäjille, että pelin edistyminen edellyttää toimenpiteitä. Shakki-esimerkissä peli-istunnon tila päivitetään kunkin pelaajan siirron jälkeen. Tämän jälkeen Steam lähettää ilmoituksia käyttäjille peli-istunnon tilan perusteella, jotta he tietävät olevan heidän pelivuoronsa.

Pelin tehtävät

Tyypillinen offline-peli hallitsee peli-istuntoa ja päivittää kunkin käyttäjän statukseksi tilan, joka lähettää puolestaan käyttäjälle ilmoituksen, että tämän on käynnistettävä peli ja toimittava. Käynnistyksen ja pelitoimintojen yhteydessä pelin pitäisi päivittää istunto uudelleen istunnon kaikkien pelaajien päivitetyillä tiloilla.

Steamin tehtävät

Steam hallinnoi ilmoitusten lähettämistä pelaajille pelin ilmoittamien tilojen ja käyttäjän pelille valitsemien erityisasetusten perusteella. Ilmoitus näytetään Steam-sovelluksessa ja selaimessa käyttäjälle, kun pelissä edellytetään toimenpidettä.

Vaatimukset

Peli-ilmoitusten API tarjotaan Web API -metodien avulla, ja se edellyttää kelvollista julkaisijan avainta. Web API -metodin kutsujen on oltava peräisin isännöidystä palvelimesta, joka on erillään pelisovelluksesta – julkaisijan avainta ei saa julkaista pelisovelluksen koodissa.

Todennus ja kolmannen osapuolen tilit

Peli-ilmoitusten APIen kutsuminen edellyttää, että selvität ensin peliisi kirjautuneen Steam-käyttäjän henkilöllisyyden. Sen voi tehdä kahdella tapaa. Sovelluspeli voi luoda todennusistuntolipun ja siirtää sen takaisin palvelimelle tai verkkopohjainen peli voi tarkistaa käyttäjän henkilöllisyyden OpenID-tunnistuksella. Ohjeet löytyvät täältä: Kolmannen osapuolen tilien linkittäminen Steam-tileihin. Älä luota käyttäjän henkilöllisyyteen viesteissä, jotka on lähetetty suoraan pelisovelluksesta pelipalvelimellesi, sillä näitä viestejä voidaan peukaloida.
Noudata kolmannen osapuolen tilejä käyttävien pelien kohdalla edellä annettuja ohjeita, mutta tallenna käyttäjän Steam ID järjestelmäsi välimuistiin.

Peli-ilmoitusten API

Tekniset tiedot

Peli-ilmoitusten API on kirjoitettu ja tarjotaan Web APIen kautta, ja se edellyttää neljän parametrin määrittämistä kullekin metodille:
  • appid (pelisi sovellustunnus)
  • format (Tuloksen muoto. Suosittelemme json-muotoa)
  • input_json (kaikkien metodin edellyttämien parametrien json-koodaus)
  • key (julkaisijan avain, joka määritetään jokaisessa kutsussa)
API palauttaa onnistumisesta HTTP-tilakoodin 200, ja viestin teksti sisältää (tarvittaessa) tarkemmat tiedot.

Vakioarvot

Käyttäjän tila

Merkkijonon arvo, joka määritellään yhdeksi seuraavista:
  • waiting – Käyttäjä odottaa muita pelaajia eikä estä mitään toimintoja. Käyttäjälle ei lähetetä ilmoitusta, koska hän odottaa, että jotakin tapahtuu.
  • ready – Käyttäjä on valmis – peli-istunto odottaa vastausta käyttäjältä. Käyttäjälle lähetetään ilmoitus, kunnes tämä tila on poistettu.
  • done – Peli on suoritettu loppuun kyseisen pelaajan osalta. Käyttäjälle ilmoitetaan, että peli on päättynyt, mutta mitään toimia ei tarvita.

Tietorakenteet (JSON)

Kaikki tietorakenteet esitetään JSON-muodossa.

Variable

{ "key": "key_name", // merkkijono "value": "value_of_key" // merkkijono }

LocalizedText

{ "token": "value", // merkkijono, joka kuvaa lokalisointitunnistetta "variables": [ " // muuttujavalikoima (above) ] }

UserStatus

{ "steamid": "76561197960265729", // uint64 "state": // yksi (ylläkuvatuista) käyttäjän tilan vakioista, "title": // lokalisoitu tekstiobjekti (kuvattu yllä), "message": // lokalisoitu tekstiobjekti (kuvattu yllä) }

Session

{ "sessionid": "1", // uint64 "title": // lokalisoitu tekstiobjekti (yllä), "time_created": "100000", // Unix-aika (1.1.1970 alkaen). "time_updated": "200000", // Unix-aika (1.1.1970 alkaen). // 64-bittinen arvo, jonka kehittäjä ilmoittaa istunnon aluksi, ja joka siirretään peliin, kun se käynnistetään. // Näin yhdistät helposti istunto-objektin omaan taustaobjektiin. Steam ei käytä sitä sisäisesti. Steam. "context": "31415926", "user_status": [ // käyttäjätilavalikoima (kuvattu yllä) ] }

RequestedSession

{ "sessionid": "1", // uint64 "include_all_user_messages": "0" // bool }

Yleisiä ohjelmointirajapintoja on saatavilla.

Koko luettelo on kohdassa IGameNotificationsService.

Tiettyjen peli-istuntojen käynnistäminen

Käyttäjät voivat tarkastella kaikkia aktiivisia peli-istuntojaan yhteisöprofiilisivullaan Steamissä. Pelin tilan lisäksi sivulla näkyy painike, jolla voidaan pyytää Steamia käynnistämään peli erityisillä käynnistysparametreilla peli-istunnon määrittelemiseksi. Kun peli käynnistetään tällä tavalla, pelille annetaan parametri "_sessionid". Saat tämän parametrin käyttämällä kutsua ISteamApps::GetLaunchQueryParam
seuraavasti:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Pelin, joka tukee käynnistämistä suoraan peliin tällä tavalla, pitäisi kutsua tätä rajapintaa peliä käynnistettäessä ja määritellä, esiintyykö istuntotunnusmerkkijonoa ja onko se voimassa sisäänkirjautuneelle käyttäjälle, ja ladata peli suoraan.

Lokalisointi

Pelikehittäjä tarjoaa lokalisoinnin sovelluksen määrityksiin kuuluvan lokalisointityökalun avulla. Olet vastuussa kunkin kielen käännöksen määrittämisestä kaikkiin lokalisointityökaluun syötetyille merkkijonoille. Merkkijonot, joita ei ole käännetty pelaajan kielelle, renderöidään englanniksi.
Peli-ilmoitukset tukevat lokalisointia seuraavien ominaisuuksien osalta:

Kukin lokalisoitu teksti koostuu kahdesta komponentista:

Tunniste on avain, joka alkaa #-symbolilla ja kuvaa merkkijonoa, joka on lokalisoitu eri kielille sovelluksen määrityksiin kuuluvan lokalisointityökalun avulla. Yksittäinen tunniste voi sisältää useita muuttujan esiintymiä, jotka voidaan korvata suoritusaikana pelin kontekstin perusteella, kun tekstiä luodaan. Esimerkki:
#InvitationText = "{{user}} has invited you to play a game of Chess."

Edellä olevassa esimerkissä englanninkielinen käännös tunnisteelle #InvitationText sisältää yhden muuttujan nimeltä käyttäjä. Jos haluat renderöidä tämän tekstimuotoisen viestin käyttäjälle, kun "SteamUserName" kutsuu hänet peliin, päivitä LocalizationText-objekti seuraavilla ominaisuuksilla:
"message": { "token": "#InvitationText", "variables": [ { "key": "user", "value": "Michael" } ] }

Kun pelaaja katsoo omaa tilaansa, hän näkee seuraavan viestin (omalla kielellänsä): "Michael on kutsunut sinut pelaamaan Chess-peliä."
Lokalisointimerkit voi ladata sovelluksellesi Steamworks-asetussivulta, Yhteisö-välilehden asynkronisen lokalisoinnin kohdasta.
Kunkin kielen voi ladata erikseen VDF-tiedostoina, jotka näyttävät seuraavilta:
"lang" { "Language" "english" "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } }

Vaihtoehtoisesti kaikkien kielten tunnisteet voidaan lähettää yhdessä tiedostossa, joka näyttää tältä:
"lang" { "english" { "Tokens" { "TheNameOfTheToken" "The localized text associated with the token" "TheNameOfAnotherToken" "The localized text associated with the second token" } } "spanish" { "Tokens" { "TheNameOfTheToken" "El texto localizado asociado con el token" "TheNameOfAnotherToken" "El texto localizado asociado con el segundo token" } } }