Parodyk, ką kas nors žaidžia

Apžvalga

mssgs kompiuterio programėlė paleidžia nedidelį vietinį HTTP tiltą, su kuriuo bendrauja tame pačiame kompiuteryje esantis žaidimas. Tavo žaidimas niekada nesijungia prie mūsų serverių, niekada nemato paskyros slaptažodžio ar tokeno ir niekada negali skelbti žaidėjo vardu. Jis bendrauja su ta mssgs kopija, prie kurios žaidėjas jau prisijungęs, o ta kopija sprendžia, ką atsakyti.

Ką su juo gali daryti:

• Aptikti, kad mssgs įdiegta ir kas nors yra prisijungęs.
• Perskaityti, kas yra žaidėjas: user_guid, username, avataras.
• Paklausti „ar šis žaidėjas yra bendruomenėje X?“ ir kokį vaidmenį jis ten turi.
• Paskelbti būseną „Playing …“ su mygtuku Join now kitiems.
• Gauti prisijungimo duomenis, kai kas nors paspaudžia tą mygtuką.

Kliento paieška

Tiltas klauso tik 127.0.0.1, pirmame laisvame nedidelio intervalo prievade. Bandyk juos iš eilės, kol kuris nors atsakys: 7440, 7441, 7442, 7443. Kūrimo (development) mssgs versijos vietoj to klauso 7540–7543, todėl bandomoji versija niekada neatsako į tikro žaidimo užklausas.

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

Prieš eidamas toliau, patikrink product === "mssgs" ir api. Jei neatsako nė vienas iš keturių prievadų, mssgs neveikia. Tiesiog pasiūlyk įprastą patirtį, užuot vertęs žaidėją laukti.

Leidimo prašymas

Viskam, išskyrus /hello, reikia tokeno, o tokenas atsiranda tik tada, kai žaidėjas patvirtina tavo žaidimą programėlės dialogo lange. Prašyk tik tų aprėpčių, kurias tikrai naudoji: žaidėjas mato kiekvieną atskirai, su paaiškinimu, ir gali kiekvieną atžymėti atskirai.

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

Atgal gauni {"status":"pending","request_id":"…","poll_after_ms":1000}, o žaidėjas mato dialogo langą. Tada periodiškai tikrink (polling), kol jis atsakys (prašymas nustoja galioti po 3 minučių):

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

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

Išsaugok tokeną ir siųsk jį kaip Authorization: Bearer <token>. Jis išlieka po paleidimų iš naujo, todėl žaidėjas tavo žaidimą patvirtina vieną kartą, o ne kiekvienos sesijos metu. Jei vėliau autorizuosi iš naujo su jau suteiktomis aprėptimis, iškart gausi tą patį tokeną be jokio dialogo lango.

Aprėptys ir privatumas

Penkios aprėptys atskleidžia labai skirtingą kiekį duomenų. Tai ne atsitiktinumas; tuo ir grindžiamas visas sumanymas. Prašyk kuo mažiau, eidamas šia lentele iš viršaus žemyn.

Narystės tikrinimas

Tai alternatyva prašymui „duok man visą sąrašą“. Nurodai savo bendruomenės server_guid (kurį jau žinai) ir gauni atsakymą tik apie ją.

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

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

# ne narys, ir nieko daugiau:
# {"server_guid":"…","member":false}

„Ne“ reiškia būtent tai ir nieko daugiau. Viename iškvietime gali perduoti iki 10 guid (pakartok server_guid arba atskirk juos kableliais), tada gausi masyvą results. Grupės @everyone niekada nėra roles sąraše: ji galioja kiekvienam nariui, todėl nieko tau nepasako.

Žaidimo būsenos skelbimas

Vienas PUT įdeda eilutę „Playing …“ po žaidėjo vardu visur, kur jį mato jo bendruomenės.

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

Privalomas tik name. Atsakymas nurodo, kiek laiko būsena galioja ir kaip dažnai siųsti heartbeat:

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

Žaidėjų skaičius ir vaidmuo

party.kind lemia, kuris sakinys rodomas, nes tie patys du skaičiai reiškia ne tą patį. Keturių žmonių komanda nėra serveris su keturiais žaidėjais.

role (iki 48 simbolių) yra tai, kuo žaidėjas žaidžia: profesija, klasė ar personažas. Jam skirtas atskiras laukas, o ne dar vienas sakinys state, nes jis rodomas kaip etiketė šalia žaidėjų skaičiaus.

details ir state ribojami iki 128 simbolių kiekvienas, name iki 64. Eilučių lūžiai ir valdymo simboliai pašalinami. Ikonos URL tyčia nepalaikomas: jį parsisiųstų kiekvienas klientas, rodantis šią eilutę, o tai paverstų būseną švyturiu, pranešančiu tavo serveriui apie kiekvieną kiekvienos bendruomenės, kurioje yra žaidėjas, narį.

Mygtukas Join now

Įdėk į savo veiklą (activity) bloką join, ir kiti nariai šalia būsenos gaus mygtuką Join now. Yra du būdai, ir juos galima derinti.

1. Paslaptis (natyviniams žaidimams)

Nustatyk {"join":{"secret":"raid-42"}}. Kai kas nors paspaudžia Join now, ši paslaptis pristatoma jo paties tavo žaidimo kopijai, jo paties kompiuteryje, susietai pagal tą patį game_id. Joks URL neatidaromas ir jokia schemos tvarkyklė nekviečiama. Tavo žaidimas ją pasiima taip:

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

Tikrink su ?since=<cursor>, kad kiekvieną įvykį pamatytum tik kartą. Jei paspaudusiojo žaidimas neveikia, niekas nepristatoma, ir tai gera priežastis pasiūlyti ir URL.

2. https URL (naršyklės žaidimams ir lobby nuorodoms)

Nustatyk {"join":{"url":"https://play.example.com/s/abc"}}, ir mygtukas atidarys tą nuorodą. Priimamas tik https. Savita schema (steam://, mygame://, file://) atmetama: šis blokas atsiduria kiekvieno nario ekrane, o toks URL yra būdas priversti kieno nors kito kompiuterį iškviesti vietinę tvarkyklę su tavo pasirinktais argumentais.

FiveM

FiveM kliento pusės Lua aplinkoje neturi HTTP, todėl resursas bendrauja su tiltu per NUI, CEF rodinį, kuris siunčia Origin. Tiltas šiuos origin priima aiškiai: https://cfx-nui-<resource> ir senesnį nui://<resource>. Įprasti tinklalapiai ir toliau atmetami, o puslapis atvirame internete negali apsimesti šiuo origin; jį nustato pati naršyklė.

-- NUI puslapis atlieka HTTP; Lua tik perduoda jam duomenis.
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: būsena nustoja galioti po 90 s
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // bandyk 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']          // čia daugiau nieko nereikia
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Dabar žaidėjas mssgs mato leidimo dialogo langą.
  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' } // tavo cfx.re nuoroda
    })
  });
});

Rezultatas: Playing FiveM · Los Santos Roleplay · 4/100 players · Police, su mygtuku Join now, kuris atidaro tavo cfx.re nuorodą.

Naršyklės ir telefono žaidimai: susiejimas per tavo backend

Žaidimas naršyklės skirtuke ar telefone negali pasiekti aukščiau aprašyto tilto. Tiltas veikia žaidėjo kompiuteryje, o tarp jų stovi trys sienos: tiltas atmeta kiekvieną užklausą su naršyklės Origin, Chrome, prieš viešam puslapiui kreipiantis į 127.0.0.1, parodo leidimo užklausą, Safari iškart atsisako, o telefonas apskritai neturi kelio į kompiuterio loopback.

Todėl kryptis apsiverčia. Tavo paties backend jau žino, kas žaidžia, ir jis praneša mssgs apie žaidėjus, kurie susiejo savo mssgs paskyrą su tavo žaidimu. Susiejimas patvirtinamas mssgs programėlėje, niekada ne tavo žaidime, ir jis sukuria ryšį, niekada ne sesiją: niekas toliau aprašyta negali nieko prijungti ar veikti žaidėjo vardu. Tavo žaidimo klientas niekada nemato rakto ir niekada nesikreipia į mss.gs. Pirmasis žaidimas šiuo keliu yra CozyCity, miesto kūrimo žaidimas, išleistas kaip WebGL puslapis ir iPhone programėlė be kompiuterio versijos; toliau pateikti pavyzdžiai yra būtent iš jo.

1. Užregistruok žaidimą

Užregistruok žaidimą Game SDK registracijos puslapyje: savo game_id (pavyzdžiui, com.deverence.cozycity), pavadinimą ir ikoną, kuriuos žaidėjas mato patvirtinimo lange, ir savo backend serverių pavadinimus (hostnames). Peržiūrime ją ten pat, o kai ji patvirtinama, tame pačiame puslapyje tavęs laukia backend raktas, parodomas vieną kartą; mes saugome tik jo santrauką (digest). Raktas turi būti tavo serveryje ir niekur kitur. Ten pat gali jį bet kada pakeisti nauju, o senasis galioja dar 24 valandas, kad diegimas spėtų pereiti.

Užregistruok savo žaidimą

Pavadinimas ir ikona lange visada imami iš registracijos, niekada iš užklausos. Kitaip sukčiavimo (phishing) nuoroda galėtų paversti susiejimo prašymą bet kokiu žaidimu. Serverių pavadinimai riboja, kur gali vesti join.url, žr. toliau.

2. Susiek žaidėją

Žaidėjas tavo žaidime pasirenka Connect mssgs. Tavo žaidimas klausia tavo backend, o backend klausia mūsų:

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 yra tavo paties nekintamas to žaidėjo ID (iki 128 simbolių), ne sesijos ar mačo; player_name (iki 64) yra tai, ką langas rodo kaip „Player: …“. Savo žaidimo klientui perduok tik link_code, qr_url ir deep_link. device_code yra tavo tikrinimo (polling) rankena ir lieka serveryje.

Tada tavo žaidimas iš karto parodo tris dalykus, nes žaidėjas gali būti bet kur:

• QR kodą iš qr_url. Telefonas su mssgs jį atidaro tiesiai programėlės patvirtinimo lange. Be programėlės jis patenka į mss.gs puslapį, kuris parodo kodą ir pasiūlo atsisiųsti programėlę.
• Mygtuką „Open in mssgs“ su deep_link, skirtą kompiuterio naršyklei, šalia kurios veikia kompiuterio programėlė. Tai vienintelis išorinis URL, kurį tavo žaidimui kada nors reikės atidaryti.
• Patį kodą, dviem grupėmis po keturis simbolius, kurį reikia įvesti skiltyje Settings → Game Activity → Link a game. Abėcėlėje nėra 0/O ar 1/I, todėl jį įvedant retai suklystama.

Ką žaidėjas mato mssgs, langą, kurį programėlė sudaro pagal registraciją:

Tuo metu tavo backend tikrina kas interval sekundžių (į dažnesnes užklausas atsakoma 429 SLOW_DOWN), kol būsena pasikeičia. Kodas veikia vieną kartą ir nustoja galioti po dešimties minučių:

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"}      # žaidėjas pasirinko Not now
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Išsaugok link_guid prie savo žaidėjo; nuo šiol tai adresas, kuriam skelbi. Atsakyme yra tik user_guid; username pridedamas tik tada, kai tavo registracija turi aprėptį identity.link, ir nieko daugiau. Antras patvirtinimas tam pačiam player_ref pakeičia ankstesnį susiejimą, todėl vienas tavo žaidimo žaidėjas yra viena mssgs paskyra. Ta pati mssgs paskyra gali būti susieta su keliais žaidimais ir su keliais vieno žaidimo player_ref (šeimos iPad).

3. Paskelbk žaidimo būseną

Tas pats blokas kaip ir tilte, su tomis pačiomis taisyklėmis ir ribomis, tik dabar kiekvienam susiejimui atskirai ir su tavo backend raktu:

{
  "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}     # blokas pasikeitė ir buvo transliuotas
200 {"published":true,"changed":false}    # toks pat kaip išsaugotas; atnaujintas tik TTL
204                                        # išsaugota, bet žaidėjas dabar nėra prisijungęs prie mssgs
410 {"error":"LINK_REVOKED"}               # žaidėjas atsijungė: pašalink susiejimą

Į 200 ir 204 reaguok vienodai: išsaugota. { "activity": null } išvalo bloką, siųsk tai, kai žaidėjas išeina. Vienas skirtumas nuo tilto: join.url serveris turi būti vienas iš tavo užregistruotų backend serverių (arba jo subdomenas), kitaip gausi 400 INVALID_PAYLOAD. Taigi backend negali pridėti prie žaidėjo būsenos mygtuko Join now, vedančio ten, kur tas žaidėjas niekada nežaidė.

Kai prisijungę šimtai žaidėjų, siųsk heartbeat vienu iškvietimu, iki 100 elementų vienu metu. Kiekvienas elementas gauna savo būseną, todėl vienas žaidėjas, atsijungęs mssgs, niekada nesustabdo kitų devyniasdešimt devynių:

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

Kaip rodoma būsena

• Lygiai taip pat kaip būsena iš tilto: Playing CozyCity · Lantern Hollow · 6/40 players, su Join now, kai yra join.url. Serverio pusėje blokas pažymimas via: "backend", todėl klientas gali pridėti „Shared by the game's server“.
• Tik kol žaidėjas prisijungęs prie mssgs. Kai neatidarytas joks mssgs klientas, paskyra yra neprisijungusi ir tokia lieka; tavo backend negali padaryti, kad kas nors atrodytų esantis. Tai taip pat neleidžia šiam keliui tapti švyturiu „ar René prie kompiuterio“.
• Pirmenybė: žaidimas programėlėje > žaidimas per tiltą > tavo backend. Jei žaidėjas mssgs viduje sėda žaisti šachmatų, o tavo backend toliau siunčia heartbeat, laimi šachmatai, o ne tas, kuris rašė paskutinis.

Atsijungimas

Žaidėjas mato kiekvieną susiejimą skiltyje Settings → Game Activity → Linked games, su tavo ikona ir pavadinimu, žaidėjo vardu iš tavo žaidimo, susiejimo ir paskutinio skelbimo laiku bei mygtuku Disconnect. Po to į tavo kitą skelbimą atsakoma 410 LINK_REVOKED; taip tavo žaidimas apie tai sužino. Pašalink link_guid ir vėl pasiūlyk „Connect mssgs“. Iš savo pusės susiejimą užbaigsi su DELETE /game-sdk/v1/links/{link_guid}.

Endpoint’ų žinynas: tiltas

Bazinis URL http://127.0.0.1:<port>. Visiems, išskyrus pirmus tris, reikia Authorization: Bearer <token>.

Endpoint’ų žinynas: susieti backend serveriai

Bazinis URL https://ams1-gateway.mss.gs. Kiekvienam maršrutui reikia Authorization: Bearer <backend key> ir aprėpties activity.write tavo registracijoje; atsakymai siunčiami su Cache-Control: no-store. Kviesk juos iš savo serverio, niekada iš žaidimo kliento.

Klaidų kodai

Klaidos grąžinamos kaip {"error":"CODE","message":"…"} su atitinkamu HTTP būsenos kodu.

Susieti backend serveriai

Backend maršrutai naudoja tą pačią formą. Paketo užklausoje būsena grąžinama kiekvienam elementui atskirai lauke results, todėl vienas užbaigtas susiejimas niekada nesugadina viso iškvietimo.

Saugumas

Tik natyviniai žaidimai

Užklausos su tinklalapio Origin atmetamos su 403 ORIGIN_NOT_ALLOWED. Jei bet kuris tinklalapis galėtų aptikti, kad naudoji mssgs, ir iškviesti leidimo dialogo langą, tai būtų spraga sekimui (fingerprinting) ir sukčiavimui, o ne funkcija. Natyvinis žaidimas visai nesiunčia Origin, todėl jo tai neliečia, o paties žaidimo įterpta naršyklė leidžiama pagal pavadinimą, žr. FiveM. Jei kuri naršyklės ar telefono žaidimą, su tiltu nebendrauji: susietų žaidėjų būsenas skelbia tavo paties backend, žr. Naršyklės ir telefono žaidimai.

Ką žaidėjas išlaiko savo rankose

• Žaidėjas gali išjungti tiltą skiltyje Settings → Game Activity, ir tada joks žaidimas apskritai nemato mssgs.
• Kiekvienas patvirtintas žaidimas ten išvardytas su tiksliais jo turimais leidimais, paskutinio aktyvumo laiku ir mygtuku Remove. Pašalinimas veikia iškart: tokenas iš karto nustoja galioti.
• Susietas naršyklės ar telefono žaidimas išvardytas skiltyje Linked games su mygtuku Disconnect. Atsijungimas taip pat veikia iškart: kitas to backend skelbimas gauna 410.
• Tiltas klauso tik 127.0.0.1, niekada tinkle.
• Asmeninės žinutės niekada neatskleidžiamos, net su servers.list.
• Kiekvienas žaidimas turi 120 užklausų per minutę limitą.

Geroji praktika

• Prašyk aprėpčių tada, kai jų reikia, o ne visų iš karto per pirmą paleidimą.
• Veik ir be mssgs: žaidėjas neprivalo jos turėti.
• Išvalyk būseną, kai žaidimas baigiasi, užuot laukęs TTL.
• Atmestą aprėptį laikyk įprastu rezultatu, o ne klaida.