Näytä, mitä joku pelaa

Yleiskatsaus

mssgs:n työpöytäsovellus ajaa pientä paikallista HTTP-siltaa, jonka kanssa samalla koneella oleva peli keskustelee. Pelisi ei koskaan keskustele palvelimiemme kanssa, ei koskaan näe tilin salasanaa tai tokenia eikä voi koskaan kirjoittaa pelaajan nimissä. Se keskustelee sen mssgs-sovelluksen kanssa, johon pelaaja on jo kirjautunut, ja sovellus päättää, mitä vastata.

Mitä voit tehdä sillä:

• Havaita, että mssgs on asennettu ja joku on kirjautunut.
• Lukea, kuka pelaaja on: user_guid, käyttäjänimi, avatar.
• Kysyä "onko tämä pelaaja yhteisössä X?" ja mikä rooli hänellä siellä on.
• Julkaista "Pelaa peliä …" -tilan, jossa on muille Liity nyt -painike.
• Vastaanottaa liittymisen luovutuksen, kun joku painaa sitä painiketta.

Sovelluksen löytäminen

Silta kuuntelee vain osoitetta 127.0.0.1, pienen alueen ensimmäisessä vapaassa portissa. Kokeile niitä järjestyksessä, kunnes jokin vastaa: 7440, 7441, 7442, 7443. mssgs:n kehitysversiot kuuntelevat sen sijaan portteja 7540–7543, joten testiversio ei koskaan vastaa oikean pelin kutsuihin.

{
  "product": "mssgs",
  "api": 1,
  "client": "desktop",
  "version": "14.2.20015",
  "platform": "darwin",
  "signed_in": true,
  "scopes": ["identity", "staff", "membership.query", "servers.list", "presence.write"]
}

Tarkista product === "mssgs" ja api ennen kuin jatkat. Jos mikään neljästä portista ei vastaa, mssgs ei ole käynnissä. Tarjoa silloin tavallinen kokemuksesi sen sijaan, että pelaaja joutuisi odottamaan.

Luvan pyytäminen

Kaikki paitsi /hello vaatii tokenin, ja token syntyy vasta, kun pelaaja on hyväksynyt pelisi sovelluksen sisäisessä ikkunassa. Pyydä vain scopet, joita oikeasti käytät: pelaaja näkee jokaisen erikseen selitettynä ja voi poistaa niistä valinnan yksitellen.

curl -X POST http://127.0.0.1:7440/mssgs/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "com.acme.spacegame",
    "name": "Space Raiders",
    "scopes": ["identity", "membership.query", "presence.write"]
  }'

Saat takaisin {"status":"pending","request_id":"…","poll_after_ms":1000}, ja pelaaja näkee ikkunan. Kysele sitten, kunnes hän vastaa (pyyntö vanhenee 3 minuutin kuluttua):

curl http://127.0.0.1:7440/mssgs/v1/authorize/<request_id>

# {"status":"approved","token":"…","scopes":["identity","presence.write"],"game_id":"com.acme.spacegame"}

Tallenna token ja lähetä se muodossa Authorization: Bearer <token>. Se säilyy uudelleenkäynnistysten yli, joten pelaaja hyväksyy pelisi kerran eikä joka istunnossa. Jos valtuutat myöhemmin uudelleen jo myönnetyillä scopeilla, saat saman tokenin suoraan takaisin ilman ikkunaa.

Scopet ja yksityisyys

Viisi scopea luovuttavat hyvin eri määriä tietoa. Se ei ole sattumaa; se on koko suunnittelun ydin. Pyydä niin vähän kuin voit, tätä taulukkoa alaspäin edeten.

Jäsenyyden tarkistaminen

Tämä on vaihtoehto pyynnölle "anna minulle koko luettelo". Nimeät oman yhteisösi server_guidin (jonka tiedät jo) ja saat vastauksen vain siitä.

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7440/mssgs/v1/membership?server_guid=ca94ecc…f4g02"

# jäsen:
# {"server_guid":"ca94ecc…","member":true,"name":"Acme Fans","is_owner":false,
#  "roles":[{"guid":"0aa32…","name":"Pro"}]}

# ei jäsen, eikä mitään muuta:
# {"server_guid":"…","member":false}

"Ei" on täsmälleen sitä eikä mitään enempää. Voit antaa kutsua kohden enintään 10 guidia (toista server_guid tai erota pilkuilla), jolloin saat results-taulukon. @everyone-ryhmä ei ole koskaan roles-kentässä: se pätee jokaiseen jäseneen, joten se ei kerro mitään.

Pelaamistilan julkaiseminen

Yksi PUT tuo "Pelaa peliä …" -rivin pelaajan nimen alle kaikkialla, missä hänen yhteisönsä näkevät hänet.

{
  "name":    "Space Raiders",
  "details": "Sector 7",
  "state":   "In a raid",
  "role":    "Gunner",
  "started_at": 1755859200000,
  "party":   { "size": 3, "max": 4, "kind": "party" },
  "join":    { "secret": "raid-42" }
}

Vain name on pakollinen. Vastaus kertoo, kuinka kauan tila on voimassa ja kuinka usein heartbeat lähetetään:

{ "ok": true, "expires_in_ms": 90000, "heartbeat_every_ms": 30000 }

Pelaajamäärä ja rooli

party.kind ratkaisee, mikä lause näytetään, koska samat kaksi lukua eivät tarkoita samaa. Neljän hengen ryhmä ei ole palvelin, jolla on neljä pelaajaa.

role (enintään 48 merkkiä) on se, minä pelaaja pelaa: ammatti, luokka tai hahmo. Sillä on oma kenttänsä eikä se ole uusi lause state-kentässä, koska se näytetään tunnisteena pelaajamäärän vieressä.

details ja state on rajattu 128 merkkiin kumpikin, name 64 merkkiin. Rivinvaihdot ja ohjausmerkit poistetaan. Kuvakkeen URL:ää ei tueta tarkoituksella: jokainen riviä näyttävä sovellus hakisi sen, jolloin tilasta tulisi majakka, joka raportoi palvelimellesi jokaisen jäsenen jokaisesta yhteisöstä, jossa pelaaja on.

Liity nyt -painike

Lisää join-lohko aktiviteettiisi, niin muut jäsenet saavat tilan viereen Liity nyt -painikkeen. Tapoja on kaksi, ja voit yhdistää ne.

1. Salaisuus (natiivipeleille)

Aseta {"join":{"secret":"raid-42"}}. Kun joku painaa Liity nyt, salaisuus toimitetaan hänen omaan pelisi kopioonsa hänen omalla koneellaan, saman game_id:n perusteella. Mitään URL:ää ei avata eikä mitään skeemankäsittelijää kutsuta. Pelisi noutaa sen näin:

{
  "events": [
    { "seq": 1, "type": "join", "secret": "raid-42",
      "from": { "user_guid": "62e377…", "username": "mssgs-test-1" } }
  ],
  "cursor": 1
}

Kysele parametrilla ?since=<cursor>, niin näet jokaisen tapahtuman kerran. Jos painajan peli ei ole käynnissä, mitään ei toimiteta, mikä on hyvä syy tarjota myös URL.

2. https-URL (verkkopeleille ja aulalinkeille)

Aseta {"join":{"url":"https://play.example.com/s/abc"}}, niin painike avaa sen linkin. Vain https hyväksytään. Mukautettu skeema (steam://, mygame://, file://) evätään: lohko päätyy jokaisen jäsenen näytölle, ja sellainen URL on tapa saada jonkun toisen kone kutsumaan paikallista käsittelijää valitsemillasi argumenteilla.

FiveM

FiveM:n asiakaspuolen Lua-ajoympäristössä ei ole HTTP:tä, joten resurssi keskustelee sillan kanssa NUI:n kautta. NUI on CEF-näkymä, joka lähettää Origin-otsakkeen. Silta hyväksyy nämä originit nimenomaisesti: https://cfx-nui-<resource> ja vanhemman nui://<resource>. Tavalliset verkkosivut evätään edelleen, eikä avoimen verkon sivu voi väittää olevansa tuo origin; selain asettaa sen itse.

-- NUI-sivu hoitaa HTTP:n; Lua vain lähettää sille tiedot.
CreateThread(function()
  while true do
    SendNUIMessage({
      action  = 'mssgs:publish',
      players = GetActivePlayers and #GetActivePlayers() or 0,
      maxPlayers = GetConvarInt('sv_maxclients', 100),
      job     = exports['qb-core'] and 'Police' or nil
    })
    Wait(30000) -- heartbeat: tila vanhenee 90 s:n kuluttua
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // kokeile 7440-7443
let token = null;

async function authorize () {
  const res = await fetch(`${BASE}/authorize`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      game_id: 'fivem.lossantos.rp',
      name: 'Los Santos Roleplay',
      scopes: ['presence.write']          // muuta ei tässä tarvita
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Pelaaja näkee nyt lupaikkunan mssgs:ssä.
  for (let i = 0; i < 180; i += 1) {
    await new Promise((r) => { setTimeout(r, 1000); });
    const poll = await (await fetch(`${BASE}/authorize/${started.request_id}`)).json();
    if (poll.status === 'approved') { return poll.token; }
    if (poll.status !== 'pending') { return null; }
  }
  return null;
}

window.addEventListener('message', async (event) => {
  if (event.data.action !== 'mssgs:publish') { return; }
  if (!token) { token = await authorize(); }
  if (!token) { return; }

  await fetch(`${BASE}/activity`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
    body: JSON.stringify({
      name: 'FiveM',
      details: 'Los Santos Roleplay',
      role: event.data.job,                       // "Police"
      party: { size: event.data.players, max: event.data.maxPlayers, kind: 'server' },
      join: { url: 'https://cfx.re/join/abc123' } // cfx.re-linkkisi
    })
  });
});

Tulos: Pelaa peliä FiveM · Los Santos Roleplay · 4/100 pelaajaa · Police, ja Liity nyt -painike, joka avaa cfx.re-linkkisi.

Selain- ja puhelinpelit: liittäminen taustajärjestelmäsi kautta

Selainvälilehdellä tai puhelimessa oleva peli ei tavoita yllä kuvattua siltaa. Silta toimii pelaajan työpöytäkoneella, ja välissä on kolme muuria: silta hylkää jokaisen pyynnön, jossa on selaimen Origin, Chrome näyttää lupakehotteen ennen kuin julkinen sivu saa hakea osoitteesta 127.0.0.1 ja Safari kieltäytyy suoraan, eikä puhelimella ole mitään reittiä työpöytäkoneen loopbackiin.

Suunta siis kääntyy. Oma taustajärjestelmäsi tietää jo, kuka pelaa, ja se kertoo sen mssgs:lle niiden pelaajien osalta, jotka liittivät mssgs-tilinsä peliisi. Liitos hyväksytään mssgs-sovelluksessa, ei koskaan pelissäsi, ja se luo liitoksen, ei koskaan istuntoa: mikään alla oleva ei voi kirjata ketään sisään eikä toimia pelaajan nimissä. Pelisi asiakassovellus ei koskaan näe avainta eikä koskaan keskustele mss.gs:n kanssa. Ensimmäinen tätä reittiä käyttävä peli on CozyCity, kaupunkirakentelupeli, joka julkaistaan WebGL-sivuna ja iPhone-sovelluksena ilman työpöytäversiota; alla olevat esimerkit ovat sen omia.

1. Rekisteröi pelisi

Rekisteröi peli Game SDK:n rekisteröintisivulla: pelisi game_id (esimerkiksi com.deverence.cozycity), nimi ja kuvake, jotka pelaaja näkee hyväksyntäikkunassa, sekä taustajärjestelmäsi isäntänimet. Tarkistamme sen siellä, ja hyväksynnän jälkeen backend-avaimesi odottaa samalla sivulla, kerran näytettynä; me säilytämme siitä vain tiivisteen. Avain kuuluu palvelimellesi eikä minnekään muualle. Voit vaihtaa sen siellä milloin tahansa, ja vanha pysyy voimassa 24 tuntia, jotta julkaisu ehtii edetä.

Rekisteröi pelisi

Ikkunan nimi ja kuvake tulevat aina rekisteröinnistä, ei koskaan pyynnöstä. Muuten tietojenkalastelulinkki voisi pukea liitospyynnön miksi tahansa peliksi. Isäntänimet rajaavat, minne join.url saa osoittaa, katso alta.

2. Liitä pelaaja

Pelaaja valitsee pelissäsi Yhdistä mssgs. Pelisi kysyy taustajärjestelmältäsi, ja taustajärjestelmäsi kysyy meiltä:

curl -X POST https://ams1-gateway.mss.gs/game-sdk/v1/link/start \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "player_ref": "player-8812", "player_name": "René\u2019s city" }'

# {"link_code":"K7PQ2XM4","device_code":"…","qr_url":"https://mss.gs/gl/K7PQ2XM4",
#  "deep_link":"mssgs://link-game/K7PQ2XM4","expires_in":600,"interval":5}

player_ref on oma pysyvä tunnisteesi kyseiselle pelaajalle (enintään 128 merkkiä), ei istunnolle tai ottelulle; player_name (enintään 64) näkyy ikkunassa muodossa "Pelaaja: …". Anna pelisi asiakassovellukselle vain link_code, qr_url ja deep_link. device_code on kyselykahvasi ja pysyy palvelimella.

Pelisi näyttää sitten kolme asiaa yhtä aikaa, koska pelaaja voi olla missä tahansa:

• QR-koodin osoitteesta qr_url. Puhelin, jossa on mssgs, avaa sen suoraan sovelluksen hyväksyntäikkunaan. Ilman sovellusta se päätyy mss.gs:n sivulle, joka näyttää koodin ja tarjoaa latausta.
• "Avaa mssgs:ssä" -painikkeen, jossa on deep_link, työpöytäselaimelle, joka on työpöytäsovelluksen vieressä. Se on ainoa ulkoinen URL, jonka pelisi koskaan tarvitsee avata.
• Itse koodin kahtena neljän merkin ryhmänä, kirjoitettavaksi kohdassa Asetukset → Pelitoiminta → Liitä peli. Merkistössä ei ole 0/O:ta eikä 1/I:tä, joten kirjoittaminen menee harvoin pieleen.

Mitä pelaaja näkee mssgs:ssä, sovelluksen rekisteröinnin perusteella piirtämänä:

Sillä välin taustajärjestelmäsi kyselee interval sekunnin välein (nopeampaan vastataan 429 SLOW_DOWN), kunnes tila vaihtuu. Koodi toimii kerran ja vanhenee kymmenen minuutin kuluttua:

curl -X POST https://ams1-gateway.mss.gs/game-sdk/v1/link/poll \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "…" }'

# {"status":"pending"}
# {"status":"denied"}      # pelaaja valitsi Ei nyt
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Tallenna link_guid pelaajasi yhteyteen; tästä lähtien se on osoite, jolle julkaiset. Vastaus sisältää vain user_guid:n; username lisätään vain, kun rekisteröinnilläsi on identity.link-scope, eikä sen lisäksi ole mitään. Toinen hyväksyntä samalle player_ref:lle korvaa aiemman liitoksen, joten yksi pelisi pelaaja on yksi mssgs-tili. Sama mssgs-tili voi olla liitetty useaan peliin ja saman pelin useaan player_ref:iin (perheen iPad).

3. Julkaise pelaamistila

Sama lohko kuin sillassa, samoin säännöin ja samoin rajoin, nyt vain liitoskohtaisesti ja backend-avaimellasi:

{
  "activity": {
    "name":       "CozyCity",
    "details":    "Lantern Hollow",
    "state":      "Day 12 · 34 residents",
    "started_at": 1788901000000,
    "party":      { "size": 6, "max": 40, "kind": "server" },
    "join":       { "url": "https://cozycity.net/game/?share=…" }
  }
}

200 {"published":true,"changed":true}     # lohko muuttui ja se lähetettiin
200 {"published":true,"changed":false}    # sama kuin tallennettu; vain TTL päivitettiin
204                                        # tallennettu, mutta pelaaja ei ole juuri nyt paikalla mssgs:ssä
410 {"error":"LINK_REVOKED"}               # pelaaja katkaisi yhteyden: pudota liitos

Käsittele 200 ja 204 samoin: tallennettu. { "activity": null } tyhjentää lohkon; lähetä se, kun pelaaja lopettaa. Yksi ero siltaan: join.url:n isännän on oltava jokin rekisteröidyistä taustajärjestelmistäsi (tai sen aliverkkotunnus), tai saat 400 INVALID_PAYLOAD. Taustajärjestelmä ei siis voi laittaa pelaajan tilaan Liity nyt -painiketta, joka vie paikkaan, jossa pelaaja ei ole koskaan pelannut.

Kun paikalla on satoja pelaajia, lähetä heartbeat yhdellä kutsulla, enintään 100 kohdetta kerrallaan. Jokainen kohde saa oman tilansa, joten yksi pelaaja, joka katkaisi yhteyden mssgs:ssä, ei koskaan pysäytä muita yhdeksääkymmentäyhdeksää:

{ "items": [ { "link_guid": "…", "activity": { "name": "CozyCity", "details": "Lantern Hollow" } },
             { "link_guid": "…", "activity": null } ] }

// → 200 { "results": [ { "link_guid": "…", "status": 200, "changed": false },
//                      { "link_guid": "…", "status": 410 } ] }

Miten tila näytetään

• Samoin kuin sillan kautta tuleva tila: Pelaa peliä CozyCity · Lantern Hollow · 6/40 pelaajaa, ja Liity nyt, kun join.url on annettu. Lohkoon merkitään palvelinpuolella via: "backend", joten sovellus voi lisätä tekstin "Jakaa pelin palvelin".
• Vain kun pelaaja on paikalla mssgs:ssä. Kun mikään mssgs-sovellus ei ole auki, tili on poissa ja pysyy poissa; taustajärjestelmäsi ei voi saada ketään näyttämään paikalla olevalta. Se estää myös tätä reittiä muuttumasta "onko René koneellaan" -majakaksi.
• Etusijajärjestys: sovelluksen sisäinen peli > sillan kautta tuleva peli > taustajärjestelmäsi. Jos pelaaja istahtaa pelaamaan shakkia mssgs:ssä samalla kun taustajärjestelmäsi lähettää heartbeatia, shakki voittaa, ei viimeisin kirjoittaja.

Yhteyden katkaiseminen

Pelaaja näkee jokaisen liitoksen kohdassa Asetukset → Pelitoiminta → Liitetyt pelit kuvakkeesi ja nimesi, pelisi pelaajanimen, liittämisajan ja viimeisimmän julkaisun kera, sekä Katkaise yhteys -painikkeen. Sen jälkeen seuraava julkaisusi vastaa 410 LINK_REVOKED; siitä pelisi saa tietää. Pudota link_guid ja tarjoa taas "Yhdistä mssgs". Omalta puoleltasi lopetat liitoksen kutsulla DELETE /game-sdk/v1/links/{link_guid}.

Päätepisteviite: silta

Perus-URL http://127.0.0.1:<port>. Kaikki paitsi kolme ensimmäistä vaativat otsakkeen Authorization: Bearer <token>.

Päätepisteviite: liitetyt taustajärjestelmät

Perus-URL https://ams1-gateway.mss.gs. Jokainen reitti vaatii otsakkeen Authorization: Bearer <backend key> ja rekisteröinnillesi activity.write-scopen; vastaukset lähetetään otsakkeella Cache-Control: no-store. Kutsu näitä palvelimeltasi, älä koskaan pelin asiakassovelluksesta.

Virhekoodit

Virheet palautetaan muodossa {"error":"CODE","message":"…"} vastaavan HTTP-tilakoodin kanssa.

Liitetyt taustajärjestelmät

Taustajärjestelmän reitit käyttävät samaa muotoa. Batchin sisällä tila palautetaan kohdekohtaisesti results-kentässä, joten yksi päättynyt liitos ei koskaan kaada koko kutsua.

Tietoturva

Vain natiivipelit

Pyynnöt, joissa on verkkosivun Origin, hylätään koodilla 403 ORIGIN_NOT_ALLOWED. Jos mikä tahansa verkkosivu voisi havaita, että käytät mssgs:ää, ja avata lupaikkunan, se olisi sormenjälkien keräämisen ja tietojenkalastelun väylä, ei ominaisuus. Natiivipeli ei lähetä Originia lainkaan, joten se ei vaikuta siihen, ja pelin oma upotettu selain sallitaan nimeltä, katso FiveM. Jos rakennat selain- tai puhelinpeliä, et keskustele sillan kanssa: oma taustajärjestelmäsi julkaisee liitetyille pelaajille, katso Selain- ja puhelinpelit.

Mitä pelaaja pitää hallussaan

• Pelaaja voi kytkeä sillan pois kohdassa Asetukset → Pelitoiminta, minkä jälkeen yksikään peli ei näe mssgs:ää lainkaan.
• Jokainen hyväksytty peli on listattu siellä täsmälleen niine oikeuksineen, jotka sillä on, viimeisimmän aktiivisuusajan ja Poista-painikkeen kera. Poisto on välitön: token kuolee heti.
• Liitetty selain- tai puhelinpeli on listattu kohdassa Liitetyt pelit, ja siinä on Katkaise yhteys -painike. Yhteyden katkaisu on myös välitön: taustajärjestelmän seuraava julkaisu saa vastauksen 410.
• Silta kuuntelee vain osoitetta 127.0.0.1, ei koskaan verkkoa.
• Yksityisviestejä ei koskaan paljasteta, ei edes servers.list-scopella.
• Jokaisella pelillä on 120 pyynnön minuuttikohtainen kiintiö.

Hyvät tavat

• Pyydä scopeja silloin, kun tarvitset niitä, äläkä kaikkia kerralla ensimmäisellä käynnistyskerralla.
• Toimi ilman mssgs:ää: pelaajalla ei tarvitse olla sitä.
• Tyhjennä tilasi, kun pelaaminen loppuu, äläkä odota TTL:n umpeutumista.
• Käsittele evättyä scopea tavallisena lopputuloksena, ei virheenä.