Näita, mida keegi mängib

Ülevaade

mssgs’i arvutirakendus käitab väikest kohalikku HTTP-silda, millega samas arvutis olev mäng suhtleb. Sinu mäng ei suhtle kunagi meie serveritega, ei näe kunagi konto parooli ega tokenit ega saa kunagi mängija nimel postitada. See suhtleb selle mssgs’i koopiaga, kuhu mängija on juba sisse logitud, ja see koopia otsustab, mida vastata.

Mida sellega teha saab:

• Tuvastada, et mssgs on paigaldatud ja keegi on sisse logitud.
• Lugeda, kes mängija on: user_guid, username, avatar.
• Küsida „kas see mängija on kogukonnas X?“ ja millist rolli ta seal kannab.
• Avaldada teistele „Playing …“ olek nupuga Join now.
• Võtta vastu liitumisandmed, kui keegi seda nuppu vajutab.

Kliendi leidmine

Sild kuulab ainult aadressil 127.0.0.1, väikese vahemiku esimesel vabal pordil. Proovi neid järjest, kuni mõni vastab: 7440, 7441, 7442, 7443. mssgs’i arendusversioonid kuulavad selle asemel portidel 7540–7543, nii et testversioon ei vasta kunagi päris mängu päringutele.

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

Enne edasi minemist kontrolli product === "mssgs" ja api. Kui ükski neljast pordist ei vasta, mssgs ei tööta. Paku siis lihtsalt oma tavalist kogemust, selle asemel et mängijat ootama panna.

Loa küsimine

Kõik peale /hello vajab tokenit ja token tekib alles siis, kui mängija on sinu mängu rakenduse dialoogis heaks kiitnud. Küsi ainult neid ulatusi, mida tegelikult kasutad: mängija näeb igaüht eraldi koos selgitusega ja saab igaühelt eraldi linnukese ära võtta.

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"]
  }'

Tagasi saad {"status":"pending","request_id":"…","poll_after_ms":1000} ja mängija näeb dialoogi. Seejärel küsitle, kuni ta vastab (päring aegub 3 minuti pärast):

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

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

Salvesta token ja saada see kujul Authorization: Bearer <token>. See püsib üle taaskäivituste, nii et mängija kiidab sinu mängu heaks ühe korra, mitte igal seansil. Kui hiljem autoriseerid uuesti juba antud ulatustega, saad sama tokeni kohe tagasi, ilma dialoogita.

Ulatused ja privaatsus

Viis ulatust annavad välja väga erineva hulga andmeid. See pole juhuslik, see ongi kogu disaini mõte. Küsi nii vähe kui võimalik, liikudes selles tabelis ülevalt alla.

Liikmesuse kontrollimine

See on alternatiiv palvele „anna mulle kogu nimekiri“. Annad oma kogukonna server_guid väärtuse (mida sa juba tead) ja saad vastuse ainult selle kohta.

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

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

# pole liige ja muud midagi:
# {"server_guid":"…","member":false}

„Ei“ tähendab täpselt seda ja mitte midagi enamat. Ühes päringus võid anda kuni 10 guidi (korda parameetrit server_guid või eralda need komadega), siis saad tagasi massiivi results. Gruppi @everyone pole kunagi loendis roles: see kehtib iga liikme kohta, nii et see ei ütle sulle midagi.

Mänguoleku avaldamine

Üks PUT-päring paneb „Playing …“ rea mängija nime alla kõikjal, kus tema kogukonnad teda näevad.

{
  "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" }
}

Kohustuslik on ainult name. Vastus ütleb, kui kaua olek kestab ja kui tihti heartbeati saata:

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

Mängijate arv ja roll

party.kind otsustab, milline lause kuvatakse, sest samad kaks numbrit ei tähenda alati sama asja. Neljaliikmeline meeskond pole server, kus on neli mängijat.

role (kuni 48 märki) on see, kellena mängija mängib: amet, klass või tegelane. Sellel on oma väli, mitte järjekordne lause väljal state, sest seda näidatakse sildina mängijate arvu kõrval.

details ja state on piiratud kumbki 128 märgiga, name 64 märgiga. Reavahetused ja juhtmärgid eemaldatakse. Ikooni URL-i teadlikult ei toetata: selle laadiks alla iga klient, mis rea kuvab, ja nii muutuks olek majakaks, mis raporteerib sinu serverile iga liikme igast kogukonnast, kus mängija on.

Nupp Join now

Pane oma tegevusse plokk join ja teised liikmed saavad oleku kõrvale nupu Join now. Selleks on kaks viisi ja neid võib kombineerida.

1. Saladus (natiivsetele mängudele)

Määra {"join":{"secret":"raid-42"}}. Kui keegi vajutab Join now, toimetatakse see saladus tema enda koopiale sinu mängust, tema enda arvutis, sobitatuna sama game_id järgi. Ühtegi URL-i ei avata ja ühtegi skeemi käsitlejat ei käivitata. Sinu mäng korjab selle üles nii:

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

Küsitle parameetriga ?since=<cursor>, et näha iga sündmust ainult üks kord. Kui vajutaja mäng ei tööta, ei toimetata midagi kohale, ja see on hea põhjus pakkuda ka URL-i.

2. https-URL (veebimängudele ja lobby linkidele)

Määra {"join":{"url":"https://play.example.com/s/abc"}} ja nupp avab selle lingi. Lubatud on ainult https. Kohandatud skeem (steam://, mygame://, file://) lükatakse tagasi: see plokk jõuab iga liikme ekraanile ja selline URL on viis panna kellegi teise arvuti käivitama kohalikku käsitlejat sinu valitud argumentidega.

FiveM

FiveM-i kliendipoolses Lua keskkonnas pole HTTP-d, nii et ressurss suhtleb sillaga NUI kaudu: see on CEF-vaade, mis saadab Origin päise. Sild aktsepteerib neid päritolusid selgesõnaliselt: https://cfx-nui-<resource> ja vanemat nui://<resource>. Tavalised veebilehed lükatakse endiselt tagasi ja avatud veebis olev leht ei saa seda päritolu enda omaks kuulutada; brauser määrab selle ise.

-- NUI-leht teeb HTTP-päringu; Lua saadab sellele ainult andmed.
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: olek aegub 90 s pärast
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // proovi 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']          // rohkem pole siin vaja
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Mängija näeb nüüd mssgs’is loa dialoogi.
  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' } // sinu cfx.re link
    })
  });
});

Tulemus: Playing FiveM · Los Santos Roleplay · 4/100 players · Police, koos nupuga Join now, mis avab sinu cfx.re lingi.

Brauseri- ja telefonimängud: sidumine sinu backendi kaudu

Brauseri vahelehel või telefonis töötav mäng ei ulatu ülalkirjeldatud sillani. Sild töötab mängija arvutis ja vahel on kolm müüri: sild lükkab tagasi iga päringu, millel on brauseri Origin, Chrome näitab loaküsimust, enne kui avalik leht saab pöörduda aadressi 127.0.0.1 poole, ja Safari keeldub otse, ning telefonil pole arvuti loopbackini üldse teed.

Seega pöördub suund ümber. Sinu enda backend teab juba, kes mängib, ja annab sellest mssgs’ile teada nende mängijate puhul, kes on oma mssgs’i konto sinu mänguga sidunud. Sidumine kinnitatakse mssgs’i rakenduses, mitte kunagi sinu mängus, ja see loob seose, mitte kunagi seanssi: miski allpool ei saa kedagi sisse logida ega mängija nimel tegutseda. Sinu mängu klient ei näe kunagi võtit ega suhtle kunagi mss.gs-iga. Esimene mäng sellel teel on CozyCity, linnaehitusmäng, mis ilmub WebGL-lehena ja iPhone’i rakendusena ilma arvutiversioonita; allolevad näited on tema omad.

1. Registreeri oma mäng

Registreeri mäng Game SDK registreerimislehel: sinu game_id (näiteks com.deverence.cozycity), nimi ja ikoon, mida mängija kinnituslehel näeb, ning sinu backendi hostinimed. Vaatame selle seal üle ja kui see on heaks kiidetud, ootab samal lehel sinu backendi võti, mida näidatakse ühe korra; meie hoiame alles ainult selle räsi. Võti kuulub sinu serverisse ja mitte kuhugi mujale. Saad seda seal igal ajal vahetada ja vana jääb 24 tunniks kehtima, et juurutus jõuaks rahulikult läbi minna.

Registreeri oma mäng

Nimi ja ikoon kinnituslehel tulevad alati registreeringust, mitte kunagi päringust. Muidu saaks andmepüügilink sidumispäringu riietada ükskõik milliseks mänguks. Hostinimed piiravad, kuhu join.url tohib viidata, vaata allpool.

2. Seo mängija

Mängija valib sinu mängus Connect mssgs. Sinu mäng küsib sinu backendilt ja sinu backend küsib 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 sinu enda püsiv ID selle mängija jaoks (kuni 128 märki), mitte seansi või matši jaoks; player_name (kuni 64) on see, mida kinnitusleht näitab kujul „Player: …“. Anna oma mängukliendile ainult link_code, qr_url ja deep_link. device_code on sinu küsitlemise käepide ja jääb serverisse.

Seejärel näitab sinu mäng korraga kolme asja, sest mängija võib olla ükskõik kus:

• QR-kood väärtusest qr_url. Telefon, kus on mssgs, avab selle otse rakenduse kinnituslehele. Ilma rakenduseta jõuab see lehele mss.gs-is, mis näitab koodi ja pakub allalaadimist.
• Nupp „Open in mssgs“ lingiga deep_link, brauserile arvutis, kus töötab ka arvutirakendus. See on ainus väline URL, mida sinu mäng kunagi avama peab.
• Kood ise, kahes neljases rühmas, sisestamiseks menüüs Settings → Game Activity → Link a game. Tähestikus pole 0/O ega 1/I, nii et sisestamisel läheb harva midagi valesti.

Mida mängija mssgs’is näeb; rakendus koostab selle registreeringu põhjal:

Vahepeal küsitleb sinu backend iga interval sekundi järel (kiiremini küsides tuleb vastuseks 429 SLOW_DOWN), kuni olek muutub. Kood töötab ühe korra ja aegub kümne minuti pärast:

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"}      # mängija valis Not now
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Salvesta link_guid oma mängija juurde; nüüdsest on see aadress, mille jaoks avaldad. Vastuses on ainult user_guid; username lisatakse ainult siis, kui sinu registreeringul on ulatus identity.link, ja rohkem pole midagi. Teine kinnitus sama player_ref jaoks asendab varasema seose, nii et üks sinu mängu mängija on üks mssgs’i konto. Sama mssgs’i konto võib olla seotud mitme mänguga ja ühe mängu mitme player_ref väärtusega (pere iPad).

3. Avalda mänguolek

Sama plokk nagu sillal, samade reeglite ja piirangutega, ainult nüüd iga seose kohta eraldi ja sinu backendi võtmega:

{
  "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}     # plokk muutus ja saadeti laiali
200 {"published":true,"changed":false}    # sama mis salvestatud; värskendati ainult TTL-i
204                                        # salvestatud, aga mängija pole praegu mssgs’is võrgus
410 {"error":"LINK_REVOKED"}               # mängija katkestas seose: kustuta see

Käsitle vastuseid 200 ja 204 ühtemoodi: salvestatud. { "activity": null } tühjendab ploki, saada see, kui mängija lahkub. Üks erinevus sillast: join.url host peab olema üks sinu registreeritud backendidest (või selle alamdomeen), muidu saad 400 INVALID_PAYLOAD. Nii ei saa backend panna mängija olekule nuppu Join now, mis viib kuhugi, kus see mängija pole kunagi mänginud.

Kui võrgus on sadu mängijaid, saada heartbeat ühe päringuga, kuni 100 kirjet korraga. Iga kirje saab oma oleku, nii et üks mängija, kes mssgs’is seose katkestas, ei peata kunagi ülejäänud üheksakümmend üheksat:

{ "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 } ] }

Kuidas olekut näidatakse

• Täpselt nagu silla olek: Playing CozyCity · Lantern Hollow · 6/40 players, koos nupuga Join now, kui on olemas join.url. Server märgistab ploki kui via: "backend", nii et klient võib lisada „Shared by the game's server“.
• Ainult siis, kui mängija on mssgs’is võrgus. Kui ükski mssgs’i klient pole avatud, on konto võrgust väljas ja jääb selleks; sinu backend ei saa panna kedagi kohalolevana paistma. See takistab ka seda, et sellest teest saaks „kas René on arvuti taga“ majakas.
• Eelisjärjekord: rakendusesisene mäng > mäng sillal > sinu backend. Kui mängija istub mssgs’is male mängima, samal ajal kui sinu backend heartbeate saadab, võidab male, mitte see, kes viimasena kirjutas.

Seose katkestamine

Mängija näeb iga seost jaotises Settings → Game Activity → Linked games koos sinu ikooni ja nimega, sinu mängust pärit mängijanimega, sidumise ja viimase avaldamise ajaga ning nupuga Disconnect. Pärast seda vastab sinu järgmine avaldamine 410 LINK_REVOKED; nii saab sinu mäng sellest teada. Kustuta link_guid ja paku uuesti „Connect mssgs“. Enda poolt lõpetad seose päringuga DELETE /game-sdk/v1/links/{link_guid}.

Endpointide teatmik: sild

Baas-URL http://127.0.0.1:<port>. Kõik peale kolme esimese nõuavad päist Authorization: Bearer <token>.

Endpointide teatmik: seotud backendid

Baas-URL https://ams1-gateway.mss.gs. Iga marsruut nõuab päist Authorization: Bearer <backend key> ja sinu registreeringul ulatust activity.write; vastused saadetakse päisega Cache-Control: no-store. Kutsu neid välja oma serverist, mitte kunagi mängukliendist.

Veakoodid

Vead tulevad tagasi kujul {"error":"CODE","message":"…"} koos vastava HTTP olekukoodiga.

Seotud backendid

Backendi marsruudid kasutavad sama kuju. Koondpäringus tuleb olek tagasi iga kirje kohta eraldi väljal results, nii et üks lõppenud seos ei nurjata kunagi kogu päringut.

Turvalisus

Ainult natiivsed mängud

Päringud, millel on veebilehe Origin, lükatakse tagasi koodiga 403 ORIGIN_NOT_ALLOWED. Kui iga veebileht saaks tuvastada, et kasutad mssgs’i, ja avada loa dialoogi, oleks see sõrmejälgede kogumise ja andmepüügi pind, mitte funktsioon. Natiivne mäng ei saada üldse Origin päist, nii et teda see ei puuduta, ja mängu enda sisseehitatud brauser on nime järgi lubatud, vaata FiveM. Kui ehitad brauseri- või telefonimängu, sa sillaga ei suhtle: sinu enda backend avaldab seotud mängijate eest, vaata Brauseri- ja telefonimängud.

Mille üle mängija kontrolli säilitab

• Mängija saab silla välja lülitada jaotises Settings → Game Activity, misjärel ükski mäng ei näe mssgs’i üldse.
• Iga heakskiidetud mäng on seal loetletud täpselt nende õigustega, mis tal on, viimase aktiivsuse ajaga ja nupuga Remove. Eemaldamine on kohene: token sureb otsekohe.
• Seotud brauseri- või telefonimäng on loetletud jaotises Linked games nupuga Disconnect. Ka seose katkestamine on kohene: selle backendi järgmine avaldamine saab vastuseks 410.
• Sild kuulab ainult aadressil 127.0.0.1, mitte kunagi võrgus.
• Otsesõnumeid ei avalikustata kunagi, isegi mitte ulatusega servers.list.
• Iga mängu kohta on piirang 120 päringut minutis.

Hea tava

• Küsi ulatusi siis, kui neid vajad, mitte kõiki korraga esimesel käivitamisel.
• Tööta ka ilma mssgs’ita: mängijal ei pea seda olema.
• Tühjenda oma olek, kui mängimine lõpeb, selle asemel et TTL-i oodata.
• Käsitle tagasilükatud ulatust tavalise tulemusena, mitte veana.